From 88369c48de67596d34795770d1ff332ec05ee3ae Mon Sep 17 00:00:00 2001 From: offx-zinth Date: Sun, 19 Apr 2026 18:36:11 +0530 Subject: [PATCH] documentation work --- API.md | 134 ++++++++++++++++++++++++++++ ARCHITECTURE.md | 92 +++++++++++++++++++ CONTRIBUTING.md | 95 ++++++++++++++++++++ README.md | 232 ++++++++++-------------------------------------- USER_GUIDE.md | 109 +++++++++++++++++++++++ 5 files changed, 475 insertions(+), 187 deletions(-) create mode 100644 API.md create mode 100644 ARCHITECTURE.md create mode 100644 CONTRIBUTING.md create mode 100644 USER_GUIDE.md diff --git a/API.md b/API.md new file mode 100644 index 0000000..dc36a10 --- /dev/null +++ b/API.md @@ -0,0 +1,134 @@ +# API Reference: Structural Memory Protocol (SMP) + +SMP exposes a **JSON-RPC 2.0** API. All requests must be sent as POST requests to `/rpc` with `Content-Type: application/json`. + +## πŸ“‘ General Request Format +```json +{ + "jsonrpc": "2.0", + "method": "smp/method_name", + "params": { ... }, + "id": 1 +} +``` + +--- + +## πŸ” Discovery & Search + +### `smp/locate` +Finds relevant code entities using Community-Routed Graph RAG. +- **Params:** + - `query` (string): The natural language description of what to find. + - `seed_k` (int, optional): Number of initial vector seeds. Default: 3. + - `hops` (int, optional): Depth of graph traversal. Default: 2. + - `top_k` (int, optional): Number of final results. Default: 10. +- **Returns:** `LocateResponse` containing ranked results and a structural map of relationships. + +### `smp/search` +BM25-ranked full-text search across enriched metadata. +- **Params:** + - `query` (string): Keywords to search. + - `match` (string): `"all"` (AND) or `"any"` (OR). + - `filter` (object, optional): + - `node_types` (list): e.g., `["Function", "Class"]`. + - `tags` (list): e.g., `["billing"]`. + - `scope` (string): e.g., `"package:src/payments"`. + - `top_k` (int): Number of results. +- **Returns:** List of matches ranked by BM25 score. + +--- + +## πŸ›  Enrichment & Annotation + +### `smp/enrich` +Extracts static metadata (docstrings, decorators) from a specific node. +- **Params:** + - `node_id` (string): ID of the node to enrich. + - `force` (bool, optional): Re-enrich even if source hash is unchanged. +- **Returns:** Extracted metadata or status (`enriched`, `skipped`, `no_metadata`). + +### `smp/enrich/batch` +Enriches all nodes within a given scope. +- **Params:** + - `scope` (string): `"full"`, `"package:"`, or `"file:"`. + - `force` (bool): Force re-enrichment. +- **Returns:** Counts of enriched, skipped, and failed nodes. + +### `smp/enrich/stale` +Lists nodes whose source code has changed since the last enrichment. +- **Params:** `scope` (string). +- **Returns:** List of stale nodes with `current_hash` vs `enriched_hash`. + +### `smp/annotate` +Manually set metadata on a node (used for `no_metadata` nodes). +- **Params:** + - `node_id` (string). + - `description` (string). + - `tags` (list[string]). +- **Returns:** Confirmation of annotation. + +### `smp/tag` +Bulk-apply or remove tags across a scope. +- **Params:** + - `scope` (string). + - `tags` (list[string]). + - `action` (string): `"add"`, `"remove"`, or `"replace"`. + +--- + +## 🌐 Community & Architecture + +### `smp/community/detect` +Runs the Louvain algorithm to partition the codebase into Coarse (L0) and Fine (L1) communities. +- **Params:** + - `algorithm` (string): `"louvain"`. + - `relationship_types` (list): Types to consider (e.g., `["CALLS_STATIC", "IMPORTS"]`). + - `levels` (list): Resolution settings for L0 and L1. +- **Returns:** Community statistics and list of detected communities. + +### `smp/community/list` +Lists all detected communities. +- **Params:** `level` (int): `0` (coarse), `1` (fine), or omit for both. +- **Returns:** List of community objects (labels, member counts, etc.). + +### `smp/community/get` +Gets all nodes within a specific community. +- **Params:** + - `community_id` (string). + - `node_types` (list, optional). + - `include_bridges` (bool): Include edges crossing into other communities. + +### `smp/community/boundaries` +Calculates coupling strength between community pairs. +- **Params:** + - `level` (int): `0` or `1`. + - `min_coupling` (float): Filter out pairs below this weight. +- **Returns:** Coupling weights and the specific "bridge nodes" responsible for the coupling. + +--- + +## 🧠 Agent Context + +### `smp/context` +The primary method for agents to get a "mental model" of a file. +- **Params:** + - `file_path` (string). + - `scope` (string): `"edit"`, `"review"`, or `"architect"`. + - `depth` (int): Traversal depth for related patterns. +- **Returns:** A comprehensive context object containing: + - `self`: The file node. + - `imports` / `imported_by`: Dependency graph. + - `defines`: Symbols defined in the file. + - `summary`: A pre-computed structural summary (blast radius, complexity, heat score). + +--- + +## ⚠️ Error Codes + +| Code | Message | Description | +| :--- | :--- | :--- | +| `-32600` | Invalid Request | JSON parsing error. | +| `-32601` | Method not found | The requested SMP method does not exist. | +| `-32001` | Node not found | The specified `node_id` does not exist in the graph. | +| `-32002` | Conflict | Attempted to overwrite a docstring without `force: true`. | diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..251d77f --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,92 @@ +# Architecture Guide: Structural Memory Protocol (SMP) + +The Structural Memory Protocol (SMP) is designed to provide AI agents with a "programmer's mental model" of a codebase. Unlike traditional RAG, which treats code as a series of text chunks, SMP treats code as a structured graph of interrelated entities. + +## 🎯 Design Goals +- **Precision over Probability:** Replace "likely" text matches with "exact" structural relationships. +- **Architectural Awareness:** Enable agents to understand domain boundaries and module coupling. +- **Scalability:** Support massive codebases by routing queries to specific structural communities. +- **Hybrid Truth:** Combine the "what the code says" (static) with "what the code does" (runtime). + +--- + +## βš™οΈ The Ingestion Pipeline + +The ingestion pipeline transforms raw source code into a queryable knowledge graph. + +### 1. Parser (AST Extraction) +SMP uses **Tree-sitter** to perform fast, incremental parsing of multiple languages. It extracts high-level entities: +- **Nodes:** Classes, Functions, Variables, Interfaces. +- **Metadata:** Signatures, docstrings, modifiers (e.g., `async`, `export`). +- **Dependencies:** Import statements and export lists. + +### 2. Graph Builder & The Linker +The Graph Builder creates the initial nodes and relationships. The **Linker** then resolves these relationships to ensure accuracy. + +#### Static Linking (Namespaced Resolution) +To avoid ambiguity (e.g., two different files having a `save()` function), the Static Linker uses the file's `imports` as a namespace map. It traces a call to its exact origin file, marking edges as `resolved: true` or `CALLS_UNRESOLVED`. + +#### Runtime Linking (eBPF Traces) +Static analysis cannot resolve Dependency Injection or Metaprogramming. SMP uses a **Runtime Linker** that: +1. Spawns a sandboxed environment. +2. Executes the code (e.g., via a test suite). +3. Captures kernel-level function entries/exits using **eBPF**. +4. Injects `CALLS_RUNTIME` edges into the graph. + +### 3. Enricher +The Enricher attaches human-readable semantic metadata to structural nodes without using an LLM. It extracts: +- Docstrings and inline comments. +- Decorators and type annotations. +- Source hashes (to detect when a node becomes "stale" and needs re-enrichment). + +### 4. Community Detection +SMP uses the **Louvain Algorithm** via Neo4j GDS to partition the graph into two levels of structural clusters: +- **Level 0 (Coarse):** High-level architectural domains (e.g., `api_gateway`, `data_layer`). +- **Level 1 (Fine):** Detailed functional modules (e.g., `auth_oauth`, `payments_stripe`). + +Each community is assigned a **centroid embedding** (the mean of its members' embeddings), enabling efficient query routing. + +--- + +## πŸ” The Query Engine: SeedWalkEngine + +The `SeedWalkEngine` implements a 4-phase pipeline to find the most relevant code for a given query. + +### Phase 0: Route +The query embedding is compared against the **Level-1 Community Centroids** in ChromaDB. If the confidence exceeds a threshold, the search is scoped to that specific community (~200 nodes), drastically reducing noise. + +### Phase 1: Seed +A vector search is performed in ChromaDB to find the top-K "seed" nodes whose signatures or docstrings most closely match the query. + +### Phase 2: Walk +From the seeds, the engine performs a multi-hop traversal in Neo4j, following `CALLS_STATIC`, `CALLS_RUNTIME`, and `IMPORTS` edges. This captures the structural context (who calls this? what does this call?). + +### Phase 3: Rank +Nodes are ranked using a composite score: +$$\text{Score} = \alpha \cdot \text{VectorSimilarity} + \beta \cdot \text{NormalizedPageRank} + \gamma \cdot \text{HeatScore}$$ +- **Vector Similarity:** Relevance to the query. +- **PageRank:** Structural importance in the graph. +- **Heat Score:** Frequency of execution (from telemetry/runtime traces). + +### Phase 4: Assemble +The engine produces a ranked list of `RankedResult` objects and a `structural_map` (adjacency list) allowing the agent to visualize the call chain. + +--- + +## πŸ’Ύ Persistence Layer + +SMP utilizes a dual-store strategy to balance speed and structure. + +| Store | Technology | Role | Data Held | +| :--- | :--- | :--- | :--- | +| **Graph Store** | **Neo4j** | Structural Truth | Entities, Relationships, Communities, PageRank, Full-Text Index. | +| **Vector Store** | **ChromaDB** | Entry Point | Node Embeddings, Community Centroids. | + +--- + +## πŸ”Œ MCP Integration + +SMP implements the **Model Context Protocol (MCP)**. This allows it to serve as a "Codebase Memory Server" for any MCP-compatible client. Instead of the agent reading files blindly, it calls SMP tools to: +1. `locate`: Find the right starting point in a massive repo. +2. `get_context`: Get a structural summary of a file and its dependencies. +3. `assess_impact`: Find all nodes affected by a potential change. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..9f7e5a9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,95 @@ +# Contributing to SMP + +Thank you for contributing to the Structural Memory Protocol! To maintain high code quality and architectural consistency, please follow these guidelines. + +## πŸ›  Development Environment + +### Python Version +SMP requires **Python 3.11** explicitly. It uses features like `X | Y` unions and `tomllib` that are not available in older versions. + +### Setup +1. **Create a Virtual Environment:** + ```bash + python3.11 -m venv .venv + source .venv/bin/activate + ``` +2. **Install Dependencies:** + ```bash + pip install -e ".[dev]" + ``` +3. **Configure Environment:** + Copy `.env.example` to `.env` and configure your Neo4j credentials. + +--- + +## πŸ“ Coding Standards + +We enforce a strict a set of styles to ensure the codebase remains maintainable for both humans and AI agents. + +### Imports +- Every file must start with `from __future__ import annotations`. +- Group imports: `stdlib` $\rightarrow$ `third-party` $\rightarrow$ `local`, separated by blank lines. +- Use absolute imports for local modules: `from smp.core.models import GraphNode`. + +### Type Annotations +- **Strict Typing:** All function signatures must have full type annotations. +- **Modern Unions:** Use `X | Y` instead of `Optional[X]` or `Union[X, Y]`. +- **Built-in Generics:** Use `list[...]`, `dict[...]`, `set[...]` instead of `List`, `Dict`, `Set`. + +### Naming & Style +- **Classes:** `PascalCase` +- **Functions/Methods:** `snake_case` +- **Private Members:** `_leading_underscore` +- **Docstrings:** Use triple double-quotes, imperative mood, and Google style. +- **Line Length:** Max 120 characters. + +### Architectural Patterns +- **Layered Design:** `core` (models) $\rightarrow$ `engine` (logic) $\rightarrow$ `protocol` (API) $\rightarrow$ `store` (persistence). +- **Interfaces:** Use `abc.ABC` and `@abc.abstractmethod` for all store and parser interfaces. +- **Models:** Use `msgspec.Struct` for data models; prefer `frozen=True` for immutability. + +--- + +## πŸ”„ Development Workflow + +### Branching +- Use `feature/description` for new functionality. +- Use `fix/description` for bug fixes. + +### Linting & Formatting +We use **Ruff** for both linting and formatting. +```bash +# Check for lint errors +ruff check . + +# Automatically format code +ruff format . +``` + +### Type Checking +We use **Mypy** in strict mode. +```bash +mypy smp/ +``` + +### Testing +We use **pytest** with `pytest-asyncio`. +```bash +# Run all tests +pytest + +# Run a specific test file +pytest tests/test_query.py +``` + +--- + +## βœ… Pre-Commit Checklist + +Before submitting a Pull Request, ensure you have completed these four steps: +1. [ ] `ruff check .` β€” No lint errors. +2. [ ] `ruff format .` β€” Code is perfectly formatted. +3. [ ] `mypy smp/` β€” No type errors. +4. [ ] `pytest` β€” All tests pass. + +For detailed agent-specific instructions, please refer to `AGENTS.md`. diff --git a/README.md b/README.md index f025172..bfce570 100644 --- a/README.md +++ b/README.md @@ -1,241 +1,99 @@ # Structural Memory Protocol (SMP) -**High-Fidelity Codebase Intelligence for AI Agents** +**High-Fidelity Codebase Intelligence Made for AI to Handle Large Codebases Without Breaking** -Structural Memory Protocol (SMP) is a graph-based memory system that provides AI agents with a deep, structured understanding of complex codebases. Unlike RAG which treats code as flat text, SMP models code as a multi-dimensional graph of entities, relationships, and semantic meanings. +Structural Memory Protocol (SMP) provides AI agents with a "programmer's brain." While traditional RAG treats code as flat textβ€”often leading to context window overflow, hallucinations, and a loss of architectural contextβ€”SMP models code as a multi-dimensional graph of entities, relationships, and semantic meanings. -Built with **Python 3.11**, **FastAPI**, and **Neo4j**, SMP enables agents to perform precise code navigation, impact analysis, and safe refactoring β€” using static analysis (no LLM required). +By combining structural graph analysis with vector-seeded discovery, SMP allows AI agents to navigate massive codebases with precision, perform deep impact analysis, and execute safe refactorings without losing sight of the big picture. --- -## Quickstart (Docker Compose) +## πŸš€ Key Features -The fastest way to get SMP running: +* **AI-First Architecture:** Specifically designed to prevent agents from "breaking" when facing 100k+ line codebases. +* **MCP Native:** Fully supports the **Model Context Protocol (MCP)**, allowing SMP to act as a standardized memory layer for any MCP-compatible AI IDE or agent. +* **Community-Routed Graph RAG:** Uses a hybrid approachβ€”**ChromaDB** for high-speed seed discovery and **Neo4j** for structural traversalβ€”to provide exact, context-aware results. +* **Hybrid Linking:** Combines static AST analysis (Tree-sitter) with runtime execution traces (eBPF) to resolve dynamic dependencies that static analysis misses. +* **Automatic Community Detection:** Partitions the codebase into structural clusters, allowing agents to reason about domain boundaries and architecture. +* **Blast Radius Analysis:** Quantify the exact impact of a change before a single line of code is edited. +--- + +## πŸ›  Quickstart + +### 1. Docker Compose (Fastest) ```bash -# Clone the repository git clone https://github.com/your-org/smp.git cd smp - -# Copy and configure environment -cp .env.example .env -# Edit .env with your Neo4j password - -# Start all services +cp .env.example .env # Edit with your Neo4j password docker compose up -d - -# Verify health -curl http://localhost:8420/health -# Returns: {"status":"ok"} +curl http://localhost:8420/health # Returns: {"status":"ok"} ``` ---- - -## Quickstart (Manual) +### 2. Manual Installation +**Requirements:** Python 3.11, Neo4j 5.x. -### 1. Requirements -- **Python 3.11+** -- **Neo4j 5.x** (Local or AuraDB) - -### 2. Environment ```bash -# Copy the example and configure +# Environment Setup cp .env.example .env - -# Edit .env with your credentials: -# SMP_NEO4J_PASSWORD=your_neo4j_password -``` - -### 3. Install & Run -```bash -# Clone and enter the repo -git clone https://github.com/offx-zinth/smp.git -cd smp - -# Create venv with Python 3.11 python3.11 -m venv .venv source .venv/bin/activate pip install -e ".[dev]" -# Start the server -smp serve +# Start the Server +smp serve --port 8420 ``` --- -## Architecture: Manual Efficient Method (SMP V2) +## πŸ“ How it Works: The "Programmer's Brain" -SMP V2 is designed for production-grade efficiency. It relies on **static AST extraction** and **Neo4j full-text indexing** β€” no LLM or vector embeddings required. +SMP replaces flat-text retrieval with a structured pipeline: -- **Parser**: Tree-sitter extracts functions, classes, imports, and docstrings directly from AST. -- **Enricher**: Extracts docstrings, decorators, and type annotations statically. -- **Linker**: Namespaced cross-file resolution for CALLS edges. -- **Query Engine**: Neo4j full-text index (BM25) for keyword search. -- **Safety Protocol**: Session management, dry-runs, and isolated sandbox execution. +1. **Ingestion:** Tree-sitter parses source code into an AST $\rightarrow$ Graph Builder creates entities (Classes, Functions) $\rightarrow$ Linker resolves `CALLS` and `IMPORTS` edges. +2. **Enrichment:** Static metadata (docstrings, type annotations) is extracted and indexed. +3. **Vector Seeding:** ChromaDB stores embeddings of function signatures and docstrings for initial "seed" discovery. +4. **Graph Traversal:** From the seeds, the engine performs a multi-hop walk in Neo4j to capture the structural context surrounding the target code. +5. **Routing:** Community detection (Louvain) routes queries to specific architectural modules, reducing noise and increasing precision. --- -## Demo: JSON-RPC Query - -Ingest a codebase and query it: +## πŸ’» Usage +### Ingest and Query via CLI ```bash # Ingest a project smp ingest /path/to/your/project -# Query via JSON-RPC -curl -X POST http://localhost:8420/rpc \ - -H "Content-Type: application/json" \ - -d '{ - "jsonrpc": "2.0", - "method": "smp/context", - "params": { - "file_path": "smp/core/models.py", - "scope": "edit", - "depth": 2 - }, - "id": 1 - }' +# Query the intelligence layer +smp query "Where is the authentication logic handled?" ``` -**Response:** -```json -{ - "jsonrpc": "2.0", - "result": { - "self": { - "id": "smp/core/models.py::GraphNode", - "type": "Class", - "name": "GraphNode", - "signature": "class GraphNode", - "start_line": 130, - "end_line": 220 - }, - "neighbors": [ - { - "id": "smp/core/models.py::StructuralProperties", - "type": "Class", - "relationship": "CONTAINS" - }, - { - "id": "smp/core/models.py::SemanticProperties", - "type": "Class", - "relationship": "CONTAINS" - } - ], - "context": { - "file": "smp/core/models.py", - "imports": ["msgspec", "typing"], - "defines": ["GraphNode", "GraphEdge", "NodeType", "EdgeType"] - } - }, - "id": 1 -} -``` - ---- - -## Key Capabilities - -* **Graph-Augmented Retrieval:** Navigate via `CALLS`, `INHERITS`, `IMPORTS` relationships -* **Semantic Search:** Neo4j full-text index (BM25) for keyword search across docstrings/tags -* **Static Enrichment:** Docstrings, decorators, and type annotations extracted from AST -* **Impact Assessment:** Determine the "blast radius" before changes -* **Safety & Sandboxing:** Session management, dry-runs, isolated execution -* **Multi-Language:** Python and TypeScript/JavaScript via Tree-sitter - ---- - -## Architecture - -``` -smp/ -β”œβ”€β”€ smp/ -β”‚ β”œβ”€β”€ core/ # Models, logging -β”‚ β”œβ”€β”€ engine/ # Query, enricher, linker, safety -β”‚ β”œβ”€β”€ protocol/ # JSON-RPC 2.0 API -β”‚ β”‚ └── handlers/ # Modular method handlers -β”‚ β”œβ”€β”€ store/ # Neo4j (graph + full-text) -β”‚ β”œβ”€β”€ parser/ # Tree-sitter parsing -β”‚ β”œβ”€β”€ sandbox/ # Isolated execution -β”‚ β”œβ”€β”€ cli.py # CLI -β”‚ └── client.py # Python SDK -β”œβ”€β”€ tests/ # Test suite -└── .github/workflows/# CI/CD -``` - ---- - -## Usage - -### Ingest a Project -```bash -smp ingest /path/to/project --clear -``` - -### Run Server -```bash -smp serve --port 8420 --safety -``` - -### Python SDK +### Python SDK Example ```python import asyncio from smp.client import SMPClient async def main(): async with SMPClient("http://localhost:8420") as client: - # Semantic search - results = await client.locate("authentication logic") - - # Trace call graph - graph = await client.trace("src/auth.py::login", depth=5) + # Locate a feature using Community-Routed Graph RAG + results = await client.locate("user registration flow") - # Impact assessment - impact = await client.assess_impact("src/models/user.py::User") - print(f"Affects {impact['total_affected_nodes']} nodes") + # Perform impact analysis + impact = await client.assess_impact("src/auth/manager.py::authenticate") + print(f"Change affects {impact['total_affected_nodes']} nodes") asyncio.run(main()) ``` --- -## Development - -```bash -# Format -ruff format . - -# Lint -ruff check . - -# Type check -mypy smp/ - -# Test -pytest -``` - ---- - -## Troubleshooting - -| Issue | Solution | -|:---|:---| -| `sqlite3` ImportError | Install `pysqlite3-binary` | -| Neo4j Connection | Check `SMP_NEO4J_URI` and credentials in `.env` | -| SyntaxError | Use Python 3.11 | -| Enrichment Timeout | Set `SMP_ENRICHMENT=none` in `.env` | - ---- - -## Contributing - -1. Use `feature/` or `fix/` branches -2. Follow patterns in `AGENTS.md` -3. Add tests for new features -4. Run `ruff check . && ruff format . && mypy smp/ && pytest` +## πŸ“– Documentation +- [Architecture Guide](ARCHITECTURE.md) - Deep dive into the Graph RAG pipeline. +- [API Reference](API.md) - JSON-RPC 2.0 specification. +- [User Guide](USER_GUIDE.md) - Tutorials and advanced workflows. +- [Contributing](CONTRIBUTING.md) - How to extend SMP. --- -*SMP β€” Empowering agents with structural memory.* \ No newline at end of file +*SMP β€” Giving AI agents the structural memory to master any codebase.* diff --git a/USER_GUIDE.md b/USER_GUIDE.md new file mode 100644 index 0000000..ea5d784 --- /dev/null +++ b/USER_GUIDE.md @@ -0,0 +1,109 @@ +# User Guide: Using the Structural Memory Protocol (SMP) + +This guide provides practical instructions for using SMP to analyze, navigate, and maintain complex codebases. + +## 🌟 What can you do with SMP? + +SMP is designed to help you (or your AI agents) answer structural questions that traditional search cannot: +- **"Where is the logic for X implemented?"** $\rightarrow$ Use `locate` (Graph RAG). +- **"If I change this function, what else will break?"** $\rightarrow$ Use `assess_impact` (Blast Radius). +- **"How does data flow from the API to the Database?"** $\rightarrow$ Use `trace` (Call Graph). +- **"What are the main architectural modules of this project?"** $\rightarrow$ Use `community/list`. + +--- + +## ⌨️ CLI Usage + +The `smp` CLI is the fastest way to interact with the memory server. + +### 1. Ingesting a Codebase +To analyze a project, you must first ingest it into the graph. +```bash +# Basic ingestion +smp ingest /path/to/your/project + +# Ingest and clear previous data for that project +smp ingest /path/to/your/project --clear +``` + +### 2. Querying the Intelligence Layer +Once ingested, you can ask natural language questions. +```bash +smp query "Find the part of the code that handles JWT validation" +``` + +### 3. Running the Server +If you are using the SDK or an MCP client, the server must be running. +```bash +smp serve --port 8420 --safety +``` + +--- + +## 🐍 Python SDK Usage + +For integrating SMP into your own AI agents or scripts, use the `SMPClient`. + +### Basic Setup +```python +from smp.client import SMPClient +import asyncio + +async def main(): + async with SMPClient("http://localhost:8420") as client: + # Your code here + pass + +asyncio.run(main()) +``` + +### Feature Location (`locate`) +Use this to find the "seed" of a feature using semantic and structural search. +```python +results = await client.locate("payment gateway integration") +for res in results.results: + print(f"Found {res.name} in {res.file} (Score: {res.final_score})") +``` + +### Impact Analysis (`assess_impact`) +Determine the "Blast Radius" of a change to a specific function or class. +```python +impact = await client.assess_impact("src/auth/manager.py::authenticate") +print(f"Total affected nodes: {impact['total_affected_nodes']}") +# The response includes a list of all dependent functions across the repo. +``` + +### Programmer's Context (`get_context`) +Get a structural summary of a file, including who imports it and its complexity. +```python +context = await client.get_context("src/api/routes.py") +print(f"Role: {context['summary']['role']}") +print(f"Blast Radius: {context['summary']['blast_radius']}") +``` + +--- + +## πŸ”Œ Advanced Workflows + +### Using SMP with MCP +SMP natively supports the **Model Context Protocol (MCP)**. You can add SMP as a server in MCP-compatible IDEs (like Cursor or Windsurf). This allows the AI to automatically call `locate` and `get_context` as it writes code, preventing it from making assumptions about your architecture. + +### Architectural Review +Use the community tools to understand the boundaries of your system: +1. **List Communities:** `smp/community/list` to see the high-level domains. +2. **Analyze Coupling:** `smp/community/boundaries` to find "bridge nodes" that connect two different domains. If a bridge node has too many connections, it's a sign of high coupling (architectural debt). + +### Maintaining the Graph +As you change your code, the graph can become "stale." +- Use `smp/enrich/stale` to find nodes that need updating. +- Run `smp/enrich/batch` to refresh the metadata for an entire package. + +--- + +## πŸ›  Troubleshooting + +| Issue | Solution | +| :--- | :--- | +| **`SyntaxError` or `ImportError`** | Ensure you are using **Python 3.11**. | +| **Neo4j Connection Failure** | Check your `.env` file and ensure the Neo4j container is running (`docker ps`). | +| **Empty Search Results** | Ensure you ran `smp ingest` and that the project has docstrings/type annotations for the enricher to find. |