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

{rag_wright-0.4.0 → 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.4.0/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.4.0 → rag_wright-0.5.0}/.claude/skills/using-the-rag-wright-engine/SKILL.md

@@ -137,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.4.0 → rag_wright-0.5.0}/CHANGELOG.md

@@ -4,6 +4,18 @@ 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)
 
 

{rag_wright-0.4.0 → 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 and released as `rag-wright` 0.3.1** (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:
-> 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,
+> 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rag-wright
-Version: 0.4.0
+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

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.4.0 → 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.4.0 → 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.
@@ -238,6 +250,22 @@ Build a pack's store extension (or any object that wraps the workspace store) ov
 
 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).

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

@@ -106,6 +106,7 @@ and how to manage workspaces.
   call. Override one role with `RAG_MODEL_<ROLE>` (e.g. `RAG_MODEL_VISION_OCR`, `RAG_MODEL_GENERAL`), or every
   role at once with `RAG_MODEL_ALL`; the role-specific variable wins.
 - **Structured output** is client-side tag-parse (ADR-0045); any provider flags live in the profile.
+- **A self-hosted Qwen server**: see [A self-hosted model server](#a-self-hosted-model-server-qwen-on-modal) below.
 - **Decision models** (e.g. Jev) are reached through a `DecisionModelProfile` (default `jev-1.13`;
   `RAG_DECISION_MODEL` only overrides which profile). The reference contract pipeline uses the decision model
   whenever its key (`OPENROUTER_API_KEY`) is set **and** the `jev_decision` capability is registered
@@ -114,6 +115,70 @@ and how to manage workspaces.
   (deterministic boundaries; the LLM judge and residual call). `RAG_SEMANTIC_JUDGE=llm` / `RAG_RESIDUAL_EXTRACTOR=llm`
   switch the judge / the residual values back to the LLM.
 
+## A self-hosted model server (Qwen on Modal)
+
+By default every role uses Qwen3.8-27B through OpenRouter. A product can instead run its own Qwen server on Modal,
+deployed from the engine, and use it like any other model. The server's setup is the locked one from the
+`qwen-vllm-modal` skill (ADR-0110: FP8 weights and KV cache on one A100-80GB, 16K context); you choose only its name
+and its concurrency target.
+
+**One-time setup.**
+
+```sh
+uv add 'rag-wright[modal]'      # Modal is an optional extra
+uv run modal token new          # log in to Modal once per machine
+```
+
+and put the server's API key in your `.env` (any secret string; the server is deployed with it and every call
+sends it): `VLLM_API_KEY=<a long random string>`. There is no default key.
+
+**Deploy, then use it like any model.**
+
+```python
+from rag_wright.api import (EngineConfig, ModelServerSpec, StoreConfig, adeploy_model_server, open_workspace,
+                            stop_model_server)
+
+spec = ModelServerSpec(name="acme-qwen", max_num_seqs=32)   # name = the Modal app (and URL); 32 = concurrency target
+server = await adeploy_model_server(spec)                    # deploys, waits for /health, prints progress
+
+ws = open_workspace(EngineConfig(store=StoreConfig.from_env(), models={"general": server.model_id,
+                                                                        "structured_reasoning": server.model_id}),
+                    corpus="acme")
+# every engine call for this workspace that uses those roles now runs on the server
+```
+
+`server.model_id` (here `qwen3.8-27b-modal@acme-qwen`) is an ordinary model id: put it in `EngineConfig.models`
+for the roles it should serve, or pass it as a `model=` argument. Its profile carries the server's own endpoint and
+the Qwen thinking settings, so no `VLLM_BASE_URL` is needed, and two servers (one per tenant, say) are just two
+model ids in two workspaces' configs.
+
+**In a service.** Deploy from one place (a startup job or an operator script). Every other process reconnects
+without redeploying, which only looks up the server and registers its model id:
+
+```python
+from rag_wright.api import amodel_server, await_model_server
+
+server = await amodel_server(ModelServerSpec(name="acme-qwen", max_num_seqs=32))   # same spec as the deploy
+await await_model_server(server)    # returns at once if it is up; waits through a cold start if it scaled down
+```
+
+**What to know before you rely on it.**
+
+- **Cold start.** A new or scaled-down server takes minutes to become ready (226 s in the last live run; up to about
+  8 minutes, ADR-0109). After 10 idle minutes Modal scales the container to zero (no GPU billing) but keeps the app
+  deployed; the next request waits through a cold start, so call `await_model_server` before sending traffic.
+- **Cost.** An A100 bills while a container runs. `stop_model_server("acme-qwen")` removes the app entirely; deploy
+  again to bring it back.
+- **Concurrency.** `max_num_seqs` is how many requests the server batches at once (ADR-0110 sets it to your real
+  concurrency target); keep your own client concurrency below it.
+- **Timeouts.** Reasoning-on structured calls under full load can take about a minute; raise
+  `RAG_STRUCTURED_TIMEOUT_S` (default 60) for bulk work, or calls time out and retry.
+- **Process-wide.** A registered server model id is known to the whole process, like every model profile; after a
+  restart, call `amodel_server` again.
+
+The `qwen-vllm-modal` skill has the operational detail (the image fixes, serving gotchas, the manual `modal deploy`
+command) and ADR-0130 the design.
+
 ## Environment variables (reference)
 
 Prefer config; use env for secrets and for non-API callers. The common ones the engine reads:

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

@@ -18,7 +18,9 @@ ADR-0117/0118 engine API + capability runtime). Read [Concepts](../concepts.md)
    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: one corpus and one config per tenant, with the settings that stay per process listed in
