anchor-kb 0.2.0__tar.gz

anchor_kb-0.2.0/.gitignore

@@ -0,0 +1,67 @@
+# Build / cache
+__pycache__/
+*.pyc
+.pytest_cache/
+.import_linter_cache/
+.venv/
+*.egg-info/
+dist/
+build/
+*.tsbuildinfo
+
+# Frontend
+node_modules/
+web/dist/
+
+# User data — never tracked, lives in --data-dir / ANCHOR_DATA_DIR
+data/
+# Note: top-level docs/ IS tracked — the architecture documentation lives
+# there. User-data canvases/ live inside `data/` which is already ignored.
+
+# Local config / env files — never commit credentials
+.env
+.env.local
+.env.*.local
+
+# Editor
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+.playwright-cli/
+.next/
+
+# Legacy v1 working-tree leftovers at the repo root. These directories /
+# files existed before v2 was promoted; they survive locally as untracked
+# entries after pulling this commit. Full history is on the
+# `archive/pre-v2` branch / `pre-v2-cutoff` tag.
+#
+# Leading slashes restrict the patterns to the repo root so they don't
+# shadow legitimate files of the same name inside `web/`.
+/backend/
+/backend2/
+/packages/
+/paperx/
+/paper/
+/posters/
+/public/
+/mydata/
+/uploads/
+/tmp/
+/Untitled/
+/v2/
+/src/components/
+/src/app/
+/2026-*-hi.txt
+/output_bboxes.txt
+/metadata.json
+/package.json
+/package-lock.json
+/pnpm-lock.yaml
+/postcss.config.cjs
+/tailwind.config.cjs
+/tsconfig.json
+/next.config.ts
+/next-env.d.ts
+/todos.md

anchor_kb-0.2.0/.importlinter

@@ -0,0 +1,67 @@
+[importlinter]
+root_package = anchor
+include_external_packages = True
+
+[importlinter:contract:layered]
+name = Hexagonal layering — adapters → infra → core
+type = layers
+layers =
+    anchor.adapters
+    anchor.infra
+    anchor.core
+
+[importlinter:contract:core_purity]
+name = Core has no I/O / framework dependencies
+type = forbidden
+source_modules =
+    anchor.core
+forbidden_modules =
+    httpx
+    fastapi
+    openai
+    mcp
+    pymupdf
+    docling
+    uvicorn
+    starlette
+    typer
+    aiofiles
+    sse_starlette
+
+[importlinter:contract:infra_no_transport]
+name = Infra implements ports, not transport
+type = forbidden
+source_modules =
+    anchor.infra
+forbidden_modules =
+    fastapi
+    mcp
+    uvicorn
+    starlette
+    typer
+    sse_starlette
+
+[importlinter:contract:canvas_no_extensions]
+name = Canvas primitive does not depend on extensions
+type = forbidden
+source_modules =
+    anchor.core
+    anchor.infra
+forbidden_modules =
+    anchor.extensions
+
+[importlinter:contract:extension_layered]
+name = Extensions follow the same layering as the canvas
+type = layers
+layers =
+    anchor.extensions.anchor_pdfs.adapters
+    anchor.extensions.anchor_pdfs.infra
+    anchor.extensions.anchor_pdfs.core
+
+[importlinter:contract:anchor_sysml_layered]
+name = anchor_sysml: layered, anchor_sysml.adapters → anchor_sysml.infra → anchor_sysml.core
+type = layers
+layers =
+    anchor.extensions.anchor_sysml.adapters
+    anchor.extensions.anchor_sysml.infra
+    anchor.extensions.anchor_sysml.core

anchor_kb-0.2.0/EXTENSIONS.md

