rag-wright 0.1.0__py3-none-any.whl

rag_wright/models/tag_structured.py

@@ -0,0 +1,285 @@
+"""Client-side XML-tag structured output -- the app's LLM-AGNOSTIC structured-output mechanism (ADR-0045).
+
+Server-side guided decoding (`response_format`/`with_structured_output` json_schema) is NOT portable: it runs
+away to max length on self-hosted Gemma-4/vLLM and costs ~60s/call on OpenRouter->Cerebras, while PLAIN free-text
+generation is fast and correct everywhere. So instead of forcing a JSON schema at decode time, we ask the model
+to answer in light XML tags and parse them CLIENT-SIDE into the Pydantic contract. Tags (not JSON) because a
+field body needs no escaping -- unlike a JSON string full of legal quotes/brackets/newlines.
+
+`build_tag_structured` is a DROP-IN for `models.seam.build_structured` (same `(model_id, schema)` -> runnable
+with `.invoke(prompt) -> schema instance`), so a caller swaps the mechanism by swapping the factory.
+
+Scope (ADR-0045 + TAGPARSE-INGEST-1a): FLAT schemas -- scalars (str/int/float/bool), enum/Literal, `str | None`,
+`list[<scalar>]` -- AND NESTED schemas: a single nested `BaseModel` field and `list[<BaseModel>]`, emitted and
+parsed by recursion (nested `<field><sub>..</sub></field>`; list items as repeated `<item>..</item>` blocks).
+That covers the query-side schemas (generation, query understanding, highlight field-extract, reader judgments),
+the flat ingest judges (extraction_semantic_judge -> SemanticVerdict), AND the ingestion extraction contracts
+(Clause with its nested bounded_by/caps/governed_by + the `excepts` list; ContractParties with `parties`), which
+TAGPARSE-INGEST-1 routes off docling-graph's server-side json_object onto this path. The ingest clause-function
+classifier (nested `list[SpanFunctions]` / `list[RawScore]`) still uses its OWN bespoke free-text tags + client-
+side parse in `spans/clause_function_classifier.py`, not this generic parser (issue 0005), and is unchanged.
+"""
+
+from __future__ import annotations
+
+import re
+import types
+import typing
+from enum import Enum
+from typing import Any, get_args, get_origin
+
+from pydantic import BaseModel, ValidationError
+
+from rag_wright.models.seam import astream_text, build_model
+
+
+def _unwrap_optional(ann: Any) -> Any:
+    """`X | None` / `Optional[X]` -> `X`; otherwise unchanged."""
+    if get_origin(ann) in (typing.Union, getattr(types, "UnionType", None)):
+        non_none = [a for a in get_args(ann) if a is not type(None)]
+        if len(non_none) == 1:
+            return non_none[0]
+    return ann
+
+
+def _classify(ann: Any) -> tuple[str, type[BaseModel] | None, str]:
+    """Classify a field annotation into `(kind, submodel, hint)`:
+      - 'scalar'      : a single scalar/enum/Literal/bool/number value  (submodel None)
+      - 'list_scalar' : `list[<scalar/enum>]`                           (submodel None)
+      - 'nested'      : a single nested `BaseModel`                     (submodel = that model)
+      - 'nested_list' : `list[<BaseModel>]`                            (submodel = the item model)
+    Nested kinds (TAGPARSE-INGEST-1a) let the ingestion contracts (Clause's bounded_by/caps/governed_by + the
+    `excepts` list, ContractParties' `parties` list) round-trip through tags; the emitter/parser recurse."""
+    ann = _unwrap_optional(ann)
+    if get_origin(ann) is list:
+        item = (get_args(ann) or (str,))[0]
+        if isinstance(item, type) and issubclass(item, BaseModel):
+            return "nested_list", item, ""
+        return "list_scalar", None, "one value per line"
+    if isinstance(ann, type) and issubclass(ann, BaseModel):
+        return "nested", ann, ""
+    if isinstance(ann, type) and issubclass(ann, Enum):
+        return "scalar", None, "one of: " + " | ".join(str(e.value) for e in ann)
+    if get_origin(ann) is typing.Literal:
+        return "scalar", None, "one of: " + " | ".join(str(v) for v in get_args(ann))
+    if ann is bool:
+        return "scalar", None, "true or false"
+    if ann in (int, float):
+        return "scalar", None, "a number"
+    return "scalar", None, "text"
+
+
+def _field_lines(schema: type[BaseModel], fields: set[str] | None = None) -> list[str]:
+    """One tag-template block per field of `schema`; recurses into nested models and list[model] items. `fields`
+    (if given) restricts to that subset -- for the per-group ingestion passes (TAGPARSE-INGEST-1b)."""
+    out: list[str] = []
+    for name, field in schema.model_fields.items():
+        if fields is not None and name not in fields:
+            continue
+        kind, sub, hint = _classify(field.annotation)
+        desc = (field.description or "").strip()
+        # Guidance goes AFTER the tags (a trailing `-- ...`), NOT inside them: a hint placed inside the tag body
+        # (e.g. `(one of: a | b)`) gets ECHOED by the model (`<f>(a)</f>`), which then fails value/enum parsing.
+        # The tag body is left EMPTY for the model to fill with ONLY the value.
+        guide = "; ".join(g for g in (hint, desc) if g)
+        tail = f"  -- {guide}" if guide else ""
+        if kind == "scalar":
+            out.append(f"<{name}></{name}>{tail}")
+        elif kind == "list_scalar":
+            out.append(f"<{name}>\n</{name}>{tail}")
+        elif kind == "nested":
+            inner = "\n".join(_field_lines(sub))  # type: ignore[arg-type]
+            out.append(f"<{name}>{(' -- ' + desc) if desc else ''}\n{inner}\n</{name}>")
+        else:  # nested_list
+            inner = "\n".join(_field_lines(sub))  # type: ignore[arg-type]
+            out.append(f"<{name}>{(' -- ' + desc) if desc else ''} (repeat the <item> block once per entry)\n"
+                       f"<item>\n{inner}\n</item>\n</{name}>")
+    return out
+
+
+def tag_instructions(schema: type[BaseModel], fields: set[str] | None = None) -> str:
+    """The prompt appendix telling the model to emit one XML-tag block per field of `schema` (recursing into
+    nested models and list[model] items). `fields` (if given) restricts to that subset."""
+    return "\n".join([
+        "Respond using EXACTLY these XML-style tags, one block per field. Fill EACH tag body with ONLY the raw "
+        "value -- no quotes, no JSON, no markdown fences, and do NOT copy the guidance. Any text after `--` is "
+        "guidance for you, not part of the value:",
+        *_field_lines(schema, fields),
+        "Omit the tag entirely for any field whose value is unknown or not applicable.",
+    ])
+
+
+def _extract(text: str, name: str) -> str | None:
+    m = re.search(rf"<{re.escape(name)}>(.*?)</{re.escape(name)}>", text, re.DOTALL | re.IGNORECASE)
+    return m.group(1) if m else None
+
+
+def _field_value(body: str, field: Any, lenient: bool, full_text: str | None = None) -> Any:
+    """The Python value for one `<field>` body: scalar/enum/bool/number verbatim; `list[<scalar>]` split
+    one-per-line (commas too); a nested `BaseModel` recursed; a `list[<BaseModel>]` split on its `<item>` blocks
+    and each recursed. In `lenient` mode an unbuildable list ITEM is dropped (kept in strict).
+
+    For a nested `BaseModel`, the sub-model is parsed from `full_text` when given, not just the `<field>` body:
+    models often FLATTEN a nested field -- emitting `<governed_by>Delaware</governed_by>` then the sub-fields
+    `<jurisdiction_name>...`/`<law_multiplicity>...` as SIBLINGS rather than nested inside. Sub-field tag names are
+    unique in these contracts, so scanning the full text finds them whether nested or flattened."""
+    kind, sub, _ = _classify(field.annotation)
+    if kind == "scalar":
+        return body.strip()
+    if kind == "list_scalar":
+        return [x.strip() for x in re.split(r"[\r\n,]+", body.strip()) if x.strip()]
+    if kind == "nested":
+        src = full_text if full_text is not None else body
+        if not any((_extract(src, sn) or "").strip() for sn in sub.model_fields):  # type: ignore[union-attr]
+            return None  # no non-empty sub-field anywhere -> the nested block is absent (never a hollow model)
+        return parse_tagged(src, sub, lenient=lenient)  # type: ignore[arg-type]
+    # nested_list
+    out = []
+    for it in re.findall(r"<item>(.*?)</item>", body, re.DOTALL | re.IGNORECASE):
+        try:
+            out.append(parse_tagged(it, sub, lenient=lenient))  # type: ignore[arg-type]
+        except ValidationError:
+            if not lenient:
+                raise
+    return out
+
+
+def _prune_invalid_optionals(schema: type[BaseModel], data: dict[str, Any], err: ValidationError) -> BaseModel:
+    """Drop each NON-required top field the ValidationError blames (a partial nested block, a constraint-violating
+    scalar) so it falls back to its default, then rebuild ONCE. A required field cannot be omitted, so if the
+    error is (also) on a required field the rebuild re-raises -- the caller's graceful-degrade contract then owns
+    it. Only used on the last, lenient attempt."""
+    pruned = False
+    for e in err.errors():
+        loc = e.get("loc") or ()
+        if not loc:
+            continue
+        top = loc[0]
+        f = schema.model_fields.get(top)  # type: ignore[arg-type]
+        if f is not None and not f.is_required() and top in data:
+            del data[top]
+            pruned = True
+    if not pruned:
+        raise err  # nothing omittable (the failure is on required data) -> genuine, propagate
+    return schema(**data)
+
+
+def parse_tagged(text: str, schema: type[BaseModel], *, lenient: bool = False,
+                 fields: set[str] | None = None) -> BaseModel:
+    """Parse XML-tagged free text into `schema`. An absent tag is omitted so the field's default/optional applies;
+    Pydantic does the final validation. STRICT (default): a missing required field or a malformed/partial nested
+    block raises ValidationError (which `build_tag_structured` retries -- the re-ask). LENIENT (the last attempt,
+    TAGPARSE-INGEST-1a): omit-to-default -- a NON-required field whose value fails to validate (an unbuildable
+    nested block, a constraint-violating scalar, an invalid list item) is dropped to its default rather than
+    failing the whole extraction; a missing REQUIRED field still raises."""
+    data: dict[str, Any] = {}
+    for name, field in schema.model_fields.items():
+        if fields is not None and name not in fields:
+            continue
+        kind, _sub, _ = _classify(field.annotation)
+        body = _extract(text, name)
+        if body is None:
+            # ISSUE-0020: a nested single model may be FULLY FLATTENED -- the model emits its sub-fields as siblings
+            # with NO <name> wrapper at all (the temporal_bound miss: <temporal_duration>/<temporal_kind> flat, no
+            # <bounded_by>). Unlike the wrapper-present flatten (handled in `_field_value` via full_text), that case
+            # is invisible here because `_extract(text, name)` is None. Recover it from the full text by the sub-
+            # model's (unique) sub-field names; every other absent tag is genuinely absent -> omit.
+            if kind == "nested" and any((_extract(text, sn) or "").strip() for sn in _sub.model_fields):  # type: ignore[union-attr]
+                try:
+                    val = parse_tagged(text, _sub, lenient=lenient)  # type: ignore[arg-type]
+                except ValidationError:
+                    if not lenient:
+                        raise
+                    val = None
+                if val is not None:
+                    data[name] = val
+            continue
+        if kind in ("scalar", "list_scalar") and not body.strip():
+            continue  # an empty <tag></tag> means "not provided" -> omit (never coerce "" to an enum OTHER)
+        try:
+            val = _field_value(body, field, lenient, full_text=text)
+        except ValidationError:
+            if not lenient:  # strict: let the re-ask handle it; lenient: omit this field (default applies)
+                raise
+            continue
+        if kind == "nested" and val is None:
+            continue  # all-empty nested block -> absent (not a hollow model)
+        data[name] = val
+    try:
+        return schema(**data)
+    except ValidationError as exc:
+        if not lenient:
+            raise
+        return _prune_invalid_optionals(schema, data, exc)
+
+
+class _TagStructuredRunnable:
+    """A `build_structured`-shaped runnable that drives structured output client-side (free-text + tag parse)."""
+
+    def __init__(
+        self, model_id: str, schema: type[BaseModel], *, temperature: float, max_tokens: int | None, retries: int,
+        label: str | None = None, fields: set[str] | None = None,
+    ) -> None:
+        self._model_id = model_id
+        self._schema = schema
+        self._temperature = temperature
+        self._max_tokens = max_tokens
+        self._retries = retries
+        self._label = label  # ADR-0058: stage/call-site name for the deadline warning (threaded to astream_text)
+        self._fields = fields  # TAGPARSE-INGEST-1b: restrict this pass to a field subset (per-group extraction)
+
+    def _full_prompt(self, prompt: Any) -> Any:
+        # `prompt` is a plain string or a LangChain message sequence (e.g. [SystemMessage, HumanMessage]); append
+        # the tag instructions as a trailing human turn either way.
+        instr = tag_instructions(self._schema, fields=self._fields)
+        return f"{prompt}\n\n{instr}" if isinstance(prompt, str) else [*prompt, ("human", instr)]
+
+    def invoke(self, prompt: Any, config: Any = None) -> BaseModel:  # config accepted for runnable-compat, unused
+        # Drop-in for build_structured. The re-ask is STRICT (so a malformed/partial answer is re-asked); the
+        # FINAL attempt is LENIENT (omit-to-default) so a persistently-partial nested block degrades rather than
+        # failing the whole extraction (TAGPARSE-INGEST-1a).
+        full = self._full_prompt(prompt)
+        attempts = self._retries + 1
+        last: Exception | None = None
+        for i in range(attempts):
+            text = str(build_model(
+                self._model_id, temperature=self._temperature, max_tokens=self._max_tokens).invoke(full).content)
+            try:
+                return parse_tagged(text, self._schema, lenient=(i == attempts - 1), fields=self._fields)
+            except ValidationError as exc:  # malformed/incomplete -> re-ask, bounded
+                last = exc
+        raise last  # type: ignore[misc]
+
+    async def ainvoke(self, prompt: Any, config: Any = None) -> BaseModel:
+        # ASYNC-A3 (ADR-0057): the async tag-parse structured path -- stream the free-text answer (idle-drip
+        # detection + true wall-clock deadline via astream_text), then parse the light tags client-side, with the
+        # same bounded re-ask on a ValidationError.
+        full = self._full_prompt(prompt)
+        attempts = self._retries + 1
+        last: Exception | None = None
+        for i in range(attempts):
+            text = await astream_text(
+                self._model_id, full, temperature=self._temperature, max_tokens=self._max_tokens,
+                label=self._label)
+            try:
+                return parse_tagged(text, self._schema, lenient=(i == attempts - 1), fields=self._fields)
+            except ValidationError as exc:
+                last = exc
+        raise last  # type: ignore[misc]
+
+
+def build_tag_structured(
+    model_id: str, schema: type[BaseModel], *, include_raw: bool = False, temperature: float = 0.0,
+    max_tokens: int | None = 2048, retries: int = 1, label: str | None = None, fields: set[str] | None = None,
+) -> _TagStructuredRunnable:
+    """Drop-in for `models.seam.build_structured`: returns a runnable whose `.invoke(prompt)` yields a validated
+    `schema` instance -- but via CLIENT-SIDE tag parsing (no server guided decoding), so it works on any model/
+    provider. `max_tokens` defaults to a generous cap (free-text terminates on its own). `label` (ADR-0058) names
+    the stage/call-site in the deadline warning. `fields` (TAGPARSE-INGEST-1b) restricts emission+parsing to a
+    subset of `schema`'s fields -- for per-group ingestion passes over one big schema. `include_raw` is accepted
+    for signature-compat but not supported (no query-side caller uses it)."""
+    if include_raw:
+        raise NotImplementedError("tag_structured: include_raw is not supported")
+    return _TagStructuredRunnable(
+        model_id, schema, temperature=temperature, max_tokens=max_tokens, retries=retries, label=label,
+        fields=fields)

