rag-wright 0.1.0__py3-none-any.whl

rag_wright/__init__.py

@@ -0,0 +1,13 @@
+"""RAG_Wright: the open-core RAG ENGINE (RAG_Capability_Spec.md v0.1; engine/product split, ADR-0052).
+
+This package builds and registers the FR-C capabilities (parsing, chunking, embedding, hybrid search,
+reranking, graph extraction, entity resolution, ontology and registry derivation, reasoning and generation,
+and the RLM skill) as ordinary tested software, AND the ingestion and query pipelines that compose them --
+ordinary hardened LangGraph subgraphs, not a compiler output (GraphWright is PARKED, ADR-0052). Each capability
+is registered under its FR-C name for Agentic Resource Discovery (ARD, `urn:air`).
+
+The engine is ASYNC end to end (ADR-0057): every model call runs under a true wall-clock deadline. The public
+ingest / query / compliance entrypoints are `async` (or return LangGraph graphs called via `.ainvoke`); see
+`docs/product/engine_async_api.md` for the interface contract the product (RuleWright) depends on. Dependency
+direction is strict and one-way: Product -> Engine, never Engine -> Product.
+"""

rag_wright/api/__init__.py

@@ -0,0 +1,33 @@
+"""The engine API layer (ADR-0117): the stable, domain-agnostic surface a product builds on.
+
+EP-API-1 ships the typed config + the opaque workspace handle. Future increments add the per-kind invokers
+(EP-API-2), generic `kg_read`/`kg_write` + id/format accessors (EP-API-3), and the options catalog + pluggable
+embedders (EP-API-4). The product imports from here; it never reaches the store/embedder/model implementations."""
+from __future__ import annotations
+
+from rag_wright.api.config import EngineConfig, EngineOptions, IngestOptions, StoreConfig
+# The capability-registration surface lives in capabilities.manifests; re-export it here (PREP-1.5) so the public
+# story is uniformly "everything is rag_wright.api". The original import path keeps working — these are the same
+# objects, not a fork.
+from rag_wright.capabilities.manifests import (
+    load_reference_pack,
+    reference_pack,
+    register_capability,
+)
+from rag_wright.api.documents import aparse_document, parse_document, source_document
+from rag_wright.api.ids import decode_bbox, document_of, id_source
+from rag_wright.api.discover import Discovered, discover
+from rag_wright.api.invoke import ainvoke_model, ainvoke_subgraph, capability_index, invoke_model
+from rag_wright.api.kg import entities_by_name, kg_edges, kg_read, kg_write, span_positions
+from rag_wright.api.usage import ModelUsage, UsageTotals, measure_usage
+from rag_wright.api.workspace import WorkspaceHandle, open_workspace
+
+__all__ = [
+    "EngineConfig", "StoreConfig", "EngineOptions", "IngestOptions", "WorkspaceHandle", "open_workspace",
+    "ainvoke_subgraph", "invoke_model", "ainvoke_model", "capability_index", "discover", "Discovered",
+    "kg_read", "kg_write", "kg_edges", "entities_by_name", "span_positions",
+    "document_of", "id_source", "decode_bbox",
+    "source_document", "parse_document", "aparse_document",
+    "measure_usage", "UsageTotals", "ModelUsage",
+    "register_capability", "load_reference_pack", "reference_pack",
+]

rag_wright/api/config.py