@@ -0,0 +1,283 @@
+# Anchor extensions — the contract
+
+Anchor's canvas primitive is domain-agnostic. **Extensions** layer specific
+ingestion pipelines, node types, edge styles, and UI components on top of it.
+Today the PDF medallion pipeline (Docling + VLM region extraction + spec
+tables with page+bbox provenance) lives inside the same wheel as the canvas;
+this document describes the contract every extension follows so future
+extensions — transcription, code regions, web pages, your own — can ship
+either in-tree or as separate `anchor-canvas-*` packages.
+
+---
+
+## What an extension provides
+
+```python
+from anchor.canvas import CanvasCore, NodeType, ToolDef, SourceRefKind
+
+class AnchorExtension(Protocol):
+    NAME: str               # machine identifier, used as namespace prefix.
+                            # e.g. "anchor_pdfs", "anchor_transcribe"
+    DISPLAY_NAME: str       # human-friendly label for UI
+    VERSION: str            # extension version (semver)
+    REQUIRES_CANVAS: str    # canvas-core compat range, e.g. ">=0.2,<0.3"
+
+    def configure(self, canvas: CanvasCore) -> None:
+        """Called once at canvas startup. Register everything here."""
+        canvas.node_types.register_many([
+            NodeType("pdf:document", data_schema=DocumentData),
+            NodeType("pdf:spec_table", data_schema=SpecTableData),
+            ...
+        ])
+        canvas.source_ref_kinds.register(
+            SourceRefKind("pdf-page-bbox", schema=PdfPageBboxRef,
+                          renderer_hint="open_pdf_at_bbox"),
+        )
+        canvas.mcp_tools.register_namespace("pdf", [
+            ToolDef("ingest", schema=...),
+            ToolDef("list_documents", schema=...),
+            ...
+        ])
+        canvas.http.mount_router("/api/pdfs", router)
+        canvas.events.register([DocBronzed, DocSilvered, DocIngested, ...])
+        canvas.services.provide("pdfs.ingest_service", IngestService(...))
+```
+
+**Frontend half** (parallel contract for the React app):
+
+```typescript
+import { registerExtension } from "@anchor/canvas/extensions";
+import { SpecTableNode, DocumentNode } from "./nodes";
+
+registerExtension({
+  name: "anchor_pdfs",
+  nodeTypes: {
+    "pdf:document": DocumentNode,
+    "pdf:spec_table": SpecTableNode,
+  },
+  edgeStyles: {
+    "pdf:evidence": { stroke: "#FF8E2B", dasharray: "4 4" },
+  },
+  sourceRefHandlers: {
+    "pdf-page-bbox": openPdfAtBbox,
+  },
+});
+```
+
+---
+
+## Naming convention
+
+- **Node types:** `<extension_name_short>:<type>` (e.g. `pdf:spec_table`,
+  `transcribe:segment`, `code:region`). The `:` prefix prevents collisions.
+- **MCP tools:** prefixed namespaces (`pdf.ingest`, `pdf.list_documents`,
+  `transcribe.ingest_audio`).
+- **HTTP routes:** `/api/<extension_short>/...` (`/api/pdfs/...`,
+  `/api/transcribe/...`).
+- **Source-ref kinds:** `<short>-<address-shape>` (`pdf-page-bbox`,
+  `audio-timestamp`, `code-line-range`).
+- **On-disk substrates:** `data/<short>/...` (`data/bronze/`, `data/silver/`,
+  `data/gold/` for PDFs; would be `data/transcripts/` for transcription).
+
+---
+
+## What the canvas core provides
+
+The canvas core is the **substrate**. Extensions consume:
+
+```
+core/
+  workspace/      # Workspace aggregate, Node, Edge, reducer, validator
+  events/canvas.py  # NodeAdded, NodeMoved, EdgeAdded, …
+  ports/          # WorkspaceStore, EventBus, AssetStore
+  services/       # WorkspaceService — generic CRUD over canvases
+
+infra/
+  stores/fs_workspace_store.py
+  bus/memory_bus.py
+
+adapters/
+  http/routers/{workspaces, nodes, edges, sse}.py
+  mcp/{server, handlers_canvas, stdio_main}.py
+  cli/main.py     # the `anchor` binary, with extension subcommands
+
+Built-in node types: concept, entity, fact, area, note
+Built-in edge types: floating, anchored
+```
+
+Every extension can use these without re-inventing them. Extensions only
+add what's specific to their domain.
+
+---
+
+## Three ways to ship an extension
+
+### 1. In-tree (`extensions/` folder, recommended for the curated set)
+
+```
+v2/extensions/
+└── anchor_pdfs/
+    ├── pyproject.toml
+    ├── src/anchor_pdfs/
+    │   ├── extension.py              # AnchorExtension implementation
+    │   ├── core/, infra/, adapters/  # backend code
+    │   └── ...
+    ├── web/
+    │   ├── package.json
+    │   └── src/index.ts              # registerExtension(...)
+    └── tests/
+```
+
+Discovery: the canvas runner walks `extensions/` at startup, imports each
+`extension:Extension` class, calls `configure(canvas)`. Frontend imports each
+`extensions/*/web/dist/index.js` at canvas mount.
+
+**Status today:** PDF ingestion lives inside `src/anchor/` directly, not yet
+extracted into `extensions/anchor_pdfs/`. The split lands as a refactor pass
+once the API surface is stable. Use `extensions/` for genuinely new
+extensions you'd contribute upstream.
+
+### 2. Out-of-tree pip-installable package
+
+Anyone publishes their own `anchor-canvas-<name>` package to PyPI:
+
+```toml
+# my-anchor-ext/pyproject.toml
+[project]
+name = "anchor-canvas-mermaid"
+dependencies = ["anchor-canvas>=0.2"]
+
+[project.entry-points."anchor.extensions"]
+mermaid = "anchor_canvas_mermaid.extension:MermaidExtension"
+```
+
+Discovery: the canvas runner reads Python entry points
+(`importlib.metadata.entry_points(group='anchor.extensions')`) and loads each
+registered class.
+
+```bash
+uv tool install --with anchor-canvas-mermaid anchor-canvas
+anchor serve --data-dir ~/anchor-data    # picks up mermaid automatically
+```
+
+### 3. Local / editable (for extension developers)
+
+Set `ANCHOR_EXTENSIONS_PATH` to a colon-separated list of directories
+containing extension source code. Canvas runner walks each path, finds the
+`extension.py` entry point, loads the extension without packaging.
+
+```bash
+export ANCHOR_EXTENSIONS_PATH=~/dev/my-ext:~/dev/another-ext
+anchor serve --data-dir ~/anchor-data
+```
+
+Useful for iterating on a new extension without `pip install -e .` round-trips.
+
+---
+
+## Per-project extension pinning (planned)
+
+For reproducible extension sets bound to a `--data-dir`:
+
+```toml
+# ~/anchor-data/cooling-system/anchor.toml
+[anchor]
+canvas_version = ">=0.2,<0.3"
+
+[[extensions]]
+name = "anchor-canvas-pdfs"
+version = ">=0.2"
+
+[[extensions]]
+git = "https://github.com/someone/anchor-canvas-mermaid"
+ref = "v0.1"
+
+[[extensions]]
+path = "/Users/me/dev/my-custom-ext"
+```
+
+`anchor serve --data-dir <dir>` reads `<dir>/anchor.toml`, ensures every
+listed extension is available (or fails loudly with install instructions),
+loads them, starts. Lands in v0.4.
+
+---
+
+## What lives in the canvas core vs. an extension
+
+| Concern | Canvas core | Extension |
+|---|---|---|
+| Workspace, Node, Edge, reducer | ✓ | |
+| Generic node types: concept, entity, fact, area, note | ✓ | |
+| Generic edge types: floating, anchored | ✓ | |
+| EventBus, SSE, WebSocket | ✓ | |
+| Asset upload + serve | ✓ | |
+| Screenshot mechanism (browser-as-screenshotter) | ✓ | |
+| Viewport math (fit, visibility) | ✓ | |
+| Lock state on nodes | ✓ | |
+| `data.locked`, `data.visible`, `data.layer`, `data.opacity` | ✓ | |
+| Domain-specific node types (pdf:spec_table, transcribe:segment, …) | | ✓ |
+| Domain-specific schemas in `Node.data` | | ✓ |
+| Domain-specific source-ref kinds | | ✓ |
+| Ingestion pipelines (Docling, Whisper, tree-sitter, …) | | ✓ |
+| Domain-specific React renderers | | ✓ |
+| Domain-specific edge styling (e.g. `pdf:evidence` orange-dashed) | | ✓ |
+| MCP tools for domain operations | | ✓ |
+
+**The principle:** if the canvas core needs to know about a domain to
+function, it doesn't belong in core. Canvas core only knows registries.
+
+---
+
+## Honest gotchas for extension authors
+
+1. **Frontend bundling is the harder problem.** Extensions need to ship JS
+   bundles that load into the canvas's React app. Today (in-tree) we glob
+   `extensions/*/web/src/index.ts` at build time. Out-of-tree extensions
+   eventually need Module Federation. We'll ship that path when there's
+   demand.
+
+2. **`Node.data` is not type-safe across the wire.** Validators in the
+   `NodeTypeRegistry` enforce schemas at command time, but anyone reading the
+   stored JSON has to revalidate. Keep your schemas backwards-compatible.
+
+3. **Source-ref kinds need to be unique.** If two extensions both register
+   `"page-bbox"` you'll get an error at startup. Always namespace
+   (`"pdf-page-bbox"`, not `"page-bbox"`).
+
+4. **Don't fight the layer rules.** Your extension's `core/` may not import
+   `httpx`/`fastapi`/`openai`/etc. Same hexagonal discipline applies. Run
+   `lint-imports` on your extension.
+
+5. **Test against the canvas's in-memory implementations.** The canvas
+   core ships `MemoryWorkspaceStore`, `MemoryDocStore`, `MemoryEventBus` —
+   use them in your unit tests so you don't need a real filesystem.
+
+---
+
+## Status of the contract
+
+**Stable today:**
+- Canvas core's domain model (Workspace, Node, Edge, reducer, events)
+- `NodeTypeRegistry` for runtime node-type registration
+- HTTP/MCP/CLI/SSE adapter shape
+
+**In flux (will stabilise as we extract the canvas primitive):**
+- The `AnchorExtension` Protocol class itself (today: implicit in how PDF
+  code is wired; tomorrow: an explicit class)
+- Frontend `registerExtension(...)` API
+- Source-ref kind registry
+- Edge-style registry
+
+**Not yet implemented but documented here:**
+- Out-of-tree extension discovery via Python entry points
+- `anchor.toml` per-project extension pinning
+- `ANCHOR_EXTENSIONS_PATH` for editable-install paths
+- `anchor extensions {list, install, remove}` CLI subcommand
+
+If you're writing an extension *today*, your safest bet is to clone v2,
+add it under `extensions/`, follow the patterns in the existing PDF code
+(see `src/anchor/core/services/ingest_service.py`,
+`src/anchor/adapters/mcp/handlers_ingest.py`,
+`src/anchor/infra/llm/`). The contract above is the target shape; the
+move from "implicit in v2" to "explicit Protocol" is a follow-up
+refactor.

