rag-wright 0.3.1__tar.gz → 0.4.0__tar.gz

{rag_wright-0.3.1/src/rag_wright/.agents → rag_wright-0.4.0/.claude}/skills/building-an-ingestion-capability/SKILL.md

@@ -49,7 +49,9 @@ The unit is the text one extractor call reads. Get it right first; every other c
 - Units are capped at `IngestionTuning.max_unit_chars` (default 6000); a split table repeats its header row in each
   continuation unit.
 - A source is a file path or uploaded bytes: `IngestSource(path=...)`, or `IngestSource(data=..., name=...)` (the
-  name's extension picks the format), so an upload from object storage needs no temp file.
+  name's extension picks the format), so an upload from object storage needs no temp file. Attach your own fields to
+  a document with `IngestSource(metadata={...})`: they land on its `Document` node (and its embedded files') in the
+  same write, for `kg_read(ws, "Document", where=...)` to filter on.
 - If your documents mark units in a way layout does not show (a numbering scheme, a domain heading convention),
   override `unit_grouper=` or pass a `boundary_decider=` (candidate line texts -> "starts a new unit?" per text) to
   settle the lines the default grouper is unsure of. Domain conventions belong in your pack, never in the engine.
@@ -59,8 +61,10 @@ The unit is the text one extractor call reads. Get it right first; every other c
   Without it a unit is represented by its first member, which is usually its heading: the weakest text to tag and a
   poor citation. The reference contracts pack passes `provision_vote` (ADR-0126): the label with the highest
   probability summed over the non-heading members, cited by the member most confident in it; on 510 CUAD contracts
-  that beat heading-first by about 10 points. Measure your own rule on a gold set of your documents before choosing
-  it (the creating-evals skill).
+  that beat heading-first by about 10 points. Build the gold BEFORE you choose a rule: for a sample of your documents,
+  a short snippet from each unit you can label, with its expected label. Then compare rules with
+  `evaluate_ingestion(..., span_tagger=..., unit_representative=..., unit_labels=...)` (leave out
+  `unit_representative` for the first-member baseline) and keep the rule that labels best (the creating-evals skill).
 
 ## 3. Declare your record types in the pack `.ttl`
 
@@ -143,7 +147,8 @@ network-bound work inside it; the engine runs up to `IngestionTuning.extract_con
 
 ## 6. Verify (definition of done)
 
-1. `evaluate_ingestion` passes on a representative sample of YOUR documents (not a hand-picked easy one).
+1. `evaluate_ingestion` passes on a representative sample of YOUR documents (not a hand-picked easy one). If your
+   units carry labels, its `labels` report on your gold meets the bar you set, with the confusions understood.
 2. A live ingest of that sample: no dead letters, `extraction_failures` explained, records cite spans
    (`kg_read(ws, "<your type>", fields=["span_id"])`), and `span_positions(ws, doc_id)` gives the citation positions.
 3. A hermetic test of your extractor on fixed units (no model calls in the default suite; the engine's test network

{rag_wright-0.3.1 → rag_wright-0.4.0}/.claude/skills/creating-evals/SKILL.md

@@ -90,6 +90,17 @@ on a diagnostic).
 - **Ingestion structure**: `evaluate_ingestion` (in `rag_wright.api`) is the packaged structural eval of the
   ingestion hooks (tiling, table-row integrity, layout respect, coverage) on your own sample documents. Gate
   patterns: `eval/segmenter_eval.py`, `eval/unit_grouper_eval.py`.
+- **Unit labelling** (when a unit's leading tag is a label something acts on): the same call with your
+  `span_tagger`, any `unit_representative` and `unit_labels`, the gold `{<file name>: [{"text": <a snippet that
+  occurs in exactly one unit>, "label": <expected, "" for none>}]}`. It needs no knowledge graph, so build it before
+  the first ingest: label the units of a representative sample (headings, short fragments and units that should
+  carry no label included, not only clean examples). `labels` reports accuracy, per-label recall and precision, and
+  the confusion pairs, scored per unit. A snippet found in no unit or in several, and a unit whose snippets carry
+  different labels, are failures, because that gold cannot be scored (if your units hold several labelled things,
+  label the unit, not each thing in it).
+  Compare candidate representatives (and the first-member baseline) on the same gold. Reference example, numbers
+  only: the reference pack chose its rule this way on 510 documents with gold (ADR-0126): a vote over the non-heading
+  members labelled 56.6% of units correctly, against 46.8% for the first member (usually the heading).
 
 ## 3. Build the gold cheaply (without faking it)
 - **Silver bootstrapping**: a higher-capability teacher (LLM, or a decision model) labels candidate items; CURATE

{rag_wright-0.3.1/src/rag_wright/.agents → rag_wright-0.4.0/.claude}/skills/using-the-rag-wright-engine/SKILL.md

@@ -33,7 +33,8 @@ open-core and domain-neutral; your product brings the domain. Hard rules:
   `IngestionReport`), its hook contracts (`Segmenter`, `SpanTagger`, `UnitGrouper`, `BoundaryDecider`,
   `UnitRepresentative`, `BoundaryDiscoverer` with `default_chunk_discoverer(guidance=...)`, `Extractor`,
   `RecordWriter`, `DocumentHook`, checked by `check_tiling`/`check_units`/`check_extraction`), `IngestionTuning`,
-  `IngestSource` (a `path`, or `data` + `name` for bytes; `table_mode`, `include_hidden_sheets`) and
+  `IngestSource` (a `path`, or `data` + `name` for bytes; `table_mode`, `include_hidden_sheets`, your own `metadata`
+  for the document's `Document` node) and
   `evaluate_ingestion`. Your **pack's own code** (its capabilities, stores, graphs) also imports
   `rag_wright.pack_sdk`: identifiers and provenance, the model seam, the LangGraph scaffold, the `Store` protocol, the
   entity-graph building blocks (`build_graph_extraction`, `disambiguate`, `resolve_entities`, `EntityRules`,
@@ -67,6 +68,16 @@ contract/compliance worked example. The engine's `src/rag_wright/packs/reference
 registers in its constructor). Without it `ainvoke_subgraph` raises `KeyError` and the decision-model paths fall back
 silently to the LLM.
 
+The catalog is **one per process** (a known limitation): it is shared by every workspace, and registering a slug
+replaces it for all of them. Workspaces can differ in store, corpus and configuration, not in which implementation a
+slug resolves to. Tenants that need different implementations of one slug run in separate processes, or use one slug
+per implementation chosen per tenant in your code.
+
+**Workspaces.** One corpus and one `EngineConfig` per tenant, a `cache_dir` per tenant, document metadata on
+`IngestSource(metadata=...)`; models follow the workspace's `EngineConfig.models` in every call that takes it
+(`use_workspace_models(ws)` for a call that does not). To change a tenant's config, open its corpus again with the
+new config: a different config replaces the cached handle, no restart needed. `docs/workspaces.md` lists what applies per workspace, per call and per process.
+
 Repository paths in this skill (`docs/`, `eval/`, `scripts/`, `tests/`, `src/`) are in the engine repository: read them there or on GitHub, at the tag matching your installed engine.
 
 ## 2. Ground before you write (graphify)
@@ -97,7 +108,8 @@ The engine's `docs/` are NOT shipped in the wheel — read them in the engine re
 or on GitHub. Start with **Concepts** and **Architecture**, then the **domain-adaptation guide**
 (`docs/domain-adaptation/README.md`) — the 9-step sequence this skill operationalizes — and its companions
 (ontology authoring, KG construction, entity resolution, authoring capabilities, classification & decision models),
-plus **Quickstart**, **Reference pack**, and the generated **API reference** (`docs/api/`).
+plus **Quickstart**, **Workspaces** (`docs/workspaces.md`: per workspace, per call, per process), **Reference
+pack**, and the generated **API reference** (`docs/api/`).
 
 ## 4. Follow the build sequence
 

rag_wright-0.4.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.4.0"
+}

