{"id":47973291,"url":"https://github.com/teabranch/agentic-code-indexer","last_synced_at":"2026-04-04T10:51:14.683Z","repository":{"id":300023808,"uuid":"1004959411","full_name":"teabranch/agentic-code-indexer","owner":"teabranch","description":"A library or cli to index a folder with code using llms and embeddings","archived":false,"fork":false,"pushed_at":"2025-06-19T13:20:18.000Z","size":96,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-19T13:52:51.558Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Cypher","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/teabranch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-19T12:47:32.000Z","updated_at":"2025-06-19T13:20:22.000Z","dependencies_parsed_at":"2025-06-19T13:52:53.318Z","dependency_job_id":"1a2d32d7-2099-4539-aa55-db8c5af3b250","html_url":"https://github.com/teabranch/agentic-code-indexer","commit_stats":null,"previous_names":["teabranch/agentic-code-indexer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/teabranch/agentic-code-indexer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teabranch%2Fagentic-code-indexer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teabranch%2Fagentic-code-indexer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teabranch%2Fagentic-code-indexer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teabranch%2Fagentic-code-indexer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/teabranch","download_url":"https://codeload.github.com/teabranch/agentic-code-indexer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teabranch%2Fagentic-code-indexer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31397055,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T10:51:14.050Z","updated_at":"2026-04-04T10:51:14.670Z","avatar_url":"https://github.com/teabranch.png","language":"Cypher","funding_links":[],"categories":[],"sub_categories":[],"readme":"![image](https://github.com/user-attachments/assets/ffc8a373-60e8-46b0-a8c8-b211f4de57fa)\n\n\n# 🤖 Agentic Code Indexer\n\nAn intelligent code analysis and graph-based indexing system that creates a comprehensive, searchable representation of your codebase using Neo4j, LLMs, and semantic embeddings.\n\n## ✨ Features\n\n- **🌐 Multi-language Support**: Python, C#, JavaScript/TypeScript\n- **📊 Graph-based Representation**: Rich code relationships in Neo4j\n- **🧠 LLM-powered Summarization**: Hierarchical code summaries using Claude\n- **🔍 Hybrid Search System**: Vector similarity + entity lookup + graph context expansion\n- **🎯 Natural Language Queries**: \"Find authentication methods\" or \"PaymentService class\"\n- **🕸️ GraphRAG Context**: Expand search results with related code relationships\n- **🌐 REST API**: FastAPI-based search API with interactive documentation\n- **⚡ Incremental Processing**: Change detection with SHA-256 checksums\n- **🚀 Concurrent Processing**: Async/await for high-performance indexing\n- **🎨 Beautiful CLI**: Rich terminal interface with progress tracking\n\n## 🏗️ Architecture\n\n```\n┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐\n│   File Traversal    │───▶│  Language Chunkers  │───▶│   Graph Ingestion   │\n│  \u0026 Change Detection │    │  (Python/C#/JS/TS) │    │     (Neo4j)         │\n└─────────────────────┘    └─────────────────────┘    └─────────────────────┘\n                                                                   │\n┌─────────────────────┐    ┌─────────────────────┐                │\n│  Embedding Gen.     │◀───│  LLM Summarization  │◀───────────────┘\n│ (Jina Embeddings)   │    │  (Anthropic Claude) │\n└─────────────────────┘    └─────────────────────┘\n```\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Python 3.8+\n- Node.js 18+ \n- .NET 6+\n- Neo4j Database\n- Anthropic API Key (optional, for LLM features)\n\n### Installation\n\n1. **Clone the repository**\n```bash\ngit clone https://github.com/your-org/agentic-code-indexer.git\ncd agentic-code-indexer\n```\n\n2. **Start Neo4j Database**\n```bash\ndocker-compose up -d\n```\n\n3. **Install Python dependencies**\n```bash\ncd src/agentic_code_indexer\npip install -r requirements.txt\n```\n\n4. **Set up environment variables**\n```bash\nexport ANTHROPIC_API_KEY=\"your-api-key-here\"  # Optional\nexport NEO4J_PASSWORD=\"your-neo4j-password\"\n```\n\n### Basic Usage\n\n1. **Index your codebase**\n```bash\n# Index current directory with database initialization\npython -m agentic_code_indexer index . --init-db\n\n# Index specific directory\npython -m agentic_code_indexer index /path/to/your/project\n\n# Skip LLM features (faster, no API required)\npython -m agentic_code_indexer index . --skip-llm\n```\n\n2. **Check indexing status**\n```bash\npython -m agentic_code_indexer status\n```\n\n3. **Generate summaries and embeddings**\n```bash\npython -m agentic_code_indexer summarize\n```\n\n4. **Search your codebase**\n```bash\n# Natural language search\npython -m agentic_code_indexer search \"authentication methods\"\npython -m agentic_code_indexer search \"PaymentService class\" --types Class\npython -m agentic_code_indexer search \"error handling\" --context --code\n\n# Explain how a query would be processed\npython -m agentic_code_indexer explain \"user authentication\"\n\n# Start the search API server\npython -m agentic_code_indexer api --host 0.0.0.0 --port 8000\n# Then visit http://localhost:8000/docs for interactive API documentation\n```\n\n## 📚 Component Overview\n\n### Phase 1: Foundation (✅ Complete)\n\n- **🗃️ Neo4j Database Setup**: Comprehensive schema with constraints and vector indexes\n- **🐍 Python Chunker**: LibCST-based AST analysis with scope resolution\n- **🔷 C# Chunker**: Microsoft.CodeAnalysis with semantic symbol resolution  \n- **🟨 JavaScript/TypeScript Chunker**: TypeScript Compiler API + Acorn parser\n- **📋 Common Data Format**: Pydantic models for cross-language compatibility\n\n### Phase 2: Main Pipeline (✅ Complete)\n\n- **📁 File Traversal**: Recursive directory scanning with change detection\n- **🔄 Chunker Orchestration**: Coordinates all language-specific chunkers\n- **📊 Graph Ingestion**: Efficient batched Neo4j operations with MERGE clauses\n- **🧠 Hierarchical Summarization**: Bottom-up LLM processing (Parameters → Variables → Methods → Classes → Files)\n- **🔍 Embedding Generation**: Local vector generation using Jina embeddings\n- **⚙️ Transaction Management**: Error handling, retry mechanisms, and batch optimization\n\n### Phase 3: Retrieval System (✅ Complete)\n\n- **🔍 Vector Search Engine**: Semantic similarity search using Neo4j vector indexes\n- **🕸️ Graph Traversal Engine**: GraphRAG-style context expansion with relationship following\n- **🎯 Hybrid Search System**: Combines vector similarity, entity lookup, and graph context\n- **🤖 Query Intent Parsing**: Intelligent analysis of natural language queries\n- **📊 Call \u0026 Inheritance Hierarchy**: Analyze method calls and class inheritance patterns\n- **🌐 REST API**: FastAPI-based search API with comprehensive endpoints\n- **💻 Interactive CLI**: Rich terminal search interface with explanations\n\n## 🛠️ Advanced Usage\n\n### Custom Configuration\n\n```bash\n# Use different Neo4j instance\npython -m agentic_code_indexer index . \\\n  --neo4j-uri bolt://your-server:7687 \\\n  --neo4j-user your-username \\\n  --neo4j-password your-password\n\n# Adjust performance settings\npython -m agentic_code_indexer index . \\\n  --max-concurrent 10 \\\n  --batch-size 2000\n\n# Verbose logging\npython -m agentic_code_indexer index . --verbose\n```\n\n### Recovery Operations\n\n```bash\n# Reset processing status (if interrupted)\npython -m agentic_code_indexer reset --confirm\n\n# Re-run just summarization\npython -m agentic_code_indexer summarize --batch-size 50\n```\n\n## 📊 Database Schema\n\nThe system creates a rich graph model in Neo4j:\n\n### Node Types\n- **File**: Source code files with checksums and metadata\n- **Class/Interface**: Type definitions with inheritance relationships  \n- **Method/Function**: Callable code elements with parameters\n- **Variable/Parameter**: Data elements with type information\n- **Import**: Dependency declarations\n\n### Relationships\n- **CONTAINS**: Hierarchical containment (File → Class → Method)\n- **DEFINES**: Definition relationships (Class → Method)\n- **CALLS**: Function/method invocations\n- **EXTENDS/IMPLEMENTS**: Inheritance relationships\n- **IMPORTS**: Module dependencies\n\n### Vector Indexes\n- 768-dimensional embeddings on all major node types\n- Cosine similarity for semantic search\n- Optimized for `jina-embeddings-v2-base-code` model\n\n## 🔍 Search Examples\n\n### Natural Language Search\n\n```bash\n# Find authentication-related code\npython -m agentic_code_indexer search \"user authentication login\"\n\n# Search for specific classes\npython -m agentic_code_indexer search \"PaymentService\" --types Class\n\n# Find error handling patterns\npython -m agentic_code_indexer search \"exception handling try catch\" --context\n\n# Search with source code included\npython -m agentic_code_indexer search \"database connection\" --code --verbose\n\n# Explain search strategy\npython -m agentic_code_indexer explain \"API rate limiting middleware\"\n```\n\n### REST API Examples\n\n```bash\n# Start the API server\npython -m agentic_code_indexer api\n\n# Search via HTTP\ncurl -X POST \"http://localhost:8000/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"authentication methods\", \"max_results\": 5, \"include_context\": true}'\n\n# Get call hierarchy for a method\ncurl -X POST \"http://localhost:8000/hierarchy/call\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"node_id\": \"method_123\", \"direction\": \"both\", \"max_depth\": 2}'\n\n# Get inheritance hierarchy for a class\ncurl -X POST \"http://localhost:8000/hierarchy/inheritance\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"node_id\": \"class_456\"}'\n```\n\n### Example Cypher Queries\n\n```cypher\n// Find all classes that implement a specific interface\nMATCH (c:Class)-[:IMPLEMENTS]-\u003e(i:Interface {name: \"IUserRepository\"})\nRETURN c.name, c.generated_summary\n\n// Semantic search for payment-related code\nCALL db.index.vector.queryNodes('embedding_index', 10, $payment_embedding)\nYIELD node, score\nRETURN node.name, node.generated_summary, score\n\n// Find complex methods (high cyclomatic complexity)\nMATCH (m:Method)\nWHERE m.raw_code CONTAINS \"if\" AND m.raw_code CONTAINS \"for\"\nRETURN m.full_name, m.generated_summary\n```\n\n## 🧪 Testing\n\nEach chunker includes comprehensive test coverage:\n\n```bash\n# Test Python chunker\ncd src/python-chunker \u0026\u0026 python -m pytest\n\n# Test C# chunker  \ncd src/csharp-chunker/CSharpChunker \u0026\u0026 dotnet test\n\n# Test Node.js chunker\ncd src/nodejs-chunker \u0026\u0026 npm test\n```\n\n## 📈 Performance\n\n- **Throughput**: ~50-100 files/second (depends on file size and complexity)\n- **Concurrency**: Configurable concurrent processing (default: 5 workers)\n- **Memory**: Efficient streaming with batched database operations\n- **Incremental**: Only processes changed files using SHA-256 checksums\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass\n5. Submit a pull request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- **Microsoft CodeAnalysis** for C# semantic analysis\n- **LibCST** for Python concrete syntax trees\n- **TypeScript Compiler API** for JavaScript/TypeScript analysis\n- **Neo4j** for graph database capabilities\n- **Anthropic Claude** for intelligent code summarization\n- **Jina AI** for state-of-the-art code embeddings\n\n## Cite this project\n\n### Code citation\n```\n@software{agentic-code-indexer,\n  author = {TeaBranch},\n  title = {agentic-code-indexer: An intelligent code analysis and graph-based indexing system that creates a comprehensive, searchable representation of your codebase using Neo4j, LLMs, and semantic embeddings.},\n  year = {2025},\n  publisher = {GitHub},\n  journal = {GitHub Repository},\n  howpublished = {\\url{https://github.com/teabranch/agentic-code-indexer}},\n  commit = {use the commit hash you’re working with}\n}\n```\n\n### Text citation\n\nTeaBranch. (2025). agentic-code-indexer: An intelligent code analysis and graph-based indexing system that creates a comprehensive, searchable representation of your codebase using Neo4j, LLMs, and semantic embeddings. [Computer software]. GitHub. https://github.com/teabranch/agentic-code-indexer\n\n\n---\n\n**Ready to explore your codebase like never before?** 🚀\n\nGet started with the Agentic Code Indexer and unlock the full potential of graph-based code analysis! \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteabranch%2Fagentic-code-indexer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fteabranch%2Fagentic-code-indexer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteabranch%2Fagentic-code-indexer/lists"}