rag-wright 0.15.0__tar.gz → 0.16.1__tar.gz

{rag_wright-0.15.0 → rag_wright-0.16.1}/.claude/skills/building-an-ingestion-capability/SKILL.md

@@ -28,7 +28,7 @@ Repository paths in this skill (`docs/`, `eval/`, `scripts/`, `tests/`, `src/`)
 | group spans into units | engine default, domain may override | a heading starts a unit, a table stays whole (a record table is one unit per row), page furniture dropped, units capped | `unit_grouper=`, `boundary_decider=` |
 | choose each unit's representative span (its `anchor` + leading tag) | **domain decision**, optional | the grouper's choice: the first member, often a heading | `unit_representative=` |
 | extract records from a unit | **domain (required)** | (none) | the `extractor` argument |
-| write records | engine default | `kg_write` | `writer=` |
+| write records | engine default | `kg_write` | `writer=` (returns the number of records now in the graph, or `None`) |
 | per-document follow-up (e.g. an entity graph) | domain, optional | none | `document_hook=` |
 | `Document` node, embedded children (`EmbeddedIn` / `AttachedTo`), progress, dead-lettering | engine | always on | (none) |
 

{rag_wright-0.15.0 → rag_wright-0.16.1}/.claude/skills/specifying-a-product-on-the-engine/SKILL.md

@@ -58,7 +58,7 @@ Every product item lands in one or more of these. The route column is where the
 | **Domain knowledge**: vocabulary, schema, constraints, synonyms, decision criteria | "controlled vocabularies", "the ontology", "mandatory fields", "valid ranges" | `EngineConfig(pack=...)` (the store creates the declared types on `open_workspace`); your capabilities read value sets and SHACL shapes with `rdflib` / `pyshacl` | `authoring-a-capability` | ontology authoring |
 | **Ingestion**: documents, spreadsheets, images, embedded files into the graph | "parse the forms", "load the lab reports", "idempotent re-runs" | `build_ingestion` (your extractor + optional hooks) → `aingest`; `IngestSource`, `IngestionTuning`, `table_rows` / `TableRow`, `evaluate_ingestion`, `check_extraction`; `KgNode` / `KgEdge` | `building-an-ingestion-capability` | KG construction |
 | **Entity and registry resolution** | "resolve against the yarn register", "queue unresolved mentions" | your `document_hook`; the entity-resolution building blocks on `rag_wright.pack_sdk` | `building-an-ingestion-capability` | entity resolution |
-| **A typed query or retrieval** | "find similar cases", "filter the table", "the dossier" | a query capability of your pack composing the primitives (`kg_read`, `kg_edges`, `NOT_NULL`, `Range`, hybrid span search with `span_search` from `rag_wright.api`), registered with `CapabilityManifest` + `register_capability` / `load_pack`, invoked with `ainvoke_subgraph` | `authoring-a-capability` | authoring capabilities |
+| **A typed query or retrieval** | "find similar cases", "filter the table", "the dossier" | a query capability of your pack composing the primitives (`kg_read`, `kg_edges`, `NOT_NULL`, `Range`, `Contains`, hybrid span search with `span_search` from `rag_wright.api`), registered with `CapabilityManifest` + `register_capability` / `load_pack`, invoked with `ainvoke_subgraph` | `authoring-a-capability` | authoring capabilities |
 | **A cited answer, or a refusal** | "every answer cites its source", "say when it is not in the records" | `agenerate_answer` over `EvidenceItem`s (an answer states its support; "none" abstains), `ajudge_spans` | `authoring-a-capability` | concepts (answers) |
 | **A typed decision or classification** | "classify the structure", "which of these is it" | `classifier-opportunity-analysis` first; then rules, a trained classifier, or the decision model (`jev_decision` from `engine_capabilities()`, criteria in the pack) | `classifier-opportunity-analysis` → `setfit` / `laya` | classification and decision models |
 | **A deterministic workflow behind a button** (mode **D**) | "upload, confirm, save", "export CSV" | a product **operation** (one function per user operation) calling your capabilities; the route calls the operation | `building-a-product-backend` | domain-adaptation step 8 |

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