@@ -0,0 +1,59 @@
+"""EP-API-1/4 (ADR-0117): the engine's typed configuration. The product constructs an `EngineConfig` and passes it
+to `open_workspace`; the engine resolves backends behind an opaque handle. This is the ONLY place a store backend is
+named -- everything else goes through the handle. EP-API-4a adds the `options` catalog (ingest knobs today;
+retrieval/rerank groups land as needed), so a product tunes the engine through config, never environment variables."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class StoreConfig:
+    """How to reach the KG/retrieval store. `backend` selects the implementation (only `arcadedb` today; a new
+    backend -- e.g. Neo4j -- is added here, invisibly to the product)."""
+
+    host: str
+    port: str
+    user: str
+    password: str
+    backend: str = "arcadedb"
+    protocol: str = "http"
+
+
+@dataclass(frozen=True)
+class IngestOptions:
+    """Ingest-time knobs, settable through config instead of environment variables (EP-API-4a). Every field defaults
+    to `None` = "use the engine default", so the engine's existing env fallback is preserved (a non-API caller is
+    unaffected) and an API caller that leaves these unset gets today's behavior exactly. Set a field to override."""
+
+    classify_concurrency: Optional[int] = None    # function-classify parallelism (was CLASSIFY_CONCURRENCY)
+    clause_concurrency: Optional[int] = None       # clause-extraction parallelism (was CLAUSE_CONCURRENCY)
+    affiliations: Optional[bool] = None            # run affiliation extraction (was RAG_INGEST_AFFILIATIONS)
+    function_classifier: Optional[str] = None      # "setfit" | "llm" (was RAG_FUNCTION_CLASSIFIER)
+    list_model: Optional[str] = None               # secondary list-union model, "off" to disable (was RAG_INGEST_LIST_MODEL)
+    clause_samples: Optional[int] = None           # multi-sample count for the list union (was RAG_INGEST_CLAUSE_SAMPLES)
+
+
+@dataclass(frozen=True)
+class EngineOptions:
+    """The engine's options catalog. Ingest knobs today; retrieval / reranking / chunking groups are added here as
+    they are promoted off environment variables."""
+
+    ingest: IngestOptions = field(default_factory=IngestOptions)
+
+
+@dataclass(frozen=True)
+class EngineConfig:
+    """The product's view of the engine: the store connection, chosen models (by role alias), the embedding profile,
+    and the `options` catalog. Defaults just work; override only to trade quality/cost/latency. Implementation
+    details (ArcadeDB, BGE) never cross this boundary."""
+
+    store: StoreConfig
+    models: dict[str, str] = field(default_factory=dict)  # ModelRole value -> engine-supported model alias (override)
+    embeddings: dict[str, str] = field(default_factory=lambda: {"text": "bge-m3"})  # profile -> supported embedder
+    options: EngineOptions = field(default_factory=EngineOptions)  # EP-API-4a: ingest (+ future) knobs via config
+    # AC-journey: the DOMAIN pack `.ttl` declaring this domain's KG vertex/edge types (open_workspace creates them).
+    # None = the engine's reference CONTRACT pack. A new domain points this at its own `.ttl` -- "config + .ttl",
+    # no engine edit -- and `ensure_schema` creates that domain's schema on top of the always-on engine types.
+    pack: Optional[str] = None

rag_wright/api/discover.py

