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.
Files changed (60) hide show
  1. saurix-0.1.0/.github/workflows/publish.yaml +36 -0
  2. saurix-0.1.0/.gitignore +43 -0
  3. saurix-0.1.0/LICENSE +21 -0
  4. saurix-0.1.0/PKG-INFO +186 -0
  5. saurix-0.1.0/README.md +164 -0
  6. saurix-0.1.0/demo-mcp.md +130 -0
  7. saurix-0.1.0/docs/agent-lifecycle.md +53 -0
  8. saurix-0.1.0/docs/assets/README.md +14 -0
  9. saurix-0.1.0/docs/benchmarks.md +28 -0
  10. saurix-0.1.0/main.py +5 -0
  11. saurix-0.1.0/pyproject.toml +51 -0
  12. saurix-0.1.0/saurix/__init__.py +5 -0
  13. saurix-0.1.0/saurix/agents/__init__.py +1 -0
  14. saurix-0.1.0/saurix/agents/mcp/__init__.py +3 -0
  15. saurix-0.1.0/saurix/agents/mcp/handlers.py +217 -0
  16. saurix-0.1.0/saurix/agents/mcp/schemas.py +31 -0
  17. saurix-0.1.0/saurix/agents/mcp/server.py +106 -0
  18. saurix-0.1.0/saurix/agents/mcp/utils.py +27 -0
  19. saurix-0.1.0/saurix/analysis/__init__.py +7 -0
  20. saurix-0.1.0/saurix/analysis/base.py +14 -0
  21. saurix-0.1.0/saurix/analysis/common.py +95 -0
  22. saurix-0.1.0/saurix/analysis/go_extractor.py +103 -0
  23. saurix-0.1.0/saurix/analysis/java_extractor.py +101 -0
  24. saurix-0.1.0/saurix/analysis/python_builder.py +119 -0
  25. saurix-0.1.0/saurix/analysis/python_extractor.py +186 -0
  26. saurix-0.1.0/saurix/analysis/python_utils.py +87 -0
  27. saurix-0.1.0/saurix/analysis/regex_lang.py +77 -0
  28. saurix-0.1.0/saurix/analysis/stub_extractor.py +26 -0
  29. saurix-0.1.0/saurix/analysis/tree_sitter_support.py +50 -0
  30. saurix-0.1.0/saurix/analysis/typescript_extractor.py +365 -0
  31. saurix-0.1.0/saurix/cli/__init__.py +3 -0
  32. saurix-0.1.0/saurix/cli/app.py +160 -0
  33. saurix-0.1.0/saurix/cli/commands.py +272 -0
  34. saurix-0.1.0/saurix/cli/extra_commands.py +70 -0
  35. saurix-0.1.0/saurix/cli/help.py +26 -0
  36. saurix-0.1.0/saurix/cli/render.py +102 -0
  37. saurix-0.1.0/saurix/cli/ui.py +136 -0
  38. saurix-0.1.0/saurix/core/__init__.py +5 -0
  39. saurix-0.1.0/saurix/core/cache.py +80 -0
  40. saurix-0.1.0/saurix/core/graph.py +196 -0
  41. saurix-0.1.0/saurix/core/indexing.py +263 -0
  42. saurix-0.1.0/saurix/core/models.py +29 -0
  43. saurix-0.1.0/saurix/core/source.py +75 -0
  44. saurix-0.1.0/saurix/discovery/__init__.py +4 -0
  45. saurix-0.1.0/saurix/discovery/basic.py +100 -0
  46. saurix-0.1.0/saurix/discovery/traversal.py +262 -0
  47. saurix-0.1.0/saurix/discovery/visual.py +263 -0
  48. saurix-0.1.0/saurix/exporters/__init__.py +3 -0
  49. saurix-0.1.0/saurix/exporters/graph_exports.py +86 -0
  50. saurix-0.1.0/saurix/infra/__init__.py +4 -0
  51. saurix-0.1.0/saurix/infra/config.py +42 -0
  52. saurix-0.1.0/saurix/infra/logging.py +42 -0
  53. saurix-0.1.0/scripts/benchmark_incremental.py +122 -0
  54. saurix-0.1.0/scripts/benchmark_suite.py +157 -0
  55. saurix-0.1.0/tests/__init__.py +1 -0
  56. saurix-0.1.0/tests/conftest.py +86 -0
  57. saurix-0.1.0/tests/test_extractors.py +269 -0
  58. saurix-0.1.0/tests/test_graph.py +184 -0
  59. saurix-0.1.0/tests/test_query.py +241 -0
  60. 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/*
@@ -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._
@@ -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.*
saurix-0.1.0/main.py ADDED
@@ -0,0 +1,5 @@
1
+ from saurix.cli import run
2
+
3
+
4
+ if __name__ == "__main__":
5
+ raise SystemExit(run())