@@ -28,8 +28,8 @@ open-core and domain-neutral; your product brings the domain. Hard rules:
   (`temporary_workspace`/`drop_workspace` for disposable and removed databases), the invokers
   (`ainvoke_subgraph`/`invoke_model`/`ainvoke_model`), discovery (`capability_index`/`discover`), the KG accessors
   (`kg_read`, `kg_write`, `kg_edges`, `kg_count`/`kg_delete`/`kg_update`, all filtering by `where` values that
-  are equality, a list for membership, `NOT_NULL` or a `Range(gt=, ge=, lt=, le=)` on any number of fields,
-  evaluated in the store;
+  are equality, a list for membership, `NOT_NULL`, a `Range(gt=, ge=, lt=, le=)` or a `Contains(text, case_sensitive=False)` (a literal
+  substring; an empty field never matches) on any number of fields, evaluated in the store;
   `entities_by_name`, `span_positions`), hybrid span search (`span_search` / `aspan_search`: cited spans from
   the dense and sparse index, fused in the store), `pack_store(ws, cls)` (build your pack's store extension over the
   workspace's store; the store itself stays private), metering and tracing (`measure_usage`, `record_usage`,

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

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

{rag_wright-0.15.0 → rag_wright-0.16.1}/CHANGELOG.md

@@ -4,6 +4,28 @@ 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.16.1](https://github.com/fzaidi-dai/RAG_Wright/compare/0.16.0...0.16.1) (2026-11-01)
+
+
+### Bug Fixes
+
+* **PS-57:** a retried write no longer loses a document's clauses; the conflict budget is configurable ([5d209d7](https://github.com/fzaidi-dai/RAG_Wright/commit/5d209d7eb1ab4bad93cd7026e81e79d9b6852fe5))
+* **PS-58:** a record writer reports the count that landed ([a7c384c](https://github.com/fzaidi-dai/RAG_Wright/commit/a7c384cfab59832f9714bac9996f91a29340ed71))
+* **PS-59:** the store's client keeps keep-alive connections, one session per thread ([f644ba3](https://github.com/fzaidi-dai/RAG_Wright/commit/f644ba3f3f37f12102037405b9a58567098358b3))
+
+## [0.16.0](https://github.com/fzaidi-dai/RAG_Wright/compare/0.15.0...0.16.0) (2026-10-28)
+
+
+### Features
+
+* **PS-54:** a Contains where value matches a substring of a text field in the store ([e00b9e2](https://github.com/fzaidi-dai/RAG_Wright/commit/e00b9e271f7185cf5c15a0312d2e76c7c1eb68c6))
+
+
+### Bug Fixes
+
+* **PS-55:** only the BGE models run on Metal, one call at a time per process ([1cb1c90](https://github.com/fzaidi-dai/RAG_Wright/commit/1cb1c90ccc1d5e93421806c26862ab97d503bb72))
+* **PS-56:** the BGE reranker scores again on transformers 5 ([d06ec1b](https://github.com/fzaidi-dai/RAG_Wright/commit/d06ec1b97ad4ae457a232ba9f1bb5e89b033513b))
+
 ## [0.15.0](https://github.com/fzaidi-dai/RAG_Wright/compare/0.14.1...0.15.0) (2026-10-28)
 
 

{rag_wright-0.15.0 → rag_wright-0.16.1}/CLAUDE.md

@@ -55,7 +55,11 @@ The failure mode to avoid, which has happened before: a command fails with "modu
 
 ## Start of every session
 
-> **CURRENT STATE (2026-10-28): `rag-wright` 0.14.1 is RELEASED** (PR #17; TexWright's two requests: PS-49 a retried
+> **CURRENT STATE (2026-10-29): `rag-wright` 0.16.0 is RELEASED** (PR #19; TexWright's requests: PS-54 a `Contains`
+> substring `where` value, PS-55 only the BGE models on Metal under one process lock (ADR-0140); PS-56 the BGE reranker
+> scores again on transformers 5). Before it, **`rag-wright` 0.15.0 is RELEASED** (PR #18; PS-51 the frontend skill draws the shell and
+> ships its scaffold, RuleWright's request; PS-52 one workspace embedder under concurrent first use and PS-53 KG calls refuse
+> a name that is not an identifier, TexWright's requests). Before it, **`rag-wright` 0.14.1 is RELEASED** (PR #17; TexWright's two requests: PS-49 a retried
 > ArcadeDB write conflict no longer prints as an error, PS-50 `ensure_pack_schema` declares a property a pack gains on an
 > existing type). Before it, **(2026-10-17): the LangGraph ingestion workstream is RELEASED as `rag-wright` 0.14.0** (PR #16; LGI-1..5,
 > `docs/specs/langgraph-ingestion/plan.md`, ADR-0124 amended): `build_ingestion` is a LangGraph graph

{rag_wright-0.15.0 → rag_wright-0.16.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rag-wright
-Version: 0.15.0
+Version: 0.16.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
@@ -42,6 +42,7 @@ Requires-Dist: pydantic>=2.0
 Requires-Dist: pypdfium2>=5.11
 Requires-Dist: pyshacl>=0.40.1
 Requires-Dist: python-dotenv>=1.2
+Requires-Dist: requests>=2.34.2
 Requires-Dist: scikit-learn>=1.9.1
 Requires-Dist: sentence-transformers>=6.1.0
 Requires-Dist: transformers<5.9,>=5.4

rag_wright-0.16.1/docs/adr/0140-one-model-family-on-metal.md

@@ -0,0 +1,57 @@
+# ADR-0140: One model family on Metal, under one process lock
+
+**Status:** accepted · **Date:** 2026-10-29 · **Related:** PS-55, TexWright's request
+`2026-10-25-two-model-families-in-one-process-abort-on-metal.md`, RuleWright T-7.25 / T-7.46 (`_avoid_mps`), ADR-0076
+(issue 0016, the per-instance embedder lock), ADR-0138 (pdfium)
+
+## Context
+
+PyTorch's Apple Metal (`mps`) backend is not safe for concurrent use. Two threads running models on it abort the
+process inside Metal (`failed assertion _status < MTLCommandBufferStatusCommitted ... setCurrentCommandEncoder:`) or
+segfault it. Either way it is a native `abort()`, so nothing in Python can catch it.
+
+The engine reached Metal from three model families, each choosing its own device automatically:
+
+- the BGE-M3 embedder (`_resolve_device`);
+- the BGE reranker (FlagEmbedding's choice);
+- Docling's layout, table and RapidOCR-torch models (`AcceleratorOptions(device="auto")`).
+
+It also runs them on different threads: an ingest embeds one document while it parses another, and a server embeds
+a query while an upload parses. Issue 0016's per-instance locks do not help across instances or families.
+
+Reproduced with the BGE-M3 embedder in one thread and Docling in another, each run in a child process:
+
+- On torch 2.14.1 (TexWright's environment), 6 of 6 runs died within seconds: 5 SIGABRT with TexWright's
+  assertion, 1 SIGSEGV. Three of the runs OCR'd a screen image and three parsed PDFs.
+- On torch 2.12.1 the same shapes survived every run, so the failure depends on the torch version, and the newer
+  version makes it certain.
+- RuleWright measured it independently on their contract ingest: 4 crashes in about 8 runs on Metal, 0 in 6 on CPU.
+  They fixed it in their own seam (`_avoid_mps`), and the engine never adopted the fix.
+
+`docs/workspaces.md` claimed that concurrent calls in one process are safe without qualification.
+
+## Decision
+
+- **`rag_wright.util.devices`** owns the engine's device policy. Unless told otherwise, it uses CUDA when present.
+  On Metal it allows only the BGE family (the embedder and the reranker, the hot path, about 2x faster there).
+  Everything else goes to CPU.
+- **Docling** runs on CPU where its `auto` would pick Metal. The engine passes the device explicitly, because
+  Docling's default options are built once at import. Docling's output is identical on CPU and Metal (measured on
+  the engine's fixtures).
+- **The reference pack's classifiers** (SetFit, Laya) follow the same policy. Packs get it through
+  `pack_sdk.torch_device`, which never picks Metal unless asked.
+- **On Metal, every BGE call holds `METAL_LOCK`**, one re-entrant lock per process. Two embedders, or an embedder
+  and the reranker, never run on Metal at once. Off Metal each instance keeps its own lock (issue 0016), so a CUDA
+  host loses no concurrency.
+- **Explicit choices always win**, `mps` included: `EMBED_DEVICE` (the whole BGE family), `DOCLING_DEVICE`,
+  `RAG_SETFIT_DEVICE`, and any `device=` argument. This keeps the crash reproducible, and it means an operator who
+  puts a second family on Metal gives up the guarantee.
+
+## Consequences
+
+- A product needs no process-per-pipeline workaround. A server may stage an upload's ingest beside query traffic.
+  RuleWright can delete `_avoid_mps`, and TexWright can delete its spawned-process seed and the skipped browser test.
+- On Apple Silicon, Docling parses and the pack classifiers run on CPU (slower than Metal), and BGE calls from
+  different instances queue behind one another. A CUDA or CPU-only host is unchanged.
+- The rule holds only while engine code chooses the devices. A product's own torch model should take its device from
+  `pack_sdk.torch_device`, or it must stay off Metal.

{rag_wright-0.15.0 → rag_wright-0.16.1}/docs/adr/README.md

@@ -195,4 +195,5 @@ framing that still appears in older ADRs and the root `SPEC.md`/`plan.md`.
 0136 A spreadsheet table cut at its blank rows is glued back together after the parse ·
 0137 A generated answer states the evidence's support every time, and "none" is an abstention ·
 0138 PDF parses run one at a time, and the engine reaches pdfium through one locked door ·
-0139 The agent harness substrate is engine scope
+0139 The agent harness substrate is engine scope ·
+0140 One model family on Metal, under one process lock

{rag_wright-0.15.0 → rag_wright-0.16.1}/docs/api/README.md

@@ -8,7 +8,7 @@
 
 The product's view of the engine: the store connection, chosen models (`models`: `ModelRole` value -> model alias), the embedding profile, the `options` catalog (generic `ingest` knobs + each pack's options under `packs`), and `pack`: the path to the domain pack `.ttl` whose KG types `open_workspace` creates (None = only the neutral engine types: Chunk, Entity, Relationship, Mentions, Span, Document, EmbeddedIn, AttachedTo). Defaults just work; override only to trade quality/cost/latency. Implementation details (ArcadeDB, BGE) never cross this boundary.
 
-### `StoreConfig(host: 'str', port: 'str', user: 'str', password: 'str', backend: 'str' = 'arcadedb', protocol: 'str' = 'http') -> None`
+### `StoreConfig(host: 'str', port: 'str', user: 'str', password: 'str', backend: 'str' = 'arcadedb', protocol: 'str' = 'http', conflict_attempts: 'Optional[int]' = None, conflict_backoff_cap_s: 'Optional[float]' = None) -> None`
 
 How to reach the KG/retrieval store. `backend` selects the implementation (only `arcadedb` today; a new backend -- e.g. Neo4j -- is added here, invisibly to the product).
 
@@ -88,6 +88,10 @@ A `where` value meaning a comparison, evaluated in the store (ER-1): `gt` (>), `
 
 `[(operator, bound), ...]`, lower bound first.
 
+### `Contains(text: 'str', case_sensitive: 'bool' = False) -> None`
+
+A `where` value meaning "this string field contains `text`", evaluated in the store (PS-54). The match is literal (`%`, `_` and `?` are ordinary characters), case-insensitive unless `case_sensitive=True`, and a field with no value never matches. It composes with equality, membership, `NOT_NULL` and `Range` on every KG call that takes `where`: `where={"composition": Contains("UHMWPE"), "gsm": Range(ge=250, le=320)}`.
+
 ### `BlankPageText(*, source: str, pages: dict[int, str], cache_files: list[str]) -> None`
 
 One cached parse with text on blank pages. `source` is the PDF's path (or the name given with its bytes), `pages` maps each blank page to the text the cached parse holds there, and `cache_files` are the cached parse(s) and their OCR sidecar: delete them, then re-ingest the document so it is parsed again.
@@ -300,9 +304,9 @@ PS-R3: which member span represents a unit -- a DOMAIN decision. The engine appl
 
 One unit -> the domain's typed records (required; the domain-specific step).
 
-### `RecordWriter: (source_doc_id: 'str', extractions: 'Sequence[UnitExtraction]') -> 'Awaitable[None]'`
+### `RecordWriter: (source_doc_id: 'str', extractions: 'Sequence[UnitExtraction]') -> 'Awaitable[Optional[int]]'`
 
-Optional: persist a document's extractions. The engine default writes them with `kg_write`.
+Optional: persist a document's extractions. The engine default writes them with `kg_write`. Return the number of records now in the graph (written, or found already written); `None` lets the engine count the record nodes it handed over (RuleWright, 2026-10-31: only the writer knows what landed).
 
 ### `BoundaryDiscoverer: (**kwargs)`
 
@@ -424,7 +428,7 @@ Rank the live ARD catalog by semantic match to `query`; return the top `k` (opti
 
 ### `kg_read(ws: 'WorkspaceHandle', node_type: 'str', *, where: 'Optional[dict]' = None, fields: 'Optional[list]' = None, distinct: 'Optional[str]' = None, order_by: 'Optional[str]' = None, limit: 'Optional[int]' = None, key_range: 'Optional[tuple]' = None) -> 'list[dict]'`
 
-Read typed nodes of `node_type` from the workspace (see `Store.kg_read`). Each `where` value is a scalar (equality), a list (membership; an empty list is scope-to-nothing -> `[]`), `NOT_NULL` (presence) or a `Range` (comparisons, on any number of fields: `{"weight": Range(ge=180, le=220), "tensile": Range(gt=400)}`); all filters are AND-ed and evaluated in the store. `key_range=(field, lo, hi)` is the half-open shorthand (`lo <= field < hi`). Then projection, distinct, order and limit. Every name is checked, never interpolated unchecked (the module docstring): a request-chosen field is safe, but an unknown one matches nothing.
+Read typed nodes of `node_type` from the workspace (see `Store.kg_read`). Each `where` value is a scalar (equality), a list (membership; an empty list is scope-to-nothing -> `[]`), `NOT_NULL` (presence), a `Range` (comparisons, on any number of fields: `{"weight": Range(ge=180, le=220), "tensile": Range(gt=400)}`) or a `Contains` (a literal substring, case-insensitive unless `case_sensitive=True`; an empty field never matches: `{"composition": Contains("UHMWPE")}`); all filters are AND-ed and evaluated in the store. `key_range=(field, lo, hi)` is the half-open shorthand (`lo <= field < hi`). Then projection, distinct, order and limit. Every name is checked, never interpolated unchecked (the module docstring): a request-chosen field is safe, but an unknown one matches nothing.
 
 ### `kg_write(ws: 'WorkspaceHandle', nodes: 'list', edges: 'Any' = ()) -> 'None'`
 
@@ -436,7 +440,7 @@ Generic edge TRAVERSAL over the workspace (see `Store.kg_edges`): node-start out
 
 ### `kg_count(ws: 'WorkspaceHandle', type_name: 'str', *, where: 'Optional[dict]' = None, key_range: 'Optional[tuple]' = None) -> 'int'`
 
-The number of vertices or edges of `type_name` matching `where` / `key_range` (see `Store.kg_count`); `where` as in `kg_read`, `Range` values included.
+The number of vertices or edges of `type_name` matching `where` / `key_range` (see `Store.kg_count`); `where` as in `kg_read`, `Range` and `Contains` values included.
 
 ### `kg_delete(ws: 'WorkspaceHandle', type_name: 'str', *, where: 'Optional[dict]' = None, key_range: 'Optional[tuple]' = None) -> 'int'`
 

{rag_wright-0.15.0 → rag_wright-0.16.1}/docs/api/pack_sdk.md

@@ -116,11 +116,11 @@ Write the document's nodes/edges (one transaction), unless an unchanged run alre
 
 The graph query capability's output: candidate answers as evidence for fusion (FR-C.5, FR-Q.3).
 
-### `BGEReranker(model_name: 'str' = 'BAAI/bge-reranker-v2-m3', *, use_fp16: 'bool' = False, model: 'object | None' = None) -> 'None'`
+### `BGEReranker(model_name: 'str' = 'BAAI/bge-reranker-v2-m3', *, use_fp16: 'bool' = False, device: 'str | None' = None, model: 'object | None' = None) -> 'None'`
 
-The real reranker: `FlagEmbedding.FlagAutoReranker` (model loaded lazily).
+The real reranker: a `sentence_transformers.CrossEncoder` over `bge-reranker-v2-m3` (PS-56), scoring raw logits (no activation), 512 tokens per pair as before.
 
-THREAD-SAFE (engine issue 0016): FlagEmbedding mutates the model in place on every call (the same in-place `.to()`/`.eval()` conversions that segfault the shared BGE-M3 embedder under thread concurrency), so a shared reranker is guarded by an instance lock too -- defense-in-depth for any concurrent `score` caller.
+THREAD-SAFE (engine issue 0016): a shared reranker is guarded by an instance lock -- defense-in-depth for any concurrent `score` caller (its FlagEmbedding predecessor mutated the model in place on every call). It is in the BGE family: its device follows the embedder's (`EMBED_DEVICE`), and on Metal its lock is the process-wide one the embedders hold (PS-55), so a rerank never runs on Metal beside an embed.
 
 #### `BGEReranker.score(self, query: 'str', passages: 'list[str]') -> 'list[float]'`
 
@@ -182,7 +182,7 @@ Group into units (checked), attach table rows, extract each unit concurrently (p
 
 #### `IngestionStages.write(self, sd: 'Any', extractions: 'list') -> 'int'`
 
-Persist the records (the domain's writer, else `kg_write`). Returns the number of record nodes.
+Persist the records (the domain's writer, else `kg_write`). Returns the number that landed: the writer's own count when it returns one; else the record nodes handed over, which the default `kg_write` lands in one transaction (it raises rather than land part of them).
 
 #### `IngestionStages.write_document_node(self, doc_id: 'str', *, parent_id: 'Optional[str]', filename: 'str', media_type: 'str', sha256: 'str', metadata: 'Optional[dict]' = None) -> 'None'`
 
@@ -358,6 +358,10 @@ True when at least one usage scope is active — the seam checks this to decide
 
 The models root (see the module docstring for the resolution order).
 
+### `torch_device(explicit: 'Optional[str]' = None, *, env: 'Optional[str]' = None, metal: 'bool' = False) -> 'str'`
+
+The device for one engine model: `explicit`, else the `env` variable, else CUDA when present, else Metal only for the family allowed on it (`metal=True`, the BGE family), else CPU.
+
 ### `business_span(name: 'str', **attributes: 'Any') -> 'Iterator[Any]'`
 
 A domain/business span on the AMBIENT tracer (never a new provider). No-op when OTel is absent.

{rag_wright-0.15.0 → rag_wright-0.16.1}/docs/configuration.md

@@ -45,6 +45,14 @@ configuration change takes effect without a restart ([`workspaces.md`](workspace
 | `password` | `str` | — | password |
 | `backend` | `str` | `"arcadedb"` | store implementation (only `arcadedb` today) |
 | `protocol` | `str` | `"http"` | `http` locally; `https` for a remote/Modal store |
+| `conflict_attempts` | `int \| None` | `None` | attempts per write when ArcadeDB reports a write conflict (`None`: `ARCADEDB_CONFLICT_ATTEMPTS`, else 20) |
+| `conflict_backoff_cap_s` | `float \| None` | `None` | the longest wait between those attempts, in seconds (`None`: `ARCADEDB_CONFLICT_BACKOFF_CAP_S`, else 2) |
+
+Concurrent writers that touch the same page get a write conflict; the store retries the write (the failed
+transaction is rolled back whole) with a doubling wait from 10 ms up to the cap. Two writers creating the same new
+node by `kg_write` get a duplicate key instead, which is retried the same way. A write that is still conflicting
+after the last attempt raises, about 25 s after the first one with the defaults. Raise the budget when more than
+eight documents write into one graph at once.
 
 `StoreConfig.from_env()` builds one from `ARCADEDB_HOST` (default `localhost`), `ARCADEDB_PORT` (required: no
 default, so an unset variable cannot reach another instance on the machine),
@@ -284,6 +292,7 @@ Prefer config; use env for secrets and for non-API callers. The common ones the
 | variable | purpose |
 |---|---|
 | `ARCADEDB_HOST` / `ARCADEDB_PORT` / `ARCADEDB_USER` / `ARCADEDB_PASSWORD` / `ARCADEDB_DATABASE` / `ARCADEDB_PROTOCOL` | store connection: `StoreConfig.from_env()` reads them (and the scripts do); `open_workspace` itself reads only the `StoreConfig` it is given |
+| `ARCADEDB_CONFLICT_ATTEMPTS` / `ARCADEDB_CONFLICT_BACKOFF_CAP_S` | the write-conflict retry budget when `StoreConfig.conflict_attempts` / `conflict_backoff_cap_s` are unset |
 | `OPENROUTER_API_KEY` / `OPENROUTER_BASE_URL` / `OPENROUTER_PROVIDER` / `OPENROUTER_ALLOW_FALLBACKS` | OpenRouter access + provider routing (`OPENROUTER_SORT` / `OPENROUTER_PROVIDER_ORDER`: the contracts pack's docling-graph extraction only) |
 | `RAG_SERVING` / `VLLM_BASE_URL` / `VLLM_API_KEY` / `STACK_URL` | serving backend (openrouter \| vllm) + self-hosted endpoint |
 | `RAG_MODEL_<ROLE>` (e.g. `RAG_MODEL_GENERAL`, `RAG_MODEL_VISION_OCR`) / `RAG_MODEL_ALL` / `RAG_GRAPH_EXTRACT_MODEL` / `RAG_DECISION_MODEL` | model overrides (one role / all roles / graph extraction / decision-model profile) |
@@ -294,7 +303,8 @@ Prefer config; use env for secrets and for non-API callers. The common ones the
 | `RAG_MODEL_DEADLINE_S` | total wall-clock limit for one model call across its retries (default: follows `RAG_STRUCTURED_TIMEOUT_S`, never under 180 s) |
 | `RAG_SPACY_MODEL` | the spaCy model name for the optional NER extra |
 | `RAG_MODELS_DIR` | the models root every trained classifier loads its weights from (default: the engine checkout's `data/models` when it exists, else `./data/models`); fill it with `scripts/fetch_reference_models.py` for the reference pack |
-| `EMBED_DEVICE` / `RAG_SETFIT_DEVICE` / `RAG_SETFIT_CLAUSE_DIR` / `RAG_SETFIT_THRESHOLD` / `RAG_SETFIT_TOPK` | embedder / classifier device + fleet knobs (`RAG_SETFIT_CLAUSE_DIR` overrides `<models root>/setfit_clause`) |
+| `EMBED_DEVICE` / `DOCLING_DEVICE` / `RAG_SETFIT_DEVICE` | where the local models run. Unset: CUDA when present; on Apple Silicon the BGE embedder and reranker (`EMBED_DEVICE`) run on Metal under one process lock and Docling and the classifiers on CPU, because Metal is not safe for concurrent use (PS-55, `docs/workspaces.md`). An explicit value, `mps` included, always wins |
+| `RAG_SETFIT_CLAUSE_DIR` / `RAG_SETFIT_THRESHOLD` / `RAG_SETFIT_TOPK` | classifier fleet knobs (`RAG_SETFIT_CLAUSE_DIR` overrides `<models root>/setfit_clause`) |
 | `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` / `LANGFUSE_HOST` / `RAG_TRACE_LEVEL` | observability (Langfuse tracing; see [`OBSERVABILITY.md`](OBSERVABILITY.md)) |
 | `RAG_EVAL_BACKEND` | `local` (default) or `langfuse`: where `arun_eval` runs when its `langfuse` argument is not given. `langfuse` needs the Langfuse keys and a gold set with `local_only=False`; a `local_only` gold set is refused before anything is sent |
 

{rag_wright-0.15.0 → rag_wright-0.16.1}/docs/domain-adaptation/kg-construction.md

@@ -59,7 +59,9 @@ parse → chunk → segment (+ optional tag) → index  (embed each span → the
   A unit holding exactly one data row of a parsed table carries that row as `Unit.table_row` (exact cells).
 - **extract**: your `extractor` turns each unit into **typed records** (`UnitExtraction`: `KgNode`s and `KgEdge`s
   in your pack's schema). This is the domain-specific step.
-- **write**: persist the records (your `writer`, else `kg_write`), then a generic `Document` node per document.
+- **write**: persist the records (your `writer`, else `kg_write`), then a generic `Document` node per document. Your
+  `writer` returns the number of records now in the graph (the report's `records`), or `None` to let the engine count
+  the record nodes it handed over.
 - **entity graph + resolve**: not run by default. Run your entity extraction and resolution in a `document_hook`
   (see [entity resolution](entity-resolution.md)).
 

{rag_wright-0.15.0 → rag_wright-0.16.1}/docs/specs/public-surface/plan.md

@@ -125,4 +125,10 @@ in two at the PS-6 gate so the store rewrite is its own visible task. One task,
 | PS-51 | RuleWright's request (`docs/engine-requests/2026-10-28-the-frontend-skill-never-says-what-the-shell-looks-like.md`, their repo; TexWright shipped a top bar, no rail, no detail region, no current-surface state): `building-a-product-frontend` gains Decision 2, the shell's regions (`rail | main detail` over a reserved run row, entailed by the six things; a horizontal bar cannot grow; four columns do not fit at 1440px), the registry's real fields (`nav: { label, end }`, no `icon`), `aria-current` and more than colour with its test, the shell before the surfaces in the build order, two checklist items, and a shipped scaffold (`scaffold/surfaces.tsx`, `ShellLayout.tsx`, `ShellLayout.test.tsx`) | scaffold: strict `tsc`, 7/7 jsdom tests, the `end` and `aria-current` guards proved by planting; a production build measured in Chromium at 1440x900 (rail 256px, detail beside main, 44px links); `test_shipped_skills.py` checks the scaffold is named and ships in wheel + sdist | done 2026-10-28 |
 | PS-52 | TexWright's request (`docs/engine-requests/2026-10-24-workspace-embedder-is-not-thread-safe.md`, their repo): `WorkspaceHandle._embedder` was an unguarded check-then-set, so threads arriving at first use each built a model (`arun_eval(concurrency=4)`: four loads, then a SIGSEGV; each `BGEM3Embedder` locks only itself). A per-handle lock with a double check builds one; `ws.embedder`, `workspace_embedder` and `span_search` say the embedder may be called from several threads | a hermetic 8-thread first-use test (8 builds before, 1 after); live BGE-M3, 4 threads x 3 runs: 4 models in 12-18s before, 1 model in ~6s after; API reference regenerated | done 2026-10-28 |
 | PS-53 | TexWright's request (`docs/engine-requests/2026-10-21-identifiers-in-kg-queries-are-interpolated-unescaped.md`, their repo): KG calls escaped VALUES but interpolated NAMES raw (`where={"1=1 OR id": NOT_NULL}` returned every row). Every name a KG call puts into SQL is now checked first (types; `where` / `key_range` / `set` / `fields` / `distinct` fields; `order_by` terms; `kg_edges` select aliases and expressions; `KgNode` / `KgEdge` properties, key fields and types): an identifier, `@rid`/`@type`/`@in`/`@out` where read, `field [ASC|DESC]`, or a field on `c.`/`e.`/`v.`/`inV().`/`outV().`; else `ValueError`, nothing sent. Unknown fields still match nothing (undeclared properties are supported, the engine's own types carry them); the API docstrings say so | 29 hermetic cases (28 fail before); TexWright's payloads refused live; full hermetic (2327) and live store (67) suites green | done 2026-10-28 |
+| PS-54 | TexWright's request (`docs/engine-requests/2026-10-19-substring-match-in-the-kg-filter-grammar.md`, their repo): the KG filter grammar had no substring predicate ("composition contains UHMWPE" over free text). `Contains(text, case_sensitive=False)`, a `where` value beside `Range` on every KG call that takes `where`: a literal `indexOf` test (not `LIKE`, whose `%`, `_` and `?` are wildcards, measured live), case folded on both sides in the store, a field with no value never matches, empty text refused | 8 hermetic tests (red before) + a live test (case both ways, literal wildcards, quotes and backslashes, accents, missing values, with `Range`, `kg_count`, a `kg_edges` traversal filtered at all three points); full hermetic (2353) and live store (42) suites green | done 2026-10-29 |
+| PS-55 | TexWright's request (`docs/engine-requests/2026-10-25-two-model-families-in-one-process-abort-on-metal.md`, their repo): Metal is not safe for concurrent use and the engine put three families on it automatically (BGE-M3, the BGE reranker, Docling's layout/table/RapidOCR models), then ran them on different threads (an ingest embeds while it parses; a server embeds a query while an upload parses), so a process aborted in Metal. RuleWright had measured and pinned it in their own seam (T-7.25/T-7.46), never adopted here. `rag_wright.util.devices` (ADR-0140): only the BGE family on Metal, every call there under one process lock (`METAL_LOCK`); Docling and the pack classifiers on CPU where Metal would be picked (`pack_sdk.torch_device`); explicit device variables win; CUDA/CPU hosts unchanged; `docs/workspaces.md` corrected | red, torch 2.14.1 (TexWright's env, this engine tree): embedder + Docling in two threads, 6/6 child runs died in seconds (5 SIGABRT with their assertion, 1 SIGSEGV; OCR and PDF); torch 2.12.1 never failed. Green, same interpreter: 9/9 runs survived 150s each (OCR, PDF, two embedders). Full hermetic (2361) and live embed/parse/store (60) suites green. 8 hermetic tests (4 behaviour tests red before); Docling output identical CPU vs Metal | done 2026-10-29 |
+| PS-56 | Found during PS-55: `BGEReranker` failed on every call (`XLMRobertaTokenizer has no attribute prepare_for_model`): FlagEmbedding's `FlagAutoReranker.compute_score` calls a tokenizer method transformers 5 removed, so the reference pack's `intra_document_qa` rerank (and RuleWright's copy) and any product composing `BGEReranker` over `span_search` hits were broken. The reranker is now a `sentence_transformers.CrossEncoder` (already a dependency) over the same `bge-reranker-v2-m3`, raw logits, 512 tokens per pair; same `BGEReranker` API, device and lock (PS-55) | red: the live reranker test failed on the tokenizer error. Green: it passes, plus a one-pair and a >512-token case; CrossEncoder's logits equal the model card's plain-transformers recipe (max abs diff 0.0, truncated passage included); embedder + reranker on Metal under the shared lock, torch 2.14.1: 3/3 runs survived 150s, 590 reranks and 586 embeds, none failing (before: the rerank thread died on its first call); full hermetic (2361) green | done 2026-10-29 |
+| PS-57 | RuleWright's request (`docs/engine-requests/2026-10-31-a-write-conflict-loses-a-documents-clauses-and-your-pack-carries-the-defect.md`, their repo): at 4 concurrent documents, 2 of 15 reported `ingested` with zero clauses. The contracts pack's `write` node popped the pending extractions (filled by `extract_clauses`) before the store write landed, so the node's retry wrote nothing and reported success; it now reads them and releases them after the write. The conflict budget is reachable: `StoreConfig.conflict_attempts` / `conflict_backoff_cap_s`, else `ARCADEDB_CONFLICT_ATTEMPTS` / `ARCADEDB_CONFLICT_BACKOFF_CAP_S`; default raised 10 attempts / 0.5 s cap to 20 / 2 s. Found by the live probe: two writers creating the same new node get a duplicate key, never retried; `kg_write` and `write_graph` (UPSERT-only) now retry it | pack retry test through the real per-document graph (0/3 clauses landed before, 3/3 after); six store tests; live probe (clause-shaped transactions over shared value nodes, pooled sessions): old budget lost 38/2,400 at 4 and 8 writers, new lost 0/2,400 at the same wall-clock; live store suite 42 passed | done 2026-11-01 |
+| PS-58 | RuleWright's request (`docs/engine-requests/2026-10-31-ingestionstages-write-returns-a-count-derived-from-its-own-input.md`, their repo): `IngestionStages.write` returned the record nodes it was handed, and `RecordWriter` (declared `-> None`) could not say what landed. A writer now returns the number of records in the graph (`Optional[int]`; `None` keeps the engine's count); the default `kg_write` branch keeps the handed-over count, true because that write is one transaction (lands whole or raises). The contracts pack's writer returns the clauses in the graph and its `write` node reports that as `clauses` | three hermetic tests + the PS-57 retry test's count (red before, green after); live `build_ingestion` on two fixtures: default and a writer landing every other record, `records` equals the graph in all four documents | done 2026-11-01 |
+| PS-59 | Found during PS-57: the ArcadeDB client opens a new connection for every request (`requests.post`, no session); at 8 concurrent writers against Docker on macOS about two thirds of writes failed with `RemoteDisconnected`, and with a keep-alive session per thread the same run lost none. Give the store's client a pooled session | live probe at 8 writers: zero connection drops | done 2026-11-01: the store's client (`_PooledClient`) keeps one keep-alive `requests.Session` per thread and `ArcadeDBStore.close()` releases them; live, the same probe lost 374 of 800 transactions to `RemoteDisconnected` unpooled and 0 of 800 at 8 writers and 0 of 1,600 at 16 pooled |
 | PS-48 | Port the agent harness's substrate behaviour tests from RuleWright onto the engine's fabric fixture (ADR-0139 handover): of RuleWright's 553 harness-touching tests, 314 test the substrate (port), 213 RuleWright's composition (stay), 25 live (1 substrate: OpenRouter cost accounting). Seven gated sub-tasks: **a** shared `tests/harness/fabric.py` + scripting/slow/hanging/failing fake models + `InMemorySaver` helpers, then events, skills, clarify (~23); **b** models and errors (~42); **c** runs, confirm, continuation (~32); **d** decisions and rules (~51); **e** grading (~32); **f** seen and memory (~41); **g** workers, batch, dispatch, tiers, agent wiring, filesystem, interpreter, withhold + the live accounting test (~93, may split). Ambiguous tests split, not moved whole; a ported test failing on engine code is a substrate defect fixed in that sub-task; deadline globals via monkeypatch; no new dependencies. Follow-up (owner RuleWright): retire its substrate duplicates once ported | each sub-task's ported tests green on the fabric fixture | todo (proposed; awaiting go-ahead) |

{rag_wright-0.15.0 → rag_wright-0.16.1}/docs/workspaces.md

@@ -31,11 +31,18 @@ crosses corpora: every read and write goes through the handle's store.
 | per process | the serving backend and endpoints, provider routing, call timeouts | `RAG_SERVING`, `VLLM_BASE_URL`, `OPENROUTER_*`, `RAG_*_TIMEOUT_S` |
 | per process | the decision model's profile (one call can name another in the `jev_decision` input `model`) | `RAG_DECISION_MODEL` |
 | per process | trained classifier weights and their knobs | `RAG_MODELS_DIR`, `RAG_SETFIT_*` |
+| per process | where the local models run (Metal, CUDA or CPU) | `EMBED_DEVICE`, `DOCLING_DEVICE`, `RAG_SETFIT_DEVICE` |
 | per process | one cached handle per corpus, replaced when the corpus is opened with a different config | see "Changing a workspace's configuration" |
 | per process | the reference pack's graph-extraction model and its standalone MCP servers (they read the environment when they start) | `RAG_GRAPH_EXTRACT_MODEL`; one server process per deployment |
 
 Concurrent calls for different workspaces in one process are safe: each call resolves its own workspace's models,
-and metering and trace scopes belong to the call that opened them.
+and metering and trace scopes belong to the call that opened them. That includes Apple Silicon, where it takes one
+rule (PS-55): PyTorch's Metal backend is not safe for concurrent use (two threads running models on it abort the
+process inside Metal, which no caller can catch), so the engine keeps only its BGE models (the embedder and the
+reranker) on Metal, every call to them under one process-wide lock, and runs Docling and the classifiers on CPU. A
+query embedding in a server and an upload's parse in the same process therefore never meet on Metal. Setting
+`DOCLING_DEVICE=mps` or `RAG_SETFIT_DEVICE=mps` puts a second family back on Metal and gives this up; a pack's own
+torch model takes its device from `pack_sdk.torch_device`, which never picks Metal unless asked.
 
 ## Managing workspaces
 

{rag_wright-0.15.0 → rag_wright-0.16.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rag-wright"
-version = "0.15.0"
+version = "0.16.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"
@@ -51,6 +51,7 @@ dependencies = [
     "pypdfium2>=5.11",
     "pyshacl>=0.40.1",
     "python-dotenv>=1.2",
+    "requests>=2.34.2",
     "scikit-learn>=1.9.1",
     "sentence-transformers>=6.1.0",
     "transformers>=5.4,<5.9",

{rag_wright-0.15.0 → rag_wright-0.16.1}/src/rag_wright/.agents/skills/building-an-ingestion-capability/SKILL.md

@@ -28,7 +28,7 @@ Repository paths in this skill (`docs/`, `eval/`, `scripts/`, `tests/`, `src/`)
 | group spans into units | engine default, domain may override | a heading starts a unit, a table stays whole (a record table is one unit per row), page furniture dropped, units capped | `unit_grouper=`, `boundary_decider=` |
 | choose each unit's representative span (its `anchor` + leading tag) | **domain decision**, optional | the grouper's choice: the first member, often a heading | `unit_representative=` |
 | extract records from a unit | **domain (required)** | (none) | the `extractor` argument |
-| write records | engine default | `kg_write` | `writer=` |
+| write records | engine default | `kg_write` | `writer=` (returns the number of records now in the graph, or `None`) |
 | per-document follow-up (e.g. an entity graph) | domain, optional | none | `document_hook=` |
 | `Document` node, embedded children (`EmbeddedIn` / `AttachedTo`), progress, dead-lettering | engine | always on | (none) |
 

{rag_wright-0.15.0 → rag_wright-0.16.1}/src/rag_wright/.agents/skills/specifying-a-product-on-the-engine/SKILL.md

@@ -58,7 +58,7 @@ Every product item lands in one or more of these. The route column is where the
 | **Domain knowledge**: vocabulary, schema, constraints, synonyms, decision criteria | "controlled vocabularies", "the ontology", "mandatory fields", "valid ranges" | `EngineConfig(pack=...)` (the store creates the declared types on `open_workspace`); your capabilities read value sets and SHACL shapes with `rdflib` / `pyshacl` | `authoring-a-capability` | ontology authoring |
 | **Ingestion**: documents, spreadsheets, images, embedded files into the graph | "parse the forms", "load the lab reports", "idempotent re-runs" | `build_ingestion` (your extractor + optional hooks) → `aingest`; `IngestSource`, `IngestionTuning`, `table_rows` / `TableRow`, `evaluate_ingestion`, `check_extraction`; `KgNode` / `KgEdge` | `building-an-ingestion-capability` | KG construction |
 | **Entity and registry resolution** | "resolve against the yarn register", "queue unresolved mentions" | your `document_hook`; the entity-resolution building blocks on `rag_wright.pack_sdk` | `building-an-ingestion-capability` | entity resolution |
-| **A typed query or retrieval** | "find similar cases", "filter the table", "the dossier" | a query capability of your pack composing the primitives (`kg_read`, `kg_edges`, `NOT_NULL`, `Range`, hybrid span search with `span_search` from `rag_wright.api`), registered with `CapabilityManifest` + `register_capability` / `load_pack`, invoked with `ainvoke_subgraph` | `authoring-a-capability` | authoring capabilities |
+| **A typed query or retrieval** | "find similar cases", "filter the table", "the dossier" | a query capability of your pack composing the primitives (`kg_read`, `kg_edges`, `NOT_NULL`, `Range`, `Contains`, hybrid span search with `span_search` from `rag_wright.api`), registered with `CapabilityManifest` + `register_capability` / `load_pack`, invoked with `ainvoke_subgraph` | `authoring-a-capability` | authoring capabilities |
 | **A cited answer, or a refusal** | "every answer cites its source", "say when it is not in the records" | `agenerate_answer` over `EvidenceItem`s (an answer states its support; "none" abstains), `ajudge_spans` | `authoring-a-capability` | concepts (answers) |
 | **A typed decision or classification** | "classify the structure", "which of these is it" | `classifier-opportunity-analysis` first; then rules, a trained classifier, or the decision model (`jev_decision` from `engine_capabilities()`, criteria in the pack) | `classifier-opportunity-analysis` → `setfit` / `laya` | classification and decision models |
 | **A deterministic workflow behind a button** (mode **D**) | "upload, confirm, save", "export CSV" | a product **operation** (one function per user operation) calling your capabilities; the route calls the operation | `building-a-product-backend` | domain-adaptation step 8 |

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

@@ -28,8 +28,8 @@ open-core and domain-neutral; your product brings the domain. Hard rules:
   (`temporary_workspace`/`drop_workspace` for disposable and removed databases), the invokers
   (`ainvoke_subgraph`/`invoke_model`/`ainvoke_model`), discovery (`capability_index`/`discover`), the KG accessors
   (`kg_read`, `kg_write`, `kg_edges`, `kg_count`/`kg_delete`/`kg_update`, all filtering by `where` values that
-  are equality, a list for membership, `NOT_NULL` or a `Range(gt=, ge=, lt=, le=)` on any number of fields,
-  evaluated in the store;
+  are equality, a list for membership, `NOT_NULL`, a `Range(gt=, ge=, lt=, le=)` or a `Contains(text, case_sensitive=False)` (a literal
+  substring; an empty field never matches) on any number of fields, evaluated in the store;
   `entities_by_name`, `span_positions`), hybrid span search (`span_search` / `aspan_search`: cited spans from
   the dense and sparse index, fused in the store), `pack_store(ws, cls)` (build your pack's store extension over the
   workspace's store; the store itself stays private), metering and tracing (`measure_usage`, `record_usage`,

{rag_wright-0.15.0 → rag_wright-0.16.1}/src/rag_wright/api/__init__.py

@@ -71,7 +71,7 @@ from rag_wright.evals import (GoldImportError, GoldMapping, aload_gold_set, arun
                               score_candidate_choice, score_classification, score_extraction, score_generation,
                               score_ingestion, score_judgment, score_relational, score_retrieval)
 from rag_wright.ingestion.tables import table_rows
-from rag_wright.store.seam import NOT_NULL, KgEdge, KgNode, Range
+from rag_wright.store.seam import NOT_NULL, Contains, KgEdge, KgNode, Range
 from rag_wright.api.invoke import ainvoke_model, ainvoke_subgraph, capability_index, invoke_model
 from rag_wright.api.kg import (aspan_search, entities_by_name, kg_count, kg_delete, kg_edges, kg_read, kg_update,
                                kg_write, span_positions, span_search)
@@ -114,7 +114,7 @@ __all__ = [
     "query_embedder",  # PS-39: the process-wide query embedder, for a seam that holds no workspace
     "ModelRole",  # PS-1 (G17): WorkspaceHandle.model_id(role) and EngineConfig.models need it
     "ainvoke_subgraph", "invoke_model", "ainvoke_model", "capability_index", "discover", "Discovered",
-    "kg_read", "kg_write", "kg_edges", "kg_count", "kg_delete", "kg_update", "entities_by_name", "span_positions", "span_search", "aspan_search", "SpanHit", "KgNode", "KgEdge", "NOT_NULL", "Range",
+    "kg_read", "kg_write", "kg_edges", "kg_count", "kg_delete", "kg_update", "entities_by_name", "span_positions", "span_search", "aspan_search", "SpanHit", "KgNode", "KgEdge", "NOT_NULL", "Range", "Contains",
     "document_of", "decode_bbox",
     "source_document", "parse_document", "aparse_document", "parse_document_bytes", "pdf_page_count", "aparse_document_bytes",
     "find_blank_pages_with_text", "BlankPageText",  # PS-47: cached parses holding text a VLM invented for a blank page

{rag_wright-0.15.0 → rag_wright-0.16.1}/src/rag_wright/api/config.py

@@ -23,6 +23,10 @@ class StoreConfig:
     password: str
     backend: str = "arcadedb"
     protocol: str = "http"
+    # RuleWright (2026-10-31): the write-conflict retry budget. None: `ARCADEDB_CONFLICT_ATTEMPTS` /
+    # `ARCADEDB_CONFLICT_BACKOFF_CAP_S`, else 20 attempts with each wait capped at 2 s (about 25 s in all).
+    conflict_attempts: Optional[int] = None
+    conflict_backoff_cap_s: Optional[float] = None
 
     @classmethod
     def from_env(cls) -> "StoreConfig":

{rag_wright-0.15.0 → rag_wright-0.16.1}/src/rag_wright/api/kg.py

@@ -30,8 +30,10 @@ def kg_read(ws: WorkspaceHandle, node_type: str, *, where: Optional[dict] = None
             distinct: Optional[str] = None, order_by: Optional[str] = None, limit: Optional[int] = None,
             key_range: Optional[tuple] = None) -> list[dict]:
     """Read typed nodes of `node_type` from the workspace (see `Store.kg_read`). Each `where` value is a scalar
-    (equality), a list (membership; an empty list is scope-to-nothing -> `[]`), `NOT_NULL` (presence) or a `Range`
-    (comparisons, on any number of fields: `{"weight": Range(ge=180, le=220), "tensile": Range(gt=400)}`); all
+    (equality), a list (membership; an empty list is scope-to-nothing -> `[]`), `NOT_NULL` (presence), a `Range`
+    (comparisons, on any number of fields: `{"weight": Range(ge=180, le=220), "tensile": Range(gt=400)}`) or a
+    `Contains` (a literal substring, case-insensitive unless `case_sensitive=True`; an empty field never matches:
+    `{"composition": Contains("UHMWPE")}`); all
     filters are AND-ed and evaluated in the store. `key_range=(field, lo, hi)` is the half-open shorthand
     (`lo <= field < hi`). Then projection, distinct, order and limit. Every name is checked, never interpolated
     unchecked (the module docstring): a request-chosen field is safe, but an unknown one matches nothing."""
@@ -42,7 +44,7 @@ def kg_read(ws: WorkspaceHandle, node_type: str, *, where: Optional[dict] = None
 def kg_count(ws: WorkspaceHandle, type_name: str, *, where: Optional[dict] = None,
              key_range: Optional[tuple] = None) -> int:
     """The number of vertices or edges of `type_name` matching `where` / `key_range` (see `Store.kg_count`); `where`
-    as in `kg_read`, `Range` values included."""
+    as in `kg_read`, `Range` and `Contains` values included."""
     return ws._store.kg_count(type_name, where=where, key_range=key_range)
 
 

{rag_wright-0.15.0 → rag_wright-0.16.1}/src/rag_wright/api/workspace.py

@@ -131,7 +131,9 @@ def _build_store(config: EngineConfig, corpus: str, *, reset: bool, create: bool
     from rag_wright.store.arcadedb import ArcadeDBStore
 
     return ArcadeDBStore.from_config(sc.host, sc.port, sc.user, sc.password, database=corpus,
-                                     protocol=sc.protocol, reset=reset, pack_ttl=config.pack, create=create)
+                                     protocol=sc.protocol, reset=reset, pack_ttl=config.pack, create=create,
+                                     conflict_attempts=sc.conflict_attempts,
+                                     conflict_backoff_cap_s=sc.conflict_backoff_cap_s)
 
 
 def drop_workspace(config: EngineConfig, *, corpus: str) -> bool:

{rag_wright-0.15.0 → rag_wright-0.16.1}/src/rag_wright/capabilities/embedding.py

@@ -17,7 +17,6 @@ from __future__ import annotations
 
 import asyncio
 import math
-import threading
 from typing import Protocol, runtime_checkable
 
 from pydantic import BaseModel, field_validator
@@ -63,49 +62,43 @@ class ChunkEmbedding(BaseModel):
 
 
 def _resolve_device(device: str | None) -> str:
-    """The device to run BGE-M3 on: explicit arg, else `EMBED_DEVICE`, else auto (Metal `mps` when available,
-    else `cpu`). Auto-MPS offloads embedding from the CPU (freeing it for LegalBERT + extraction during ingest)
-    and is ~2x faster; the vectors are bit-for-bit equivalent to CPU (verified cosine 1.0), so it is a pure
-    speed choice, not a semantic one."""
-    import os
-
-    chosen = device or os.environ.get("EMBED_DEVICE")
-    if chosen:
-        return chosen
-    try:
-        import torch
-
-        if torch.backends.mps.is_available():
-            return "mps"
-        if torch.cuda.is_available():  # a GPU box (e.g. the bulk-ingestion VM) -> use the GPU
-            return "cuda"
-    except Exception:  # noqa: BLE001 - torch/device probing must never break model construction
-        pass
-    return "cpu"
+    """The device to run the BGE family (this embedder and `BGEReranker`) on: explicit arg, else `EMBED_DEVICE`,
+    else CUDA, else Metal `mps`, else `cpu`. Metal offloads embedding from the CPU and is ~2x faster; the vectors
+    are bit-for-bit equivalent to CPU (verified cosine 1.0), so it is a pure speed choice. The BGE family is the
+    ONE family the engine puts on Metal, and every call to it there holds the process-wide Metal lock (PS-55,
+    `rag_wright.util.devices`)."""
+    from rag_wright.util.devices import torch_device
+
+    return torch_device(device, env="EMBED_DEVICE", metal=True)
 
 
 class BGEM3Embedder:
     """The real embedder: BGE-M3 via `FlagEmbedding.BGEM3FlagModel` (model loaded lazily).
 
-    THREAD-SAFE (engine issue 0016): FlagEmbedding mutates the model IN PLACE on every `encode`
+    THREAD-SAFE (engine issue 0016, PS-55): FlagEmbedding mutates the model IN PLACE on every `encode`
     (`self.model.float()` / `.to(device)` / `.eval()`), and those C++ conversions release the GIL, so two threads
     driving one shared model swap the same parameter-tensor storage under each other and SEGFAULT the interpreter
     (not a catchable exception). The engine SHARES one `Embedder` across concurrent-document ingestion
     (`run_job(max_concurrency=...)` -> per-document `encode_batch`) and across `embed_chunks`' per-chunk thread
     fan-out. So every model call is serialized by an instance lock. The lock guards ONLY `self._model.encode`
     (the numpy results are per-call, thread-local); the serialized section is the CPU/GPU encode, which is a small
-    slice of ingest time -- the concurrency worth overlapping is the network-bound extraction, not the encode."""
+    slice of ingest time -- the concurrency worth overlapping is the network-bound extraction, not the encode.
+    On Metal the lock is the process-wide `METAL_LOCK` instead (PS-55): Metal is not safe for concurrent use, and a
+    process can hold several embedders (the query embedder, each workspace's) plus the reranker."""
 
     def __init__(self, model_name: str = "BAAI/bge-m3", *, use_fp16: bool = False,
                  device: str | None = None, batch_size: int = 64, model: object | None = None) -> None:
         self._batch_size = batch_size  # cross-item independent, so batching never changes a vector, only speed
-        self._lock = threading.Lock()  # issue 0016: serialize the in-place-mutating BGE-M3 encode across threads
+        from rag_wright.util.devices import model_lock
+
+        resolved = _resolve_device(device)
+        self._lock = model_lock(resolved)  # issue 0016 per instance; on Metal one lock per process (PS-55)
         if model is not None:  # injected (hermetic tests) -- avoids loading the real model
             self._model = model
         else:
             from FlagEmbedding import BGEM3FlagModel
 
-            self._model = BGEM3FlagModel(model_name, use_fp16=use_fp16, devices=_resolve_device(device))
+            self._model = BGEM3FlagModel(model_name, use_fp16=use_fp16, devices=resolved)
 
     def encode_dense(self, text: str) -> list[float]:
         with self._lock:  # issue 0016

{rag_wright-0.15.0 → rag_wright-0.16.1}/src/rag_wright/capabilities/parsing.py

@@ -70,12 +70,29 @@ def _thread_converter():
     keep their own)."""
     converter = getattr(_THREAD, "converter", None)
     if converter is None:
-        from docling.document_converter import DocumentConverter
-
-        converter = _THREAD.converter = DocumentConverter()
+        converter = _THREAD.converter = _new_converter()
     return converter
 
 
+def _new_converter():
+    """Docling's converter with the engine's device for its layout, table and OCR models (PS-55): `cpu` where
+    Docling's `auto` would pick Metal, which is not safe for concurrent use and is kept for the BGE family;
+    `DOCLING_DEVICE` when set; else Docling's own choice. Passed explicitly because Docling's default options are
+    built once, at import. The output is identical on CPU and Metal (measured on the engine's fixtures)."""
+    from docling.datamodel.accelerator_options import AcceleratorOptions
+    from docling.datamodel.base_models import InputFormat
+    from docling.datamodel.pipeline_options import PdfPipelineOptions
+    from docling.document_converter import DocumentConverter, ImageFormatOption, PdfFormatOption
+
+    from rag_wright.util.devices import docling_device
+
+    def options() -> PdfPipelineOptions:
+        return PdfPipelineOptions(accelerator_options=AcceleratorOptions(device=docling_device()))
+
+    return DocumentConverter(format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=options()),
+                                             InputFormat.IMAGE: ImageFormatOption(pipeline_options=options())})
+
+
 class DoclingParser:
     """The real parser: Docling's `DocumentConverter` (the calling thread's, reused across documents). Built
     lazily so importing the capability (and the hermetic tests) does not load Docling's models."""