anchor_kb-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christoffer Björkskog, Lamin Jatta, and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

anchor_kb-0.2.0/OIP.md

@@ -0,0 +1,33 @@
+# OIP — Open Ingestion Protocol
+
+The OIP specification has moved to its own repository:
+
+**📦 https://github.com/Novia-RDI-Seafaring/OIP**
+
+That repo is the single source of truth for the protocol, manifest schema,
+and discovery rules. It also ships a CLI (`uvx oip`) for validating
+producer manifests and inspecting compliant on-disk trees.
+
+## What OIP is, in one paragraph
+
+OIP is a small, governance-neutral specification for ingestion tools that
+produce structured, source-grounded knowledge. Any tool that conforms to
+OIP can be consumed by any OIP-aware application — the same way any
+LSP-compliant language server works in any LSP-aware editor. Anchor is the
+first reference consumer; Anchor's PDF medallion pipeline is the first
+reference producer. Both can be replaced.
+
+## Anchor's relationship to OIP
+
+- **Anchor's canvas** is an OIP **consumer**: it reads OIP-compliant gold
+  regions from disk and renders them as canvas nodes with row-level
+  provenance.
+- **Anchor's bundled extensions** (`anchor_pdfs`, `anchor_fmus`,
+  `anchor_cad`, `anchor_sysml`) are OIP **producers**: each declares an
+  OIP manifest, writes to the OIP-fixed artefact tree, and exposes
+  ingest/list/get operations the canvas can discover.
+
+For the manifest schema, the on-disk tree, the discovery rules, and the
+list of source-kinds, **read the OIP repo's spec**. This file used to
+contain a draft of that spec; the draft is now superseded by the
+versioned spec in the OIP repo and is no longer maintained here.