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

{rag_wright-0.3.1/src/rag_wright/.agents → rag_wright-0.5.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.5.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 → rag_wright-0.5.0}/.claude/skills/laya/SKILL.md

@@ -86,6 +86,26 @@ One JSONL line per case (`research/scripts/finetune_single_device.py` reads this
 - Runs on **one 16 GB GPU (T4)** — ~1–2 h for large data, minutes for our small dims. RLCD = soft-CE + GRPO-style
   policy gradient on proper scoring rules. Calibration (one temperature per type) is fitted inside the run on a
   held-out slice; **argmax/accuracy unchanged, only confidence moves** — always fit before gating on confidence.
+- **Check the fitted temperatures against the SERVING runtime's range (a known Laya mismatch).** The research
+  fine-tuning script fits each type's temperature and clips it to [0.1, 10]
+  (`research/scripts/finetune_single_device.py:154`); the Laya runtime (0.3.22) serves only [0.5, 5]
+  (`laya.common.TEMP_MIN` / `TEMP_MAX`) and clamps the rest, with a load-time `RuntimeWarning` ("... values outside
+  [0.5, 5] ... treat confidence ... as uncalibrated"). A clamped `choice` temperature leaves the ranking alone (one
+  scale per question: argmax, top-k and `none`-abstains are stable) but makes the probabilities sharper than
+  fitted, so they are overconfident. So, after every training run:
+  1. read `temperature` in each checkpoint's `rl_agent_config.json` and compare it with the runtime range;
+  2. if you only rank (top-k, abstain on `none`), an out-of-range value changes no label: record it and move on;
+  3. if anything gates on `probabilities` or `answer_confidence`, refit within the runtime range with the runtime
+     calibrator on a held-out labelled slice (`laya.calibrate.records_from_labeled(agent, pairs)` ->
+     `fit_temperature_map(records)`, whose fits are clamped to the runtime range), save it with
+     `Agent.save_calibration(path)` and serve with `Agent.load_calibration(path)`.
+
+  The engine's reference fleet has nine such checkpoints and only ranks (ADR-0129). A report to Laya upstream is
+  drafted in the engine repository (`docs/upstream/laya-temperature-range-mismatch.md`, not yet filed); check the
+  Laya release notes before relying on either range. Repository paths in this skill (`docs/`) are in the engine repository:
+  read them there or on GitHub.
+- **Train with the scikit-learn your serving environment runs** (or raise the serving floor with it): a SetFit
+  head pickled by a newer scikit-learn warns on load and can change predictions without an error.
 - **OOM knobs:** ModernBERT-large (~400M) is tight on a 16 GB T4/L4. The single-device script has NO batch or
   sequence flags: it fixes `micro_batch = 8`, `max_tokens_per_batch = 4096`, `max_len = 1024` and `head_max_len = 256`
   in code, and turns on gradient checkpointing on CUDA. Our short-clause dims ran with it unchanged. If a run still

{rag_wright-0.3.1/src/rag_wright/.agents → rag_wright-0.5.0/.claude}/skills/qwen-vllm-modal/SKILL.md

@@ -26,6 +26,26 @@ This skill is the operational checklist that ties them together.
 - Served-model-name is `Qwen/Qwen3.8-27B` (what the engine profile `qwen3.8-27b-modal` asks for), even though the
   weights are the `-FP8` repo.
 
+**From the engine (PS-19): deploy, then use the server like any model.** `ModelServerSpec`'s defaults ARE the
+locked config below (FP8 weights + FP8 KV, one A100-80GB, TP 1, 16K, 0.95, served `Qwen/Qwen3.8-27B`, hermes +
+qwen3 parsers, image builder 2025.06); state only the concurrency target, which ADR-0110 leaves to you.
+`adeploy_model_server` runs the deploy below with those settings, waits for `/health` (with progress; a cold start is
+~8 min), and registers a model profile with the server's own endpoint, so no `VLLM_BASE_URL` is needed:
+
+```python
+from rag_wright.api import EngineConfig, ModelServerSpec, adeploy_model_server, stop_model_server
+
+server = await adeploy_model_server(ModelServerSpec(name="acme-qwen", max_num_seqs=32))  # key from VLLM_API_KEY
+config = EngineConfig(store=..., models={"general": server.model_id})   # or any model= argument
+...
+stop_model_server("acme-qwen")                                            # stop billing
+```
+
+`amodel_server(spec)` reconnects to a server deployed earlier (a restart, another process) without redeploying.
+The API key comes from the variable `ModelServerSpec.api_key_env` names (default `VLLM_API_KEY`); there is no default
+key, so set a real one. Needs `rag-wright[modal]` and a Modal login. One app per server name: different names give
+different servers (and URLs), for example one per tenant.
+
 **The exact working deploy (this succeeded):**
 ```
 MODAL_IMAGE_BUILDER_VERSION=2025.06 \

{rag_wright-0.3.1 → rag_wright-0.5.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
 
@@ -125,6 +137,13 @@ Work the domain-adaptation guide, grounding each engine call (step 2) and writin
 6. **Build the product seam** — your thin layer over the engine API + registered caps (tenancy, orchestration,
    the product tool surface). Wrap `open_workspace`/the invokers/`kg_read`/`measure_usage`.
 
+**Using a self-hosted model (Qwen on Modal).** Deploy it from the engine and use its model id like any model:
+`server = await adeploy_model_server(ModelServerSpec(name="<app>", max_num_seqs=<concurrency target>))` (the locked
+setup of the `qwen-vllm-modal` skill; needs `rag-wright[modal]`, a Modal login and `VLLM_API_KEY` in `.env`), then
+`EngineConfig(models={"general": server.model_id, ...})`. Other processes reconnect with `amodel_server(spec)`;
+call `await_model_server(server)` before traffic (cold start is minutes); `stop_model_server(name)` stops billing.
+Full walk-through: `docs/configuration.md`, "A self-hosted model server".
+
 **Using the decision model (Jev).** Register `jev_decision` (from `engine_capabilities()`) and set
 `OPENROUTER_API_KEY` (`RAG_DECISION_MODEL` overrides the default profile `jev-1.13`). Without both, the reference
 pack's decision paths silently fall back (to deterministic rules or the LLM); your own

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

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

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

@@ -4,6 +4,37 @@ 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.5.0](https://github.com/fzaidi-dai/RAG_Wright/compare/0.4.0...0.5.0) (2026-10-10)
+
+
+### Features
+
+* **PS-19:** deploy the self-hosted model server from the engine and use it like any model ([5cd4d22](https://github.com/fzaidi-dai/RAG_Wright/commit/5cd4d22b6e684052b2d75162df32078fdf1cf2e6))
+
+
+### Bug Fixes
+
+* **PS-18:** scikit-learn floor 1.9.1 for the shipped heads; Laya temperatures recorded (ADR-0129) ([2350de4](https://github.com/fzaidi-dai/RAG_Wright/commit/2350de44a877bd74ad4e920c39a1557d43a0f2c8))
+
+## [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.5.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.4.0** (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 from `docs/specs/public-surface/rulewright-migration-0.3.0.md` then `rulewright-migration-0.4.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.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rag-wright
-Version: 0.3.1
+Version: 0.5.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
@@ -39,9 +39,11 @@ Requires-Dist: pydantic>=2.0
 Requires-Dist: pypdfium2>=5.11
 Requires-Dist: pyshacl>=0.40.1
 Requires-Dist: python-dotenv>=1.2
-Requires-Dist: scikit-learn>=1.9.0
+Requires-Dist: scikit-learn>=1.9.1
 Requires-Dist: sentence-transformers>=6.1.0
 Requires-Dist: transformers<5.9,>=5.4
+Provides-Extra: modal
+Requires-Dist: modal>=1.5.3; extra == 'modal'
 Provides-Extra: ner
 Requires-Dist: spacy>=3.8.14; extra == 'ner'
 Provides-Extra: ocr-bench
@@ -105,7 +107,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.5.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.5.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.5.0/docs/adr/0129-laya-temperatures-and-the-sklearn-floor.md

@@ -0,0 +1,47 @@
+# ADR-0129: The shipped Laya temperatures stay as fitted; scikit-learn floor at 1.9.1
+
+**Status:** accepted · **Date:** 2026-10-10 · **Related:** ADR-0116 (Laya property classifiers), ADR-0119 (decision
+models), PS-5 (reference weights on GCS)
+
+## Context
+
+RuleWright reported (its engine request of 2026-10-10) two findings in the shared reference weights:
+
+1. Laya 0.3.22 warns on loading 9 of the 15 Laya checkpoints: their `choice` temperature (`temperature[0]`, from
+   5.64 to 10.0) is outside the runtime's accepted [0.5, 5], so it is clamped to 5 and the probabilities are
+   "uncalibrated".
+2. Eight shipped SetFit heads (the three clause-function heads, five property-dimension heads) were pickled with
+   scikit-learn 1.9.1 while the engine declared and ran 1.9.0, so each warns on load (`InconsistentVersionWarning`).
+
+## Findings
+
+- **Cause of the temperatures.** Laya's own fine-tuning script (`research/scripts/finetune_single_device.py:154`)
+  fits one temperature per question type by log-likelihood on a held-out slice and clips it to [0.1, 10]; the
+  runtime accepts [0.5, 5]. The values are fitted, not left uninitialised; the three at 10.0 hit the training clip.
+  The mismatch is between Laya's training script and its runtime.
+- **Effect on labels.** The reference pack's classifier lane (`_classifier_assertions`) emits the top-k options by
+  rank and abstains when `none` is among them; it never reads the probability value. One temperature scales every
+  option of a question alike, so it cannot reorder them. Measured on 300 CUAD paragraphs, every affected
+  checkpoint and dimension, served (5) vs shipped temperature, 5,400 paired predictions: 0 abstain decisions
+  changed; 45 emitted label sets (0.8%) differed, every one between options equal to 4 decimals (Laya rounds its
+  probabilities, and the sort breaks the tie); 1 primary label changed, on a `damage_type` answer with all options
+  between 0.17 and 0.22. Scoring twice at one temperature is identical.
+- **Effect on probabilities.** For these 9 checkpoints the served probabilities are up to 0.22 sharper than the
+  fitted calibration, so they are overconfident. Nothing in the engine reads them.
+
+## Decision
+
+1. The nine checkpoints are not re-exported; the cause and the measured effect are recorded here, in the reference
+   pack's documentation and in the `laya` skill. A re-export at temperature 5.0 would serve identically and only
+   silence the warning; widening the accepted range is Laya's decision, not the engine's. A report to Laya is
+   drafted (`docs/upstream/laya-temperature-range-mismatch.md`, not filed).
+2. A product that gates on these classifiers' probabilities must not treat them as calibrated (or must refit within
+   the runtime's range).
+3. The engine requires `scikit-learn>=1.9.1`, the version the shipped heads were pickled with, and
+   `tests/models/test_classifier_heads_load_clean.py` fails when any shipped head warns on load.
+
+## Consequences
+
+- Labels from the reference fleet are as they were; the warning on loading those 9 checkpoints remains.
+- A future training run checks `rl_agent_config.json` against the serving runtime's temperature range, and the
+  training image's scikit-learn version is the engine's floor (or the floor moves with it).

rag_wright-0.5.0/docs/adr/0130-deploy-the-self-hosted-model-server-from-the-engine.md

@@ -0,0 +1,32 @@
+# ADR-0130: A product deploys the self-hosted model server from the engine and uses it like any model
+
+**Status:** accepted · **Date:** 2026-10-10 · **Related:** ADR-0110 (the locked Qwen config), ADR-0109 (cold start),
+ADR-0100 (model strings carry their backend), PS-14 (per-workspace models)
+
+## Context
+
+The self-hosted Qwen server was stood up by hand: the `qwen-vllm-modal` skill's `modal deploy` command, then
+`VLLM_BASE_URL` / `VLLM_API_KEY` in the environment. A product could not deploy it through the engine, and every
+vLLM profile read one process-wide endpoint, so two servers (one per tenant) needed custom profiles and variables.
+
+## Decision
+
+1. `ModelServerSpec` describes one server; its defaults are the skill's locked Config B (ADR-0110), and the
+   concurrency target (`max_num_seqs`) has no default because ADR-0110 leaves it to the deployment.
+2. `adeploy_model_server(spec)` runs the deploy script shipped with the skill (Modal's own CLI, the documented
+   command), waits for `/health` with progress, and registers a model profile for the server: the
+   `qwen3.8-27b-modal` profile's Qwen settings, the server's own endpoint, and the API-key variable the spec names.
+   `amodel_server(spec)` reconnects without redeploying; `stop_model_server(name)` stops it.
+3. A model profile can carry an explicit `base_url`, which wins over its `base_url_env`; `register_model_profile`
+   adds one at run time. So a deployed server is just another model id (`qwen3.8-27b-modal@<name>`) for
+   `EngineConfig.models` or any `model=` argument.
+4. The API key has no default: deploying refuses when the named variable is unset. `modal` is an optional extra
+   (`rag-wright[modal]`).
+
+## Consequences
+
+- Live (2026-10-10): deploy through the API, ready after 226 s, one answer through a workspace metered on the
+  server's model id, stopped (the app no longer resolves); 239 s of A100 in all.
+- Cold start remains a separate task (PS-20, ADR-0109); the readiness wait reports it, it does not shorten it.
+- Registered server profiles are process-wide, like every profile; a restarted process reconnects with
+  `amodel_server`.

{rag_wright-0.3.1 → rag_wright-0.5.0}/docs/adr/README.md

@@ -1,7 +1,7 @@
 # Architecture Decision Records — index
 
 128 ADR files (0001–0119, plus 0120 — the former duplicate `0015`, renumbered 2026-10-05 to repair the collision —
-and 0121–0128). ADRs are an
+and 0121–0130). ADRs are an
 immutable, cross-referenced decision log: nothing here is moved or renumbered — legacy records carry a `Status:`
 banner pointing to what replaced them. This index groups them so a newcomer isn't drowned.
 
