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

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

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

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

@@ -4,6 +4,13 @@ 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.1](https://github.com/fzaidi-dai/RAG_Wright/compare/0.5.0...0.5.1) (2026-10-10)
+
+
+### Bug Fixes
+
+* **PS-19:** a runnable model-server example for products; async Modal URL lookup ([35cd80f](https://github.com/fzaidi-dai/RAG_Wright/commit/35cd80f003453dfbb648df020a03ffe85ef64826))
+
 ## [0.5.0](https://github.com/fzaidi-dai/RAG_Wright/compare/0.4.0...0.5.0) (2026-10-10)
 
 

{rag_wright-0.5.0 → rag_wright-0.5.1}/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.4.0** (ledger
+> **CURRENT STATE (2026-10-09): the public-surface workstream is COMPLETE and released as `rag-wright` 0.5.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 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,
+> RuleWright moves from `docs/specs/public-surface/rulewright-migration-0.3.0.md` then `rulewright-migration-0.4.0.md` and `-0.5.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.5.0 → rag_wright-0.5.1}/PKG-INFO

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

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

@@ -176,6 +176,10 @@ await await_model_server(server)    # returns at once if it is up; waits through
 - **Process-wide.** A registered server model id is known to the whole process, like every model profile; after a
   restart, call `amodel_server` again.
 
+**A runnable example.** `examples/model_server.py` does all of this through `rag_wright.api`: `deploy` brings a
+server up, asks one question on it through a workspace, checks the call was metered on the server's model id, then
+stops it and confirms it is gone; `reconnect` is the service-process path (look up, wait, ask, leave it running).
+
 The `qwen-vllm-modal` skill has the operational detail (the image fixes, serving gotchas, the manual `modal deploy`
 command) and ADR-0130 the design.
 

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

@@ -92,5 +92,5 @@ in two at the PS-6 gate so the store rewrite is its own visible task. One task,
 | 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-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). Follow-up: `examples/model_server.py` (`deploy` and `reconnect` modes, public API only) for RuleWright and other products, and the URL lookup moved to Modal's async interface (no `AsyncUsageWarning`); live: all three steps passed (ready after a 254 s cold start, reconnect ready in 1 s, each call metered on the server's model id, stopped, no longer resolves) |
 | 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.5.0 → rag_wright-0.5.1}/docs/specs/public-surface/rulewright-migration-0.5.0.md

@@ -46,3 +46,13 @@ The engine's full walk-through is `docs/configuration.md`, "A self-hosted model
 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.
+
+The engine's `examples/model_server.py` is that check, written against the public API only, and the place to start
+(read it from the engine checkout; it is not in the wheel):
+
+- `uv run python examples/model_server.py deploy` brings a server up (`adeploy_model_server`), opens a workspace
+  whose `general` role is `server.model_id`, asks one question inside `measure_usage()`, checks the call was metered
+  on the server's model id, then stops the server (`stop_model_server`, always, even on failure) and confirms it no
+  longer resolves.
+- `uv run python examples/model_server.py reconnect` is what each RuleWright service process does at startup:
+  `amodel_server` then `await_model_server`, one question, and the server left running.

rag_wright-0.5.1/examples/model_server.py

@@ -0,0 +1,91 @@
+"""Bring up a self-hosted Qwen server through the engine, use it as a workspace's model, and bring it down.
+
+Everything goes through `rag_wright.api`. The server is the locked setup of the `qwen-vllm-modal` skill (ADR-0110);
+the walk-through is docs/configuration.md, "A self-hosted model server (Qwen on Modal)".
+
+Prerequisites (see docs/installation.md):
+  - `uv add 'rag-wright[modal]'` and a Modal login (`uv run modal token new`).
+  - VLLM_API_KEY in .env: the server's API key (any long random string; there is no default).
+  - ArcadeDB running locally, with ARCADEDB_* set in .env.
+
+Run from the repo root:
+    uv run python examples/model_server.py deploy      # deploy, ask one question on it, stop it, confirm it is gone
+    uv run python examples/model_server.py reconnect   # reconnect to a server already deployed, ask one question
+
+`deploy` is what an operator script or startup job does, and it always stops the server at the end (an A100 bills
+while it runs). `reconnect` is what every service process does at startup: it never deploys, and it leaves the
+server running. A cold start takes minutes; progress is printed as `i/N`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+import time
+
+from dotenv import load_dotenv
+
+from rag_wright.api import (
+    EngineConfig,
+    EvidenceItem,
+    ModelRole,
+    ModelServer,
+    ModelServerSpec,
+    StoreConfig,
+    adeploy_model_server,
+    agenerate_answer,
+    amodel_server,
+    await_model_server,
+    measure_usage,
+    open_workspace,
+    stop_model_server,
+)
+
+# The same spec in every process: the name is the Modal app (and so the URL); max_num_seqs is the concurrency target.
+SPEC = ModelServerSpec(name="rw-qwen3-example", max_num_seqs=16)
+
+
+async def ask_one_question(server: ModelServer) -> None:
+    """Use the server like any model: name it for a role in the workspace's config, then call the engine."""
+    config = EngineConfig(store=StoreConfig.from_env(), models={ModelRole.GENERAL.value: server.model_id})
+    ws = open_workspace(config, corpus="model_server_example")
+    with measure_usage() as usage:
+        out = await agenerate_answer(
+            "How long is the warranty?",
+            [EvidenceItem(chunk_id="c1", text="The warranty period is 24 months from delivery.")],
+            ws=ws,
+        )
+    print(f"answer: {out.answer!r}")
+    print(f"metered on: {sorted(usage.by_model)} ({usage.calls} call)")
+    if sorted(usage.by_model) != [server.model_id]:
+        raise SystemExit(f"expected the call to be metered on {server.model_id}")
+
+
+async def deploy() -> None:
+    start = time.monotonic()
+    try:
+        server = await adeploy_model_server(SPEC, poll_s=20)  # deploys, waits for /health, registers the model id
+        print(f"ready in {time.monotonic() - start:.0f}s: model id {server.model_id}, endpoint {server.base_url}")
+        await ask_one_question(server)
+    finally:
+        stop_model_server(SPEC.name)  # always, even if something above failed
+    try:
+        await amodel_server(SPEC)
+    except Exception as exc:  # a stopped app no longer resolves
+        print(f"stopped: {SPEC.name} no longer resolves ({type(exc).__name__}); {time.monotonic() - start:.0f}s total")
+    else:
+        raise SystemExit(f"{SPEC.name} still resolves after stop")
+
+
+async def reconnect() -> None:
+    server = await amodel_server(SPEC)  # looks the server up and registers its model id; does not deploy
+    await await_model_server(server, poll_s=20)  # at once if it is up; through a cold start if it scaled down
+    await ask_one_question(server)
+
+
+if __name__ == "__main__":
+    load_dotenv()  # VLLM_API_KEY and ARCADEDB_* from .env
+    mode = sys.argv[1] if len(sys.argv) > 1 else ""
+    if mode not in ("deploy", "reconnect"):
+        raise SystemExit("usage: uv run python examples/model_server.py deploy|reconnect")
+    asyncio.run(deploy() if mode == "deploy" else reconnect())

{rag_wright-0.5.0 → rag_wright-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rag-wright"
-version = "0.5.0"
+version = "0.5.1"
 description = "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."
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

{rag_wright-0.5.0 → rag_wright-0.5.1}/src/rag_wright/models/model_servers.py

@@ -78,10 +78,10 @@ def _modal_cli(args: list[str], env: dict[str, str]) -> None:
     subprocess.run([sys.executable, "-m", "modal", *args], env=env, check=True)
 
 
-def _web_url(name: str) -> str:
+async def _web_url(name: str) -> str:
     import modal
 
-    url = modal.Function.from_name(name, _SERVE_FUNCTION).get_web_url()
+    url = await modal.Function.from_name(name, _SERVE_FUNCTION).get_web_url.aio()  # the async form: called in a loop
     if not url:
         raise RuntimeError(f"Modal app {name!r} has no web endpoint (is it deployed?)")
     return url.rstrip("/")
@@ -146,7 +146,7 @@ async def adeploy_model_server(spec: ModelServerSpec, *, wait: bool = True, time
     progress(f"[model-server] deploying {spec.name} ({spec.model}, {spec.gpu}, max_num_seqs={spec.max_num_seqs})")
     env = {**os.environ, **spec.deploy_env(), "VLLM_API_KEY": key}
     await asyncio.to_thread(_modal_cli, ["deploy", str(QWEN_MODAL_SCRIPT)], env)
-    server = _register(spec, await asyncio.to_thread(_web_url, spec.name))
+    server = _register(spec, await _web_url(spec.name))
     progress(f"[model-server] deployed {spec.name} at {server.base_url}; model id {server.model_id}")
     if wait:
         await await_model_server(server, timeout_s=timeout_s, poll_s=poll_s, progress=progress)
@@ -157,7 +157,7 @@ async def 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)."""
     _require_modal()
-    return _register(spec, await asyncio.to_thread(_web_url, spec.name))
+    return _register(spec, await _web_url(spec.name))
 
 
 def stop_model_server(name: str) -> None:

{rag_wright-0.5.0 → rag_wright-0.5.1}/tasks.md

@@ -3,9 +3,11 @@
 Phase 2 output. The persistent, cross-session task ledger and shared memory of progress. Derived
 from `plan.md` (Phase 1) and `SPEC.md` v0.1, honoring ADR-0001 (stack) and ADR-0002 (corpus).
 
-> **⇒ RESUME / NEXT UP (2026-10-09, NEWEST): public-surface workstream COMPLETE and RELEASED as `rag-wright` 0.4.0**
+> **⇒ RESUME / NEXT UP (2026-10-09, NEWEST): public-surface workstream COMPLETE and RELEASED as `rag-wright` 0.5.0**
 > (PyPI; 0.3.1 fixed 0.3.0's missing skills; 0.4.0 adds PS-R4, PS-12..PS-17: labelling eval, document metadata,
-> per-workspace models, config changes without restart, the workspaces guide, no Gemma default). Ledger:
+> per-workspace models, config changes without restart, the workspaces guide, no Gemma default); 0.5.0 adds
+> PS-18 (scikit-learn 1.9.1, Laya temperatures ADR-0129) and PS-19 (deploy the Qwen/Modal server from the engine,
+> ADR-0130). PS-20 (cold start) is tracked for later. Ledger:
 > **`docs/specs/public-surface/plan.md`** (PS-1..PS-19, PS-8a/8b/8c, PS-R1..PS-R5c; ADR-0125..0128). Delivered: gaps
 > G15-G21 closed (`pack_store`, bytes parsing, `ModelRole`, metering/tracing, answers + relevance on the API,
 > `RAG_MODELS_DIR` + reference weights on GCS, KG count/delete/update primitives) and the `rag_wright.pack_sdk` tier
@@ -13,7 +15,7 @@ from `plan.md` (Phase 1) and `SPEC.md` v0.1, honoring ADR-0001 (stack) and ADR-0
 > reference rule chosen on 510 CUAD contracts (ADR-0126); `build_ingestion(chunk_discoverer=)`; Qwen unpinned
 > (ADR-0125); graph-extraction failures kept as PARTIAL; domain vocabulary out of the generic engine (guard + ratchet;
 > OKF retired, ADR-0127); the engine's Claude Code skills shipped in the wheel at
-> `rag_wright/.agents/skills/` (PS-10). **Next (user gates): RuleWright moves (0.3 guide, then the 0.4 guide) from
+> `rag_wright/.agents/skills/` (PS-10). **Next (user gates): RuleWright moves (0.3, 0.4, then 0.5 guide) from
 > `docs/specs/public-surface/rulewright-migration-0.3.0.md`; PS-R4 (unit-labelling eval in `evaluate_ingestion`) is
 > done (unreleased); TexWright.**
 >

{rag_wright-0.5.0 → rag_wright-0.5.1}/tests/models/test_model_servers.py

@@ -38,7 +38,10 @@ def modal_fake(monkeypatch):
         return calls["health"] >= 2  # down on the first poll, ready on the second
 
     monkeypatch.setattr(ms, "_modal_cli", cli)
-    monkeypatch.setattr(ms, "_web_url", lambda name: URL)
+    async def web_url(name):
+        return URL
+
+    monkeypatch.setattr(ms, "_web_url", web_url)
     monkeypatch.setattr(ms, "_healthy", health)
     monkeypatch.setenv("ACME_VLLM_KEY", "secret-key")
     saved = dict(PROFILES)
@@ -108,6 +111,25 @@ async def test_reconnecting_registers_without_deploying(modal_fake):
     assert modal_fake["cli"] == [] and resolve_connection(server.model_id).base_url == URL + "/v1"
 
 
+async def test_the_url_lookup_uses_modals_async_interface(monkeypatch):
+    """Modal warns (AsyncUsageWarning) when its blocking interface runs inside an event loop; the deploy and reconnect
+    paths are async, so the lookup must use the `.aio` form."""
+    import sys
+    import types
+
+    class WebUrl:
+        def __call__(self):
+            raise AssertionError("the blocking get_web_url() was called from async code")
+
+        async def aio(self):
+            return URL + "/"
+
+    fake = types.SimpleNamespace(Function=types.SimpleNamespace(
+        from_name=lambda name, fn: types.SimpleNamespace(get_web_url=WebUrl())))
+    monkeypatch.setitem(sys.modules, "modal", fake)
+    assert await ms._web_url("acme-qwen") == URL
+
+
 def test_stop_stops_the_modal_app(modal_fake):
     stop_model_server("acme-qwen")
     assert modal_fake["cli"][0][0] == ["app", "stop", "acme-qwen", "--yes"]

{rag_wright-0.5.0 → rag_wright-0.5.1}/uv.lock

@@ -3534,7 +3534,7 @@ wheels = [
 
 [[package]]
 name = "rag-wright"
-version = "0.4.0"
+version = "0.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "arcadedb-python" },

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

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