axiom-graph 1.0.0__tar.gz

axiom_graph-1.0.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.1
+Name: axiom-graph
+Version: 1.0.0
+Summary: Project knowledge indexer for AI agents — scans code, tracks documentation staleness, and serves a knowledge graph to AI agents via MCP
+License: MIT
+Keywords: indexer,documentation,staleness,knowledge-graph,mcp,ai-agents
+Author: ddpoe
+Author-email: dap182@pitt.edu
+Requires-Python: >=3.10
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Provides-Extra: js
+Provides-Extra: semantic
+Provides-Extra: semantic-torch
+Provides-Extra: viz
+Requires-Dist: click (>=8.0)
+Requires-Dist: docstring-parser (>=0.15)
+Requires-Dist: fastapi (>=0.100) ; extra == "viz"
+Requires-Dist: fastembed (>=0.3) ; (python_version >= "3.10" and python_version < "3.13") and (extra == "semantic")
+Requires-Dist: markdown-it-py (>=3.0)
+Requires-Dist: mcp[cli] (>=1.0)
+Requires-Dist: onnxruntime (>=1.17,<1.20) ; (python_version >= "3.10" and python_version < "3.13") and (extra == "semantic")
+Requires-Dist: pyyaml (>=6.0)
+Requires-Dist: sentence-transformers (>=2.0) ; extra == "semantic-torch"
+Requires-Dist: sqlite-vec (>=0.1.1) ; extra == "semantic" or extra == "semantic-torch"
+Requires-Dist: tomli (>=2.0) ; python_version < "3.11"
+Requires-Dist: tree-sitter (>=0.25.2,<0.26.0) ; extra == "js"
+Requires-Dist: tree-sitter-javascript (>=0.25.0,<0.26.0) ; extra == "js"
+Requires-Dist: tree-sitter-typescript (>=0.23.2,<0.24.0) ; extra == "js"
+Requires-Dist: uvicorn (>=0.20) ; extra == "viz"
+Description-Content-Type: text/markdown
+
+# Cortex
+
+A project knowledge indexer that scans your codebase, builds a structured graph of modules, functions, classes, and documentation, and tracks when docs drift from the code they describe. Designed for AI-assisted development -- cortex gives agents structured access to your project through the Model Context Protocol (MCP).
+
+## Quick Start
+
+```bash
+pip install cortex[viz]
+
+cortex init /path/to/your/project    # scan and build the index
+cortex check /path/to/your/project   # see what's stale
+cortex viz /path/to/your/project     # launch the dashboard
+```
+
+## Features
+
+- **Knowledge graph** -- indexes Python (and JS/TS via tree-sitter) into nodes and edges: functions, modules, classes, docs, tests, and their relationships
+- **Staleness detection** -- two-dimensional tracking (own content changes + linked dependency changes) with transitive propagation through doc chains
+- **MCP server** -- 29 tools for AI agents to search, read, navigate, and modify the index over the Model Context Protocol
+- **Viz dashboard** -- interactive browser UI with graph view, list view, doc manager, workflow explorer, and detail panels
+- **DocJSON** -- structured documentation format that links sections to code nodes, enabling automated drift detection
+- **dFlow integration** -- optional workflow/task decorators with step markers, indexed alongside code
+- **CI gate** -- `cortex check --fail-on any` in GitHub Actions prevents stale docs from merging
+
+## MCP Server Setup
+
+The MCP server is how AI agents interact with cortex. It uses stdio transport.
+
+### Claude Code
+
+Create `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "cortex": {
+      "type": "stdio",
+      "command": "/path/to/your/venv/bin/python",
+      "args": ["-m", "cortex.mcp_server"],
+      "env": {
+        "CORTEX_LOG_LEVEL": "INFO"
+      }
+    }
+  }
+}
+```
+
+### VS Code (Copilot / Continue)
+
+Add to `.vscode/settings.json`:
+
+```json
+{
+  "mcp.servers": {
+    "cortex": {
+      "command": "/path/to/your/venv/bin/python",
+      "args": ["-m", "cortex.mcp_server"],
+      "env": {
+        "CORTEX_LOG_LEVEL": "INFO"
+      }
+    }
+  }
+}
+```
+
+### Any MCP client
+
+The entry point is `cortex-mcp` (installed as a console script) or `python -m cortex.mcp_server`. Both use stdio transport -- JSON-RPC on stdin/stdout, logs on stderr.
+
+### Logging
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CORTEX_LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+| `CORTEX_LOG_FILE` | *(none)* | Path to a rotating log file (5 MB max, 2 backups) |
+
+Set `CORTEX_LOG_LEVEL=DEBUG` to see tool entry/exit timing, SQL queries, and build details. Logs always go to stderr; `CORTEX_LOG_FILE` adds a file copy.
+
+## Documentation
+
+Full documentation is available as a consumer docs site:
+
+```bash
+pip install cortex[viz]              # includes mkdocs-material
+cortex render-site /path/to/project  # generates site/ directory
+cortex render-site /path/to/project --serve  # live preview at localhost:8000
+```
+
+Or read the DocJSON source files directly in `docs/consumer/`:
+
+- [Getting Started](docs/consumer/getting-started.json)
+- [Core Concepts](docs/consumer/core-concepts.json)
+- [Staleness Engine](docs/consumer/staleness.json)
+- [Documentation System](docs/consumer/docs-system.json)
+- [dFlow Integration](docs/consumer/dflow.json)
+- [MCP Server](docs/consumer/mcp-server.json)
+- [MCP Setup & Observability](docs/consumer/mcp-setup.json)
+- [Viz Dashboard](docs/consumer/viz.json)
+- [Configuration](docs/consumer/configuration.json)
+
+## License
+
+MIT
+

