cortex-kg 0.2.1__tar.gz → 0.2.2__tar.gz

{cortex_kg-0.2.1/src/cortex_kg.egg-info → cortex_kg-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortex-kg
-Version: 0.2.1
+Version: 0.2.2
 Summary: Cortex: a persistent, workspace-level Engineering Knowledge Graph.
 Author-email: Roshan Gamage <roshangamage01@users.noreply.github.com>
 License: MIT

cortex_kg-0.2.2/docs/cortex-brain.md

@@ -0,0 +1,186 @@
+# Cortex Brain — interactive knowledge graph UI
+
+Cortex Brain is the WebGL visualization of your Engineering Knowledge Graph.
+After install, you open it in a browser — **no separate frontend server**.
+
+## One-time setup (3 commands)
+
+```bash
+# 1. Install
+pipx install cortex-kg
+# or: pip install cortex-kg
+
+# 2. Index a project (creates knowledge in a workspace)
+cortex --workspace default ingest /path/to/your/repo --project MyApp
+
+# 3. Start the API + UI
+cortex --workspace default serve-api
+```
+
+Open **http://localhost:8420** in your browser.
+
+In the top bar, set **Workspace** to the same name you used above
+(`default`, `demo`, `work`, …). If it doesn’t match, the canvas looks empty.
+
+That’s the whole setup.
+
+## What you’ll see
+
+| Area | What it does |
+|---|---|
+| **Graph canvas** | Zoom, pan, drag nodes; hover to highlight neighbors |
+| **Search** | Find a node and center it (`/` focuses the box) |
+| **Views** | Brain, Project, Architecture, Cluster, Timeline, AI Context, … |
+| **Filters** | Node/edge types, project, technology, date range |
+| **Node panel** | Metadata, connections, provenance, AI explanation |
+| **Intelligence** | Paths, impact, orphans, duplicates, similar nodes |
+| **AI Context** | Replay what retrieval would feed an LLM |
+| **Workspaces** | The Engineering Brain across one, many, or every workspace |
+
+Keyboard: `/` search · `f` fit view · `Esc` clear selection.
+
+## Workspaces view — workspace-aware knowledge visualization
+
+Every other view is scoped to the single **Workspace** field in the top bar.
+The **Workspaces** view is different: it lets you explore *across*
+workspaces, on the model that the Engineering Brain is conceptually one
+knowledge graph and a workspace is a filtering/organizational lens over it,
+not a separate graph. Pick it from the view switcher to swap the filter
+rail for a workspace selector + mode switch, with five lenses over the
+same data:
+
+| Mode | Shows |
+|---|---|
+| **Single** | One workspace's own nodes/relationships |
+| **Multi** | Selected workspaces merged, with shared knowledge cross-linked and highlighted |
+| **Global Brain** | Every known workspace, clustered together (like neural clusters connected by cross-workspace edges) |
+| **Cross-Workspace** | Only what crosses a workspace boundary — explicit links + shared knowledge |
+| **Dependency** | A workspace-level graph: one node per workspace, edges aggregate how they relate |
+
+**Shared knowledge:** a node ingested independently into two workspaces
+(e.g. the same `AuthService`) is detected by matching type + name and
+rendered as one *shared* node — larger, color-blended across its
+workspaces, with a slow breathing pulse on the canvas, and a workspace
+badge list in the node panel. This is a heuristic (exact name+type match),
+distinct from **explicit cross-workspace links** (`POST /api/workspaces/link`)
+which are authoritative, purpose-created relationships between two specific
+nodes (e.g. "our AuthService" `inspired_by` "the reference pattern in
+workspace `oss-reference`").
+
+**Workspace analytics** (in the rail, or `GET /api/workspaces/analytics`):
+most-connected workspace, most-reused knowledge, cross-workspace
+dependencies, possible duplicate knowledge, orphan workspaces, a knowledge
+reuse score, and a collaboration score — all computed from your real graph
+data (bounded per-workspace sampling for responsiveness), never fabricated.
+
+**AI Context, federated:** asking a question from the Workspaces view (with
+2+ workspaces selected) replays retrieval in *every* selected workspace and
+shows a per-workspace contribution bar — which workspace(s) were searched,
+and what percentage of the answer came from each.
+
+### How this actually works (and its honest limits)
+
+Physically, each workspace still has its own isolated embedded store
+(`~/.cortex/<workspace>/`) — Kuzu is single-writer, and workspaces have
+always been Cortex's storage-level isolation boundary (see
+`cortex.workspace.registry`). The Workspaces view delivers the "one graph"
+experience by **federating across workspaces at read time**, not by
+merging their storage:
+
+- Nodes keep their own workspace's id; "shared" is a client-visible flag
+  (`workspaceIds`, `shared`), not a physical merge — the underlying
+  duplicate nodes still exist separately, each with its own provenance.
+- A synthetic `Workspace` node is injected per workspace so it can be
+  clustered, colored, and linked like anything else in the graph.
+- Multi/Global/Cross/Dependency modes open **every selected workspace's**
+  database in the same process. A workspace that's locked by another
+  process (e.g. Cursor's `serve-mcp` integration) is skipped and reported
+  in `lockedWorkspaces` rather than failing the whole call.
+- Shared-knowledge detection and analytics sample up to a bounded number of
+  nodes per workspace (`limit`, default a few thousand) for responsiveness
+  — at true "hundreds of workspaces / millions of nodes" scale, treat these
+  as directional signals, not exhaustive ones.
+- Kuzu's per-database virtual memory reservation is capped
+  (`CORTEX_KUZU_MAX_DB_SIZE`, default 8 GiB) specifically so many workspace
+  databases can be open in one process at once without exhausting the OS's
+  mmap budget — the failure mode looks like `Buffer manager exception: Mmap
+  ... failed` if you ever raise this too high with many workspaces in play.
+
+If you want a literal single merged graph (one physical store, no
+per-workspace isolation) that's a separate, larger storage migration this
+feature intentionally does not attempt — federation was chosen so nothing
+about your existing per-workspace data or ingestion flow has to change.
+
+## Sample data (optional)
+
+From a clone of this repo:
+
+```bash
+pip install -e ".[dev]"
+cortex --workspace demo ingest examples/sample_repo --project SampleApp
+cortex --workspace demo serve-api
+```
+
+Open http://localhost:8420 and set **Workspace** to `demo`.
+
+## Tips
+
+- **Re-ingest** after code/docs change: `cortex ingest . --project MyApp`  
+  Unchanged files are skipped automatically.
+- **API docs** (same process): http://localhost:8420/docs
+- **Custom port:** `cortex serve-api --port 9000`
+- **Custom UI folder** (advanced): `export CORTEX_WEB_DIST=/path/to/dist`
+- Data lives in `~/.cortex/<workspace>/` (override with `CORTEX_HOME`)
+- The **Workspace** field in the top bar commits on blur/Enter, not every
+  keystroke — typing a workspace id auto-creates it on first use, so
+  committing on every keystroke used to create (and lock-probe) a phantom
+  workspace per partial string typed.
+
+## Troubleshooting: "Workspace 'X' is locked by another Cortex process"
+
+The embedded graph DB (Kuzu) only allows **one read-write process per
+workspace** at a time. If you see this error (a `503` in the graph
+canvas, or in `serve-api`'s logs), something else already has that
+workspace open — most commonly:
+
+- **Cursor's Cortex MCP integration** (`cortex --workspace <ws> serve-mcp`),
+  started automatically whenever Cursor uses `search_knowledge`,
+  `get_context`, etc. against that workspace.
+- **Another `serve-api` / CLI command** (`cortex ingest`, `cortex info`, …)
+  still running against the same workspace.
+
+Fix: either stop the other process, or point Brain at a workspace that
+isn't in use elsewhere (switch **Workspace** in the top bar). Ingesting
+into a workspace that Cursor's MCP server is actively using will hit the
+same conflict — pick a workspace Cursor doesn't reference, or briefly stop
+the MCP server, ingest, then restart it.
+
+## Developing the UI itself
+
+Only needed if you change the React app under `web/`:
+
+```bash
+# Terminal 1
+cortex --workspace demo serve-api
+
+# Terminal 2
+cd web && npm install && npm run dev
+```
+
+Then open the Vite URL (usually http://localhost:5173).  
+To refresh the packaged UI that `serve-api` serves:
+
+```bash
+./scripts/build_brain_ui.sh
+```
+
+## Connect Cursor (optional)
+
+The Brain UI explores knowledge in a browser. For AI tools inside Cursor:
+
+```bash
+cortex ingest . --project MyApp
+cortex setup project --write --project MyApp
+```
+
+See [cursor.md](cursor.md).

{cortex_kg-0.2.1 → cortex_kg-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cortex-kg"
-version = "0.2.1"
+version = "0.2.2"
 description = "Cortex: a persistent, workspace-level Engineering Knowledge Graph."
 readme = "README.md"
 license = { text = "MIT" }

{cortex_kg-0.2.1 → cortex_kg-0.2.2}/src/cortex/__init__.py

@@ -5,4 +5,4 @@ services, decisions, people, documents, ...) rather than files. Knowledge is
 owned by the workspace and outlives any single project.
 """
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"

{cortex_kg-0.2.1 → cortex_kg-0.2.2}/src/cortex/api/rest.py

@@ -24,7 +24,7 @@ from pydantic import BaseModel
 from sse_starlette.sse import EventSourceResponse
 
 from cortex.config import DEFAULT_WORKSPACE
-from cortex.daemon import CortexDaemon, get_daemon
+from cortex.daemon import CortexDaemon, WorkspaceLockedError, get_daemon
 from cortex.models import Edge, Node, Provenance
 from cortex.sync.change_feed import ChangeFeed
 
@@ -71,7 +71,10 @@ app.add_middleware(_StripApiPrefixMiddleware)
 
 
 def daemon_dep(workspace: str = Query(default=DEFAULT_WORKSPACE)) -> CortexDaemon:
-    return get_daemon(workspace)
+    try:
+        return get_daemon(workspace)
+    except WorkspaceLockedError as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
 
 
 class NodeIn(BaseModel):
@@ -267,7 +270,10 @@ async def change_feed_stream(workspace: str = Query(default=DEFAULT_WORKSPACE)):
     """Server-sent events: live subscription to graph changes (roadmap
     section 10) -- any tool can react to new knowledge instead of polling.
     """
-    daemon = get_daemon(workspace)
+    try:
+        daemon = get_daemon(workspace)
+    except WorkspaceLockedError as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
     feed = ChangeFeed.instance(daemon)
     q = feed.subscribe()
 
@@ -286,8 +292,10 @@ async def change_feed_stream(workspace: str = Query(default=DEFAULT_WORKSPACE)):
 
 
 from cortex.api.graph_viz import router as graph_viz_router  # noqa: E402
+from cortex.api.workspace_viz import router as workspace_viz_router  # noqa: E402
 
 app.include_router(graph_viz_router)
+app.include_router(workspace_viz_router)
 
 
 def _resolve_brain_ui_dir() -> Optional[Path]: