saurix 0.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.
- saurix-0.1.0/.github/workflows/publish.yaml +36 -0
- saurix-0.1.0/.gitignore +43 -0
- saurix-0.1.0/LICENSE +21 -0
- saurix-0.1.0/PKG-INFO +186 -0
- saurix-0.1.0/README.md +164 -0
- saurix-0.1.0/demo-mcp.md +130 -0
- saurix-0.1.0/docs/agent-lifecycle.md +53 -0
- saurix-0.1.0/docs/assets/README.md +14 -0
- saurix-0.1.0/docs/benchmarks.md +28 -0
- saurix-0.1.0/main.py +5 -0
- saurix-0.1.0/pyproject.toml +51 -0
- saurix-0.1.0/saurix/__init__.py +5 -0
- saurix-0.1.0/saurix/agents/__init__.py +1 -0
- saurix-0.1.0/saurix/agents/mcp/__init__.py +3 -0
- saurix-0.1.0/saurix/agents/mcp/handlers.py +217 -0
- saurix-0.1.0/saurix/agents/mcp/schemas.py +31 -0
- saurix-0.1.0/saurix/agents/mcp/server.py +106 -0
- saurix-0.1.0/saurix/agents/mcp/utils.py +27 -0
- saurix-0.1.0/saurix/analysis/__init__.py +7 -0
- saurix-0.1.0/saurix/analysis/base.py +14 -0
- saurix-0.1.0/saurix/analysis/common.py +95 -0
- saurix-0.1.0/saurix/analysis/go_extractor.py +103 -0
- saurix-0.1.0/saurix/analysis/java_extractor.py +101 -0
- saurix-0.1.0/saurix/analysis/python_builder.py +119 -0
- saurix-0.1.0/saurix/analysis/python_extractor.py +186 -0
- saurix-0.1.0/saurix/analysis/python_utils.py +87 -0
- saurix-0.1.0/saurix/analysis/regex_lang.py +77 -0
- saurix-0.1.0/saurix/analysis/stub_extractor.py +26 -0
- saurix-0.1.0/saurix/analysis/tree_sitter_support.py +50 -0
- saurix-0.1.0/saurix/analysis/typescript_extractor.py +365 -0
- saurix-0.1.0/saurix/cli/__init__.py +3 -0
- saurix-0.1.0/saurix/cli/app.py +160 -0
- saurix-0.1.0/saurix/cli/commands.py +272 -0
- saurix-0.1.0/saurix/cli/extra_commands.py +70 -0
- saurix-0.1.0/saurix/cli/help.py +26 -0
- saurix-0.1.0/saurix/cli/render.py +102 -0
- saurix-0.1.0/saurix/cli/ui.py +136 -0
- saurix-0.1.0/saurix/core/__init__.py +5 -0
- saurix-0.1.0/saurix/core/cache.py +80 -0
- saurix-0.1.0/saurix/core/graph.py +196 -0
- saurix-0.1.0/saurix/core/indexing.py +263 -0
- saurix-0.1.0/saurix/core/models.py +29 -0
- saurix-0.1.0/saurix/core/source.py +75 -0
- saurix-0.1.0/saurix/discovery/__init__.py +4 -0
- saurix-0.1.0/saurix/discovery/basic.py +100 -0
- saurix-0.1.0/saurix/discovery/traversal.py +262 -0
- saurix-0.1.0/saurix/discovery/visual.py +263 -0
- saurix-0.1.0/saurix/exporters/__init__.py +3 -0
- saurix-0.1.0/saurix/exporters/graph_exports.py +86 -0
- saurix-0.1.0/saurix/infra/__init__.py +4 -0
- saurix-0.1.0/saurix/infra/config.py +42 -0
- saurix-0.1.0/saurix/infra/logging.py +42 -0
- saurix-0.1.0/scripts/benchmark_incremental.py +122 -0
- saurix-0.1.0/scripts/benchmark_suite.py +157 -0
- saurix-0.1.0/tests/__init__.py +1 -0
- saurix-0.1.0/tests/conftest.py +86 -0
- saurix-0.1.0/tests/test_extractors.py +269 -0
- saurix-0.1.0/tests/test_graph.py +184 -0
- saurix-0.1.0/tests/test_query.py +241 -0
- saurix-0.1.0/uv.lock +1172 -0
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
name: Publish Python Package
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
release:
|
|
5
|
+
types: [published]
|
|
6
|
+
|
|
7
|
+
jobs:
|
|
8
|
+
publish:
|
|
9
|
+
runs-on: ubuntu-latest
|
|
10
|
+
|
|
11
|
+
permissions:
|
|
12
|
+
id-token: write
|
|
13
|
+
|
|
14
|
+
steps:
|
|
15
|
+
- name: Checkout code
|
|
16
|
+
uses: actions/checkout@v4
|
|
17
|
+
|
|
18
|
+
- name: Set up Python
|
|
19
|
+
uses: actions/setup-python@v5
|
|
20
|
+
with:
|
|
21
|
+
python-version: "3.12"
|
|
22
|
+
|
|
23
|
+
- name: Install build tools
|
|
24
|
+
run: |
|
|
25
|
+
python -m pip install --upgrade pip
|
|
26
|
+
pip install build twine
|
|
27
|
+
|
|
28
|
+
- name: Build package
|
|
29
|
+
run: python -m build
|
|
30
|
+
|
|
31
|
+
- name: Publish to PyPI
|
|
32
|
+
env:
|
|
33
|
+
TWINE_USERNAME: __token__
|
|
34
|
+
TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
|
|
35
|
+
run: |
|
|
36
|
+
twine upload dist/*
|
saurix-0.1.0/.gitignore
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Bytecode and Python cache
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
|
|
6
|
+
# Build and packaging artifacts
|
|
7
|
+
build/
|
|
8
|
+
dist/
|
|
9
|
+
wheels/
|
|
10
|
+
*.egg-info/
|
|
11
|
+
.eggs/
|
|
12
|
+
*.egg
|
|
13
|
+
pip-wheel-metadata/
|
|
14
|
+
|
|
15
|
+
# Virtual environments
|
|
16
|
+
.venv/
|
|
17
|
+
venv/
|
|
18
|
+
env/
|
|
19
|
+
|
|
20
|
+
# Test and type-checker caches
|
|
21
|
+
.pytest_cache/
|
|
22
|
+
.mypy_cache/
|
|
23
|
+
.ruff_cache/
|
|
24
|
+
.hypothesis/
|
|
25
|
+
.coverage
|
|
26
|
+
.coverage.*
|
|
27
|
+
htmlcov/
|
|
28
|
+
|
|
29
|
+
# Tooling and editor folders
|
|
30
|
+
.python-version
|
|
31
|
+
.idea/
|
|
32
|
+
.vscode/
|
|
33
|
+
|
|
34
|
+
# Local runtime files
|
|
35
|
+
*.log
|
|
36
|
+
|
|
37
|
+
# Generated artifacts
|
|
38
|
+
tmp/
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
# Other
|
|
42
|
+
saurix.graph.json
|
|
43
|
+
saurix.html
|
saurix-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Anis M
|
|
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.
|
saurix-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: saurix
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Interactive CLI that indexes polyglot repositories into a queryable knowledge graph for AI agents
|
|
5
|
+
Project-URL: Homepage, https://github.com/anismabaziz/saurix
|
|
6
|
+
Project-URL: Repository, https://github.com/anismabaziz/saurix
|
|
7
|
+
Project-URL: Issues, https://github.com/anismabaziz/saurix/issues
|
|
8
|
+
Author-email: Anis B <anisbaziz.sub@gmail.com>
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: ai-agents,architecture,knowledge-graph,mcp,static-analysis
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
16
|
+
Requires-Python: >=3.12
|
|
17
|
+
Requires-Dist: mcp>=1.1.3
|
|
18
|
+
Requires-Dist: rich>=13.9.4
|
|
19
|
+
Requires-Dist: tree-sitter-languages>=1.10.2
|
|
20
|
+
Requires-Dist: tree-sitter<0.22,>=0.21
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
# Saurix
|
|
24
|
+
|
|
25
|
+
Saurix is an interactive knowledge graph engine that transforms complex codebases into a queryable, 3D-visualizable map. It is designed to be the **Symbolic Intelligence Layer** for modern AI coding agents.
|
|
26
|
+
|
|
27
|
+
## Why Saurix for AI Agents?
|
|
28
|
+
|
|
29
|
+
Saurix solves the "Context Window" problem for LLMs by providing a structured representation of code that is superior to keyword search:
|
|
30
|
+
|
|
31
|
+
- **Structural Awareness**: Understands `CALLS`, `INHERITS`, and `IMPORTS` relationships rather than just raw text.
|
|
32
|
+
- **Context Efficiency**: Agents can query specific subgraphs, receiving only the architectural context they need, drastically reducing token usage.
|
|
33
|
+
- **Blast Radius Analysis**: Built-in `impact` analysis allows agents to calculate the transitive side effects of a proposed change before making it.
|
|
34
|
+
- **Native MCP Support**: Built on the **Model Context Protocol**, allowing AI agents to treat the repository graph as an extension of their own memory.
|
|
35
|
+
|
|
36
|
+
See [docs/agent-lifecycle.md](docs/agent-lifecycle.md) for a step-by-step walkthrough of how an AI agent uses these capabilities.
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## 1) Core Mission
|
|
41
|
+
|
|
42
|
+
- **Knowledge Extraction**: Turn local or GitHub repositories into a structured graph of symbols and relationships.
|
|
43
|
+
- **Agent Infrastructure**: Expose high-level tools (MCP) for autonomous agents to navigate complex architectures.
|
|
44
|
+
- **Fast Navigation**: Answer questions about dependencies, callers, and impact analysis in milliseconds.
|
|
45
|
+
- **Modular Architecture**: Built for extensibility across languages and tools.
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## 2) Architecture
|
|
50
|
+
|
|
51
|
+
Saurix follows a clean, domain-driven modular structure:
|
|
52
|
+
|
|
53
|
+
```mermaid
|
|
54
|
+
flowchart TD
|
|
55
|
+
subgraph core
|
|
56
|
+
A[Indexing] --> B[Graph Store]
|
|
57
|
+
B --> C[Cache]
|
|
58
|
+
D[Source Prep] --> A
|
|
59
|
+
end
|
|
60
|
+
subgraph analysis
|
|
61
|
+
E[Extractors] --> A
|
|
62
|
+
F[Python] --> E
|
|
63
|
+
G[TypeScript] --> E
|
|
64
|
+
H[Go/Java/Stub] --> E
|
|
65
|
+
end
|
|
66
|
+
subgraph discovery
|
|
67
|
+
I[Search/Query] --> B
|
|
68
|
+
J[Traversal/Impact] --> B
|
|
69
|
+
K[Visualizer] --> B
|
|
70
|
+
end
|
|
71
|
+
subgraph agents
|
|
72
|
+
L[MCP Server] --> discovery
|
|
73
|
+
L --> core
|
|
74
|
+
end
|
|
75
|
+
subgraph cli
|
|
76
|
+
M[Interactive Shell] --> discovery
|
|
77
|
+
M --> core
|
|
78
|
+
end
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
- **`saurix.core`**: Root indexing orchestration, graph models, and incremental caching.
|
|
82
|
+
- **`saurix.analysis`**: Language-specific AST and Tree-sitter extractors.
|
|
83
|
+
- **`saurix.discovery`**: Relationship discovery, search logic, and visualization generation.
|
|
84
|
+
- **`saurix.agents.mcp`**: Tooling interface for AI agents.
|
|
85
|
+
- **`saurix.infra`**: Centralized configuration and structured logging.
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## Setup & Installation
|
|
90
|
+
|
|
91
|
+
Choose the path that fits your workflow:
|
|
92
|
+
|
|
93
|
+
### A) The "Power User" Path (Global & Project-Native)
|
|
94
|
+
Recommended for using Saurix as a permanent tool for your own development projects.
|
|
95
|
+
|
|
96
|
+
1. **Install Globally**:
|
|
97
|
+
```bash
|
|
98
|
+
pip install -e .
|
|
99
|
+
```
|
|
100
|
+
2. **Initialize Any Project**:
|
|
101
|
+
```bash
|
|
102
|
+
cd /path/to/your/project
|
|
103
|
+
saurix init
|
|
104
|
+
```
|
|
105
|
+
*This command indexes your project, creates a local 3D dashboard (`saurix.html`), and generates your MCP config in one step.*
|
|
106
|
+
|
|
107
|
+
### B) The "Developer" Path (Standalone)
|
|
108
|
+
Recommended if you want to contribute to Saurix or run it in isolation using `uv`.
|
|
109
|
+
|
|
110
|
+
1. **Clone & Setup**:
|
|
111
|
+
```bash
|
|
112
|
+
git clone https://github.com/anismabaziz/saurix.git
|
|
113
|
+
cd saurix
|
|
114
|
+
uv sync
|
|
115
|
+
```
|
|
116
|
+
2. **Run via uv**:
|
|
117
|
+
```bash
|
|
118
|
+
uv run saurix
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### Running the MCP Server
|
|
122
|
+
|
|
123
|
+
Expose graph tools to AI agents (e.g., Claude Desktop, Cursor):
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
saurix-mcp
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## 4) Interactive Commands
|
|
132
|
+
|
|
133
|
+
| Command | Description |
|
|
134
|
+
| ---------------- | ----------------------------------------------------- |
|
|
135
|
+
| `init` | Zero-config setup for the current project |
|
|
136
|
+
| `index <source>` | Index a local path or GitHub URL |
|
|
137
|
+
| `stats` | Show graph statistics and extraction coverage |
|
|
138
|
+
| `find <query>` | Fuzzy search symbols by name or ID |
|
|
139
|
+
| `callers <sym>` | List symbols calling the target |
|
|
140
|
+
| `path <A> <B>` | Find shortest directed path between two symbols |
|
|
141
|
+
| `impact <sym>` | Estimate blast radius of a change |
|
|
142
|
+
| `visual` | Generate a hybrid 2D/3D knowledge graph visualization |
|
|
143
|
+
| `export` | Export to GraphML or Neo4j CSV |
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## 5) AI Agent Integration (MCP)
|
|
148
|
+
|
|
149
|
+
Saurix is optimized for agentic workflows. It exposes tools that help agents understand:
|
|
150
|
+
|
|
151
|
+
1. **Context Discovery**: `find_symbol` and `related_files`.
|
|
152
|
+
2. **Behavioral Mapping**: `callers` and `path_between`.
|
|
153
|
+
3. **Risk Assessment**: `impact_of_symbol`.
|
|
154
|
+
|
|
155
|
+
Configure your agent with the `saurix-mcp` entry point. Once configured, the AI client (e.g., Claude Desktop) will automatically manage the server lifecycle—starting it in the background when needed and stopping it when the app closes. No manual terminal execution is required.
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## 6) Development
|
|
160
|
+
|
|
161
|
+
### Running Tests
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
uv run pytest
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Testing the MCP Server
|
|
168
|
+
|
|
169
|
+
You can test the MCP integration without a full IDE using the **MCP Inspector**:
|
|
170
|
+
|
|
171
|
+
1. **Install the Inspector**: `npm install -g @modelcontextprotocol/inspector`
|
|
172
|
+
2. **Run the Server**: `npx @modelcontextprotocol/inspector uv run saurix-mcp`
|
|
173
|
+
3. **Interact**: Open `http://localhost:5173`, click **Connect**, and use the **Call Tool** tab.
|
|
174
|
+
|
|
175
|
+
For step-by-step setup (Claude Desktop, Cursor, OpenCode), simply run `saurix init` in your project folder.
|
|
176
|
+
|
|
177
|
+
### Roadmap
|
|
178
|
+
|
|
179
|
+
- [ ] **Rich Cross-Language Resolution**: Better linking across monorepos.
|
|
180
|
+
- [ ] **LLM Integration**: Optional LLM-powered relationship refinement.
|
|
181
|
+
- [ ] **Remote Store**: Support for remote graph databases (Neo4j/Memgraph).
|
|
182
|
+
- [ ] **Dynamic Language Support**: Plug-and-play extractor modules.
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
_Saurix is built for the era of autonomous coding._
|
saurix-0.1.0/README.md
ADDED
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
# Saurix
|
|
2
|
+
|
|
3
|
+
Saurix is an interactive knowledge graph engine that transforms complex codebases into a queryable, 3D-visualizable map. It is designed to be the **Symbolic Intelligence Layer** for modern AI coding agents.
|
|
4
|
+
|
|
5
|
+
## Why Saurix for AI Agents?
|
|
6
|
+
|
|
7
|
+
Saurix solves the "Context Window" problem for LLMs by providing a structured representation of code that is superior to keyword search:
|
|
8
|
+
|
|
9
|
+
- **Structural Awareness**: Understands `CALLS`, `INHERITS`, and `IMPORTS` relationships rather than just raw text.
|
|
10
|
+
- **Context Efficiency**: Agents can query specific subgraphs, receiving only the architectural context they need, drastically reducing token usage.
|
|
11
|
+
- **Blast Radius Analysis**: Built-in `impact` analysis allows agents to calculate the transitive side effects of a proposed change before making it.
|
|
12
|
+
- **Native MCP Support**: Built on the **Model Context Protocol**, allowing AI agents to treat the repository graph as an extension of their own memory.
|
|
13
|
+
|
|
14
|
+
See [docs/agent-lifecycle.md](docs/agent-lifecycle.md) for a step-by-step walkthrough of how an AI agent uses these capabilities.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## 1) Core Mission
|
|
19
|
+
|
|
20
|
+
- **Knowledge Extraction**: Turn local or GitHub repositories into a structured graph of symbols and relationships.
|
|
21
|
+
- **Agent Infrastructure**: Expose high-level tools (MCP) for autonomous agents to navigate complex architectures.
|
|
22
|
+
- **Fast Navigation**: Answer questions about dependencies, callers, and impact analysis in milliseconds.
|
|
23
|
+
- **Modular Architecture**: Built for extensibility across languages and tools.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## 2) Architecture
|
|
28
|
+
|
|
29
|
+
Saurix follows a clean, domain-driven modular structure:
|
|
30
|
+
|
|
31
|
+
```mermaid
|
|
32
|
+
flowchart TD
|
|
33
|
+
subgraph core
|
|
34
|
+
A[Indexing] --> B[Graph Store]
|
|
35
|
+
B --> C[Cache]
|
|
36
|
+
D[Source Prep] --> A
|
|
37
|
+
end
|
|
38
|
+
subgraph analysis
|
|
39
|
+
E[Extractors] --> A
|
|
40
|
+
F[Python] --> E
|
|
41
|
+
G[TypeScript] --> E
|
|
42
|
+
H[Go/Java/Stub] --> E
|
|
43
|
+
end
|
|
44
|
+
subgraph discovery
|
|
45
|
+
I[Search/Query] --> B
|
|
46
|
+
J[Traversal/Impact] --> B
|
|
47
|
+
K[Visualizer] --> B
|
|
48
|
+
end
|
|
49
|
+
subgraph agents
|
|
50
|
+
L[MCP Server] --> discovery
|
|
51
|
+
L --> core
|
|
52
|
+
end
|
|
53
|
+
subgraph cli
|
|
54
|
+
M[Interactive Shell] --> discovery
|
|
55
|
+
M --> core
|
|
56
|
+
end
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
- **`saurix.core`**: Root indexing orchestration, graph models, and incremental caching.
|
|
60
|
+
- **`saurix.analysis`**: Language-specific AST and Tree-sitter extractors.
|
|
61
|
+
- **`saurix.discovery`**: Relationship discovery, search logic, and visualization generation.
|
|
62
|
+
- **`saurix.agents.mcp`**: Tooling interface for AI agents.
|
|
63
|
+
- **`saurix.infra`**: Centralized configuration and structured logging.
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## Setup & Installation
|
|
68
|
+
|
|
69
|
+
Choose the path that fits your workflow:
|
|
70
|
+
|
|
71
|
+
### A) The "Power User" Path (Global & Project-Native)
|
|
72
|
+
Recommended for using Saurix as a permanent tool for your own development projects.
|
|
73
|
+
|
|
74
|
+
1. **Install Globally**:
|
|
75
|
+
```bash
|
|
76
|
+
pip install -e .
|
|
77
|
+
```
|
|
78
|
+
2. **Initialize Any Project**:
|
|
79
|
+
```bash
|
|
80
|
+
cd /path/to/your/project
|
|
81
|
+
saurix init
|
|
82
|
+
```
|
|
83
|
+
*This command indexes your project, creates a local 3D dashboard (`saurix.html`), and generates your MCP config in one step.*
|
|
84
|
+
|
|
85
|
+
### B) The "Developer" Path (Standalone)
|
|
86
|
+
Recommended if you want to contribute to Saurix or run it in isolation using `uv`.
|
|
87
|
+
|
|
88
|
+
1. **Clone & Setup**:
|
|
89
|
+
```bash
|
|
90
|
+
git clone https://github.com/anismabaziz/saurix.git
|
|
91
|
+
cd saurix
|
|
92
|
+
uv sync
|
|
93
|
+
```
|
|
94
|
+
2. **Run via uv**:
|
|
95
|
+
```bash
|
|
96
|
+
uv run saurix
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Running the MCP Server
|
|
100
|
+
|
|
101
|
+
Expose graph tools to AI agents (e.g., Claude Desktop, Cursor):
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
saurix-mcp
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## 4) Interactive Commands
|
|
110
|
+
|
|
111
|
+
| Command | Description |
|
|
112
|
+
| ---------------- | ----------------------------------------------------- |
|
|
113
|
+
| `init` | Zero-config setup for the current project |
|
|
114
|
+
| `index <source>` | Index a local path or GitHub URL |
|
|
115
|
+
| `stats` | Show graph statistics and extraction coverage |
|
|
116
|
+
| `find <query>` | Fuzzy search symbols by name or ID |
|
|
117
|
+
| `callers <sym>` | List symbols calling the target |
|
|
118
|
+
| `path <A> <B>` | Find shortest directed path between two symbols |
|
|
119
|
+
| `impact <sym>` | Estimate blast radius of a change |
|
|
120
|
+
| `visual` | Generate a hybrid 2D/3D knowledge graph visualization |
|
|
121
|
+
| `export` | Export to GraphML or Neo4j CSV |
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## 5) AI Agent Integration (MCP)
|
|
126
|
+
|
|
127
|
+
Saurix is optimized for agentic workflows. It exposes tools that help agents understand:
|
|
128
|
+
|
|
129
|
+
1. **Context Discovery**: `find_symbol` and `related_files`.
|
|
130
|
+
2. **Behavioral Mapping**: `callers` and `path_between`.
|
|
131
|
+
3. **Risk Assessment**: `impact_of_symbol`.
|
|
132
|
+
|
|
133
|
+
Configure your agent with the `saurix-mcp` entry point. Once configured, the AI client (e.g., Claude Desktop) will automatically manage the server lifecycle—starting it in the background when needed and stopping it when the app closes. No manual terminal execution is required.
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## 6) Development
|
|
138
|
+
|
|
139
|
+
### Running Tests
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
uv run pytest
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### Testing the MCP Server
|
|
146
|
+
|
|
147
|
+
You can test the MCP integration without a full IDE using the **MCP Inspector**:
|
|
148
|
+
|
|
149
|
+
1. **Install the Inspector**: `npm install -g @modelcontextprotocol/inspector`
|
|
150
|
+
2. **Run the Server**: `npx @modelcontextprotocol/inspector uv run saurix-mcp`
|
|
151
|
+
3. **Interact**: Open `http://localhost:5173`, click **Connect**, and use the **Call Tool** tab.
|
|
152
|
+
|
|
153
|
+
For step-by-step setup (Claude Desktop, Cursor, OpenCode), simply run `saurix init` in your project folder.
|
|
154
|
+
|
|
155
|
+
### Roadmap
|
|
156
|
+
|
|
157
|
+
- [ ] **Rich Cross-Language Resolution**: Better linking across monorepos.
|
|
158
|
+
- [ ] **LLM Integration**: Optional LLM-powered relationship refinement.
|
|
159
|
+
- [ ] **Remote Store**: Support for remote graph databases (Neo4j/Memgraph).
|
|
160
|
+
- [ ] **Dynamic Language Support**: Plug-and-play extractor modules.
|
|
161
|
+
|
|
162
|
+
---
|
|
163
|
+
|
|
164
|
+
_Saurix is built for the era of autonomous coding._
|
saurix-0.1.0/demo-mcp.md
ADDED
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# MCP Demo (Saurix)
|
|
2
|
+
|
|
3
|
+
This demo shows a simple MCP workflow with 5 tool calls and expected response shapes.
|
|
4
|
+
|
|
5
|
+
## Prerequisites
|
|
6
|
+
|
|
7
|
+
- Run `uv sync`
|
|
8
|
+
- Start MCP server: `saurix-mcp`
|
|
9
|
+
|
|
10
|
+
## 1) Index a repo
|
|
11
|
+
|
|
12
|
+
Tool call:
|
|
13
|
+
|
|
14
|
+
```json
|
|
15
|
+
{
|
|
16
|
+
"tool": "index_repo",
|
|
17
|
+
"arguments": {
|
|
18
|
+
"source": "https://github.com/anismabaziz/saurix"
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Expected response shape:
|
|
24
|
+
|
|
25
|
+
```json
|
|
26
|
+
{
|
|
27
|
+
"ok": true,
|
|
28
|
+
"data": {
|
|
29
|
+
"graph_path": ".../tmp/saurix.graph.json",
|
|
30
|
+
"source_kind": "github:anismabaziz/saurix",
|
|
31
|
+
"scanned_files": 30,
|
|
32
|
+
"indexed_files": 30,
|
|
33
|
+
"stats": { "nodes": 0, "edges": 0 }
|
|
34
|
+
},
|
|
35
|
+
"meta": { "duration_ms": 0 }
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## 2) Read graph stats
|
|
40
|
+
|
|
41
|
+
Tool call:
|
|
42
|
+
|
|
43
|
+
```json
|
|
44
|
+
{
|
|
45
|
+
"tool": "stats",
|
|
46
|
+
"arguments": {
|
|
47
|
+
"graph": "tmp/saurix.graph.json"
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Expected response includes:
|
|
53
|
+
|
|
54
|
+
- `confidence_counts`
|
|
55
|
+
- `confidence_percentages`
|
|
56
|
+
- `extraction_coverage`
|
|
57
|
+
|
|
58
|
+
## 3) Find a symbol
|
|
59
|
+
|
|
60
|
+
Tool call:
|
|
61
|
+
|
|
62
|
+
```json
|
|
63
|
+
{
|
|
64
|
+
"tool": "find_symbol",
|
|
65
|
+
"arguments": {
|
|
66
|
+
"graph": "tmp/saurix.graph.json",
|
|
67
|
+
"query": "find_symbol",
|
|
68
|
+
"limit": 10
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Expected response:
|
|
74
|
+
|
|
75
|
+
```json
|
|
76
|
+
{
|
|
77
|
+
"ok": true,
|
|
78
|
+
"data": [
|
|
79
|
+
{
|
|
80
|
+
"id": "python://saurix.query.basic:find_symbol",
|
|
81
|
+
"type": "function",
|
|
82
|
+
"name": "find_symbol",
|
|
83
|
+
"file": "saurix/query/basic.py"
|
|
84
|
+
}
|
|
85
|
+
],
|
|
86
|
+
"meta": { "count": 1, "duration_ms": 0 }
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## 4) Find path between symbols
|
|
91
|
+
|
|
92
|
+
Tool call:
|
|
93
|
+
|
|
94
|
+
```json
|
|
95
|
+
{
|
|
96
|
+
"tool": "path_between",
|
|
97
|
+
"arguments": {
|
|
98
|
+
"graph": "tmp/saurix.graph.json",
|
|
99
|
+
"source": "python://saurix.cli.commands:cmd_find",
|
|
100
|
+
"target": "python://saurix.query.basic:find_symbol",
|
|
101
|
+
"max_depth": 12
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Expected response:
|
|
107
|
+
|
|
108
|
+
- `ok: true`
|
|
109
|
+
- `data`: list of path steps (`step`, `edge`, `id`, `type`, `name`)
|
|
110
|
+
|
|
111
|
+
## 5) Impact analysis
|
|
112
|
+
|
|
113
|
+
Tool call:
|
|
114
|
+
|
|
115
|
+
```json
|
|
116
|
+
{
|
|
117
|
+
"tool": "impact_of_symbol",
|
|
118
|
+
"arguments": {
|
|
119
|
+
"graph": "tmp/saurix.graph.json",
|
|
120
|
+
"symbol": "python://saurix.query.basic:find_symbol",
|
|
121
|
+
"depth": 3,
|
|
122
|
+
"limit": 50
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Expected response:
|
|
128
|
+
|
|
129
|
+
- `ok: true`
|
|
130
|
+
- `data`: reverse-neighborhood rows (`distance`, `via`, `id`, `type`, `name`, `file`)
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# The Lifecycle of an AI Agent using Saurix
|
|
2
|
+
|
|
3
|
+
This walkthrough illustrates how an AI Agent (like Claude or Antigravity) uses Saurix to solve a real-world task: **"Modify the data persistence layer to support PostgreSQL."**
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
### Phase 0: Triggering a Smart Workflow (Optional)
|
|
8
|
+
Before the agent even looks at the code, the user can jumpstart the process using a pre-defined **MCP Prompt**.
|
|
9
|
+
- **User Action**: Selects the `repo_onboarding` prompt.
|
|
10
|
+
- **Agent Instruction**: "You are an expert architect. Index the repo, get stats, and explain the entry points."
|
|
11
|
+
- **Benefit**: The agent is immediately put into a "High-Level Architecture" mindset without manual prompting.
|
|
12
|
+
|
|
13
|
+
### Phase 1: Environmental Awareness (The Bird's Eye View)
|
|
14
|
+
The agent is dropped into a 50,000-line repository it has never seen.
|
|
15
|
+
- **Agent Action**: Calls `saurix.stats()`.
|
|
16
|
+
- **Knowledge Gained**: "Okay, this is 80% Python with 450 nodes. It's a medium-sized OO project."
|
|
17
|
+
- **Next Step**: The agent uses `find_symbol(query="persistence")` to locate the `DatabaseStore` class in `core/db.py`.
|
|
18
|
+
- **Benefit**: The agent doesn't have to guess where the "important" files are.
|
|
19
|
+
|
|
20
|
+
### Phase 2: Navigation (Finding the Entry Point)
|
|
21
|
+
The agent needs to find where the database logic is actually used.
|
|
22
|
+
- **Agent Action**: Calls `saurix.find_symbol(query="Database")`.
|
|
23
|
+
- **Knowledge Gained**: It finds `core.persistence:SQLiteStore` and `core.persistence:BaseStore`.
|
|
24
|
+
- **Benefit**: Instant pinpointing of relevant classes without reading irrelevant "database" mentions in documentation or logs.
|
|
25
|
+
|
|
26
|
+
### Phase 3: Relationship Mapping (Connecting the Dots)
|
|
27
|
+
The agent needs to know how the rest of the app interacts with the database.
|
|
28
|
+
- **Agent Action**: Calls `saurix.path_between(source="cli.app:main", target="core.persistence:SQLiteStore")`.
|
|
29
|
+
- **Knowledge Gained**: "The flow is: `main` -> `CommandDispatcher` -> `RepositoryIndexer` -> `GraphStore` -> `SQLiteStore`."
|
|
30
|
+
- **Benefit**: The agent now understands the **Data Flow** of the entire application across 5 different files.
|
|
31
|
+
|
|
32
|
+
### Phase 4: Risk Assessment (The "Blast Radius")
|
|
33
|
+
The agent is about to change the `BaseStore` interface to support PostgreSQL.
|
|
34
|
+
- **Agent Action**: Calls `saurix.impact_of_symbol(symbol="core.persistence:BaseStore")`.
|
|
35
|
+
- **Knowledge Gained**: "Wait, if I change this interface, I will break 12 different tests and 3 exporters I didn't know existed."
|
|
36
|
+
- **Benefit**: The agent identifies potential regressions **before** it even starts writing code.
|
|
37
|
+
|
|
38
|
+
### Phase 5: Implementation & Verification
|
|
39
|
+
The agent writes the new `PostgresStore` class.
|
|
40
|
+
- **Agent Action**: Calls `saurix.index_repo(source=".")`.
|
|
41
|
+
- **Knowledge Gained**: The agent verifies that the new class is correctly "seen" by the graph and that its inheritance edges to `BaseStore` are active.
|
|
42
|
+
- **Benefit**: Final structural verification that the new code is correctly integrated into the system.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
### Comparison: With vs. Without Saurix
|
|
47
|
+
|
|
48
|
+
| Feature | Without Saurix | With Saurix |
|
|
49
|
+
| :--- | :--- | :--- |
|
|
50
|
+
| **Discovery** | Reads 20 files (Slow, Expensive) | `stats()` + `find()` (Instant, Cheap) |
|
|
51
|
+
| **Data Flow** | Manually traces imports (Error-prone) | `path_between()` (Absolute precision) |
|
|
52
|
+
| **Safety** | "Guess" what might break | `impact()` (Transitive dependencies) |
|
|
53
|
+
| **Confidence** | Low (Missing context) | High (Full architectural map) |
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# Demo Assets Placeholder
|
|
2
|
+
|
|
3
|
+
Add your screenshots/GIF here and keep these filenames for README references:
|
|
4
|
+
|
|
5
|
+
- `cli-workflow.png`
|
|
6
|
+
- `visual-workflow.png`
|
|
7
|
+
- `mcp-workflow.png`
|
|
8
|
+
- `saurix-demo.gif`
|
|
9
|
+
|
|
10
|
+
Suggested capture flow:
|
|
11
|
+
|
|
12
|
+
1. CLI: `index`, `stats`, `find`, `impact`
|
|
13
|
+
2. Visual UI: search + edge filters + path highlight
|
|
14
|
+
3. MCP: `index_repo` -> `find_symbol` -> `path_between` -> `impact_of_symbol`
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Saurix Performance Benchmarks
|
|
2
|
+
|
|
3
|
+
This report is automatically generated by `scripts/benchmark_suite.py`.
|
|
4
|
+
|
|
5
|
+
## Indexing & Storage Performance
|
|
6
|
+
Comparison of cold-start indexing vs. incremental re-indexing, and resulting graph size.
|
|
7
|
+
|
|
8
|
+
| Repository | Language | Files | Full Index | Incremental | Speedup | Graph Size |
|
|
9
|
+
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
|
|
10
|
+
| `pallets/flask` | python | 83 | 0.22s | 0.10s | 2.3x | 2211.7 KB |
|
|
11
|
+
| `axios/axios` | typescript | 219 | 0.16s | 0.05s | 3.1x | 546.3 KB |
|
|
12
|
+
| `django/django` | python | 3015 | 9.38s | 4.93s | 1.9x | 103386.3 KB |
|
|
13
|
+
| `facebook/react` | typescript | 4366 | 8.82s | 0.90s | 9.7x | 10263.7 KB |
|
|
14
|
+
| `kubernetes/kubernetes` | go | 17015 | 104.13s | 30.34s | 3.4x | 484022.7 KB |
|
|
15
|
+
|
|
16
|
+
## Query & Graph Complexity
|
|
17
|
+
Measurements of internal graph density and response time for complex symbolic queries.
|
|
18
|
+
|
|
19
|
+
| Repository | Nodes | Edges | Density | Impact Query (D3) |
|
|
20
|
+
| :--- | :--- | :--- | :--- | :--- |
|
|
21
|
+
| `pallets/flask` | 2095 | 5340 | 2.55 | 0.0 ms |
|
|
22
|
+
| `axios/axios` | 456 | 1259 | 2.76 | 0.0 ms |
|
|
23
|
+
| `django/django` | 64431 | 238181 | 3.70 | 0.0 ms |
|
|
24
|
+
| `facebook/react` | 8218 | 16436 | 2.00 | 0.1 ms |
|
|
25
|
+
| `kubernetes/kubernetes` | 124795 | 1278966 | 10.25 | 0.0 ms |
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
*Benchmarks performed on: macOS / Apple Silicon.*
|