axiom_graph-1.0.0/README.md

@@ -0,0 +1,103 @@
+# Cortex
+
+A project knowledge indexer that scans your codebase, builds a structured graph of modules, functions, classes, and documentation, and tracks when docs drift from the code they describe. Designed for AI-assisted development -- cortex gives agents structured access to your project through the Model Context Protocol (MCP).
+
+## Quick Start
+
+```bash
+pip install cortex[viz]
+
+cortex init /path/to/your/project    # scan and build the index
+cortex check /path/to/your/project   # see what's stale
+cortex viz /path/to/your/project     # launch the dashboard
+```
+
+## Features
+
+- **Knowledge graph** -- indexes Python (and JS/TS via tree-sitter) into nodes and edges: functions, modules, classes, docs, tests, and their relationships
+- **Staleness detection** -- two-dimensional tracking (own content changes + linked dependency changes) with transitive propagation through doc chains
+- **MCP server** -- 29 tools for AI agents to search, read, navigate, and modify the index over the Model Context Protocol
+- **Viz dashboard** -- interactive browser UI with graph view, list view, doc manager, workflow explorer, and detail panels
+- **DocJSON** -- structured documentation format that links sections to code nodes, enabling automated drift detection
+- **dFlow integration** -- optional workflow/task decorators with step markers, indexed alongside code
+- **CI gate** -- `cortex check --fail-on any` in GitHub Actions prevents stale docs from merging
+
+## MCP Server Setup
+
+The MCP server is how AI agents interact with cortex. It uses stdio transport.
+
+### Claude Code
+
+Create `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "cortex": {
+      "type": "stdio",
+      "command": "/path/to/your/venv/bin/python",
+      "args": ["-m", "cortex.mcp_server"],
+      "env": {
+        "CORTEX_LOG_LEVEL": "INFO"
+      }
+    }
+  }
+}
+```
+
+### VS Code (Copilot / Continue)
+
+Add to `.vscode/settings.json`:
+
+```json
+{
+  "mcp.servers": {
+    "cortex": {
+      "command": "/path/to/your/venv/bin/python",
+      "args": ["-m", "cortex.mcp_server"],
+      "env": {
+        "CORTEX_LOG_LEVEL": "INFO"
+      }
+    }
+  }
+}
+```
+
+### Any MCP client
+
+The entry point is `cortex-mcp` (installed as a console script) or `python -m cortex.mcp_server`. Both use stdio transport -- JSON-RPC on stdin/stdout, logs on stderr.
+
+### Logging
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CORTEX_LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+| `CORTEX_LOG_FILE` | *(none)* | Path to a rotating log file (5 MB max, 2 backups) |
+
+Set `CORTEX_LOG_LEVEL=DEBUG` to see tool entry/exit timing, SQL queries, and build details. Logs always go to stderr; `CORTEX_LOG_FILE` adds a file copy.
+
+## Documentation
+
+Full documentation is available as a consumer docs site:
+
+```bash
+pip install cortex[viz]              # includes mkdocs-material
+cortex render-site /path/to/project  # generates site/ directory
+cortex render-site /path/to/project --serve  # live preview at localhost:8000
+```
+
+Or read the DocJSON source files directly in `docs/consumer/`:
+
+- [Getting Started](docs/consumer/getting-started.json)
+- [Core Concepts](docs/consumer/core-concepts.json)
+- [Staleness Engine](docs/consumer/staleness.json)
+- [Documentation System](docs/consumer/docs-system.json)
+- [dFlow Integration](docs/consumer/dflow.json)
+- [MCP Server](docs/consumer/mcp-server.json)
+- [MCP Setup & Observability](docs/consumer/mcp-setup.json)
+- [Viz Dashboard](docs/consumer/viz.json)
+- [Configuration](docs/consumer/configuration.json)
+
+## License
+
+MIT

axiom_graph-1.0.0/cortex/__init__.py

@@ -0,0 +1,3 @@
+"""Cortex — project knowledge indexer for AI agents."""
+
+__version__ = "0.1.0"