-   [Workspaces](../workspaces.md). → [Configuration](../configuration.md).
+   [Workspaces](../workspaces.md). To run on your own Qwen server instead of OpenRouter, deploy it from the engine
+   and use its model id in `EngineConfig.models` ([A self-hosted model server](../configuration.md#a-self-hosted-model-server-qwen-on-modal)).
+   → [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.4.0 → rag_wright-0.5.0}/docs/installation.md

@@ -47,6 +47,8 @@ to reach the network (mock the call, or mark the test). The live markers, declar
   uv add 'rag-wright[ner]'                         # in a product; working on the engine itself: uv sync --extra ner
   uv run python -m spacy download en_core_web_sm   # configurable via RAG_SPACY_MODEL
   ```
+- **`rag-wright[modal]`**: Modal, for deploying the self-hosted Qwen server from the engine
+  (`adeploy_model_server`; see [Configuration](configuration.md)). Log in once with `uv run modal token new`.
 - **`rag-wright[ocr-bench]`** — the OCR-benchmark extras (`mlx-vlm`, `ocrmac`, `onnxruntime`, `scikit-image`).
 
 ### Skills for coding agents

{rag_wright-0.4.0 → rag_wright-0.5.0}/docs/reference-pack.md

@@ -112,6 +112,12 @@ to `build_ingestion(unit_representative=...)`.
 
 ## Its trained weights: fetched, not shipped
 
+Two things to know about these weights (ADR-0129). Nine of the 15 Laya checkpoints carry a `choice` temperature
+above the Laya runtime's accepted range, so Laya clamps it and warns on load. The fleet's labels are unaffected,
+because it emits options by rank and never reads the probability, but those nine checkpoints' probabilities are
+sharper than calibrated: do not gate on them. The SetFit heads were pickled with scikit-learn 1.9.1, the engine's
+floor.
+
 The pack's two `model` capabilities load trained weights that are not in the wheel or the repository (about 16 GB):
 the clause-type SetFit ensemble and the 29-dimension SetFit/Laya property fleet. They load from the models root
 (`RAG_MODELS_DIR`; default the engine checkout's `data/models` when it exists, else `./data/models`). Fetch them

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

@@ -91,3 +91,6 @@ in two at the PS-6 gate so the store rewrite is its own visible task. One task,
 | 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) |
+| PS-18 | RuleWright's request of 2026-10-10: raise the floor to `scikit-learn>=1.9.1` (8 shipped heads were pickled with 1.9.1) with a guard test that loads every shipped head with `InconsistentVersionWarning` as an error; the Laya temperatures (9 of 15 above Laya 0.3.22's [0.5, 5]) left as they are with the cause and the measured effect written down (ADR): fitted by Laya's training script within [0.1, 10], clamped at serving; labels unaffected (the fleet uses the ranking, not the probability; 5,400 paired predictions: 0 abstain changes, 45 rounding-tie differences); a reply to RuleWright | guard test; full suite | done: `scikit-learn>=1.9.1` (lock 1.9.0 -> 1.9.1); guard loads the 8 heads in the shipped model folders with the version warning as an error; ADR-0129; reference-pack note; the `laya` skill's post-training temperature checklist + scikit-learn lesson; reply to RuleWright; upstream Laya report drafted at `docs/upstream/laya-temperature-range-mismatch.md` (not filed) |
+| PS-19 | A product deploys the self-hosted Qwen server from the engine and uses it like any model: `ModelServerSpec` (defaults = the `qwen-vllm-modal` skill / ADR-0110 locked Config B: Qwen3.8-27B-FP8 + fp8 KV, 1x A100-80GB, TP 1, 16K, 0.95, served name `Qwen/Qwen3.8-27B`, hermes + qwen3 parsers, image builder 2025.06), `adeploy_model_server` (deploys the shipped script, waits for `/health` with X/N progress), reconnect by name, status, stop; each server registered as a model profile with its own endpoint (no `VLLM_BASE_URL` needed), so its `model_id` goes in `EngineConfig.models` or any `model=`; the API key from a named environment variable, never a default; `rag-wright[modal]` extra; Modal grounded in the framework graph | hermetic tests (Modal and HTTP mocked); live: deploy, one call through a workspace, stop, confirm stopped | done: `ModelServerSpec` (Config B defaults, `max_num_seqs` required), `adeploy_model_server` / `amodel_server` / `await_model_server` / `stop_model_server`; profiles carry an explicit `base_url`, `register_model_profile`; `rag-wright[modal]`; ADR-0130; configuration.md walk-through linked from the engine-usage skill, domain-adaptation guide, workspaces, templates; RuleWright 0.5 guide; live: ready in 226 s, one call metered on the server's model id, stopped (239 s of A100) |
+| PS-20 | Cold start of the self-hosted Qwen server (~8 min, CPU-bound engine init + CUDA-graph capture; ADR-0109): GPU snapshot / sleep mode, measured against the current baseline. Later, by your decision | live cold-start measurement | todo (later) |

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

@@ -72,3 +72,5 @@ store per database from the environment, and `export_engine_env` republishes the
 Run RuleWright's suite against the engine checkout (editable path) and its live engine-seam test. If you move to
 customer workspaces: open two customers with different `general` models, run a question for each concurrently
 inside `measure_usage()`, and check each call was metered on its own customer's model.
+
+Next: `docs/specs/public-surface/rulewright-migration-0.5.0.md` (its own Qwen server; the scikit-learn floor).

rag_wright-0.5.0/docs/specs/public-surface/rulewright-migration-0.5.0.md

@@ -0,0 +1,48 @@
+# RuleWright: moving to rag-wright 0.5 (its own Qwen server)
+
+What the release after 0.4.0 adds for RuleWright, written from a read-only scan of the RuleWright repo
+(2026-10-10). Do the 0.3 and 0.4 guides first. Nothing here is edited from the engine repo.
+
+**Short version.** Nothing breaks. RuleWright can now deploy its own Qwen server from the engine and point any of
+its model settings at it by changing a string. The scikit-learn floor it asked for is in.
+
+## 1. Nothing breaks
+
+- **scikit-learn.** The engine now requires `scikit-learn>=1.9.1` (RuleWright's request, ADR-0129); RuleWright
+  already declares the same floor.
+- **Model profiles** can carry an explicit endpoint. Existing profiles have none, so every model RuleWright uses
+  today resolves exactly as before.
+
+## 2. Running on its own Qwen server (optional)
+
+Today RuleWright's model settings are model-id strings: `rulewright_answer_model`, `rulewright_query_model` and
+`rulewright_ingest_model`, all `qwen3.8-27b-modal-or` (Qwen through OpenRouter). Its `config.py` already notes that
+pointing at its own server "is a string change here, not a code change". The engine now makes that string come from
+a server it deploys:
+
+1. **One-time setup.** `uv add 'rag-wright[modal]'`, `uv run modal token new`, and a real `VLLM_API_KEY` in its
+   settings (there is no default key; the server is deployed with it).
+2. **Deploy once,** from an operator script or a startup job, with the locked setup of the `qwen-vllm-modal` skill:
+   `server = await adeploy_model_server(ModelServerSpec(name="rulewright-qwen", max_num_seqs=<target>))`.
+   `max_num_seqs` is RuleWright's real concurrency target (ADR-0110); keep its client concurrency below it.
+3. **Every service process reconnects at startup** without redeploying, then waits for readiness:
+   `server = await amodel_server(spec)`, then `await await_model_server(server)`.
+4. **Use `server.model_id`** (`qwen3.8-27b-modal@rulewright-qwen`) as the value of those three settings, or in a
+   customer workspace's `EngineConfig.models` (0.4 guide, section 2). It is an ordinary model id: the seam, answer
+   generation and the ported pack's docling-graph extraction (`default_extraction_model`, which resolves through
+   the profile) all reach the server's own endpoint. `VLLM_BASE_URL` and `RAG_SERVING` are not needed for it.
+5. **A server per customer,** if wanted: one `ModelServerSpec` name per customer gives one server and one model id
+   each, used in that customer's `EngineConfig.models`.
+
+Two cautions. The ported pack's `vllm_model()` helper (`packs/contracts/capabilities/dg_extraction.py`) reads
+`VLLM_BASE_URL` directly and so cannot see a deployed server's endpoint; nothing calls it, so do not start using it.
+And a server scales to zero after 10 idle minutes: the next request waits through a cold start (minutes), so call
+`await_model_server` before sending traffic; `stop_model_server(name)` removes it entirely.
+
+The engine's full walk-through is `docs/configuration.md`, "A self-hosted model server"; the design is ADR-0130.
+
+## 3. Verify
+
+Run RuleWright's suite against the engine checkout. If it moves a setting to a server: deploy (or reconnect), run
+one question inside `measure_usage()`, and check the call was metered on the server's model id; then stop the
+server if it was a test deployment.

rag_wright-0.5.0/docs/specs/public-surface/rulewright-reply-2026-10-10-laya-and-sklearn.md

@@ -0,0 +1,44 @@
+# Reply to RuleWright: Laya temperatures and the scikit-learn floor (2026-10-10)
+
+Answers RuleWright's `docs/engine-requests/2026-10-10-laya-temperatures-and-sklearn-floor.md`. The decision record is
+ADR-0129. Nothing here is edited in the RuleWright repo.
+
+## 1. The Laya temperatures: not a bug, and labels are unaffected; T-7.23 can proceed
+
+**The values are fitted.** Laya's own fine-tuning script fits one temperature per question type by log-likelihood on
+a held-out slice and clips it to [0.1, 10] (`research/scripts/finetune_single_device.py:154`); the Laya runtime
+(0.3.22) accepts [0.5, 5] and clamps the rest. The three at (or within 0.002 of) 10.0 hit the training clip: the fit
+wanted an even softer scale. So it is a range mismatch between Laya's training script and its runtime, not an
+uninitialised value.
+
+**The engine's classifier lane does not gate on the probability.** `_classifier_assertions`
+(`rag_wright/packs/contracts/spans/property_extractor.py`) emits the top-k options by rank, abstains when `none` is
+among them, and 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 temperature
+(5) against the shipped one, 5,400 paired predictions:
+
+| | result |
+|---|---|
+| abstain decisions changed | 0 |
+| emitted label sets changed | 45 (0.8%), every one between options equal to 4 decimals (Laya rounds probabilities; the sort breaks the tie) |
+| primary label changed | 1, on a `damage_type` answer with all five options between 0.17 and 0.22 |
+| the same temperature scored twice | identical |
+
+So the clamp does not produce missing labels in the engine's pack, and measuring recall now gives the same answer
+it would after any temperature change. **One thing to check on your side:** if your ported pack added a confidence
+threshold to this lane, the clamp matters there, because those nine checkpoints' probabilities are up to 0.22
+sharper than calibrated.
+
+**What the engine did:** recorded the cause and the measurement (ADR-0129, the reference-pack docs, the `laya`
+skill). It did not re-export the nine: a re-export at 5.0 would serve identically and only silence the warning.
+Widening Laya's accepted range is Laya's decision; a report to Laya upstream is drafted in the engine repo
+(`docs/upstream/laya-temperature-range-mismatch.md`, not yet filed). The `laya` skill now says what to check after
+every training run.
+
+## 2. The scikit-learn floor: done, and wider than the three heads
+
+The engine now requires `scikit-learn>=1.9.1`. Eight shipped heads were pickled with 1.9.1, not three: the three
+clause-function heads and five property-dimension heads (`cap_basis`, `carve_out`, `covered_parties`, `mutuality`,
+`nonsolicit_target`). `tests/models/test_classifier_heads_load_clean.py` now loads every head inside the shipped
+model directories with the version warning as an error, so a future skew fails the engine's suite. This ships in the
+next engine release; RuleWright's own `>=1.9.1` already matches.

{rag_wright-0.4.0 → rag_wright-0.5.0}/docs/templates/product-starter/CLAUDE.md.template

@@ -130,7 +130,9 @@ are re-made after every engine upgrade.
 ## Engine documentation (not shipped in the wheel — read in the engine repo / on GitHub)
 
 - **Concepts** + **Architecture** — the mental model and the engine/product boundary.
-- **Installation** + **Configuration** + **Quickstart** — `uv add`, ArcadeDB, the model provider, `EngineConfig`.
+- **Installation** + **Configuration** + **Quickstart** — `uv add`, ArcadeDB, the model provider, `EngineConfig`;
+  Configuration's "A self-hosted model server" deploys your own Qwen server (`adeploy_model_server`) and uses its
+  model id like any model.
 - **Workspaces** (`docs/workspaces.md`) — one corpus and one `EngineConfig` per tenant; what applies per
   workspace, per call and per process; document metadata; how a config change takes effect.
 - **Domain adaptation** (`docs/domain-adaptation/`) — the build sequence + companions (ontology, KG, ER,

{rag_wright-0.4.0 → rag_wright-0.5.0}/docs/templates/product-starter/playbook.md.template

@@ -114,6 +114,8 @@ code-review-and-quality, using-agent-skills · plus **Graphify** (builds/queries
   your own libs against `project`.
 - The reference pack (contract/compliance) is the engine's EXAMPLE, not your domain — author your
   own .ttl pack + capabilities.
+- Self-hosted model: deploy it with adeploy_model_server (the locked qwen-vllm-modal setup) and put
+  server.model_id in EngineConfig.models; never hand-edit VLLM_BASE_URL for it.
 - Workspaces: one corpus + one EngineConfig + one cache_dir per tenant; register capabilities once
   per process; the engine's docs/workspaces.md says what is per workspace, per call, per process.
 - Per task: ground, define the contract, failing test (TDD), implement to green, verify, short ADR

rag_wright-0.5.0/docs/upstream/laya-temperature-range-mismatch.md

@@ -0,0 +1,49 @@
+# DRAFT, not filed: Laya issue on the temperature range mismatch
+
+A draft issue for the Laya repository (https://github.com/NandhaKishorM/laya). Not filed; filing it is a separate,
+explicit step. It names no customer, product or dataset beyond what is public. Background: ADR-0129.
+
+---
+
+**Title:** `finetune_single_device.py` fits temperatures in [0.1, 10] but the runtime only serves [0.5, 5]
+
+**Summary.** The research fine-tuning script fits each question type's temperature by NLL and clips it to
+[0.1, 10]. The runtime accepts [0.5, 5] (`laya/common.py`, `TEMP_MIN = 0.5`, `TEMP_MAX = 5.0`) and clamps anything
+outside, with a load-time `RuntimeWarning` ("this checkpoint ships invalid temperatures or values outside [0.5, 5]
+... Treat confidence from the affected entries as uncalibrated"). So a checkpoint produced by the documented
+training path can load with a temperature the runtime will not serve.
+
+**Where.**
+
+- Training: `research/scripts/finetune_single_device.py`, line 154 (at the 0.3.22 commit, `6d942c9`):
+  `return float(torch.clamp(log_t.exp(), 0.1, 10.0).item())`
+- Runtime: `laya/common.py`, `TEMP_MIN = 0.5`, `TEMP_MAX = 5.0`, applied by `clamp_temperature` when an `Agent` loads
+  `rl_agent_config.json`. The runtime's own calibrator (`laya.calibrate.fit_one_temperature`) already clamps to the
+  runtime range, so only the research script disagrees.
+
+**What we saw.** 15 checkpoints fine-tuned from the English ModernBERT-large base with this script (laya 0.3.22,
+single device). 9 of 15 have a `choice` temperature (`temperature[0]`) above 5: 10.0, 9.998, 10.0, 7.280, 7.129,
+6.402, 6.202, 6.109, 5.637. The three at or near 10.0 sit on the script's clip, so their unconstrained fit was
+higher still. The other six are within range.
+
+**Effect.** For `choice` questions the clamp leaves the option ranking unchanged (one scale per question), so
+argmax and top-k are stable: across 5,400 paired predictions (served 5.0 against the shipped value) no abstain
+decision changed and every top-k difference was a tie between options equal at 4 decimals. The probabilities do
+change, by up to 0.22 here, and in the direction of overconfidence (a sharper distribution than the fit chose).
+Anyone gating on `probabilities` or `answer_confidence` for these checkpoints is gating on uncalibrated values,
+and the only signal is a load-time warning.
+
+**Suggested fixes (any one).**
+
+1. Clip the research script's fit to the runtime range (`TEMP_MIN`, `TEMP_MAX` from `laya.common`), or reuse
+   `laya.calibrate.fit_one_temperature`, so a trained checkpoint is always servable as fitted.
+2. If temperatures above 5 are legitimate for small fine-tunes (the fit says the model is overconfident), widen the
+   runtime range to match the training clip, so the shipped value is served and the warning is not raised for a
+   valid fit.
+3. At minimum, have the training script warn (or record `"temperature_bound_limited": true` in
+   `rl_agent_config.json`) when the fit lands outside the runtime range, so the mismatch is caught at training time
+   rather than at load.
+
+**Workaround we use.** We rank by the answer and do not gate on its probability, and we document that these
+checkpoints' probabilities are uncalibrated. A refit with the runtime calibrator (`records_from_labeled` +
+`fit_temperature_map`, saved with `Agent.save_calibration`) would give in-range values.

{rag_wright-0.4.0 → rag_wright-0.5.0}/docs/workspaces.md

@@ -21,7 +21,7 @@ crosses corpora: every read and write goes through the handle's store.
 | scope | what | how you set it |
 |---|---|---|
 | **per workspace** | the corpus and everything stored in it, including document metadata | `open_workspace(config, corpus=...)`; `IngestSource(metadata=...)` |
-| per workspace | the model for each role (`ModelRole`) | `EngineConfig.models`: ahead of `RAG_MODEL_<ROLE>` / `RAG_MODEL_ALL` for every engine call that takes the workspace (`aingest`, the invokers and the MCP tools on them, `agenerate_answer`, `ajudge_spans`) |
+| per workspace | the model for each role (`ModelRole`), including a self-hosted server's `model_id` ([A self-hosted model server](configuration.md#a-self-hosted-model-server-qwen-on-modal)) | `EngineConfig.models`: ahead of `RAG_MODEL_<ROLE>` / `RAG_MODEL_ALL` for every engine call that takes the workspace (`aingest`, the invokers and the MCP tools on them, `agenerate_answer`, `ajudge_spans`) |
 | per workspace | the embedding profile, the ingestion tuning, each pack's options | `EngineConfig.embeddings`, `EngineConfig.options` |
 | **per call** | the caches (parse, chunk, decisions) | the `cache_dir` you pass to `aingest` / `evaluate_ingestion` |
 | per call | usage metering and trace grouping | `measure_usage()`, `traced_run(...)` around the call |