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.
- agent_coderag-1.1.0/LICENSE +21 -0
- agent_coderag-1.1.0/NOTICE +17 -0
- agent_coderag-1.1.0/PKG-INFO +188 -0
- agent_coderag-1.1.0/README.md +154 -0
- agent_coderag-1.1.0/agent_coderag.egg-info/PKG-INFO +188 -0
- agent_coderag-1.1.0/agent_coderag.egg-info/SOURCES.txt +29 -0
- agent_coderag-1.1.0/agent_coderag.egg-info/dependency_links.txt +1 -0
- agent_coderag-1.1.0/agent_coderag.egg-info/entry_points.txt +2 -0
- agent_coderag-1.1.0/agent_coderag.egg-info/requires.txt +8 -0
- agent_coderag-1.1.0/agent_coderag.egg-info/top_level.txt +1 -0
- agent_coderag-1.1.0/code_rag/__init__.py +0 -0
- agent_coderag-1.1.0/code_rag/core/__init__.py +0 -0
- agent_coderag-1.1.0/code_rag/core/interfaces.py +29 -0
- agent_coderag-1.1.0/code_rag/core/manager.py +70 -0
- agent_coderag-1.1.0/code_rag/core/models.py +33 -0
- agent_coderag-1.1.0/code_rag/discovery/__init__.py +0 -0
- agent_coderag-1.1.0/code_rag/discovery/dependency.py +40 -0
- agent_coderag-1.1.0/code_rag/entry/__init__.py +0 -0
- agent_coderag-1.1.0/code_rag/entry/cli.py +214 -0
- agent_coderag-1.1.0/code_rag/intelligence/__init__.py +0 -0
- agent_coderag-1.1.0/code_rag/intelligence/distiller.py +80 -0
- agent_coderag-1.1.0/code_rag/intelligence/embedder.py +100 -0
- agent_coderag-1.1.0/code_rag/parsers/__init__.py +0 -0
- agent_coderag-1.1.0/code_rag/parsers/ast_index.py +81 -0
- agent_coderag-1.1.0/code_rag/storage/__init__.py +0 -0
- agent_coderag-1.1.0/code_rag/storage/duckdb_impl.py +111 -0
- agent_coderag-1.1.0/pyproject.toml +51 -0
- agent_coderag-1.1.0/setup.cfg +4 -0
- agent_coderag-1.1.0/tests/test_ast_parser.py +70 -0
- agent_coderag-1.1.0/tests/test_code_rag_simple.py +72 -0
- 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
|
+
[](https://www.python.org/downloads/)
|
|
40
|
+
[](https://opensource.org/licenses/MIT)
|
|
41
|
+
[](#-key-technologies)
|
|
42
|
+
[](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
|
+
[](https://www.python.org/downloads/)
|
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
|
7
|
+
[](#-key-technologies)
|
|
8
|
+
[](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
|
+
[](https://www.python.org/downloads/)
|
|
40
|
+
[](https://opensource.org/licenses/MIT)
|
|
41
|
+
[](#-key-technologies)
|
|
42
|
+
[](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 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
code_rag
|
|
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
|