Metadata-Version: 2.4
Name: cortex-kg
Version: 0.3.2
Summary: Cortex: a persistent, workspace-level Engineering Knowledge Graph.
Author-email: Roshan Gamage <roshangamage01@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/RoshanGamage01/Cortex
Project-URL: Repository, https://github.com/RoshanGamage01/Cortex
Project-URL: Documentation, https://github.com/RoshanGamage01/Cortex/tree/main/docs
Project-URL: Issues, https://github.com/RoshanGamage01/Cortex/issues
Project-URL: Changelog, https://github.com/RoshanGamage01/Cortex/releases
Keywords: knowledge-graph,mcp,engineering,ai,local-first,rag,cursor
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: kuzu>=0.11
Requires-Dist: lancedb>=0.15
Requires-Dist: pyarrow>=15
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: watchdog>=4.0
Requires-Dist: tree-sitter>=0.21
Requires-Dist: tree-sitter-python>=0.23
Requires-Dist: tree-sitter-javascript>=0.23
Requires-Dist: tree-sitter-typescript>=0.23
Requires-Dist: tree-sitter-go>=0.23
Requires-Dist: tree-sitter-java>=0.23
Requires-Dist: pypdf>=4.0
Requires-Dist: pillow>=10.0
Requires-Dist: cryptography>=42.0
Requires-Dist: networkx>=3.2
Requires-Dist: pydantic>=2.6
Requires-Dist: mcp>=1.0
Requires-Dist: httpx>=0.27
Requires-Dist: gitpython>=3.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: neo4j>=5.19
Requires-Dist: jsonschema>=4.21
Requires-Dist: python-ulid>=2.2
Requires-Dist: sse-starlette>=2.0
Requires-Dist: python-multipart>=0.0.9
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: httpx2>=2.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: ocr
Requires-Dist: pytesseract>=0.3; extra == "ocr"
Provides-Extra: server
Requires-Dist: neo4j>=5.19; extra == "server"
Dynamic: license-file

# Cortex — Engineering Knowledge Graph

Cortex is a persistent, **workspace-level** knowledge graph for software
engineering. It models *relationships* (Services, APIs, Decisions, People,
Documents, ...) rather than files, survives project deletion, and exposes
that knowledge to any AI model or dev tool over MCP and a REST API.