rag_wright/models/tracing.py

@@ -0,0 +1,179 @@
+"""Engine LLM tracing to Langfuse (engine issue 0017).
+
+The engine owns its model calls, so it owns their instrumentation: one Langfuse **generation** per model call,
+carrying model id, token usage, latency, and the semantic metadata only the engine holds (the ADR-0058 `label`
+plus role/stage and any caller correlation id). The product queries Langfuse directly -- this module is an
+EMISSION contract, never a read API.
+
+Gating (two independent conditions, BOTH required to emit):
+  1. `RAG_TRACE_LEVEL` in {generations, verbose} (default `off`).
+  2. `LANGFUSE_*` credentials actually configured.
+Activation hinges on real CONFIGURATION, never on importability -- langfuse (and its transitive opentelemetry-sdk)
+being installed says nothing about whether the operator wants telemetry (the FastMCP/OTel lesson, restated by the
+issue). `generations` emits model+usage+latency+metadata; `verbose` also captures the input prompt and output.
+
+Tracing must NEVER break a model call: every langfuse touch is wrapped and degrades to a no-op on any error.
+"""
+
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager
+from typing import Any, Iterator, Optional
+
+_LEVELS = ("off", "generations", "verbose")
+
+
+def trace_level() -> str:
+    lvl = os.environ.get("RAG_TRACE_LEVEL", "off").strip().lower()
+    return lvl if lvl in _LEVELS else "off"
+
+
+def _configured() -> bool:
+    """Gate on REAL config -- the credentials -- not on `import langfuse` succeeding."""
+    return bool(os.environ.get("LANGFUSE_PUBLIC_KEY") and os.environ.get("LANGFUSE_SECRET_KEY"))
+
+
+def tracing_on() -> bool:
+    return trace_level() != "off" and _configured()
+
+
+_client: Any = None
+_client_tried = False
+
+
+def _get_client() -> Any:
+    """Lazy process-lifetime Langfuse client, constructed only when tracing is on AND configured. Constructing it
+    initializes langfuse's OWN OpenTelemetry provider -- we never touch the engine's dormant observability seam."""
+    global _client, _client_tried
+    if _client is not None or _client_tried:
+        return _client
+    _client_tried = True
+    if not tracing_on():
+        return None
+    try:
+        from langfuse import Langfuse
+        _client = Langfuse()  # reads LANGFUSE_PUBLIC_KEY / SECRET_KEY / HOST from env
+    except Exception:  # noqa: BLE001 - tracing must never break the engine
+        _client = None
+    return _client
+
+
+def start_generation(*, model: str, input: Any = None, label: Optional[str] = None,
+                     role: Optional[str] = None, stage: Optional[str] = None,
+                     metadata: Optional[dict[str, Any]] = None) -> Any:
+    """Open a Langfuse generation AT THE CALL START and return the observation (or None when tracing is off).
+    Its `start_time` is the moment this is called, so pairing it with `finish_generation` after the call makes
+    the span's OWN duration the real wall-clock latency. This matters because langfuse v4 has no way to
+    back-date a start: a post-hoc emit (open + immediately end) reports a ~0s duration and the real figure
+    survives only in metadata -- the defect engine issue 0048 hit (Langfuse's latency column read 0 for
+    `astream_text`/`span-relevance`). `input` is captured only at `verbose`; label/role/stage go into metadata.
+    Document/job grouping comes from the ambient `traced_run`."""
+    lf = _get_client()
+    if lf is None:
+        return None
+    verbose = trace_level() == "verbose"
+    md = {"label": label, "role": role, "stage": stage, **(metadata or {})}
+    md = {k: v for k, v in md.items() if v is not None}
+    try:
+        return lf.start_observation(
+            name=label or stage or "llm", as_type="generation",
+            input=input if verbose else None, model=model, metadata=md or None,
+        )
+    except Exception:  # noqa: BLE001 - never let tracing break a model call
+        return None
+
+
+def finish_generation(gen: Any, *, output: Any = None, usage: Optional[dict[str, int]] = None,
+                      cost: Optional[float] = None, latency_ms: Optional[float] = None,
+                      completion_start_time: Any = None,
+                      metadata: Optional[dict[str, Any]] = None) -> None:
+    """Attach a completed call's results to a generation opened by `start_generation` and END it (end_time =
+    now), so the observation's duration is the true latency. No-op when `gen` is None (tracing off). `output`
+    captured only at `verbose`; `usage` = {"input": n, "output": n}; `cost` is the provider's ACTUAL total USD
+    (OpenRouter pass-through, not an engine price table) -> `cost_details` (None when the backend omits it, e.g.
+    self-hosted vLLM, so Langfuse prices from its own table). `completion_start_time` (time to first token) lets
+    Langfuse split queue+prefill from decode -- the attribution engine issue 0048 asked for. `latency_ms` is
+    also kept in metadata (redundant with the now-correct span duration, but exact)."""
+    if gen is None:
+        return
+    verbose = trace_level() == "verbose"
+    late = {"latency_ms": latency_ms, **(metadata or {})}
+    late = {k: v for k, v in late.items() if v is not None}
+    try:
+        gen.update(output=output if verbose else None, usage_details=usage or None,
+                   cost_details=({"total": cost} if cost is not None else None),
+                   completion_start_time=completion_start_time, metadata=late or None)
+        gen.end()
+    except Exception:  # noqa: BLE001 - never let tracing break a model call
+        pass
+
+
+def record_generation(*, model: str, input: Any = None, output: Any = None,
+                      usage: Optional[dict[str, int]] = None, cost: Optional[float] = None,
+                      latency_ms: Optional[float] = None, label: Optional[str] = None,
+                      role: Optional[str] = None, stage: Optional[str] = None,
+                      metadata: Optional[dict[str, Any]] = None) -> None:
+    """Post-hoc convenience: open + immediately end a generation. The measured span duration is ~0 (the real
+    latency survives only in metadata) -- PREFER `start_generation`/`finish_generation` around the call so
+    Langfuse's own latency is correct (issue 0048). Kept for a caller that genuinely has only post-call data."""
+    gen = start_generation(model=model, input=input, label=label, role=role, stage=stage, metadata=metadata)
+    finish_generation(gen, output=output, usage=usage, cost=cost, latency_ms=latency_ms)
+
+
+@contextmanager
+def traced_step(name: str, *, metadata: Optional[dict[str, Any]] = None) -> Iterator[None]:
+    """Time a NON-generation sub-step (e.g. retrieval: ArcadeDB + embedding + rerank) as its OWN Langfuse span,
+    so its duration is separable from the generation in the same trace -- the retrieval/generation split engine
+    issue 0048 asked for. No-op unless tracing is on. (Distinct from `subgraphs.observability.business_span`,
+    which is an OTel-ambient span that no-ops under a Langfuse-only setup -- this one emits to Langfuse.)"""
+    lf = _get_client()
+    if lf is None:
+        yield
+        return
+    obs = None
+    try:
+        obs = lf.start_observation(name=name, as_type="span", metadata=metadata or None)
+    except Exception:  # noqa: BLE001 - never let tracing break the step
+        obs = None
+    try:
+        yield
+    finally:
+        if obs is not None:
+            try:
+                obs.end()
+            except Exception:  # noqa: BLE001
+                pass
+
+
+@contextmanager
+def traced_run(*, document_id: Optional[str] = None, job_id: Optional[str] = None,
+               name: Optional[str] = None, metadata: Optional[dict[str, Any]] = None) -> Iterator[None]:
+    """Group every generation emitted inside the block under one trace/session -- the caller's correlation id
+    (job/document). A no-op unless tracing is on. Flushes on exit so a short-lived run's spans are sent."""
+    if not tracing_on():
+        yield
+        return
+    cm = None
+    try:
+        from langfuse import propagate_attributes
+        md = {"document_id": document_id, **(metadata or {})}
+        md = {k: v for k, v in md.items() if v is not None}
+        cm = propagate_attributes(session_id=job_id or document_id, metadata=md or None, trace_name=name)
+        cm.__enter__()
+    except Exception:  # noqa: BLE001
+        cm = None
+    try:
+        yield
+    finally:
+        if cm is not None:
+            try:
+                cm.__exit__(None, None, None)
+            except Exception:  # noqa: BLE001
+                pass
+        lf = _get_client()
+        if lf is not None:
+            try:
+                lf.flush()
+            except Exception:  # noqa: BLE001
+                pass