@@ -0,0 +1,70 @@
+"""Capability discovery: rank the live ARD catalog by semantic match to a task (embedding-based).
+
+A product-side agent that needs to PLAN over the engine — when invoking a known capability by name through its seam
+is not enough and it must find what's available for a task — calls `discover(task, resources=ws)`, then orchestrates
+the `ainvoke_*` calls over the top matches. Ranking is by BGE-M3 embedding similarity of the task against each
+capability's `representative_queries` + description (the signal manifests carry for exactly this), using the
+workspace's query embedder — the same embedder and vector space retrieval uses. Domain-free: it ranks whatever is in
+the LIVE catalog (`MANIFEST_SPECS`), so it covers the product's OWN registered capabilities, not just the reference
+pack. Complements `capability_index` (the flat listing) with task-ranked selection.
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Optional
+
+from rag_wright.api.workspace import WorkspaceHandle
+
+
+@dataclass(frozen=True)
+class Discovered:
+    """One ranked capability match from `discover` — enough for an agent to pick and invoke it by `slug`."""
+
+    slug: str
+    kind: str
+    description: str
+    representative_queries: tuple[str, ...]
+    score: float  # cosine similarity in [-1, 1]; higher is a better task match
+
+
+def _cosine(a: list[float], b: list[float]) -> float:
+    dot = sum(x * y for x, y in zip(a, b))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(y * y for y in b))
+    return 0.0 if na == 0.0 or nb == 0.0 else dot / (na * nb)
+
+
+def _match_text(spec) -> str:
+    rq = " ".join(spec.representative_queries or ())
+    return f"{spec.display_name}. {spec.description} {rq}".strip()
+
+
+def discover(query: str, *, resources: WorkspaceHandle, kind: Optional[str] = None, k: int = 8) -> list[Discovered]:
+    """Rank the live ARD catalog by semantic match to `query`; return the top `k` (optionally filtered to one
+    `kind`: `subgraph` / `model` / `function` / `agent_skill` / `mcp_tool`). Embedding-based, via the workspace's
+    query embedder (BGE-M3, the same space retrieval uses). Returns `[]` when the (filtered) catalog is empty; raises
+    `RuntimeError` if the workspace has no query embedder available (discovery needs one)."""
+    from rag_wright.capabilities.manifests import MANIFEST_SPECS
+
+    specs = [s for s in MANIFEST_SPECS.values() if kind is None or s.kind == kind]
+    if not specs:
+        return []
+    embedder = getattr(resources, "_embedder", None)
+    if embedder is None:
+        raise RuntimeError("discover() needs a query embedder; none is available on this workspace")
+    dense, _sparse = embedder.encode_batch([query] + [_match_text(s) for s in specs])
+    query_vec, cand_vecs = dense[0], dense[1:]
+    ranked = sorted(
+        zip(specs, cand_vecs), key=lambda sv: _cosine(query_vec, sv[1]), reverse=True
+    )
+    return [
+        Discovered(
+            slug=s.slug,
+            kind=s.kind,
+            description=s.description,
+            representative_queries=tuple(s.representative_queries or ()),
+            score=round(_cosine(query_vec, v), 4),
+        )
+        for s, v in ranked[:k]
+    ]

rag_wright/api/documents.py

@@ -0,0 +1,39 @@
+"""EP-API-2b / EP-API-6 (ADR-0117): building a document to feed the ingestion capability.
+
+`source_document(document_id, text=...)` makes an engine `SourceDocument` from plain text (the simplest path, no
+parser needed). `parse_document` / `aparse_document` make a STRUCTURE-BEARING `SourceDocument` from a file PATH via
+the engine's real docling parse (`.parsed` set), so the full ingestion pipeline incl docling runs through the API --
+not only the text fallback. Heavy deps imported lazily so `import rag_wright.api` stays light."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+def source_document(document_id: str, *, text: str) -> Any:
+    """A text-only `SourceDocument` (`source_doc_id`, `text`) to pass as the `document` input of the
+    `contract_ingestion_pipeline` capability. The id should be a canonical, delimiter-safe source-doc id."""
+    from rag_wright.capabilities.document_parse import SourceDocument
+
+    return SourceDocument(source_doc_id=document_id, text=text)
+
+
+def parse_document(document_id: str, path: Any, *, cache_dir: Any, metadata: dict | None = None) -> Any:
+    """Docling-parse the file at `path` ONCE (content-hash gated + cached under `cache_dir`) into a
+    structure-bearing `SourceDocument` -- `.parsed` carries the `DoclingDocument` so the chunker's structural pass
+    fires on real headings, and `.text` holds the flattened text. This is the PDF/DOCX/HTML/MD ingest entry point
+    of the engine API; pass the result as the `document` input of `contract_ingestion_pipeline`. The docling parse
+    blocks; use `aparse_document` on an event loop."""
+    from rag_wright.capabilities.document_parse import parsed_source_document
+
+    p = Path(path)
+    return parsed_source_document(document_id, p.name, p.read_bytes(), cache_dir=cache_dir, metadata=metadata)
+
+
+async def aparse_document(document_id: str, path: Any, *, cache_dir: Any, metadata: dict | None = None) -> Any:
+    """The async, deadline-bounded twin of `parse_document` (ADR-0057): runs the docling parse off the event loop
+    so a hand-built async ingest can parse a document into a structure-bearing `SourceDocument` without blocking."""
+    from rag_wright.capabilities.document_parse import aparsed_source_document
+
+    p = Path(path)
+    return await aparsed_source_document(document_id, p.name, p.read_bytes(), cache_dir=cache_dir, metadata=metadata)

rag_wright/api/ids.py

@@ -0,0 +1,31 @@
+"""EP-API-3 (ADR-0117): engine id/format accessors.
+
+So a product never parses engine id strings or storage formats itself (today the seam reimplements these, drifting
+from the engine). Heavy deps are imported lazily so `import rag_wright.api` stays light (progressive loading)."""
+from __future__ import annotations
+
+from typing import Optional
+
+
+def document_of(entity_id: str) -> str:
+    """The source-document id embedded in a span/chunk/clause id (`<source_doc_id>:<idx>:<hash>` -> the first,
+    delimiter-safe segment). Empty in -> empty out."""
+    from rag_wright.store.arcadedb import _doc_id_of
+
+    return _doc_id_of(entity_id)
+
+
+def id_source(requirement_id: str) -> str:
+    """The source/policy of a Requirement id (`<source>:<section>:<hash>` -> the first segment; `source` is
+    delimiter-safe via `canonical_source_doc_id`, so this is the same first-segment rule as `document_of`)."""
+    from rag_wright.store.arcadedb import _doc_id_of
+
+    return _doc_id_of(requirement_id)
+
+
+def decode_bbox(raw: Optional[str]) -> Optional[tuple]:
+    """Decode the engine's best-effort bounding box (stored as a JSON `[l,t,r,b]` string) to a `(l, t, r, b)` tuple,
+    or None. The single canonical decoder (retires the product seam's copy)."""
+    from rag_wright.capabilities.highlight_serve import _decode_bbox
+
+    return _decode_bbox(raw)