This repo is a working implementation of the [technical roadmap](.cursor/plans)
for Cortex, built in Python (Kuzu/LanceDB/SQLite embedded stores, in place
of the roadmap's suggested Rust core — see "Design notes" below) and
organized into the roadmap's 7 delivery phases.

## Install

```bash
# Recommended (isolated global CLI):
pipx install cortex-kg

# Or with pip:
pip install cortex-kg
```

From source (development):

```bash
git clone https://github.com/RoshanGamage01/Cortex.git
cd Cortex
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

## Quickstart

```bash
# 1. Ingest a project (or the bundled sample from a clone):
cortex --workspace demo ingest examples/sample_repo --project SampleApp
# Or any local repo:
# cortex ingest /path/to/your/repo --project MyApp

# 2. Open Cortex Brain in your browser (API + UI, no extra frontend setup):
cortex --workspace demo serve-api
# → http://localhost:8420  (set Workspace = "demo" in the top bar)

# Ask questions from the CLI:
cortex --workspace demo search "what depends on AuthService"
cortex --workspace demo context "AuthService" --format markdown

# Wire Cursor into a project (optional):
cortex setup project --write --project MyApp
cortex --workspace demo serve-mcp   # MCP over stdio
```

Data lives at `~/.cortex/<workspace>/` (override with `CORTEX_HOME`) —
portable, backup-able, and independent of any project's lifecycle.

See **[docs/cortex-brain.md](docs/cortex-brain.md)** for the UI walkthrough.

## User guides

Full setup for Cursor, other platforms, and automation:

| Guide | Description |
|---|---|
| [docs/README.md](docs/README.md) | Guide index |
| [docs/installation.md](docs/installation.md) | pip/pipx install |
| [docs/cortex-brain.md](docs/cortex-brain.md) | **Interactive graph UI (browser)** |
| [docs/cursor.md](docs/cursor.md) | Cursor MCP + agent instructions |
| [docs/project-workflow.md](docs/project-workflow.md) | Ingest and maintain a project |
| [docs/other-platforms.md](docs/other-platforms.md) | Claude, VS Code, REST, SDKs, CI |
| [docs/automation.md](docs/automation.md) | Watch mode, hooks, automated rules |
| [docs/publishing.md](docs/publishing.md) | Release to PyPI |

**Connect Cursor to a project in two commands:**

```bash
cortex ingest . --project MyApp
cortex setup project --write --project MyApp   # writes .cursor/mcp.json + agent rule
```

Reload Cursor after setup.

## Architecture

```
Sources (code, git, docs, PDFs, images, DB schemas, APIs, notes, plugins)
   -> Extractors (deterministic first, LLM-assisted where structure is ambiguous)
   -> Entity Resolver (Candidate -> canonical Node/Edge, with provenance)
   -> Storage: Kuzu (graph) + LanceDB (vectors) + SQLite FTS5 (keyword) + SQLite (provenance/jobs/ACLs/ontology)
   -> Hybrid Query Engine (keyword + vector seeds -> graph expansion -> RRF fusion -> re-rank)
   -> Context Generator (token-budgeted, provenance-carrying context)
   -> Access layer: MCP server + REST API + TS/Python SDKs
```

Every node/edge type is **data**, not code: the ontology lives in a schema
registry (`cortex.ontology.registry`) seeded with the roadmap's default
taxonomy but extensible at runtime by extractors, plugins, or API/MCP
clients — no migration required.

## Project layout

```
src/cortex/
  config.py              workspace data-dir layout (~/.cortex/<id>/...)
  models.py               Node / Edge / Candidate / Provenance
  daemon.py                CortexDaemon: owns every store for one workspace
  cli.py                    `cortex` command-line entrypoint
  ontology/                schema registry (ontology-as-data)
  storage/                 GraphStore (Kuzu), VectorStore (LanceDB), KeywordStore (FTS5), ProvenanceStore
  ingestion/                content-hashing, entity resolver, the Detect->...->Emit pipeline
  extractors/               code (tree-sitter), git, db schema, OpenAPI, markdown, PDF, image, notes, LLM-assisted relations
  sync/                     file watcher, job queue, change feed (pub/sub)
  retrieval/                embeddings, RRF fusion, graph traversal/impact analysis, query planner, hybrid query engine
  context/                  token-budgeted context generation for LLMs
  mcp_server/                MCP server (tools + resources)
  api/                       REST API (FastAPI) + graph_viz (Brain UI API)
  static/brain/              Packaged Cortex Brain SPA (served by serve-api)
  plugins/                   out-of-process plugin interface/loader + example plugin
  security/                  ACLs, secrets scanning, encryption-at-rest, audit log
  workspace/                 multi-workspace registry + cross-workspace links + federation
  versioning/                 bitemporal nodes/edges, supersede/tombstone, history chains
  server_profile/              Neo4j/Memgraph GraphStore adapter (team-scale server profile)
  replication/                  CRDT/oplog multi-device sync
  offline/                       connectivity check + durable cloud-augmentation queue
  agents/                         agent write-back API + change-feed hooks
sdk/
  python/cortex_sdk/         Python REST client SDK
  typescript/src/index.ts     TypeScript REST client SDK
examples/sample_repo/          tiny multi-service demo repo used by the tests + quickstart
web/                           Cortex Brain source (Vite/React); build via scripts/build_brain_ui.sh
scripts/benchmark.py            ingestion/search/context performance benchmark
scripts/build_brain_ui.sh       build + copy UI into src/cortex/static/brain/
tests/                           60+ tests covering every phase below
```

## Phases (see the plan for full detail)

| Phase | What it delivers | Where |
|---|---|---|
| 1. Foundation | Daemon, Kuzu graph store, ontology-as-data, SQLite provenance, minimal API | `daemon.py`, `ontology/`, `storage/` |
| 2. Extraction & sync | Code/git/schema/API extractors, content-hash incremental sync, resolver v1 | `extractors/`, `ingestion/`, `sync/` |
| 3. Hybrid retrieval | Vectors, keyword index, traversal, RRF fusion, query planner | `retrieval/` |
| 4. Access layer | MCP server, REST API, TS+Python SDKs, context generation | `mcp_server/`, `api/`, `sdk/`, `context/` |
| 5. Unstructured + LLM-assisted | Markdown/PDF/image/notes extractors, schema-constrained LLM relation extraction, feedback loop | `extractors/markdown_extractor.py`, `pdf_extractor.py`, `image_extractor.py`, `notes_extractor.py`, `llm_relation_extractor.py` |
| 6. Platform | Plugin SDK, ACLs/encryption/secrets-scanning, multi-workspace, bitemporal versioning | `plugins/`, `security/`, `workspace/`, `versioning/` |
| 7. Scale & agents | Neo4j/Memgraph adapter, CRDT sync, offline fallback, caching, agent write-back | `server_profile/`, `replication/`, `offline/`, `agents/` |

## Design notes / deviations from the roadmap

- **Core engine is Python, not Rust.** The roadmap's storage picks (Kuzu,
  LanceDB, SQLite) and every architectural boundary (`GraphStore` /
  `VectorStore` / `Extractor` / plugin protocol) are implemented exactly as
  specified; only the host language differs, for iteration speed and
  because Kuzu/LanceDB both ship first-class embedded Python bindings. A
  Rust rewrite of the core would implement the same `GraphStore` /
  extraction / retrieval contracts.
- **Keyword index is SQLite FTS5, not Tantivy.** Zero extra dependency,
  same "exact-term/symbol search" role in the hybrid retrieval recipe;
  swappable behind `KeywordStore` if Tantivy bindings are preferred later.
- **Default embedding model is a deterministic offline hashing embedding**
  (`cortex.retrieval.embeddings.HashingEmbeddingProvider`), not a trained
  semantic model — by design, so the whole system (including tests/CI) runs
  fully offline with no model download. Swap in a real local/cloud model by
  implementing `EmbeddingProvider`.
- **LLM-assisted extraction/planning ship transparent local-heuristic
  defaults** (`cortex.extractors.llm_relation_extractor`,
  `cortex.retrieval.planner`) rather than calling a cloud model, again for
  offline-by-default operation; both are written to the exact request/response
  contract a real LLM backend would fill in via `CORTEX_LLM_PROVIDER`.

## Testing

```bash
python3 -m pytest tests/ -q
```

60 tests cover the full pipeline end-to-end (ingest the sample repo through
every extractor, resolve into the graph, hybrid-search it, generate
context, serve it over MCP/REST) plus targeted tests per phase (ACLs,
secrets scanning, encryption, CRDT merge, bitemporal versioning, plugin
sandboxing, multi-workspace federation, and the performance cache).