rag_wright/models/usage.py

@@ -0,0 +1,102 @@
+"""In-band model usage accounting (engine issue 0042): total round trips, tokens, OpenRouter's real per-call
+cost, and latency, returned to the caller WITHOUT a Langfuse round-trip and WITHOUT tracing being on.
+
+A caller opens a `usage_scope()` around an operation; the model seam records each call into the active scope.
+The scope is ambient via a `ContextVar`, so no capability signature or graph-state changes. Usage is a property
+of the CALL, captured whenever a scope is active — independent of `RAG_TRACE_LEVEL` (which defaults to `off`).
+
+Design notes (issue 0042, per RuleWright):
+- `calls_without_cost` is a DISTINCT counter (top-level AND per model): a call the backend/model returned no
+  cost for is UNKNOWN, never folded into `cost_usd` as a $0 that reads as free. A fully-unpriced run therefore
+  has `cost_usd == 0.0` with `calls_without_cost == calls` — a signal never to print the total as money.
+- NESTING IS ADDITIVE: a call records into EVERY active scope on the stack, so a task-level outer scope totals
+  everything while inner per-operation scopes attribute their own slice. (Both are tested.)
+- THREAD-SAFE: the accumulator is shared across the asyncio tasks and worker threads a scope spans (the engine
+  copies the context across its `to_thread` / dedicated-executor boundaries — ISSUE-0018), and every add is
+  locked, so concurrent model calls (the ingest/query gather + executor fan-out) accumulate correctly.
+"""
+
+from __future__ import annotations
+
+import contextvars
+import threading
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import Iterator, Optional
+
+
+@dataclass
+class ModelUsage:
+    """Per-model totals within a scope (`cost_usd` sums KNOWN per-call costs only)."""
+
+    calls: int = 0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cost_usd: float = 0.0
+    calls_without_cost: int = 0  # calls the backend/model returned NO cost for -> unknown, NOT free
+    latency_ms_total: float = 0.0  # sum of per-call wall-clock ms; avg = latency_ms_total / calls
+
+
+@dataclass
+class UsageTotals:
+    """The usage accumulated within one `usage_scope()`: top-level totals + a per-model breakdown."""
+
+    calls: int = 0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cost_usd: float = 0.0
+    calls_without_cost: int = 0
+    latency_ms_total: float = 0.0
+    by_model: dict[str, ModelUsage] = field(default_factory=dict)
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False, compare=False)
+
+    def _add(self, model: str, input_tokens: int, output_tokens: int,
+             cost: Optional[float], latency_ms: Optional[float]) -> None:
+        with self._lock:
+            per = self.by_model.get(model)
+            if per is None:
+                per = ModelUsage()
+                self.by_model[model] = per
+            for tgt in (self, per):  # same shared counters on the top-level totals and this model's row
+                tgt.calls += 1
+                tgt.input_tokens += int(input_tokens or 0)
+                tgt.output_tokens += int(output_tokens or 0)
+                tgt.latency_ms_total += float(latency_ms or 0.0)
+                if cost is None:
+                    tgt.calls_without_cost += 1
+                else:
+                    tgt.cost_usd += float(cost)
+
+
+# The STACK of active scopes (innermost last). A tuple set per scope-enter, so parallel contexts are isolated
+# and copy_context() carries the whole stack (same UsageTotals objects) into a worker thread / executor.
+_STACK: contextvars.ContextVar[tuple[UsageTotals, ...]] = contextvars.ContextVar("rag_usage_stack", default=())
+
+
+@contextmanager
+def usage_scope() -> Iterator[UsageTotals]:
+    """Accumulate model usage for the operation run inside the block; returns the totals to read after it.
+
+    Nesting is additive: a call made inside an inner scope is counted by the inner scope AND every enclosing
+    scope, so a task-level outer scope totals everything while inner per-operation scopes attribute their slice."""
+    totals = UsageTotals()
+    token = _STACK.set(_STACK.get() + (totals,))
+    try:
+        yield totals
+    finally:
+        _STACK.reset(token)
+
+
+def usage_capturing() -> bool:
+    """True when at least one usage scope is active — the seam checks this to decide whether to capture usage
+    (e.g. request `stream_usage`) on a call that would otherwise not need it."""
+    return bool(_STACK.get())
+
+
+def record_usage(model: str, *, input_tokens: int = 0, output_tokens: int = 0,
+                 cost: Optional[float] = None, latency_ms: Optional[float] = None) -> None:
+    """Record one model call into every active scope (a no-op when none is active, so it is safe to call on
+    every model call regardless of tracing). `cost=None` means the backend surfaced no cost (counted as
+    `calls_without_cost`, never as $0). `model` is the engine model-id string, keyed consistently across paths."""
+    for totals in _STACK.get():
+        totals._add(model, input_tokens, output_tokens, cost, latency_ms)

rag_wright/okf/__init__.py

@@ -0,0 +1,11 @@
+"""OKF (Open Knowledge Format) bundle compile pipeline (FR-K.1-K.4, T46).
+
+Compiles the ingested chunk corpus into an OKF v0.1 conformant bundle for the embedding-free
+knowledge-navigation path (FR-K). Not a re-chunk: bodies come from the T40 chunk-text sidecar and
+`chunk_id` identity is unchanged (FR-S.2). Three parts:
+
+  - `enrich`   : the one model-bearing step (category + one-line description per clause), gated and
+                 concurrent. Uses a cheap model for this simple task only (ADR-0023).
+  - `compile`  : deterministic bundle write (tree, frontmatter, index.md, content-hash gate).
+  - `lint`     : deterministic conformance linter (frontmatter, type, links, coverage).
+"""