{rag_wright-0.3.1 → rag_wright-0.4.0}/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to RAG_Wright are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to follow
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0](https://github.com/fzaidi-dai/RAG_Wright/compare/0.3.1...0.4.0) (2026-10-09)
+
+
+### ⚠ BREAKING CHANGES
+
+* **PS-17:** rag_wright.pack_sdk.DEFAULT_GENERAL is removed (name the model you want instead), and the legacy tag-parse extractor no longer runs a Gemma list pass by default (set RAG_INGEST_LIST_MODEL to keep one).
+
+### Features
+
+* **PS-13:** document metadata on IngestSource ([cf2372d](https://github.com/fzaidi-dai/RAG_Wright/commit/cf2372d6ed9ecde761b823d322f7944a221f59d5))
+* **PS-14:** every role-based model call honours the workspace's EngineConfig.models ([a2d086a](https://github.com/fzaidi-dai/RAG_Wright/commit/a2d086a30026146fd78e068c647c12a3a2bd3c69))
+* **PS-16:** a workspace's configuration change takes effect without a restart ([d5f0bcd](https://github.com/fzaidi-dai/RAG_Wright/commit/d5f0bcd5f3dc6a88634caf4a64d6728078a22752))
+* **PS-R4:** unit-labelling eval in evaluate_ingestion ([2d33a31](https://github.com/fzaidi-dai/RAG_Wright/commit/2d33a3178a220b18c5c745d6f30168e1240a2abc))
+
+
+### Code Refactoring
+
+* **PS-17:** no Gemma default anywhere ([427fac0](https://github.com/fzaidi-dai/RAG_Wright/commit/427fac0f88b1772c2bb3fbbe47f1ec09f4f16d15))
+
 ## [0.3.1](https://github.com/fzaidi-dai/RAG_Wright/compare/0.3.0...0.3.1) (2026-10-09)
 
 

{rag_wright-0.3.1 → rag_wright-0.4.0}/CLAUDE.md

@@ -55,10 +55,10 @@ The failure mode to avoid, which has happened before: a command fails with "modu
 
 ## Start of every session
 
-> **CURRENT STATE (2026-10-09): the public-surface workstream is COMPLETE, pending the 0.3.0 release** (ledger
+> **CURRENT STATE (2026-10-09): the public-surface workstream is COMPLETE and released as `rag-wright` 0.3.1** (ledger
 > `docs/specs/public-surface/plan.md`, ADR-0128: two public tiers, `rag_wright.api` for a product's seam and
-> `rag_wright.pack_sdk` for a pack's code, enforced by import contracts and a domain-vocabulary guard). Next: cut
-> 0.3.0; RuleWright moves from `docs/specs/public-surface/rulewright-migration-0.3.0.md`; PS-R4 is tracked. Before it,
+> `rag_wright.pack_sdk` for a pack's code, enforced by import contracts and a domain-vocabulary guard). Next:
+> RuleWright moves (to 0.3.1+) from `docs/specs/public-surface/rulewright-migration-0.3.0.md`; PS-R4 (the unit-labelling eval) is done, unreleased. Before it,
 > the **ingestion-hooks** workstream (ADR-0124) is
 > COMPLETE and released as **`rag-wright` 0.2.0** (PyPI + GitHub tag/release `0.2.0`; release process
 > `docs/releasing.md`): the generic `build_ingestion` with hooks and domain-neutral defaults, the neutral default
@@ -76,7 +76,7 @@ The failure mode to avoid, which has happened before: a command fails with "modu
 > historical/superseded docs are under `docs/archive/`, and the ADR index is `docs/adr/README.md`.
 >
 > **The consolidated doc set** (engine-prep WS2/WS4, audited in ING-5): `docs/concepts.md`, `docs/architecture.md`,
-> `docs/installation.md`, `docs/configuration.md`, `docs/quickstart.md` (+ `examples/quickstart.py`),
+> `docs/installation.md`, `docs/configuration.md`, `docs/workspaces.md`, `docs/quickstart.md` (+ `examples/quickstart.py`),
 > `docs/reference-pack.md`, the generated `docs/api/`, and the domain-adaptation guide
 > `docs/domain-adaptation/` (ontology authoring, KG construction, entity resolution, authoring capabilities,
 > classification & decision models) + `_engine-gaps.md`. The product-starter templates are

{rag_wright-0.3.1 → rag_wright-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rag-wright
-Version: 0.3.1
+Version: 0.4.0
 Summary: A domain-retargetable, open-core engine for hybrid retrieval + knowledge-graph RAG: parsing, chunking, embedding, hybrid search, reranking, graph extraction, entity resolution, ontology-driven knowledge, and a capability runtime.
 Project-URL: Homepage, https://github.com/fzaidi-dai/RAG_Wright
 Project-URL: Repository, https://github.com/fzaidi-dai/RAG_Wright
@@ -105,7 +105,8 @@ here so the engine is demoable out of the box — your product brings its own do
 The whole doc set is under [`docs/`](docs/). Pick your path:
 
 - **New here?** Read [Concepts](docs/concepts.md) (the mental model), then run the [Quickstart](docs/quickstart.md).
-- **Installing / configuring?** [Installation](docs/installation.md) → [Configuration](docs/configuration.md).
+- **Installing / configuring?** [Installation](docs/installation.md) → [Configuration](docs/configuration.md) →
+  [Workspaces](docs/workspaces.md) (what applies per workspace, per call and per process).
 - **Building a product on the engine?** The [domain-adaptation guide](docs/domain-adaptation/) walks the whole
   sequence (author a `.ttl` pack → build & register capabilities → eval-first → ingest → entity resolution → the
   product seam); a coding agent should drive it with the `using-the-rag-wright-engine` skill.

{rag_wright-0.3.1 → rag_wright-0.4.0}/README.md

@@ -52,7 +52,8 @@ here so the engine is demoable out of the box — your product brings its own do
 The whole doc set is under [`docs/`](docs/). Pick your path:
 
 - **New here?** Read [Concepts](docs/concepts.md) (the mental model), then run the [Quickstart](docs/quickstart.md).
-- **Installing / configuring?** [Installation](docs/installation.md) → [Configuration](docs/configuration.md).
+- **Installing / configuring?** [Installation](docs/installation.md) → [Configuration](docs/configuration.md) →
+  [Workspaces](docs/workspaces.md) (what applies per workspace, per call and per process).
 - **Building a product on the engine?** The [domain-adaptation guide](docs/domain-adaptation/) walks the whole
   sequence (author a `.ttl` pack → build & register capabilities → eval-first → ingest → entity resolution → the
   product seam); a coding agent should drive it with the `using-the-rag-wright-engine` skill.

{rag_wright-0.3.1 → rag_wright-0.4.0}/docs/ARCHITECTURE_OVERVIEW.md

@@ -113,7 +113,7 @@ flowchart LR
   dv --> fuse["vector.fuse"]
   sv --> fuse
   fuse --> pool["candidate pool (+ property/metadata boost)"]
-  pool --> rr["rerank (BGE reranker / Gemma listwise)"]
+  pool --> rr["rerank (BGE reranker)"]
   rr --> top["top-k, cited"]
 ```
 
@@ -210,7 +210,7 @@ Two registries:
 | Chunking (single-call / RLM discoverer) | ingestion `chunk` |
 | Embedding (BGE-M3, dense+sparse) | `index_spans`, query |
 | Hybrid search (dense+sparse fuse) | `hybrid_search` / `span_hybrid_search` |
-| Reranking (BGE reranker / Gemma listwise) | query rerank stage |
+| Reranking (BGE reranker) | query rerank stage |
 | Graph extraction | clauses (classifier fleet + Jev residual values) + parties (docling-graph) + affiliations (tag-parse, only when a cue word is present) |
 | Entity resolution | `resolve` (canonical id from the configured registry; EDGAR CIK for the CUAD corpus) |
 | Ontology-driven schema/vocab | the `.ttl` layer (all stages) |

{rag_wright-0.3.1 → rag_wright-0.4.0}/docs/api/README.md

@@ -124,9 +124,9 @@ When `auto` treats a table as a DATABASE (one unit per row): a header of `min_he
 
 What counts as a record IDENTIFIER when linking an embedded file to a row: a token (4+ chars, contains a digit) on at most `max_rows` table rows and in at most `max_files` embedded files.
 
-### `IngestSource(*, path: Optional[str] = None, data: Optional[bytes] = None, name: Optional[str] = None, doc_id: Optional[str] = None, table_mode: Literal['auto', 'record', 'block'] = 'auto', include_hidden_sheets: bool = True) -> None`
+### `IngestSource(*, path: Optional[str] = None, data: Optional[bytes] = None, name: Optional[str] = None, doc_id: Optional[str] = None, table_mode: Literal['auto', 'record', 'block'] = 'auto', include_hidden_sheets: bool = True, metadata: Optional[dict[str, Any]] = None) -> None`
 
-One document to ingest: either a file `path`, or in-memory `data` (bytes, e.g. an upload) with its file `name` (the extension picks the format); its `doc_id` (default: derived from the file name), how its tables are grouped (`auto` decides per table; `record` / `block` force one mode), and whether hidden spreadsheet sheets are ingested.
+One document to ingest: either a file `path`, or in-memory `data` (bytes, e.g. an upload) with its file `name` (the extension picks the format); its `doc_id` (default: derived from the file name), how its tables are grouped (`auto` decides per table; `record` / `block` force one mode), whether hidden spreadsheet sheets are ingested, and the product's own `metadata` (PS-13): written onto the document's `Document` node in the same write as the engine's fields, and onto each embedded file's. Keys are identifiers that do not shadow an engine field (`doc_id`, `parent_doc_id`, `filename`, `media_type`, `sha256`); values are strings, numbers, booleans, None or lists of those. Read or filter it with `kg_read(ws, "Document", where={...})`; change it later with `kg_update`.
 
 #### `IngestSource.read_bytes(self) -> 'bytes'`
 
@@ -142,7 +142,7 @@ Advanced: the individual stage functions bound to a workspace (its store, ingest
 
 #### `IngestionPipeline.aingest(self, ws: 'Any', sources: 'Sequence[Union[str, Path, IngestSource]]', *, cache_dir: 'Union[str, Path]') -> 'IngestionReport'`
 
-Ingest every source (and its embedded children) into the workspace `ws` (from `open_workspace`). `sources` are file paths or `IngestSource`s (a path, or in-memory bytes with a file name); `cache_dir` holds the content-hash-gated parse and chunk caches (a re-ingest of an unchanged file re-uses them). Documents run concurrently up to `tuning.document_concurrency`; a document that fails is dead-lettered in its `DocumentReport`, never raised. Returns the `IngestionReport`.
+Ingest every source (and its embedded children) into the workspace `ws` (from `open_workspace`). `sources` are file paths or `IngestSource`s (a path, or in-memory bytes with a file name); `cache_dir` holds the content-hash-gated parse and chunk caches (a re-ingest of an unchanged file re-uses them). Documents run concurrently up to `tuning.document_concurrency`; a document that fails is dead-lettered in its `DocumentReport`, never raised. Returns the `IngestionReport`. Every model role resolves through the workspace's `EngineConfig.models` (PS-14).
 
 ### `IngestionReport(documents: 'list[DocumentReport]' = <factory>) -> None`
 
@@ -152,14 +152,18 @@ The result of `IngestionPipeline.aingest`: one `DocumentReport` per document (em
 
 What ingesting one document did. Counts: `chunks`, `spans` (indexed), `units` (extracted), `records` (nodes written). `extraction_failures` (`{unit, anchor, reason}`) / `span_failures` (`{span_id, reason}`): the units / spans whose extraction or indexing failed; the rest of the document still lands. `skipped_hidden_sheets`: hidden spreadsheet sheets left out (`IngestSource.include_hidden_sheets=False`). `children`: the ids of embedded files and PDF attachments ingested as child documents (`parent_doc_id` is set on theirs); `embedded_skipped`: embedded files that could not be ingested. `links`: `AttachedTo` record links written, by confidence; `unmapped_links`: links whose record row could not be found. `dead_letter`: why the whole document failed (None when it landed).
 
-### `IngestionEvaluation(documents: 'list[DocumentEvaluation]' = <factory>, failures: 'list[str]' = <factory>, unlabelled_tables: 'list[str]' = <factory>) -> None`
+### `IngestionEvaluation(documents: 'list[DocumentEvaluation]' = <factory>, failures: 'list[str]' = <factory>, unlabelled_tables: 'list[str]' = <factory>, labels: 'Optional[LabelEvaluation]' = None) -> None`
 
 The result of `evaluate_ingestion`: per-document measures, the `failures` (each check that did not hold, by document) and `unlabelled_tables` (tables no `table_labels` pattern matched). `passed` (property) is True when there are no failures.
 
-### `DocumentEvaluation(doc: 'str', tiles: 'bool' = True, spans: 'int' = 0, units: 'int' = 0, table_rows: 'int' = 0, table_row_integrity: 'Optional[float]' = None, layout_respect: 'Optional[float]' = None, bare_heading_spans: 'int' = 0, headings_start_units: 'Optional[float]' = None, tables: 'int' = 0, tables_whole: 'Optional[float]' = None, furniture_in_units: 'int' = 0, coverage: 'Optional[float]' = None, cap_ok: 'bool' = True, table_modes: 'list[dict]' = <factory>, embedded_children: 'int' = 0, error: 'Optional[str]' = None) -> None`
+### `DocumentEvaluation(doc: 'str', tiles: 'bool' = True, spans: 'int' = 0, units: 'int' = 0, table_rows: 'int' = 0, table_row_integrity: 'Optional[float]' = None, layout_respect: 'Optional[float]' = None, bare_heading_spans: 'int' = 0, headings_start_units: 'Optional[float]' = None, tables: 'int' = 0, tables_whole: 'Optional[float]' = None, furniture_in_units: 'int' = 0, coverage: 'Optional[float]' = None, cap_ok: 'bool' = True, table_modes: 'list[dict]' = <factory>, embedded_children: 'int' = 0, label_results: 'list[dict]' = <factory>, error: 'Optional[str]' = None) -> None`
 
 One sample document's structural measures. Segmentation: `tiles` (spans tile every chunk), `table_row_integrity` (share of table rows that are their own span), `layout_respect` (share of spans inside one layout item), `bare_heading_spans`. Grouping: `headings_start_units` (share of headings that start a unit), `tables_whole` (share of tables kept whole or split by the record/header rule), `furniture_in_units` (page furniture that leaked into units), `coverage` (share of content spans in some unit), `cap_ok` (every unit within `max_unit_chars`). `table_modes`: the mode chosen per table. `error`: why the document could not be evaluated.
 
+### `LabelEvaluation(gold: 'int' = 0, correct: 'int' = 0, accuracy: 'Optional[float]' = None, per_label: 'dict[str, dict]' = <factory>, confusions: 'list[dict]' = <factory>, unmatched: 'list[str]' = <factory>, ambiguous: 'list[str]' = <factory>, conflicting: 'list[str]' = <factory>) -> None`
+
+Unit labelling against the gold (`evaluate_ingestion(unit_labels=...)`), scored per UNIT: snippets that land in the same unit with the same label count once. `gold`: units scored; `correct`: those whose label matches; `accuracy`: correct / gold. `per_label`: `{label: {gold, predicted, correct, recall, precision}}` over the gold units (precision is among the gold units predicted with that label; `None` when none were). `confusions`: `{gold, predicted, count}` for every wrong pair, most frequent first. `unmatched` / `ambiguous`: `"<doc>: <snippet>"` for a snippet found in no unit / in several. `conflicting`: `"<doc>: unit <i>: <labels>"` for a unit whose snippets carry different labels (not scored: one label cannot match them all). An empty label means the unit should carry none.
+
 ### `TableRow(*, table_ref: str, sheet: Optional[str] = None, page: Optional[int] = None, row_index: int, columns: list[str], values: list[str]) -> None`
 
 ING-7: one data row of a parsed table, read from the parse's cell GRID (exact cell text, whitespace collapsed) -- whole even when the chunker split the table. `columns` is the table's first row as parsed; `row_index` is the 0-based grid row (data rows start at 1). Domain-neutral: what a column MEANS is the domain's decision.
@@ -224,10 +228,16 @@ The semantic boundary-discovery seam: decide chunk boundaries as a partition of
 
 Resolve (and cache) the workspace for `corpus` (the backend database name) from `config`. Ensures the schema: the neutral engine types, plus `config.pack`'s declared types when set. Raises `RuntimeError` on a database whose `Span` type still has the pre-ING-8d field names (migrate it with `scripts/migrate_span_fields.py`). Returns an opaque `WorkspaceHandle`. `reset=True` drops + recreates the database (test/clean-slate) and bypasses the cache.
 
+One handle per store and corpus is cached for the process. An equal `config` returns it; a different one (new models, options, credentials or pack) returns a new handle that replaces it from then on, so a configuration change takes effect without a restart (PS-16). The new handle reuses the store when the store settings and the pack are unchanged, and the query embedder when the embedding profile is unchanged; a call still holding the old handle finishes on the old config.
+
 ### `pack_store(ws: 'WorkspaceHandle', cls: 'Callable[..., _T]', *args: 'Any', **kwargs: 'Any') -> '_T'`
 
 Build a pack's store extension (or any object that wraps the workspace store) over the workspace's store: `cls(<store>, *args, **kwargs)`, e.g. `pack_store(ws, MyPackStore)`. The store it receives implements the engine's `Store` protocol (`kg_read` / `kg_write` / `kg_edges` / `kg_count` / `kg_delete` / `kg_update` and the rest); the workspace keeps the store itself private, so this is the one way a product hands it to a pack.
 
+### `use_workspace_models(ws: 'Any') -> 'Iterator[None]'`
+
+Resolve every model role through `ws`'s `EngineConfig.models` inside the block (PS-14), ahead of the `RAG_MODEL_*` environment. The engine's own entry points that take a workspace (`aingest`, the invokers) do this for you; use it around engine calls that take no workspace, such as `parse_document_bytes` (OCR) or a `default_chunk_discoverer` run, when the workspace overrides those roles. Per call, never shared: concurrent blocks for different workspaces each see their own models.
+
 ### `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).
@@ -380,10 +390,12 @@ The engine's generic ingestion pipeline: pass your `extractor` (a `Unit` -> `Uni
 
 PS-R5b: the engine's default chunk-boundary rule (structural boundaries first; `chunk_model` refines only an over-cap section, through a domain-neutral prompt) with your domain's `guidance` added to that prompt (e.g. what a coherent unit is in your documents). Pass it as `build_ingestion(chunk_discoverer=...)`.
 
-### `evaluate_ingestion(sources: 'Sequence[Union[str, Path, IngestSource]]', *, cache_dir: 'Union[str, Path]', tuning: 'Optional[IngestionTuning]' = None, segmenter: 'Optional[Segmenter]' = None, unit_grouper: 'Optional[UnitGrouper]' = None, table_labels: 'Optional[list[dict[str, Any]]]' = None) -> 'IngestionEvaluation'`
+### `evaluate_ingestion(sources: 'Sequence[Union[str, Path, IngestSource]]', *, cache_dir: 'Union[str, Path]', tuning: 'Optional[IngestionTuning]' = None, segmenter: 'Optional[Segmenter]' = None, unit_grouper: 'Optional[UnitGrouper]' = None, table_labels: 'Optional[list[dict[str, Any]]]' = None, span_tagger: 'Optional[SpanTagger]' = None, unit_representative: 'Optional[UnitRepresentative]' = None, unit_labels: 'Optional[dict[str, list[dict[str, str]]]]' = None) -> 'IngestionEvaluation'`
 
 Measure the ingestion hooks' structural fidelity on YOUR sample documents, before trusting them. Runs parse, chunk, segment and group only (no store, no model calls) with the default hooks or the `segmenter` / `unit_grouper` you pass, under `tuning`. Checks: spans tile the text, table rows stay whole, spans respect layout items, no bare-heading spans, headings start units, tables stay whole (or split per row for a record table), no page furniture in units, full coverage, units within the cap. `table_labels` (`[{"pattern": <regex on the header row>, "label": "record" | "block"}]`, first match wins) also checks each table's mode. Returns an `IngestionEvaluation`; tune `IngestionTuning` until `passed`.
 
+Labelling (PS-R4): pass your `span_tagger` (and any `unit_representative`) with `unit_labels`, the gold `{<document file name>: [{"text": <a snippet that occurs in exactly one unit>, "label": <expected label, "" for none>}]}`, and `labels` (a `LabelEvaluation`) reports each gold unit's label against it: accuracy, per-label results, confusion pairs. The tagger is yours, so it may call models; nothing else does.
+
 ### `table_rows(source_document: 'Any') -> 'list[TableRow]'`
 
 Every data row of every table in a parsed document (`parse_document` output), in document order.

{rag_wright-0.3.1 → rag_wright-0.4.0}/docs/api/pack_sdk.md

@@ -184,9 +184,9 @@ Group into units (checked), attach table rows, extract each unit concurrently (p
 
 Persist the records (the domain's writer, else `kg_write`). Returns the number of record nodes.
 
-#### `IngestionStages.write_document_node(self, doc_id: 'str', *, parent_id: 'Optional[str]', filename: 'str', media_type: 'str', sha256: 'str') -> 'None'`
+#### `IngestionStages.write_document_node(self, doc_id: 'str', *, parent_id: 'Optional[str]', filename: 'str', media_type: 'str', sha256: 'str', metadata: 'Optional[dict]' = None) -> 'None'`
 
-_(no docstring)_
+The `Document` node: the engine's fields plus the product's `metadata` (PS-13), in one write.
 
 #### `IngestionStages.write_child_links(self, parent_id: 'str', child: 'Any', row_spans: 'dict', rep: 'DocumentReport') -> 'None'`
 
@@ -244,12 +244,6 @@ str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
 
 Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.
 
-### `DEFAULT_GENERAL`
-
-str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
-
-Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.
-
 ### `DEFAULT_RETRY`
 
 Configuration for retrying nodes.
@@ -294,7 +288,7 @@ Composes `doc_start = chunk_doc_start + op.start`, `doc_end = chunk_doc_start +
 
 ### `model_for(role: 'ModelRole') -> 'str'`
 
-Resolve a role to a model id. Precedence (all config, MS1-2): the ROLE-SPECIFIC override (`RAG_MODEL_<ROLE>`) > the ALL-ROLES override (`RAG_MODEL_ALL`, to point every role at one model for a quick cross-model test) > the documented default. So a run can swap one role, or every role, purely by env.
+Resolve a role to a model id. Precedence: the active workspace's `EngineConfig.models` (PS-14, see `scoped_models`) > the ROLE-SPECIFIC override (`RAG_MODEL_<ROLE>`) > the ALL-ROLES override (`RAG_MODEL_ALL`, to point every role at one model for a quick cross-model test) > the documented default.
 
 ### `profile_for(model_id: 'str') -> 'ModelProfile'`
 

{rag_wright-0.3.1 → rag_wright-0.4.0}/docs/architecture.md

@@ -106,6 +106,16 @@ graph structure. The reference query capabilities are `intra_document_qa`, `type
 See [`concepts.md`](concepts.md) for both seams in context, and [`configuration.md`](configuration.md) for the
 knobs.
 
+## Known limitations
+
+- **One capability catalog per process.** The runtime catalog that `register_capability` fills is shared by every
+  workspace in the process, and registering a slug replaces it for all of them, including the later steps of a run
+  already in progress. Workspaces in one process can differ in store, corpus and configuration, but not in which
+  implementation a slug resolves to. A product whose tenants need different implementations of the same slug runs
+  them in separate processes. There is no plan to change this; raise it if a product needs it.
+- **One handle per corpus, and per-process settings.** What applies per workspace, per call and per process, and
+  how a configuration change for an open corpus takes effect, is in [`workspaces.md`](workspaces.md).
+
 ## Pointers
 
 - [`ARCHITECTURE_OVERVIEW.md`](ARCHITECTURE_OVERVIEW.md) — the detailed as-built pipeline (diagrams, model defaults,

{rag_wright-0.3.1 → rag_wright-0.4.0}/docs/concepts.md

@@ -118,9 +118,11 @@ report = await pipeline.aingest(ws, sources, cache_dir="cache/")
   row), and the default writer uses `kg_write`. `document_hook(ws, source_document, chunks)` runs once per document
   after its records are written (for example, a domain's entity graph).
 - **Inputs and tuning.** `sources` are paths or `IngestSource` objects (a per-document `doc_id`, `table_mode` of
-  `auto`/`record`/`block`, `include_hidden_sheets`). Every structural threshold is in `IngestionTuning`; set it from
+  `auto`/`record`/`block`, `include_hidden_sheets`, and your own `metadata`, stored on the document's `Document`
+  node). Every structural threshold is in `IngestionTuning`; set it from
   `evaluate_ingestion(sources, cache_dir=...)`, which scores tiling, layout respect, table-row integrity and coverage
-  on your own samples without any model call. `table_rows(source_document)` reads a parsed table's rows from the
+  on your own samples without any model call, and (given your span tagger and a small gold set of unit labels) how
+  well units are labelled. `table_rows(source_document)` reads a parsed table's rows from the
   cell grid, whole even when the chunker split the table.
 
 The reference contract pipeline (`contract_ingestion_pipeline`) drives these same stages with legal hooks. Hook signatures are in the

{rag_wright-0.3.1 → rag_wright-0.4.0}/docs/configuration.md

@@ -29,7 +29,8 @@ ws = open_workspace(config, corpus="my_corpus", reset=False)   # corpus = the ba
 
 `open_workspace(config, *, corpus, reset=False)` resolves and caches a workspace and ensures the schema. `corpus`
 is the backend database name (tenancy is the product's concern); `reset=True` drops and recreates it and bypasses
-the cache.
+the cache. Opening a cached corpus with a different config returns a new handle that replaces the cached one, so a
+configuration change takes effect without a restart ([`workspaces.md`](workspaces.md)).
 
 ### `StoreConfig`
 
@@ -79,6 +80,19 @@ cfg = EngineConfig(store=..., options=EngineOptions(packs={"contracts": Contract
 Models are chosen by **role** (`ModelRole`) and resolved to a concrete model by a **profile** keyed by model id —
 never a hardcoded provider flag. Override a role per workspace via `EngineConfig.models`, or globally via env.
 
+**Per workspace.** A role resolves to the active workspace's `EngineConfig.models` entry first, then
+`RAG_MODEL_<ROLE>`, then `RAG_MODEL_ALL`, then the default. Every engine call that takes a workspace (ingestion
+through `aingest`, the `invoke_*` / `ainvoke_*` calls and the MCP tools built on them, `agenerate_answer`,
+`ajudge_spans`) runs under that workspace's models, and concurrent calls for different workspaces each see their
+own. Wrap a call that takes no workspace in `with use_workspace_models(ws):`, for example `parse_document_bytes`
+(its OCR escalation uses `VISION_OCR`) or a `default_chunk_discoverer` run. Not per workspace, set once for the
+process: the serving backend and its endpoints (`RAG_SERVING`, `VLLM_BASE_URL`, `OPENROUTER_*`), the decision
+model's profile (`RAG_DECISION_MODEL`; a call can name one in the `jev_decision` input `model`), the call timeouts,
+the trained classifier weights (`RAG_MODELS_DIR`), and the reference pack's graph-extraction model
+(`RAG_GRAPH_EXTRACT_MODEL`) and standalone MCP servers, which resolve their models from the environment when they
+start. [`workspaces.md`](workspaces.md) has the full picture: what applies per workspace, per call and per process,
+and how to manage workspaces.
+
 - **Serving backend** — `RAG_SERVING` selects `openrouter` (default) or `vllm` (self-hosted). For vLLM set
   `VLLM_BASE_URL` and `VLLM_API_KEY`; for OpenRouter set `OPENROUTER_API_KEY` (optionally `OPENROUTER_PROVIDER`, a
   comma-separated provider list, with `OPENROUTER_ALLOW_FALLBACKS` to allow routing beyond it; the contracts pack's
@@ -112,7 +126,7 @@ Prefer config; use env for secrets and for non-API callers. The common ones the
 | `RAG_MODEL_<ROLE>` (e.g. `RAG_MODEL_GENERAL`, `RAG_MODEL_VISION_OCR`) / `RAG_MODEL_ALL` / `RAG_GRAPH_EXTRACT_MODEL` / `RAG_DECISION_MODEL` | model overrides (one role / all roles / graph extraction / decision-model profile) |
 | `RAG_SEMANTIC_JUDGE` / `RAG_RESIDUAL_EXTRACTOR` | set to `llm` to move the reference pipeline's extraction judge / residual property values off the decision model |
 | `CLASSIFY_CONCURRENCY` / `CLAUSE_CONCURRENCY` / `RAG_INGEST_AFFILIATIONS` / `RAG_FUNCTION_CLASSIFIER` | contracts-pack ingest knobs (mirror `ContractIngestOptions`) |
-| `RAG_INGEST_LIST_MODEL` / `RAG_INGEST_CLAUSE_SAMPLES` / `RAG_INGEST_CLAUSE_EXTRACTOR` | read only by the contracts pack's legacy tag-parse clause extractor, which the default pipeline does not use (it is classifier-first) |
+| `RAG_INGEST_LIST_MODEL` / `RAG_INGEST_CLAUSE_SAMPLES` / `RAG_INGEST_CLAUSE_EXTRACTOR` | read only by the contracts pack's legacy tag-parse clause extractor, which the default pipeline does not use (it is classifier-first); its second list model runs only when `RAG_INGEST_LIST_MODEL` names one (no default model) |
 | `RAG_STRUCTURED_TIMEOUT_S` / `RAG_JEV_TIMEOUT_S` / `RAG_JUDGE_TIMEOUT_S` / `RAG_RELEVANCE_TIMEOUT_S` | call timeouts (raise for reasoning-ON bulk work) |
 | `RAG_SPACY_MODEL` | the spaCy model name for the optional NER extra |
 | `RAG_MODELS_DIR` | the models root every trained classifier loads its weights from (default: the engine checkout's `data/models` when it exists, else `./data/models`); fill it with `scripts/fetch_reference_models.py` for the reference pack |

{rag_wright-0.3.1 → rag_wright-0.4.0}/docs/domain-adaptation/README.md

@@ -17,7 +17,8 @@ ADR-0117/0118 engine API + capability runtime). Read [Concepts](../concepts.md)
 2. **Configure the engine.** Construct an `EngineConfig` (store, model roles, embedding profile, and the options
    catalog: the generic ingest `tuning`, plus your pack's own options under `EngineOptions.packs`) and
    `open_workspace(config, corpus=…) -> WorkspaceHandle`. `corpus` is the backend DB name; tenancy is
-   product-side. → [Configuration](../configuration.md).
+   product-side: one corpus and one config per tenant, with the settings that stay per process listed in
+   [Workspaces](../workspaces.md). → [Configuration](../configuration.md).
 
 3. **Author the domain `.ttl` pack.** The domain KNOWLEDGE — closed value sets, the KG schema, SHACL constraints,
    mappings — lives in the ontology, declaratively, never in Python (ADR-0066). It co-evolves with step 4 (it

{rag_wright-0.3.1 → rag_wright-0.4.0}/docs/domain-adaptation/authoring-capabilities.md

@@ -93,6 +93,12 @@ def register() -> None:
 `for m in engine_capabilities(): register_capability(m)` (or from your pack's `register()`, as above);
 otherwise `ainvoke_model("jev_decision", ...)` raises `KeyError` (unknown capability).
 
+**One catalog per process (a known limitation).** The catalog is shared by every workspace in the process:
+registering a slug replaces it for all of them, including the later steps of a run already in progress, so register
+once at startup. To give tenants different implementations of one slug (for example a decision model for one and a
+trained classifier for another), run them in separate processes, or register one slug per implementation and choose
+the slug per tenant in your own code.
+
 **Discovery.** Once registered, a product agent finds your capability two ways: `capability_index()` — the flat
 `{slug: {kind, description}}` listing (what exists) — or **`discover(task, resources=ws)`** — embedding-ranked
 selection over the live catalog for a task (returns the top matches by BGE-M3 similarity to each capability's

{rag_wright-0.3.1 → rag_wright-0.4.0}/docs/domain-adaptation/kg-construction.md

@@ -89,11 +89,43 @@ the run goes on. Every node and edge type your extractor returns must be declare
   6,000), the fragment floor, the database-table rule (`RecordTableRule`), the identifier rule for linking embedded
   files to rows (`IdentifierRule`), and the two concurrency limits. Set it on the builder or on
   `EngineConfig.options.ingest.tuning`.
+- **`IngestSource.metadata`**: your own fields for a document (an owner, a case number, tags, a received date),
+  written onto its `Document` node in the same write as the engine's fields, and onto each of its embedded files'.
+  Keys are identifiers that do not shadow an engine field (`doc_id`, `parent_doc_id`, `filename`, `media_type`,
+  `sha256`); values are strings, numbers, booleans, `None` or lists of those. Read and filter it with
+  `kg_read(ws, "Document", where={"owner": "team-a"})`, then pass the matching document ids to a query's document
+  scope (spans and records do not carry it). A re-ingest without metadata leaves it in place, and one with metadata
+  updates the keys it gives; change it at any time with `kg_update(ws, "Document", set={...}, where={"doc_id": ...})`.
+
+  ```python
+  from rag_wright.api import IngestSource, kg_read
+
+  src = IngestSource(path="intake/report-118.pdf", metadata={"owner": "team-a", "tags": ["q3", "audit"]})
+  report = await pipeline.aingest(ws, [src], cache_dir="cache/")
+  team_a = [r["doc_id"] for r in kg_read(ws, "Document", where={"owner": "team-a"}, fields=["doc_id"])]
+  ```
 - **`IngestSource.table_mode`**: `auto` (default) decides per table whether it is a database (one unit per row) or a
   form (one unit); `record` and `block` force one mode for that source.
 - **`evaluate_ingestion(sources, cache_dir=..., tuning=..., table_labels=...)`** runs the structural stages (parse,
   deterministic chunk, segment, group; no model, no store) on your own samples and reports `passed` / `failures`. Use
-  it to set `IngestionTuning` before a full run.
+  it to set `IngestionTuning` before a full run. It also measures unit **labelling** without a knowledge graph: pass
+  your `span_tagger` (and any `unit_representative`) with `unit_labels`, a small gold set of units, each found by a
+  snippet that occurs in it alone, with its expected label (`""` for none). `labels` reports accuracy, per-label
+  results and the confusion pairs, per unit; a snippet found in no unit or in several, and a unit given different
+  labels by its snippets, are reported as failures. Compare a representative rule against the first-member baseline on the same gold:
+
+  ```python
+  from rag_wright.api import evaluate_ingestion
+
+  gold = {"spec_sheet.pdf": [
+      {"text": "knitted on a 30-inch machine", "label": "construction"},
+      {"text": "Customer: Northwind Apparel", "label": ""},
+  ]}
+  baseline = evaluate_ingestion(samples, cache_dir="cache/", span_tagger=my_tagger, unit_labels=gold)
+  voted = evaluate_ingestion(samples, cache_dir="cache/", span_tagger=my_tagger, unit_representative=vote,
+                             unit_labels=gold)
+  print(baseline.labels.accuracy, voted.labels.accuracy, voted.labels.confusions[:5])
+  ```
 - **`table_rows(source_document)`** returns every parsed table's data rows (`TableRow`: `columns`, `values`,
   `cell(name)`, table ref, sheet or page, row index), read from the parse's cell grid, so a table split across chunks
   comes back whole. What a column means is your domain's decision.

{rag_wright-0.3.1 → rag_wright-0.4.0}/docs/specs/public-surface/plan.md

@@ -76,7 +76,7 @@ in two at the PS-6 gate so the store rewrite is its own visible task. One task,
 | PS-R1 | Found in PS-8a's live check: every Qwen3.8-27b call hangs to its deadline while OpenRouter's `deepinfra/bf16` endpoint is down (0% uptime), because ADR-0111 hard-pins it with fallbacks off. Remove the provider routing entirely (your decision: unpinned; classifiers + Jev carry the critical decisions, FP8 validated on Modal); ADR-0125 supersedes ADR-0111 | profile tests; live seam + party extraction succeed during the outage | done: no provider routing on the three OpenRouter Qwen profiles; ADR-0125 supersedes 0111; live during the outage: seam 1.6 s, party extraction 8.0 s (pinned: hung to the deadline) |
 | PS-R2 | A failed party (graph) extraction no longer dead-letters the document: the clause records are kept and the failure is reported | hermetic degrade test; live ingest keeps its clauses | done: `extract_graph` best-effort after its retries; `graph_failures` -> a `graph` kind in `build_partial_entry` (optional trailing arg) in both drivers; live: forced graph failure kept 6 clauses + 12 spans, no dead-letter |
 | PS-R3 | Which member span represents a unit is a domain decision: engine hook `unit_representative` (a `UnitRepresentative`: the unit's member spans -> its anchor + leading tag) on `build_ingestion` / `IngestionStages`; the reference pack's rule chosen by measurement (heading-first vs operative span vs votes) on all 510 CUAD contracts against CUAD gold; docs tell products what the hook does and why | hook tests; CUAD rule comparison (local, CUAD outputs never committed); live ingest | done: `UnitRepresentative` hook; reference rule `provision_vote` (D) chosen on 510 CUAD contracts (56.6% vs 46.8% heading-first); probabilities via `with_probabilities` + `TaggedSpan.scores`; ADR-0126 |
-| PS-R4 | A new domain can measure its unit labelling without a KG: `evaluate_ingestion` gains `span_tagger=`, `unit_representative=` and `unit_labels=` (gold: per document, each unit by a text snippet with its expected label) and reports label accuracy, per-label results and confusion pairs; the creating-evals skill gains a unit-labelling entry; building-an-ingestion-capability says to build this gold before choosing a `unit_representative`; the CUAD run is the documented reference example (numbers only) | hermetic tests; a worked example on sample documents | todo |
+| PS-R4 | A new domain can measure its unit labelling without a KG: `evaluate_ingestion` gains `span_tagger=`, `unit_representative=` and `unit_labels=` (gold: per document, each unit by a text snippet with its expected label) and reports label accuracy, per-label results and confusion pairs; the creating-evals skill gains a unit-labelling entry; building-an-ingestion-capability says to build this gold before choosing a `unit_representative`; the CUAD run is the documented reference example (numbers only) | hermetic tests; a worked example on sample documents | done: `evaluate_ingestion(span_tagger=, unit_representative=, unit_labels=)` -> `IngestionEvaluation.labels` (`LabelEvaluation`: accuracy, per-label recall/precision, confusion pairs, scored per unit; unmatched / ambiguous snippets and conflicting unit gold are failures); creating-evals + ingestion skill + kg-construction + concepts; live CUAD check (50 random contracts, reference hooks, local SetFit): vote 65.3% vs first-member 44.2% on 95 scored units, directionally ADR-0126 |
 | PS-R5a | Domain vocabulary out of the generic engine, public surface first (blocks 0.3.0): the relevance judge (`Condition.clause_type` -> `category`, its SKILL.md + prompt) and the generation method become domain-neutral, with the contract wording in a reference-pack guidance overlay; neutral discovery text in the engine capability manifests; neutral docstring examples; a vocabulary guard test (zero tolerance in engine skills, manifests and public API docstrings; a per-file ratchet elsewhere) complementing the import-linter | guard test; relevance + generation tests; live judge + answer | done: neutral relevance judge (`Condition.category`) + generation method with pack `guidance` overlays; neutral manifests + docstrings; vocabulary guard (zero tolerance + ratchet at 156 lines / 24 files); live judge + answer |
 | PS-R5b | RLM chunking prompts domain-neutral (domain hints supplied by the pack) and a `build_ingestion(chunk_discoverer=)` hook + `default_chunk_discoverer(guidance=)` so a product can set them; the entity-canonicalisation word lists (party words, party-definition fragments) moved into the pack `.ttl` (ADR-0066) | guard ratchet lowered; chunking + canonicalisation tests; live ingest | done: neutral chunking prompts with `guidance=` (pack passes contract guidance); `build_ingestion(chunk_discoverer=)` + `default_chunk_discoverer(guidance=)` + `BoundaryDiscoverer` exported; `EntityRules` with the contract roles on `cbr:entityRules` in the `.ttl`; ratchet 156 -> 133 lines; live: same 2 entities + 1 edge, over-cap chunking split per guidance |
 | PS-R5c | Retire OKF (user decision; was 'move into the pack'): `rag_wright/okf/`, the `okf_navigate` capability + skill, the `okf_compile`/`okf_navigate` pack slugs, `ModelRole.OKF_ENRICHMENT`, the OKF tests and the experiment's eval scripts; ADR-0127 | full suite; catalog + discover live; ratchet lowered; no dangling imports | done: OKF code, capability, skill, slugs, `OKF_ENRICHMENT` role, tests and experiment evals removed; ADR-0127; ratchet 133 -> 66 lines; catalog 35, no OKF |
@@ -85,3 +85,9 @@ in two at the PS-6 gate so the store rewrite is its own visible task. One task,
 | PS-9 | Docs: API reference regenerated; the engine-usage + authoring skills, the domain-adaptation guide, the product-starter templates and the RuleWright guide updated (the interim rules in its Q&A replaced by the new surface); G15-G21 closed in `_engine-gaps.md`; ADR; product-starter templates (CLAUDE.md + playbook + README) and the `using-the-rag-wright-engine` skill: define an `engine-docs` Graphify lane (`{{ENGINE_DOCS_LANE_PATH}}`: the engine repo's `docs/` + skills at the tag matching the installed engine) next to the `engine` lane, and a standing rule to rebuild both engine lanes on every engine version change (Dependabot merge, `uv sync`, editable-mode edits) before grounding the next call; skill lessons from PS-R3 (ADR-0126) in `setfit` and `creating-evals`: evaluate a classifier the way its consumers use it (top-1 accuracy when anything acts on the primary label, alongside top-k for soft tags; on pipeline-produced inputs incl. headings and no-label spans, not only curated snippets) and list the consumers of the primary label (and check them end to end) before declaring a classifier swap has no downstream impact; fix the stale `clause_function_classification` manifest description (says LegalBERT; production is the SetFit ensemble) | doc-reference test; full suite | done: RuleWright 0.3.0 guide; G21 closed, G1/G13 mostly closed (SDK +GraphWriter/build_graph_extraction, 85); skills (two tiers, engine-docs lane + rebuild rule, classifier-eval lessons, bytes sources); templates; ER/authoring/config guides; manifest text; ADR-0128; tasks.md + CLAUDE.md banner |
 | PS-10 | Ship the engine-authored Claude Code skills in the wheel, version-matched to the engine: the eight skills (`using-the-rag-wright-engine`, `authoring-a-capability`, `building-an-ingestion-capability`, `creating-evals`, `classifier-opportunity-analysis`, `setfit`, `laya`, `qwen-vllm-modal` with its Modal deploy script) live once under `src/rag_wright/.agents/skills/` (the convention docling and fastapi use) and the engine repo's `.claude/skills/` links to them; each shipped skill marks its engine-repo paths as such and gives a product its own verify step; the product-starter templates, `using-the-rag-wright-engine` and the RuleWright 0.3.0 guide say to link them from the installed package | wheel-contents test (builds the wheel); one-source + engine-repo-path tests; doc-reference test; full suite | done: 8 skills + the Qwen deploy script under `src/rag_wright/.agents/skills/`, `.claude/skills/` and `scripts/modal_qwen3_vllm_server.py` link to them; engine-repo paths marked, a product verify step in authoring-a-capability, local paths removed; one link command (by import, PyPI or editable) in the skill, installation, templates and RuleWright guide section 5; `.agents/` out of the vocabulary ratchet; wheel built offline and linked from a scratch product. The 0.3.0 release wheel (built from the sdist) shipped no skills: hatchling's sdist left out `.agents/`; fixed by an sdist `force-include`, and the test now builds sdist then wheel as `publish.yml` does (0.3.1) |
 | PS-11 | Docs: how a product swaps the model behind a hook decision (e.g. a trained classifier vs Jev for span tagging): `classification-and-decision-models.md` gains a section with a `span_tagger` that invokes a capability of the product's own by name, a Jev-backed implementation of it, the swap by re-registering the slug, filling `TaggedSpan.scores` from the probabilities so a voting `unit_representative` keeps working, measuring before choosing, and the large-label-set caveat; one cross-reference each in `kg-construction.md` and `building-an-ingestion-capability` | the section's example executed by a hermetic test (Jev stubbed); doc-reference test; full suite | done: section 5 of the classification & decision models guide (hook calls the product's own slug; classifier and Jev arms; swap by re-registering; scores for a voting representative; measure/cost/repeatability/label-set caveats); cross-references in kg-construction and the ingestion skill; example executed by `tests/api/test_decision_swap_doc_example.py`; live Jev call confirmed probabilities for every option |
+| PS-12 | Docs: the capability catalog is process-wide (one `MANIFEST_SPECS` for the process; `register_capability` replaces a slug for every workspace), so tenants that need different implementations of one slug run in separate processes; stated as a known limitation in `architecture.md`, the authoring-capabilities guide and the `using-the-rag-wright-engine` skill (not planned to change; revisit if a product needs it) | doc-reference test; full suite | done: "Known limitations" in `architecture.md`; the authoring-capabilities guide and the engine-usage skill say to register once at startup and give two ways out (separate processes, or one slug per implementation chosen per tenant); re-registering changes every later lookup, not a call already resolved |
+| PS-13 | Document metadata: `IngestSource(metadata={...})` written onto the `Document` node in the same write as the engine's fields (embedded children too); `kg_read` no longer returns the store's internal `@props` key; the `kg_update` route for metadata that changes after ingest documented; metadata survives re-ingest | hermetic tests; live store test (write, filter, re-ingest) | done: `IngestSource.metadata` (identifier keys, no engine-field keys, scalar/list values) written in the `Document` write, inherited by embedded files; `kg_read` drops `@props` only (record keys kept); kg-construction, concepts and both skills; hermetic + live store test (write, filter, re-ingest keeps / updates, `kg_update`) |
+| PS-14 | Every model call honours the workspace's `EngineConfig.models`: chunking, OCR, vision, RLM and the other role-based calls resolve through the workspace instead of the environment/defaults alone (today only `agenerate_answer` and `ajudge_spans` do); whatever cannot be per-workspace (e.g. process-wide classifier weights) documented | hermetic tests (two workspaces, two configs, each call sees its own model); live check | done: `model_for(role)` resolves the active workspace's `EngineConfig.models` first (a context variable set by `aingest`, the invokers and the MCP tools; public `use_workspace_models(ws)` for calls without a workspace); engine-started threads (`map_concurrent` timeout path, the pack's ingest job, the LLM clause classifier's sub-batch pool) carry the caller's context, which also restores their usage metering; what stays process-wide in `configuration.md`; live: two workspaces, Qwen vs Gemma, each call metered on its own model |
+| PS-15 | Docs, after PS-13 and PS-14: one place that says what is per workspace, per config object and per process (corpus and store, `EngineConfig` and its models, the capability catalog, environment variables, classifier weights, caches) and how a product manages workspaces (one corpus per workspace, its own `EngineConfig`, its own `cache_dir`, document metadata); linked from `architecture.md`, `configuration.md`, the domain-adaptation guide, the `using-the-rag-wright-engine` skill and the product-starter templates; a RuleWright section in its 0.3 guide (or the next release's) on managing its workspaces this way; in the user guides, PS-13's two behaviours: a re-ingest only adds or updates the metadata keys it is given (to remove a value, `kg_update` it to `None`), and `IngestSource.metadata` is a new public field shipped in the next minor release (products pin accordingly) | doc-reference test; full suite | done: `docs/workspaces.md` (what applies per workspace / per call / per process, managing workspaces, the two metadata behaviours, config changes need a restart); RuleWright guide `rulewright-migration-0.4.0.md` (customer workspaces, per-customer models vs `answer_model_id`, cache per customer, metadata); linked from README, architecture, configuration, the domain-adaptation guide, the engine-usage skill, both product-starter templates, the 0.3 guide and CLAUDE.md |
+| PS-16 | A configuration change takes effect without a restart: `open_workspace` returns the cached handle only when the config is equal; a different config gets a new handle (the store and the embedder reused when their settings are unchanged), and calls already holding the old handle finish on the old config; docs (workspaces, configuration, the engine-usage skill, the RuleWright 0.4 guide) updated | hermetic tests; live check (re-open with new models, same store) | done: an equal config returns the cached handle; a different one a new handle that replaces it (store reused for unchanged store settings + pack, query embedder for an unchanged profile; in-flight calls keep the old config); workspaces/configuration/skill/RuleWright 0.4 guide updated; live on ArcadeDB: same connection, new models, data visible |
+| PS-17 | No Gemma by default anywhere (your decision: Gemma only through config or a product): `DEFAULT_GENERAL` (Gemma) removed from `models.profiles` and `rag_wright.pack_sdk`; the reference pack's legacy tag-parse extractor runs its second list model only when `RAG_INGEST_LIST_MODEL` or `list_model=` names one; text that calls Gemma the model in use corrected (benchmark notes kept); the Gemma profiles stay registered so config can select Gemma correctly | guard test (no role default, constant or default-on path is Gemma); full suite | done: `DEFAULT_GENERAL` removed (profiles + `pack_sdk`, 84 symbols); the legacy extractor's list model via `list_model_for` (only when named); ~20 statements now say the GENERAL role (benchmark notes and serving gotchas kept, labelled); overview's stale Gemma listwise rerank removed; Gemma profiles stay registered; guard test; `CLAUDE.md` / `SPEC.md` wording left as is (your call) |

{rag_wright-0.3.1 → rag_wright-0.4.0}/docs/specs/public-surface/rulewright-migration-0.3.0.md

@@ -1,6 +1,9 @@
-# RuleWright: moving to rag-wright 0.3.0
+# RuleWright: moving to rag-wright 0.3 (target 0.3.1)
 
-What 0.3.0 changes for RuleWright, written from a read-only scan of the RuleWright repo (2026-10-09). It follows the
+Install rag-wright 0.3.1 or later. Every change below landed in 0.3.0, but the 0.3.0 wheel on PyPI left out the
+engine skills that section 5 links (0.3.1 fixes the packaging and changes nothing else).
+
+What 0.3 changes for RuleWright, written from a read-only scan of the RuleWright repo (2026-10-09). It follows the
 0.2.0 migration (`docs/specs/ingestion-hooks/rulewright-migration-0.2.0.md`); do that one first. Nothing here is
 edited from the engine repo.
 
@@ -86,3 +89,5 @@ for d in "$SKILLS"/*/; do ln -sfn "${d%/}" ".claude/skills/$(basename "$d")"; do
 
 Run RuleWright's suite against the engine checkout (editable path) and its live engine-seam test; re-ingest one
 contract and compare its clauses (expect the section 2 changes, not errors).
+
+Next: `docs/specs/public-surface/rulewright-migration-0.4.0.md` (customer workspaces, per-customer models, document metadata).