documentation work#26
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive documentation suite for the Structural Memory Protocol (SMP), including an API reference, architecture guide, contributing guidelines, and a user guide, while also overhauling the README to emphasize its AI-first design and MCP integration. The review identifies several critical discrepancies where the documentation does not align with the current codebase, such as missing documentation for the smp/impact and smp/trace methods, incorrect parameter and return structures for smp/locate and smp/search, and the mention of a non-existent smp query CLI command. Additionally, the architecture guide incorrectly attributes the Louvain algorithm implementation to Neo4j GDS instead of the custom Python implementation used in the code.
|
|
||
| --- | ||
|
|
||
| ## 🔍 Discovery & Search |
There was a problem hiding this comment.
This section is missing documentation for several implemented methods found in smp/protocol/handlers/query.py, specifically smp/impact (handled by ImpactHandler) and smp/trace (handled by TraceHandler). These should be included to provide a complete API reference.
| - `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. |
There was a problem hiding this comment.
There are several discrepancies between the documentation and the implementation of smp/locate:
- The parameters
seed_kandhopsare listed as optional, but theSeedWalkEngine.locatemethod (smp/engine/seed_walk.py:347) does not accept them; they are hardcoded to defaults inside the method. - The return type is documented as
LocateResponse, but theLocateHandler(smp/protocol/handlers/query.py:108) wraps the result in a{"matches": ...}object. SeedWalkEngine.locatereturns a list containing the response dictionary, which results in a nested structure:{"matches": [{...}]}.
| - `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. |
There was a problem hiding this comment.
The return value for smp/search is documented as a "List of matches", but the implementation in DefaultQueryEngine.search (smp/engine/query.py:448) returns a dictionary: {"matches": results, "total": len(results)}. The documentation should be updated to reflect this structure.
| - 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: |
There was a problem hiding this comment.
The documentation states that the Louvain algorithm is executed via Neo4j GDS. However, the implementation in smp/engine/community.py (lines 241-288) is a custom Python-based Louvain implementation. This should be corrected to accurately describe the system architecture.
| "id": 1 | ||
| }' | ||
| # Query the intelligence layer | ||
| smp query "Where is the authentication logic handled?" |
There was a problem hiding this comment.
The smp query command is documented here, but it is not implemented in the CLI (smp/cli.py). The available subcommands are ingest, serve, run, ps, stop, and logs. Please update the documentation to use a valid command or implement the missing functionality.
| ### 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" |
There was a problem hiding this comment.
The smp query command is not supported by the current CLI implementation. This example should be updated to reflect the actual available commands or the use of the Python SDK.
1 participant
No description provided.