rag_wright/api/invoke.py

@@ -0,0 +1,99 @@
+"""EP-API-2 / EP-CORE-2 (ADR-0117, ADR-0118): the engine's capability invoker -- an adapter-free ARD *client*.
+
+Progressive loading, like an agent holding skill name+metadata and loading the full thing on demand:
+  * a LIGHT index (`slug -> manifest spec`) is built ONCE from the ARD manifest specs (no capability IMPLEMENTATION
+    is imported) -- the "cards" layer, for discovery + knowing what exists;
+  * on invoke, the capability's `impl_ref` (a "module:attr" vendor-extension pointer on its manifest) is imported
+    LAZILY via `capability_impl` and called -- so there is NO central engine-owned adapter dict. A developer who
+    registers a capability with an `impl_ref` makes it invocable with zero engine edits (ADR-0118).
+The ARD registry stays metadata (ADR-0003: a string pointer, never a callable). Each per-kind invoker takes an
+opaque `WorkspaceHandle` as resources and wraps the call in a trace span; model usage/cost is captured by the
+CALLER's `api.measure_usage()` (EP-API-5). Subgraph hardening (retry/dead-letter) comes from the LangGraph scaffold."""
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from rag_wright.capabilities.invoke import capability_impl
+from rag_wright.api.workspace import WorkspaceHandle
+from rag_wright.models.tracing import traced_step
+
+def _index() -> dict[str, Any]:
+    """The light capability index (`slug -> manifest spec`): the LIVE runtime ARD catalog the developer populates
+    (EP-CORE-3). Read fresh each call so a just-registered capability is seen; carries only metadata (kind/
+    description/impl_ref/representative_queries), never an implementation."""
+    from rag_wright.capabilities.manifests import MANIFEST_SPECS
+
+    return MANIFEST_SPECS
+
+
+def capability_index() -> dict[str, dict]:
+    """Public discovery index: `{slug: {kind, description}}` for every catalogued capability (the 'cards')."""
+    return {slug: {"kind": s.kind, "description": s.description} for slug, s in _index().items()}
+
+
+def _validate(name: str, kind: str) -> None:
+    """Validate a capability name against the ARD catalog (name known, kind matches). Raises KeyError/ValueError."""
+    idx = _index()
+    if name not in idx:
+        raise KeyError(f"unknown capability {name!r} (not in the ARD catalog)")
+    if idx[name].kind != kind:
+        raise ValueError(f"capability {name!r} is kind {idx[name].kind!r}, not {kind!r}")
+
+
+async def ainvoke_subgraph(name: str, inputs: dict, *, resources: WorkspaceHandle) -> Any:
+    """Invoke a subgraph-kind capability by name over the workspace, inside a trace span. The implementation is
+    resolved lazily from the manifest `impl_ref` (no central adapter dict). Retry/dead-letter comes from the
+    LangGraph scaffold the subgraph is built on; usage is captured by the caller's `measure_usage()` (EP-API-5)."""
+    _validate(name, "subgraph")
+    factory = capability_impl(name)  # resolves impl_ref -> the co-located `ainvoke(resources, inputs)`
+    with traced_step(f"invoke:{name}"):
+        return await factory(resources, inputs)
+
+
+def invoke_model(name: str, inputs: dict, *, resources: WorkspaceHandle) -> Any:
+    """Invoke a model-kind capability by name (SYNCHRONOUSLY). Validated against the ARD catalog, then resolved via
+    `impl_ref` and dispatched -- the SAME path the ingestion pipeline routes through (one production path, no second
+    hand-built fleet). `resources` is accepted for API uniformity but model capabilities are store-independent.
+    Usage is the caller's `measure_usage()` scope (EP-API-5). A model impl may be async (I/O-bound, e.g. an
+    LLM-backed cap) -- those cannot be invoked here; call `ainvoke_model` instead (we refuse rather than silently
+    return an un-awaited coroutine)."""
+    _validate(name, "model")
+    factory = capability_impl(name)
+    if asyncio.iscoroutinefunction(factory):
+        raise TypeError(
+            f"capability {name!r} has an async impl; call ainvoke_model() instead of invoke_model()")
+    with traced_step(f"invoke:{name}"):
+        return factory(resources, inputs)
+
+
+async def ainvoke_model(name: str, inputs: dict, *, resources: WorkspaceHandle,
+                        sem: asyncio.Semaphore | None = None) -> Any:
+    """Invoke a model-kind capability by name, ASYNCHRONOUSLY -- the async surface for model caps (the subgraph
+    legs already have `ainvoke_subgraph`). A model impl is one of two shapes, and this routes each honestly:
+      * SYNC (CPU-bound local inference -- a classifier/XGBoost fleet): run OFF the event loop in a worker thread
+        (`asyncio.to_thread`), so a big batch never blocks the loop;
+      * ASYNC (I/O-bound -- an LLM-backed cap calling OpenRouter or a local vLLM client): AWAITED directly, so the
+        I/O concurrency is real (not a thread wrapping a blocking call).
+    `sem` (an `asyncio.Semaphore`) bounds total in-flight work when a caller fans out a batch -- the same
+    backpressure the ingestion pipeline applies via `adispatch_model`. Usage is the caller's `measure_usage()`
+    scope (EP-API-5)."""
+    _validate(name, "model")
+    factory = capability_impl(name)
+
+    async def _run() -> Any:
+        with traced_step(f"invoke:{name}"):
+            if asyncio.iscoroutinefunction(factory):
+                return await factory(resources, inputs)
+            return await asyncio.to_thread(factory, resources, inputs)
+
+    if sem is None:
+        return await _run()
+    async with sem:
+        return await _run()
+
+
+def _invocable_names() -> dict[str, str]:
+    """{name: kind} for every capability that declares an `impl_ref` -- the drift guard asserts each resolves to a
+    callable of the declared kind (replaces the old central-adapter-dict binding)."""
+    return {slug: s.kind for slug, s in _index().items() if getattr(s, "impl_ref", None)}

