agent-coderag 1.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. agent_coderag-1.1.0/LICENSE +21 -0
  2. agent_coderag-1.1.0/NOTICE +17 -0
  3. agent_coderag-1.1.0/PKG-INFO +188 -0
  4. agent_coderag-1.1.0/README.md +154 -0
  5. agent_coderag-1.1.0/agent_coderag.egg-info/PKG-INFO +188 -0
  6. agent_coderag-1.1.0/agent_coderag.egg-info/SOURCES.txt +29 -0
  7. agent_coderag-1.1.0/agent_coderag.egg-info/dependency_links.txt +1 -0
  8. agent_coderag-1.1.0/agent_coderag.egg-info/entry_points.txt +2 -0
  9. agent_coderag-1.1.0/agent_coderag.egg-info/requires.txt +8 -0
  10. agent_coderag-1.1.0/agent_coderag.egg-info/top_level.txt +1 -0
  11. agent_coderag-1.1.0/code_rag/__init__.py +0 -0
  12. agent_coderag-1.1.0/code_rag/core/__init__.py +0 -0
  13. agent_coderag-1.1.0/code_rag/core/interfaces.py +29 -0
  14. agent_coderag-1.1.0/code_rag/core/manager.py +70 -0
  15. agent_coderag-1.1.0/code_rag/core/models.py +33 -0
  16. agent_coderag-1.1.0/code_rag/discovery/__init__.py +0 -0
  17. agent_coderag-1.1.0/code_rag/discovery/dependency.py +40 -0
  18. agent_coderag-1.1.0/code_rag/entry/__init__.py +0 -0
  19. agent_coderag-1.1.0/code_rag/entry/cli.py +214 -0
  20. agent_coderag-1.1.0/code_rag/intelligence/__init__.py +0 -0
  21. agent_coderag-1.1.0/code_rag/intelligence/distiller.py +80 -0
  22. agent_coderag-1.1.0/code_rag/intelligence/embedder.py +100 -0
  23. agent_coderag-1.1.0/code_rag/parsers/__init__.py +0 -0
  24. agent_coderag-1.1.0/code_rag/parsers/ast_index.py +81 -0
  25. agent_coderag-1.1.0/code_rag/storage/__init__.py +0 -0
  26. agent_coderag-1.1.0/code_rag/storage/duckdb_impl.py +111 -0
  27. agent_coderag-1.1.0/pyproject.toml +51 -0
  28. agent_coderag-1.1.0/setup.cfg +4 -0
  29. agent_coderag-1.1.0/tests/test_ast_parser.py +70 -0
  30. agent_coderag-1.1.0/tests/test_code_rag_simple.py +72 -0
  31. agent_coderag-1.1.0/tests/test_dependency_discovery.py +39 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Igor Boloban
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,17 @@
1
+ CodeRAG
2
+ Copyright 2026 Igor Boloban
3
+
4
+ This product includes software developed by the following third-party projects:
5
+
6
+ - DuckDB (MIT License) - https://duckdb.org/
7
+ - NumPy (BSD License) - https://numpy.org/
8
+ - LiteLLM (MIT License) - https://litellm.ai/
9
+ - ONNX Runtime (MIT License) - https://onnxruntime.ai/
10
+ - Tokenizers (Apache License 2.0) - https://github.com/huggingface/tokenizers
11
+ - Pydantic (MIT License) - https://github.com/pydantic/pydantic
12
+ - HTTPX (BSD License) - https://github.com/encode/httpx
13
+ - Aiofiles (Apache License 2.0) - https://github.com/Tinche/aiofiles
14
+ - Sentence Transformers (Apache License 2.0) - https://www.sbert.net/
15
+
16
+ This product also uses various other open-source libraries as listed in THIRD_PARTY_LICENSES.md.
17
+ All trademarks are the property of their respective owners.
@@ -0,0 +1,188 @@
1
+ Metadata-Version: 2.4
2
+ Name: agent-coderag
3
+ Version: 1.1.0
4
+ Summary: Lightweight semantic code search and distillation utility for AI coding agents. It solves the API knowledge gap via real-time local signature extraction and intent analysis without PyTorch. Optimized for token efficiency, it compresses codebase context into compact semantic summaries stored in a local DuckDB vector similarity index.
5
+ Author-email: Igor Boloban <naranor@gmail.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/naranor/agent-coderag
8
+ Project-URL: Repository, https://github.com/naranor/agent-coderag
9
+ Project-URL: Issues, https://github.com/naranor/agent-coderag/issues
10
+ Project-URL: Changelog, https://github.com/naranor/agent-coderag/blob/main/CHANGELOG.md
11
+ Keywords: rag,ai-agents,semantic-search,code-analysis,context-compression,onnx,local-embeddings
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
20
+ Classifier: Topic :: Text Processing :: Indexing
21
+ Requires-Python: >=3.10
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ License-File: NOTICE
25
+ Requires-Dist: duckdb
26
+ Requires-Dist: numpy
27
+ Requires-Dist: litellm
28
+ Requires-Dist: onnxruntime
29
+ Requires-Dist: tokenizers
30
+ Requires-Dist: pydantic
31
+ Requires-Dist: httpx
32
+ Requires-Dist: aiofiles
33
+ Dynamic: license-file
34
+
35
+ # Agent-CodeRAG: Semantic Intelligence for AI Coding Agents
36
+
37
+ > **Fast. Local. Agent-First. Token-Efficient.**
38
+
39
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
40
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
41
+ [![No PyTorch](https://img.shields.io/badge/Footprint-No_PyTorch-green.svg)](#-key-technologies)
42
+ [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
43
+
44
+ ---
45
+
46
+ ## 📖 Table of Contents
47
+ - [🧠 The Problem: The API Knowledge Gap](#-the-problem-the-api-knowledge-gap)
48
+ - [🚀 The Solution: Real-Time Contextual Truth](#-the-solution-real-time-contextual-truth)
49
+ - [🛠 How it Works](#-how-it-works)
50
+ - [📡 API Discovery](#-api-discovery)
51
+ - [🏃 Quick Start](#-quick-start)
52
+ - [🤖 For AI Agents](#-for-ai-agents)
53
+ - [🔧 Development](#-development)
54
+ - [📄 License](#-license)
55
+
56
+ ---
57
+
58
+ ## 🧠 The Problem: The API Knowledge Gap
59
+
60
+ AI coding agents often hallucinate when calling library APIs because their training data is static. This leads to a **"Fail-Fix-Fail" cycle**:
61
+
62
+ 1. **Broken Code**: Agents use deprecated parameters or non-existent methods from outdated versions.
63
+ 2. **Token Waste**: You provide the error, the agent tries to fix it using more outdated data, consuming thousands of tokens in a loop.
64
+ 3. **Environment Mismatch**: The agent knows the API for version 1.0, but your environment has 2.0.
65
+
66
+ ### Real-world Example (The Pydantic Gap)
67
+ * **Agent's Knowledge**: Knows Pydantic v1 (`model.dict()`).
68
+ * **Your Environment**: Uses Pydantic v2 (`model.model_dump()`).
69
+ * **The Result**: The agent writes `dict()`, the code fails, and it wastes **5000+ tokens** trying to "fix" a problem it doesn't understand.
70
+
71
+ ## 🚀 The Solution: Real-Time Contextual Truth
72
+
73
+ Agent-CodeRAG acts as a lightweight semantic bridge between your local environment and the LLM.
74
+
75
+ * **API Discovery**: Extracts *actual* signatures from your installed libraries.
76
+ * **Semantic Retrieval**: Provides the LLM with the exact **Intent** of your code units, indexed locally via ONNX.
77
+ * **Token Efficiency**: Instead of sending whole files, Agent-CodeRAG distills code into compact semantic summaries, **saving up to 80% of context window tokens**.
78
+
79
+ ---
80
+
81
+ ## 🛠 How it Works
82
+
83
+ ```mermaid
84
+ graph TD
85
+ A[Local Python Code] --> B[AST Parser]
86
+ B --> C{Delta-Sync}
87
+ C -- Changed/New --> D[LLM Distiller]
88
+ C -- Unchanged --> E[Local Cache]
89
+ D --> F[Semantic Summary]
90
+ E --> F
91
+ F --> G[ONNX Embedder]
92
+ G --> H[(DuckDB VSS)]
93
+ H --> I[Semantic Search / JSON API]
94
+ ```
95
+
96
+ ### ✨ Key Features
97
+ * **⚡ No PyTorch**: Uses `onnxruntime` and `tokenizers` (Rust) for a tiny footprint and instant startup.
98
+ * **💾 DuckDB VSS**: High-performance vector similarity search stored in a single local file.
99
+ * **🔄 Delta-Sync**: Uses SHA-256 hashing to only re-distill changed code, saving your API budget.
100
+ * **🔌 Hybrid Intelligence**: Works offline using name-based embeddings; adds AI-distilled reasoning when an LLM is connected.
101
+
102
+ ---
103
+
104
+ ## 📡 API Discovery
105
+ To help your agent understand a specific library version installed in your environment:
106
+ ```bash
107
+ agent-coderag api pydantic
108
+ ```
109
+ Returns the *live* public API, methods, and signatures.
110
+
111
+ ---
112
+
113
+ ## 🏃 Quick Start
114
+
115
+ ### 1. Install
116
+ ```bash
117
+ pip install agent-coderag
118
+ ```
119
+
120
+ ### 2. Setup AI Models
121
+ Download the lightweight `paraphrase-multilingual-MiniLM` ONNX model to your global cache:
122
+ ```bash
123
+ agent-coderag setup
124
+ ```
125
+
126
+ ### 3. Configure your LLM (For Distillation)
127
+
128
+ **Option A: Cloud (OpenAI)**
129
+ ```bash
130
+ agent-coderag config --url "https://api.openai.com/v1" --model "gpt-4o-mini" --key "sk-..."
131
+ ```
132
+
133
+ **Option B: Local (Ollama) - Recommended**
134
+ ```bash
135
+ agent-coderag config --url "http://localhost:11434" --provider "ollama" --model "qwen2.5-coder:7b"
136
+ ```
137
+ *We recommend using `qwen2.5-coder` or `llama3.2` for fast and private local distillation.*
138
+
139
+
140
+ ### 4. Index your Project
141
+ ```bash
142
+ agent-coderag sync --all
143
+ ```
144
+
145
+ ### 5. Search
146
+ * **Human Mode (Compact)**: `agent-coderag search "how to handle errors"`
147
+ * **Agent Mode (JSON)**: `agent-coderag --json search "data storage" --limit 1`
148
+
149
+ ### 🐳 Docker (Alternative)
150
+ ```bash
151
+ docker build -t agent-coderag .
152
+ docker run -v ~/.cache/agent-coderag:/root/.cache/agent-coderag agent-coderag setup
153
+ ```
154
+
155
+ ---
156
+
157
+ ## 🤖 For AI Agents
158
+
159
+ Agent-CodeRAG is built specifically for programmatic consumption.
160
+
161
+ ### Agent Strategy
162
+ 1. **Search First**: Use `agent-coderag --json search "topic"` to find relevant code units before reading files.
163
+ 2. **Use Intent**: The `summary` field provides technical intent, allowing you to skip reading complex implementation details.
164
+
165
+ ---
166
+
167
+ ## 🔧 Development
168
+
169
+ ### Running Tests
170
+ ```bash
171
+ pytest tests/
172
+ pytest e2e_tests/
173
+ ```
174
+
175
+ ### Pre-commit Hooks
176
+ We use `pre-commit` to maintain high code standards:
177
+ ```bash
178
+ pip install pre-commit
179
+ pre-commit install
180
+ ```
181
+
182
+ ---
183
+
184
+ ## 📄 License
185
+ MIT © 2026 Igor Boloban
186
+
187
+ ## 🙏 Acknowledgments
188
+ This project stands on the shoulders of giants. See [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md) for a full list of open-source libraries used in Agent-CodeRAG.
@@ -0,0 +1,154 @@
1
+ # Agent-CodeRAG: Semantic Intelligence for AI Coding Agents
2
+
3
+ > **Fast. Local. Agent-First. Token-Efficient.**
4
+
5
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7
+ [![No PyTorch](https://img.shields.io/badge/Footprint-No_PyTorch-green.svg)](#-key-technologies)
8
+ [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
9
+
10
+ ---
11
+
12
+ ## 📖 Table of Contents
13
+ - [🧠 The Problem: The API Knowledge Gap](#-the-problem-the-api-knowledge-gap)
14
+ - [🚀 The Solution: Real-Time Contextual Truth](#-the-solution-real-time-contextual-truth)
15
+ - [🛠 How it Works](#-how-it-works)
16
+ - [📡 API Discovery](#-api-discovery)
17
+ - [🏃 Quick Start](#-quick-start)
18
+ - [🤖 For AI Agents](#-for-ai-agents)
19
+ - [🔧 Development](#-development)
20
+ - [📄 License](#-license)
21
+
22
+ ---
23
+
24
+ ## 🧠 The Problem: The API Knowledge Gap
25
+
26
+ AI coding agents often hallucinate when calling library APIs because their training data is static. This leads to a **"Fail-Fix-Fail" cycle**:
27
+
28
+ 1. **Broken Code**: Agents use deprecated parameters or non-existent methods from outdated versions.
29
+ 2. **Token Waste**: You provide the error, the agent tries to fix it using more outdated data, consuming thousands of tokens in a loop.
30
+ 3. **Environment Mismatch**: The agent knows the API for version 1.0, but your environment has 2.0.
31
+
32
+ ### Real-world Example (The Pydantic Gap)
33
+ * **Agent's Knowledge**: Knows Pydantic v1 (`model.dict()`).
34
+ * **Your Environment**: Uses Pydantic v2 (`model.model_dump()`).
35
+ * **The Result**: The agent writes `dict()`, the code fails, and it wastes **5000+ tokens** trying to "fix" a problem it doesn't understand.
36
+
37
+ ## 🚀 The Solution: Real-Time Contextual Truth
38
+
39
+ Agent-CodeRAG acts as a lightweight semantic bridge between your local environment and the LLM.
40
+
41
+ * **API Discovery**: Extracts *actual* signatures from your installed libraries.
42
+ * **Semantic Retrieval**: Provides the LLM with the exact **Intent** of your code units, indexed locally via ONNX.
43
+ * **Token Efficiency**: Instead of sending whole files, Agent-CodeRAG distills code into compact semantic summaries, **saving up to 80% of context window tokens**.
44
+
45
+ ---
46
+
47
+ ## 🛠 How it Works
48
+
49
+ ```mermaid
50
+ graph TD
51
+ A[Local Python Code] --> B[AST Parser]
52
+ B --> C{Delta-Sync}
53
+ C -- Changed/New --> D[LLM Distiller]
54
+ C -- Unchanged --> E[Local Cache]
55
+ D --> F[Semantic Summary]
56
+ E --> F
57
+ F --> G[ONNX Embedder]
58
+ G --> H[(DuckDB VSS)]
59
+ H --> I[Semantic Search / JSON API]
60
+ ```
61
+
62
+ ### ✨ Key Features
63
+ * **⚡ No PyTorch**: Uses `onnxruntime` and `tokenizers` (Rust) for a tiny footprint and instant startup.
64
+ * **💾 DuckDB VSS**: High-performance vector similarity search stored in a single local file.
65
+ * **🔄 Delta-Sync**: Uses SHA-256 hashing to only re-distill changed code, saving your API budget.
66
+ * **🔌 Hybrid Intelligence**: Works offline using name-based embeddings; adds AI-distilled reasoning when an LLM is connected.
67
+
68
+ ---
69
+
70
+ ## 📡 API Discovery
71
+ To help your agent understand a specific library version installed in your environment:
72
+ ```bash
73
+ agent-coderag api pydantic
74
+ ```
75
+ Returns the *live* public API, methods, and signatures.
76
+
77
+ ---
78
+
79
+ ## 🏃 Quick Start
80
+
81
+ ### 1. Install
82
+ ```bash
83
+ pip install agent-coderag
84
+ ```
85
+
86
+ ### 2. Setup AI Models
87
+ Download the lightweight `paraphrase-multilingual-MiniLM` ONNX model to your global cache:
88
+ ```bash
89
+ agent-coderag setup
90
+ ```
91
+
92
+ ### 3. Configure your LLM (For Distillation)
93
+
94
+ **Option A: Cloud (OpenAI)**
95
+ ```bash
96
+ agent-coderag config --url "https://api.openai.com/v1" --model "gpt-4o-mini" --key "sk-..."
97
+ ```
98
+
99
+ **Option B: Local (Ollama) - Recommended**
100
+ ```bash
101
+ agent-coderag config --url "http://localhost:11434" --provider "ollama" --model "qwen2.5-coder:7b"
102
+ ```
103
+ *We recommend using `qwen2.5-coder` or `llama3.2` for fast and private local distillation.*
104
+
105
+
106
+ ### 4. Index your Project
107
+ ```bash
108
+ agent-coderag sync --all
109
+ ```
110
+
111
+ ### 5. Search
112
+ * **Human Mode (Compact)**: `agent-coderag search "how to handle errors"`
113
+ * **Agent Mode (JSON)**: `agent-coderag --json search "data storage" --limit 1`
114
+
115
+ ### 🐳 Docker (Alternative)
116
+ ```bash
117
+ docker build -t agent-coderag .
118
+ docker run -v ~/.cache/agent-coderag:/root/.cache/agent-coderag agent-coderag setup
119
+ ```
120
+
121
+ ---
122
+
123
+ ## 🤖 For AI Agents
124
+
125
+ Agent-CodeRAG is built specifically for programmatic consumption.
126
+
127
+ ### Agent Strategy
128
+ 1. **Search First**: Use `agent-coderag --json search "topic"` to find relevant code units before reading files.
129
+ 2. **Use Intent**: The `summary` field provides technical intent, allowing you to skip reading complex implementation details.
130
+
131
+ ---
132
+
133
+ ## 🔧 Development
134
+
135
+ ### Running Tests
136
+ ```bash
137
+ pytest tests/
138
+ pytest e2e_tests/
139
+ ```
140
+
141
+ ### Pre-commit Hooks
142
+ We use `pre-commit` to maintain high code standards:
143
+ ```bash
144
+ pip install pre-commit
145
+ pre-commit install
146
+ ```
147
+
148
+ ---
149
+
150
+ ## 📄 License
151
+ MIT © 2026 Igor Boloban
152
+
153
+ ## 🙏 Acknowledgments
154
+ This project stands on the shoulders of giants. See [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md) for a full list of open-source libraries used in Agent-CodeRAG.
@@ -0,0 +1,188 @@
1
+ Metadata-Version: 2.4
2
+ Name: agent-coderag
3
+ Version: 1.1.0
4
+ Summary: Lightweight semantic code search and distillation utility for AI coding agents. It solves the API knowledge gap via real-time local signature extraction and intent analysis without PyTorch. Optimized for token efficiency, it compresses codebase context into compact semantic summaries stored in a local DuckDB vector similarity index.
5
+ Author-email: Igor Boloban <naranor@gmail.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/naranor/agent-coderag
8
+ Project-URL: Repository, https://github.com/naranor/agent-coderag
9
+ Project-URL: Issues, https://github.com/naranor/agent-coderag/issues
10
+ Project-URL: Changelog, https://github.com/naranor/agent-coderag/blob/main/CHANGELOG.md
11
+ Keywords: rag,ai-agents,semantic-search,code-analysis,context-compression,onnx,local-embeddings
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
20
+ Classifier: Topic :: Text Processing :: Indexing
21
+ Requires-Python: >=3.10
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ License-File: NOTICE
25
+ Requires-Dist: duckdb
26
+ Requires-Dist: numpy
27
+ Requires-Dist: litellm
28
+ Requires-Dist: onnxruntime
29
+ Requires-Dist: tokenizers
30
+ Requires-Dist: pydantic
31
+ Requires-Dist: httpx
32
+ Requires-Dist: aiofiles
33
+ Dynamic: license-file
34
+
35
+ # Agent-CodeRAG: Semantic Intelligence for AI Coding Agents
36
+
37
+ > **Fast. Local. Agent-First. Token-Efficient.**
38
+
39
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
40
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
41
+ [![No PyTorch](https://img.shields.io/badge/Footprint-No_PyTorch-green.svg)](#-key-technologies)
42
+ [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
43
+
44
+ ---
45
+
46
+ ## 📖 Table of Contents
47
+ - [🧠 The Problem: The API Knowledge Gap](#-the-problem-the-api-knowledge-gap)
48
+ - [🚀 The Solution: Real-Time Contextual Truth](#-the-solution-real-time-contextual-truth)
49
+ - [🛠 How it Works](#-how-it-works)
50
+ - [📡 API Discovery](#-api-discovery)
51
+ - [🏃 Quick Start](#-quick-start)
52
+ - [🤖 For AI Agents](#-for-ai-agents)
53
+ - [🔧 Development](#-development)
54
+ - [📄 License](#-license)
55
+
56
+ ---
57
+
58
+ ## 🧠 The Problem: The API Knowledge Gap
59
+
60
+ AI coding agents often hallucinate when calling library APIs because their training data is static. This leads to a **"Fail-Fix-Fail" cycle**:
61
+
62
+ 1. **Broken Code**: Agents use deprecated parameters or non-existent methods from outdated versions.
63
+ 2. **Token Waste**: You provide the error, the agent tries to fix it using more outdated data, consuming thousands of tokens in a loop.
64
+ 3. **Environment Mismatch**: The agent knows the API for version 1.0, but your environment has 2.0.
65
+
66
+ ### Real-world Example (The Pydantic Gap)
67
+ * **Agent's Knowledge**: Knows Pydantic v1 (`model.dict()`).
68
+ * **Your Environment**: Uses Pydantic v2 (`model.model_dump()`).
69
+ * **The Result**: The agent writes `dict()`, the code fails, and it wastes **5000+ tokens** trying to "fix" a problem it doesn't understand.
70
+
71
+ ## 🚀 The Solution: Real-Time Contextual Truth
72
+
73
+ Agent-CodeRAG acts as a lightweight semantic bridge between your local environment and the LLM.
74
+
75
+ * **API Discovery**: Extracts *actual* signatures from your installed libraries.
76
+ * **Semantic Retrieval**: Provides the LLM with the exact **Intent** of your code units, indexed locally via ONNX.
77
+ * **Token Efficiency**: Instead of sending whole files, Agent-CodeRAG distills code into compact semantic summaries, **saving up to 80% of context window tokens**.
78
+
79
+ ---
80
+
81
+ ## 🛠 How it Works
82
+
83
+ ```mermaid
84
+ graph TD
85
+ A[Local Python Code] --> B[AST Parser]
86
+ B --> C{Delta-Sync}
87
+ C -- Changed/New --> D[LLM Distiller]
88
+ C -- Unchanged --> E[Local Cache]
89
+ D --> F[Semantic Summary]
90
+ E --> F
91
+ F --> G[ONNX Embedder]
92
+ G --> H[(DuckDB VSS)]
93
+ H --> I[Semantic Search / JSON API]
94
+ ```
95
+
96
+ ### ✨ Key Features
97
+ * **⚡ No PyTorch**: Uses `onnxruntime` and `tokenizers` (Rust) for a tiny footprint and instant startup.
98
+ * **💾 DuckDB VSS**: High-performance vector similarity search stored in a single local file.
99
+ * **🔄 Delta-Sync**: Uses SHA-256 hashing to only re-distill changed code, saving your API budget.
100
+ * **🔌 Hybrid Intelligence**: Works offline using name-based embeddings; adds AI-distilled reasoning when an LLM is connected.
101
+
102
+ ---
103
+
104
+ ## 📡 API Discovery
105
+ To help your agent understand a specific library version installed in your environment:
106
+ ```bash
107
+ agent-coderag api pydantic
108
+ ```
109
+ Returns the *live* public API, methods, and signatures.
110
+
111
+ ---
112
+
113
+ ## 🏃 Quick Start
114
+
115
+ ### 1. Install
116
+ ```bash
117
+ pip install agent-coderag
118
+ ```
119
+
120
+ ### 2. Setup AI Models
121
+ Download the lightweight `paraphrase-multilingual-MiniLM` ONNX model to your global cache:
122
+ ```bash
123
+ agent-coderag setup
124
+ ```
125
+
126
+ ### 3. Configure your LLM (For Distillation)
127
+
128
+ **Option A: Cloud (OpenAI)**
129
+ ```bash
130
+ agent-coderag config --url "https://api.openai.com/v1" --model "gpt-4o-mini" --key "sk-..."
131
+ ```
132
+
133
+ **Option B: Local (Ollama) - Recommended**
134
+ ```bash
135
+ agent-coderag config --url "http://localhost:11434" --provider "ollama" --model "qwen2.5-coder:7b"
136
+ ```
137
+ *We recommend using `qwen2.5-coder` or `llama3.2` for fast and private local distillation.*
138
+
139
+
140
+ ### 4. Index your Project
141
+ ```bash
142
+ agent-coderag sync --all
143
+ ```
144
+
145
+ ### 5. Search
146
+ * **Human Mode (Compact)**: `agent-coderag search "how to handle errors"`
147
+ * **Agent Mode (JSON)**: `agent-coderag --json search "data storage" --limit 1`
148
+
149
+ ### 🐳 Docker (Alternative)
150
+ ```bash
151
+ docker build -t agent-coderag .
152
+ docker run -v ~/.cache/agent-coderag:/root/.cache/agent-coderag agent-coderag setup
153
+ ```
154
+
155
+ ---
156
+
157
+ ## 🤖 For AI Agents
158
+
159
+ Agent-CodeRAG is built specifically for programmatic consumption.
160
+
161
+ ### Agent Strategy
162
+ 1. **Search First**: Use `agent-coderag --json search "topic"` to find relevant code units before reading files.
163
+ 2. **Use Intent**: The `summary` field provides technical intent, allowing you to skip reading complex implementation details.
164
+
165
+ ---
166
+
167
+ ## 🔧 Development
168
+
169
+ ### Running Tests
170
+ ```bash
171
+ pytest tests/
172
+ pytest e2e_tests/
173
+ ```
174
+
175
+ ### Pre-commit Hooks
176
+ We use `pre-commit` to maintain high code standards:
177
+ ```bash
178
+ pip install pre-commit
179
+ pre-commit install
180
+ ```
181
+
182
+ ---
183
+
184
+ ## 📄 License
185
+ MIT © 2026 Igor Boloban
186
+
187
+ ## 🙏 Acknowledgments
188
+ This project stands on the shoulders of giants. See [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md) for a full list of open-source libraries used in Agent-CodeRAG.
@@ -0,0 +1,29 @@
1
+ LICENSE
2
+ NOTICE
3
+ README.md
4
+ pyproject.toml
5
+ agent_coderag.egg-info/PKG-INFO
6
+ agent_coderag.egg-info/SOURCES.txt
7
+ agent_coderag.egg-info/dependency_links.txt
8
+ agent_coderag.egg-info/entry_points.txt
9
+ agent_coderag.egg-info/requires.txt
10
+ agent_coderag.egg-info/top_level.txt
11
+ code_rag/__init__.py
12
+ code_rag/core/__init__.py
13
+ code_rag/core/interfaces.py
14
+ code_rag/core/manager.py
15
+ code_rag/core/models.py
16
+ code_rag/discovery/__init__.py
17
+ code_rag/discovery/dependency.py
18
+ code_rag/entry/__init__.py
19
+ code_rag/entry/cli.py
20
+ code_rag/intelligence/__init__.py
21
+ code_rag/intelligence/distiller.py
22
+ code_rag/intelligence/embedder.py
23
+ code_rag/parsers/__init__.py
24
+ code_rag/parsers/ast_index.py
25
+ code_rag/storage/__init__.py
26
+ code_rag/storage/duckdb_impl.py
27
+ tests/test_ast_parser.py
28
+ tests/test_code_rag_simple.py
29
+ tests/test_dependency_discovery.py
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ agent-coderag = code_rag.entry.cli:main
@@ -0,0 +1,8 @@
1
+ duckdb
2
+ numpy
3
+ litellm
4
+ onnxruntime
5
+ tokenizers
6
+ pydantic
7
+ httpx
8
+ aiofiles
File without changes
File without changes
@@ -0,0 +1,29 @@
1
+ from abc import ABC, abstractmethod
2
+ from typing import List, Optional
3
+ from .models import KnowledgeUnit
4
+
5
+ class IParser(ABC):
6
+ """Interface for extracting structure from code."""
7
+ @abstractmethod
8
+ async def distill_file(self, file_path: str) -> List[KnowledgeUnit]:
9
+ pass
10
+
11
+ class IStorage(ABC):
12
+ """Interface for storing the index."""
13
+ @abstractmethod
14
+ async def upsert_unit(self, unit: KnowledgeUnit):
15
+ pass
16
+
17
+ @abstractmethod
18
+ async def get_unit(self, unit_id: str) -> Optional[KnowledgeUnit]:
19
+ pass
20
+
21
+ @abstractmethod
22
+ async def search_units(self, query: str, limit: int = 5) -> List[KnowledgeUnit]:
23
+ pass
24
+
25
+ class IIntelligence(ABC):
26
+ """Interface for LLM-based analysis (distillation, embeddings)."""
27
+ @abstractmethod
28
+ async def summarize(self, code: str, unit_name: str) -> str:
29
+ pass