Metadata-Version: 2.1
Name: axiom-graph
Version: 1.0.6
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 axiom-graph[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 axiom-graph[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