rag_wright/api/kg.py

@@ -0,0 +1,61 @@
+"""EP-API-3 (ADR-0117): scoped KG access over the opaque workspace handle.
+
+Thin wrappers that delegate to the handle's resolved store, so a product does generic typed-KG reads/writes (and
+span-position lookups for citations) WITHOUT importing `ArcadeDBStore` or touching `ws._store`. The generic
+`kg_read`/`kg_write` primitives already live on the store (DD-1a/b); this exposes them on the API."""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from rag_wright.api.workspace import WorkspaceHandle
+
+# the span-position fields a citation needs (NOT the dense vector) -- offsets + page/bbox provenance
+_SPAN_POSITION_FIELDS = [
+    "span_id", "parent_chunk_id", "span_index", "text", "function", "contract_id",
+    "doc_start", "doc_end", "pages", "bbox",
+]
+
+
+def kg_read(ws: WorkspaceHandle, node_type: str, *, where: Optional[dict] = None, fields: Optional[list] = None,
+            distinct: Optional[str] = None, order_by: Optional[str] = None, limit: Optional[int] = None) -> list[dict]:
+    """Read typed nodes of `node_type` from the workspace (see `Store.kg_read`). Equality/`IN` filters, projection,
+    distinct, order, limit; an empty list `where` value is scope-to-nothing -> `[]`."""
+    return ws._store.kg_read(node_type, where=where, fields=fields, distinct=distinct, order_by=order_by, limit=limit)
+
+
+def kg_write(ws: WorkspaceHandle, nodes: list, edges: Any = ()) -> None:
+    """Upsert typed `nodes` + create typed `edges` in one transaction (see `Store.kg_write`). `nodes`/`edges` are
+    `KgNode`/`KgEdge` (from `rag_wright.store.seam`); the store encodes each field per its pack-declared type."""
+    ws._store.kg_write(nodes, edges)
+
+
+def kg_edges(ws: WorkspaceHandle, from_type: Optional[str] = None, *, where: Optional[dict] = None,
+             key_range: Optional[tuple] = None, direction: str = "out", edge_type: Optional[str] = None,
+             edge_where: Optional[dict] = None, target_where: Optional[dict] = None,
+             select: dict) -> list[dict]:
+    """Generic edge TRAVERSAL over the workspace (see `Store.kg_edges`): node-start out/in MATCH (by `where`
+    equality/membership or a contract-scope `key_range`) or a direct edge scan; `select` projects `c.`/`e.`/`v.`
+    expressions. The engine's relational/graph primitive on the API, so a domain's graph query never touches
+    `ws._store`. (`NOT_NULL` for a presence filter is `rag_wright.store.seam.NOT_NULL`.)"""
+    return ws._store.kg_edges(from_type, where=where, key_range=key_range, direction=direction,
+                              edge_type=edge_type, edge_where=edge_where, target_where=target_where, select=select)
+
+
+def entities_by_name(ws: WorkspaceHandle, name: str) -> list[dict]:
+    """Resolve an entity NAME to every entity node it matches: `[{entity_id, name, entity_type}]` (the engine owns
+    the surface-form normalization, so variants collapse to one id). One name can match several nodes (a resolved
+    node + an unlinked ref sharing a clustering key) -- all are returned. `entity_id` is exactly the
+    `start_entity_id` a graph traversal takes. The engine's generic entity-lookup primitive on the API."""
+    return ws._store.entities_by_name(name)
+
+
+def span_positions(ws: WorkspaceHandle, document: str) -> list[dict]:
+    """Every span of `document` with its position provenance (doc offsets, pages, DECODED bbox), ordered by document
+    position. The engine MECHANISM behind a product's citation/highlight types -- the product wraps these rows into
+    its own presentation type (e.g. `SpanLocation`)."""
+    from rag_wright.api.ids import decode_bbox
+    from rag_wright.store.arcadedb import SPAN_TYPE
+
+    rows = ws._store.kg_read(SPAN_TYPE, fields=_SPAN_POSITION_FIELDS, where={"contract_id": document},
+                             order_by="doc_start")
+    return [{**r, "bbox": decode_bbox(r.get("bbox"))} for r in rows]