@@ -184,4 +184,6 @@ framing that still appears in older ADRs and the root `SPEC.md`/`plan.md`.
 0125 Qwen3.8-27b on OpenRouter is unpinned (no provider routing; supersedes 0111) ·
 0126 Which span represents a unit is a domain hook; the reference pack votes over operative spans ·
 0127 Retire the OKF code ·
-0128 Two public tiers: `rag_wright.api` for products, `rag_wright.pack_sdk` for packs
+0128 Two public tiers: `rag_wright.api` for products, `rag_wright.pack_sdk` for packs ·
+0129 The shipped Laya temperatures stay as fitted; scikit-learn floor at 1.9.1 ·
+0130 A product deploys the self-hosted model server from the engine and uses it like any model

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

@@ -28,6 +28,18 @@ An opaque handle to a resolved engine workspace. Public surface: `model_id(role)
 
 Resolve a model role to its id: the `EngineConfig.models` override wins, else the profile default.
 
+### `ModelServerSpec(max_num_seqs: 'int', name: 'str' = 'rw-qwen3-modal', model: 'str' = 'Qwen/Qwen3.8-27B-FP8', kv_cache_dtype: 'str' = 'fp8', served_name: 'str' = 'Qwen/Qwen3.8-27B', gpu: 'str' = 'A100-80GB:1', tensor_parallel: 'int' = 1, max_len: 'int' = 16384, gpu_util: 'float' = 0.95, tool_parser: 'str' = 'hermes', reasoning_parser: 'str' = 'qwen3', image_builder_version: 'str' = '2025.06', api_key_env: 'str' = 'VLLM_API_KEY') -> None`
+
+One self-hosted Qwen server on Modal. The defaults are the locked setup of the `qwen-vllm-modal` skill (ADR-0110, Config B): FP8 weights + FP8 KV cache, one A100-80GB, tensor parallel 1, 16K context, 0.95 GPU memory, served as `Qwen/Qwen3.8-27B` with the hermes tool parser and the qwen3 reasoning parser, image builder 2025.06. `max_num_seqs` has no default: ADR-0110 sets it to the real concurrency target (keep client concurrency below it). `name` is the Modal app name, and so the server's URL. `api_key_env` names the environment variable that holds the server's API key.
+
+#### `ModelServerSpec.deploy_env(self) -> 'dict[str, str]'`
+
+The deploy command's settings, as the skill's documented command passes them.
+
+### `ModelServer(name: 'str', root: 'str', base_url: 'str', model_id: 'str', served_model_id: 'str', api_key_env: 'str') -> None`
+
+A deployed server: `model_id` is the model id to use (in `EngineConfig.models` or a `model=` argument); `base_url` is its OpenAI-compatible endpoint; `root` is its URL (for `/health`).
+
 ### `ModelRole(*values)`
 
 Which model does which job. The mapping to ids lives in config, not in capability code.
@@ -124,9 +136,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 +154,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 +164,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 +240,32 @@ 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.
+
+### `adeploy_model_server(spec: 'ModelServerSpec', *, wait: 'bool' = True, timeout_s: 'float' = 1500, poll_s: 'float' = 15, progress: 'Callable[[str], object]' = print) -> 'ModelServer'`
+
+Deploy (or redeploy) the server described by `spec` on Modal, register its model profile, and (with `wait`) wait for it to be ready. Returns the `ModelServer`; use `server.model_id` as the model. Raises `RuntimeError` when the API-key variable is unset (nothing is deployed). The server runs (and bills) until `stop_model_server`, or until Modal scales it down after 10 idle minutes.
+
+### `amodel_server(spec: 'ModelServerSpec') -> 'ModelServer'`
+
+Reconnect to a server deployed earlier (by this process or another) without redeploying: look up its URL and register its model profile. `spec` must match the deployed server (its name and served model).
+
+### `await_model_server(server: 'ModelServer', *, timeout_s: 'float' = 1500, poll_s: 'float' = 15, progress: 'Callable[[str], object]' = print) -> 'ModelServer'`
+
+Wait until the server answers `/health` (a cold start is about 8 minutes, ADR-0109); progress as `i/N`. Raises `TimeoutError` after `timeout_s`.
+
+### `stop_model_server(name: 'str') -> 'None'`
+
+Stop the Modal app `name` (stops billing); its URL stops answering.
+
 ### `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 +418,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.5.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.5.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.5.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