rag_wright/api/mcp.py

@@ -0,0 +1,94 @@
+"""EP-RT-2 (ADR-0117): the generic capability->MCP adapter.
+
+One function, `build_capability_mcp(slug, *, resources)`, exposes ANY catalogued invokable capability as a FastMCP
+server with NO bespoke per-capability server code -- the tool's name/title/description are read from the ARD
+manifest, and its handler dispatches through the engine invoker (`ainvoke_subgraph`/`invoke_model`) over the bound
+workspace. This is the zero-boilerplate path: a new-domain product (or a new engine capability) gets a discoverable
+MCP tool for free, the moment the capability is in the ARD catalog.
+
+The four hand-written servers in `rag_wright/mcp/` stay: they offer a CURATED, typed tool signature + description for
+the Tier-1 legs. This generic adapter is the complement -- it takes a single opaque `inputs` dict (the capability's
+own input contract, dispatched straight to the invoker) rather than a per-capability typed signature, because the
+ARD manifest carries no JSON input schema to derive one from.
+
+Only `subgraph` and `model` kinds are supported (the kinds the invoker can dispatch). An `mcp_tool` is already an
+MCP tool; `function`/`agent_skill` have no invoker adapter yet (EP-API-2c) -- all rejected with a clear error.
+
+Store binding is server-side via the `WorkspaceHandle` (issue 0035): the calling agent never supplies a tenant or
+store; the workspace is bound when the server is built. Multi-tenant request routing is a product concern (a product
+opens one workspace per corpus; `corpus` = the backend db name)."""
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from fastmcp import FastMCP
+
+from rag_wright.api.invoke import _index, ainvoke_subgraph, invoke_model
+from rag_wright.api.workspace import WorkspaceHandle
+
+_INVOKABLE_KINDS = ("subgraph", "model")
+
+
+def _jsonable(obj: Any) -> Any:
+    """Normalize an invoker result (a LangGraph state dict, a Pydantic model, or a list of them) to JSON-safe
+    data -- the structured content the calling agent receives."""
+    if hasattr(obj, "model_dump"):
+        return obj.model_dump(mode="json")
+    if isinstance(obj, dict):
+        return {k: _jsonable(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_jsonable(v) for v in obj]
+    return obj
+
+
+def build_capability_mcp(slug: str, *, resources: WorkspaceHandle, name: str | None = None) -> FastMCP:
+    """Build a FastMCP server exposing the catalogued capability `slug` as one MCP tool, driven by its ARD manifest.
+
+    The tool is named for the capability (its canonical slug -- stable + discoverable), titled with the manifest
+    display name, and described by the manifest description. It takes one `inputs` dict (the capability's input
+    contract) and dispatches through the engine invoker over `resources` (the bound workspace), returning the result
+    as JSON. Only `subgraph`/`model` kinds are supported.
+
+    Raises `KeyError` for an unknown slug; `ValueError` for a non-invokable kind."""
+    idx = _index()
+    if slug not in idx:
+        raise KeyError(f"unknown capability {slug!r} (not in the ARD catalog)")
+    spec = idx[slug]
+    if spec.kind not in _INVOKABLE_KINDS:
+        raise ValueError(
+            f"capability {slug!r} is kind {spec.kind!r}; only {_INVOKABLE_KINDS} are exposable via the generic "
+            f"MCP adapter (an mcp_tool is already an MCP tool; function/agent-skill have no invoker adapter yet)")
+
+    mcp: FastMCP = FastMCP(
+        name=name or f"rag-wright-{slug.replace('_', '-')}",
+        instructions=(
+            f"{spec.description}\n\nCall `{slug}` with an `inputs` object carrying the capability's inputs. "
+            f"Example queries: {'; '.join(spec.representative_queries)}."),
+    )
+    kind = spec.kind
+
+    @mcp.tool(name=slug, title=spec.display_name, description=spec.description)
+    async def _invoke_capability(inputs: dict) -> dict:
+        """Invoke the capability over the bound workspace.
+
+        Args:
+            inputs: The capability's input contract (e.g. {"query": ...} for a retrieval leg, or
+                {"text": ..., "functions": [...]} for a classifier). Dispatched straight to the engine invoker.
+
+        Returns:
+            {"result": <the capability's output as JSON>} -- a uniform envelope (a subgraph's state dict or a
+            model's soft-tag list both land under `result`), since the output contract varies by capability.
+        """
+        if kind == "subgraph":
+            out = await ainvoke_subgraph(slug, inputs, resources=resources)
+        else:  # model -- sync invoker; offload so the event loop is not blocked by local inference
+            out = await asyncio.to_thread(invoke_model, slug, inputs, resources=resources)
+        return {"result": _jsonable(out)}
+
+    return mcp
+
+
+def serve_capability_mcp(slug: str, *, resources: WorkspaceHandle, transport: str = "stdio") -> None:
+    """Serve one catalogued capability as an MCP tool over `transport` (default stdio, so an agent can spawn it)."""
+    build_capability_mcp(slug, resources=resources).run(transport=transport)

rag_wright/api/usage.py

@@ -0,0 +1,30 @@
+"""EP-API-5 (ADR-0117, ADR-0105): usage/cost on the engine API surface.
+
+A product measures the model usage an engine call incurs -- calls, input/output tokens, known cost (plus the count
+of calls the backend surfaced NO cost for), total latency, and a per-model breakdown -- by wrapping the call in
+`measure_usage()`. It is the public face of the engine's in-band usage accounting (`models/usage.usage_scope`), so
+the product reads stats without reaching into engine internals. Ambient (a `ContextVar`), additive across nesting
+(an outer scope totals everything; inner scopes attribute their slice), and carried into worker threads/executors.
+
+    with engine.measure_usage() as usage:
+        out = await engine.ainvoke_subgraph("intra_document_qa", {...}, resources=ws)
+    usage.calls, usage.input_tokens, usage.output_tokens, usage.cost_usd, usage.calls_without_cost,
+    usage.latency_ms_total, usage.by_model  # {model_id: ModelUsage(...)}
+"""
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Iterator
+
+from rag_wright.models.usage import ModelUsage, UsageTotals, usage_scope
+
+__all__ = ["measure_usage", "UsageTotals", "ModelUsage"]
+
+
+@contextmanager
+def measure_usage() -> Iterator[UsageTotals]:
+    """Accumulate the model usage of every engine call made inside the block; read the returned `UsageTotals`
+    after it. Nesting is additive, so a task-level scope totals everything while an inner per-call scope attributes
+    its slice. Capturing is opt-in: with no active scope, the engine records usage nowhere (zero overhead)."""
+    with usage_scope() as totals:
+        yield totals

rag_wright/api/workspace.py

@@ -0,0 +1,85 @@
+"""EP-API-1 (ADR-0117): `open_workspace` + the opaque `WorkspaceHandle`.
+
+The product names a `corpus` (the logical KG = the backend database name; the product maps its own tenant -> db-name,
+so tenancy stays product-owned) and gets back an opaque handle that resolves + caches the store (and lazily the
+embedder) from the `EngineConfig`. The handle is what the engine's per-kind invokers (EP-API-2) take as resources.
+The product never imports `ArcadeDBStore`/`query_embedder` and the handle exposes no public store accessor."""
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from rag_wright.api.config import EngineConfig
+from rag_wright.models.profiles import ModelRole, model_for
+
+logger = logging.getLogger(__name__)
+
+# Cached per (backend, host, port, corpus) -- one resolved workspace per customer DB (absorbs the product's
+# per-customer graph/store cache). Process-local; the embedder is lazy + per-handle.
+_WORKSPACES: dict[tuple, "WorkspaceHandle"] = {}
+
+
+class WorkspaceHandle:
+    """An opaque handle to a resolved engine workspace. Public surface: `model_id(role)`. The resolved store +
+    embedder are engine-internal (`_store` / `_embedder`), used by the invokers -- NOT a product accessor."""
+
+    def __init__(self, store: Any, config: EngineConfig, corpus: str) -> None:
+        self._store = store
+        self._config = config
+        self._corpus = corpus
+        self.__embedder: Any = None
+        self.__embedder_built = False
+
+    @property
+    def _embedder(self) -> Any:
+        """The query embedder for this workspace, built lazily on first use (so an ingest-only workspace -- or a
+        test -- needs no embedder backend). Best-effort: unavailable -> None (the consumer surfaces it)."""
+        if not self.__embedder_built:
+            self.__embedder = _build_embedder(self._config)
+            self.__embedder_built = True
+        return self.__embedder
+
+    def model_id(self, role: ModelRole) -> str:
+        """Resolve a model role to its id: the `EngineConfig.models` override wins, else the profile default."""
+        key = role.value if isinstance(role, ModelRole) else str(role)
+        return self._config.models.get(key) or model_for(role)
+
+
+def open_workspace(config: EngineConfig, *, corpus: str, reset: bool = False) -> WorkspaceHandle:
+    """Resolve (and cache) the workspace for `corpus` (the backend database name) from `config`. Ensures the schema.
+    Returns an opaque `WorkspaceHandle`. `reset=True` drops + recreates the database (test/clean-slate) and bypasses
+    the cache."""
+    sc = config.store
+    cache_key = (sc.backend, sc.host, sc.port, corpus)
+    if not reset and cache_key in _WORKSPACES:
+        return _WORKSPACES[cache_key]
+    store = _build_store(config, corpus, reset=reset)
+    store.ensure_schema()
+    handle = WorkspaceHandle(store, config, corpus)
+    _WORKSPACES[cache_key] = handle
+    return handle
+
+
+def _build_store(config: EngineConfig, corpus: str, *, reset: bool) -> Any:
+    sc = config.store
+    if sc.backend != "arcadedb":
+        raise ValueError(f"unsupported store backend: {sc.backend!r}")  # a new backend plugs in here (DD)
+    from rag_wright.store.arcadedb import ArcadeDBStore
+
+    return ArcadeDBStore.from_config(sc.host, sc.port, sc.user, sc.password, database=corpus,
+                                     protocol=sc.protocol, reset=reset, pack_ttl=config.pack)
+
+
+def _build_embedder(config: EngineConfig) -> Optional[Any]:
+    """The workspace's QUERY embedder, selected by the `text` embedding profile (EP-API-4b; default bge-m3). An
+    unknown profile raises; an unavailable backend degrades to None (the retrieval consumer surfaces it)."""
+    from rag_wright.capabilities.embedding_profiles import build_query_embedder
+
+    profile = config.embeddings.get("text", "bge-m3")
+    try:
+        return build_query_embedder(profile)
+    except ValueError:
+        raise  # an unknown profile is a config error, not a transient backend failure
+    except Exception:  # noqa: BLE001 - embedder backend unavailable -> None; the retrieval consumer surfaces it
+        logger.warning("engine_embedder_unavailable", exc_info=True)
+        return None

rag_wright/capabilities/__init__.py

@@ -0,0 +1,8 @@
+"""The FR-C capability catalog, each built and registered under its FR-C name.
+
+FR-C.1 Parsing (Docling), FR-C.2 Embedding (BGE-M3), FR-C.3 Hybrid search (ArcadeDB),
+FR-C.4 Reranking (BGE-reranker), FR-C.5 Graph query (ArcadeDB), FR-C.6 Graph extraction,
+FR-C.7 Entity resolution, FR-C.8 Ontology and registry derivation,
+FR-C.9 Reasoning, generation, and vision-to-text (Gemma 4), FR-C.10 RLM skill.
+Plus the ingestion-side (FR-I) and query-side (FR-Q) capability behavior.
+"""