sable-sphynx 0.7.0.dev0__py3-none-any.whl

sphynx/_composed_pipeline.py

@@ -0,0 +1,109 @@
+"""Label-free component composition and source-bound chunk truth for grading."""
+from __future__ import annotations
+from copy import deepcopy
+import hashlib
+from .contracts import ContractError
+
+
+def _require(ok,message):
+    if not ok:raise ContractError(message)
+
+
+def validate_chunks(chunks,documents):
+    _require(type(chunks) is list and len(chunks)<=4096,"composed pipeline chunk count differs")
+    known={row["document_id"]:row["text"] for row in documents};result={}
+    for row in chunks:
+        _require(type(row) is dict and set(row)=={"chunk_id","document_id","start","end","text"},"chunk fields differ")
+        source=known.get(row["document_id"])
+        _require(type(row["chunk_id"]) is str and row["chunk_id"] and row["chunk_id"] not in result
+            and type(row["start"]) is int and type(row["end"]) is int and source is not None
+            and 0<=row["start"]<row["end"]<=len(source) and source[row["start"]:row["end"]]==row["text"],"chunk source bounds/text/identity drift")
+        result[row["chunk_id"]]={"candidate_id":row["chunk_id"],"chunk_id":row["chunk_id"],"document_id":row["document_id"],
+            "start":row["start"],"end":row["end"],"input":row["text"],"input_sha256":hashlib.sha256(row["text"].encode()).hexdigest()}
+    return result
+
+
+def truth_for_chunks(task,chunks):
+    """Canonical Level2 rule: inherit truth only when every source span is contained.
+
+    This is a sealed grader transformation of predeclared source labels, not new
+    human judgments of arbitrary chunks. Unknown source truth stays unavailable.
+    """
+    source=task["candidates"];spans={row["source_span_id"]:row for row in task["source_spans"]}
+    if any(row["judgment_status"]!="judged" or row["qrel"] is None or row["qrel"]>0 and not row["source_span_ids"] for row in source):
+        return None
+    result={}
+    for cid,chunk in chunks.items():
+        document_truth=[row for row in source if row["document_id"]==chunk["document_id"]]
+        if not document_truth:return None
+        grade=0;groups=set()
+        for row in document_truth:
+            if not row["source_span_ids"]:continue
+            if all(span in spans and chunk["start"]<=spans[span]["start"] and chunk["end"]>=spans[span]["end"] for span in row["source_span_ids"]):
+                grade=max(grade,row["qrel"]);groups.update(row["evidence_group_ids"])
+        result[cid]={**chunk,"qrel":grade,"judgment_status":"judged","evidence_group_ids":sorted(groups)}
+    return result
+
+
+def compose_pipeline(request,invoke):
+    """Invoke chunker→embedder→retriever→reranker→fusion→dedup→gate in order.
+
+    ``invoke(kind, operation, payload)`` is an explicitly registered component
+    call. Every payload is copied; component outputs cannot mutate earlier input.
+    """
+    records={}
+    def call(kind,operation,payload):
+        output=invoke(kind,operation,deepcopy(payload));_require(type(output) is dict,"component output must be a dict")
+        records[kind]=deepcopy(output);return output
+    chunking=call("chunker","chunk",{"task_id":request["case_id"],"documents":request["documents"]})
+    raw_chunks=chunking.get("chunks")
+    _require(type(raw_chunks) is list and all(type(row) is dict for row in raw_chunks),"chunker output differs")
+    for row in raw_chunks:
+        _require(row.get("candidate_id",row.get("chunk_id"))==row.get("chunk_id")
+            and row.get("input",row.get("text"))==row.get("text"),"chunker aliases differ from source-bound identity/text")
+    normalized_chunks=[{key:row[key] for key in ("chunk_id","document_id","start","end","text")} for row in raw_chunks]
+    chunks=validate_chunks(normalized_chunks,request["documents"])
+    rows=[{**row,"text":row["input"]} for row in chunks.values()]
+    query_id="query:"+request["case_id"]
+    embedding=call("embedder","embed",{"items":[{"candidate_id":query_id,"text":request["query"],"input":request["query"]},*rows]})
+    values=embedding.get("embeddings")
+    _require(type(values) is list and all(type(row) is dict for row in values),"embedding outputs differ")
+    vectors={row.get("candidate_id"):row.get("vector") for row in values}
+    _require(len(vectors)==len(values) and set(vectors)==set(chunks)|{query_id},"embedding membership changed")
+    import math
+    dimensions=set()
+    for vector in vectors.values():
+        _require(type(vector) is list and vector and all(type(v) in (int,float) and math.isfinite(v) for v in vector),"invalid embedding vector")
+        dimensions.add(len(vector))
+    _require(len(dimensions)==1,"embedding dimensions differ")
+    rows=[{**row,"embedding":vectors[row["candidate_id"]]} for row in rows]
+    def ranked(kind,operation,base,rank_key,score_key):
+        output=call(kind,operation,{"task_id":request["case_id"],"query":request["query"],"query_embedding":{"candidate_id":query_id,"vector":vectors[query_id]},"candidates":base})
+        actual=output.get("candidates");_require(type(actual) is list,"ranked component candidates differ")
+        by_id={row.get("candidate_id"):row for row in actual if type(row) is dict}
+        _require(len(by_id)==len(actual) and set(by_id)==set(chunks),"ranked component membership changed")
+        ordered=sorted(by_id.values(),key=lambda row:row[rank_key])
+        _require([row[rank_key] for row in ordered]==list(range(1,len(ordered)+1)),"ranked component rank order differs")
+        before={row["candidate_id"]:row for row in base}
+        return [{**before[row["candidate_id"]],rank_key:row[rank_key],score_key:row[score_key]} for row in ordered]
+    rows=ranked("retriever","retrieve",rows,"dense_rank","dense_score")
+    rows=ranked("reranker","rerank",rows,"reranker_rank","reranker_score")
+    rows=ranked("fusion","fuse",rows,"fusion_rank","fusion_score")
+    for kind,operation,keys in (("dedup","deduplicate",("dedup_decision","post_dedup_rank")),("gate","gate",("gate_decision","gate_threshold","final_rank"))):
+        output=call(kind,operation,{"task_id":request["case_id"],"query":request["query"],"candidates":rows})
+        actual=output.get("candidates");_require(type(actual) is list,"component candidates differ")
+        by_id={row.get("candidate_id"):row for row in actual if type(row) is dict}
+        _require(len(by_id)==len(actual) and set(by_id)==set(chunks),"component candidate membership changed")
+        rows=[{**row,**{key:by_id[row["candidate_id"]][key] for key in keys}} for row in rows]
+    trace=[]
+    for row in rows:
+        trace.append({key:row[key] for key in ("candidate_id","dense_rank","dense_score","reranker_rank","fusion_score","fusion_rank",
+            "dedup_decision","post_dedup_rank","gate_decision","gate_threshold","final_rank")}|{"reranker_logit":row["reranker_score"]})
+    timings={}
+    for kind,key in (("chunker","chunking"),("embedder","embedding"),("retriever","retrieval"),("reranker","reranker"),("fusion","fusion"),("dedup","dedup"),("gate","gate")):
+        value=records[kind].get("latency_ms")
+        if type(value) in (int,float) and math.isfinite(value) and value>=0:timings[key]=float(value)
+    if len(timings)==7:timings["total"]=sum(timings.values())
+    return {"schema_version":"sphynx.rag.pipeline.composed.response.v1","case_id":request["case_id"],"input_digest":request["input_digest"],
+        "construction":{"boundary":"source_bound_chunks","chunks":normalized_chunks},"embedding":{"dimension":next(iter(dimensions))},
+        "candidates":trace,"latency_state":"cold","latency_ms":timings,"stages":records}

sphynx/_full_rag_grading.py

@@ -0,0 +1,218 @@
+"""Deterministic-first Level 3 grading and fixed-generator counterfactuals."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Literal, cast
+
+from ._full_rag_trace import CONTEXT_CONDITIONS, Level3Trace
+from typing import Any
+JsonValue = Any
+from .contracts import canonical_json
+def canonical_json_bytes(value):
+    return canonical_json(value).encode("utf-8")
+
+
+class Level3GradingError(ValueError):
+    """Raised for incomplete truth, invalid graders, or uncontrolled counterfactuals."""
+
+
+@dataclass(frozen=True, slots=True)
+class ClaimVerdict:
+    start: int
+    end: int
+    supported_by_evidence_ids: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ModelGraderVerdict:
+    criterion_id: str
+    verdict: Literal["fail", "pass", "unknown"]
+    evidence_ids: tuple[str, ...]
+    rationale: str
+    prompt_sha256: str
+    provider: str
+    model: str
+    revision: str
+    temperature: float
+    seed: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class GraderAudit:
+    independent_labels: int
+    accuracy: float
+    unknown_rate: float
+    kappa: float
+
+
+@dataclass(frozen=True, slots=True)
+class CounterfactualObservation:
+    condition: str
+    trace: Level3Trace
+    generator_config_sha256: str
+    prompt_sha256: str
+    required_fact_coverage: float | None
+
+
+def _normalized(text: str) -> str:
+    return " ".join(re.findall(r"[a-z0-9]+", text.casefold()))
+
+
+def _ratio(numerator: int, denominator: int) -> float | None:
+    return None if denominator == 0 else numerator / denominator
+
+
+def grade_level3(
+    task: Mapping[str, object],
+    trace: Level3Trace,
+    *,
+    required_facts: Mapping[str, Sequence[str]],
+    exact_values: Sequence[str],
+    claims: Sequence[ClaimVerdict],
+) -> dict[str, JsonValue]:
+    """Grade observable behavior; unavailable truth yields null instead of guessed scores."""
+
+    if trace.task_id != task.get("task_id"):
+        raise Level3GradingError("trace task identity differs from gold task")
+    answer = trace.answer or ""
+    normalized_answer = _normalized(answer)
+    actual_call = trace.actual_rag_call_count > 0
+    expected_call = bool(task["should_call_rag"])
+    call_tp = int(expected_call and actual_call)
+    call_fp = int(not expected_call and actual_call)
+    call_fn = int(expected_call and not actual_call)
+    rewritten = trace.rewritten_query or trace.as_uttered_query
+    original_tokens = set(_normalized(trace.as_uttered_query).split())
+    rewritten_tokens = set(_normalized(rewritten).split())
+    rewrite_preservation = _ratio(len(original_tokens & rewritten_tokens), len(original_tokens))
+
+    groups = cast("list[Mapping[str, object]]", task["evidence_groups"])
+    required_groups = [group for group in groups if group["requirement"] == "required"]
+    handed = set(trace.handed_context_ids)
+    covered_groups = sum(
+        bool(handed & set(cast("list[str]", group["acceptable_candidate_ids"])))
+        for group in required_groups
+    )
+    fact_hits = {
+        fact_id: any(_normalized(answer_value) in normalized_answer for answer_value in accepted)
+        for fact_id, accepted in required_facts.items()
+    }
+    exact_hits = [
+        bool(_normalized(value)) and _normalized(value) in normalized_answer
+        for value in exact_values
+    ]
+    if any(
+        claim.start < 0 or claim.end <= claim.start or claim.end > len(answer) for claim in claims
+    ):
+        raise Level3GradingError("claim spans must bind the exact answer")
+    supported_claims = sum(bool(claim.supported_by_evidence_ids) for claim in claims)
+    valid_citations = [citation for citation in trace.citations if citation.evidence_id in handed]
+    supported_citations = sum(
+        any(
+            citation.start < claim.end
+            and citation.end > claim.start
+            and citation.evidence_id in claim.supported_by_evidence_ids
+            for claim in claims
+        )
+        for citation in valid_citations
+    )
+    cited_groups = sum(
+        bool(
+            {citation.evidence_id for citation in valid_citations}
+            & set(cast("list[str]", group["acceptable_candidate_ids"]))
+        )
+        for group in required_groups
+    )
+    expected_abstention = task["expected_behavior"] == "abstain"
+    return {
+        "rag_call_true_positive": call_tp,
+        "rag_call_false_positive": call_fp,
+        "rag_call_false_negative": call_fn,
+        "rag_call_precision": _ratio(call_tp, call_tp + call_fp),
+        "rag_call_recall": _ratio(call_tp, call_tp + call_fn),
+        "rewrite_preservation": rewrite_preservation,
+        "evidence_handoff_completeness": _ratio(covered_groups, len(required_groups)),
+        "answer_required_fact_coverage": _ratio(sum(fact_hits.values()), len(fact_hits)),
+        "exact_value_unit_date_accuracy": _ratio(sum(exact_hits), len(exact_hits)),
+        "faithfulness": _ratio(supported_claims, len(claims)),
+        "unsupported_claim_rate": _ratio(len(claims) - supported_claims, len(claims)),
+        "citation_precision": _ratio(len(valid_citations), len(trace.citations)),
+        "citation_recall": _ratio(cited_groups, len(required_groups)),
+        "citation_support": _ratio(supported_citations, len(valid_citations)),
+        "correct_abstention": trace.abstained == expected_abstention,
+        "answer_completeness": _ratio(sum(fact_hits.values()), len(fact_hits)),
+        "subject_error": trace.call_outcome == "error",
+        "latency_ms": cast("dict[str, JsonValue]", trace.latency_ms),
+    }
+
+
+def validate_model_grader_verdict(
+    verdict: ModelGraderVerdict,
+    *,
+    criterion_id: str,
+    allowed_evidence_ids: frozenset[str],
+) -> None:
+    """Keep model evidence criterion-scoped and preserve an explicit unknown state."""
+
+    if verdict.criterion_id != criterion_id:
+        raise Level3GradingError("model grader crossed its criterion scope")
+    if not set(verdict.evidence_ids) <= allowed_evidence_ids:
+        raise Level3GradingError("model grader cited evidence outside its scoped packet")
+    if verdict.verdict != "unknown" and not verdict.evidence_ids:
+        raise Level3GradingError("non-unknown model verdict requires cited evidence")
+    if not verdict.rationale or re.fullmatch(r"[0-9a-f]{64}", verdict.prompt_sha256) is None:
+        raise Level3GradingError("model grader configuration or rationale is incomplete")
+    if not all((verdict.provider, verdict.model, verdict.revision)):
+        raise Level3GradingError("model grader identity is incomplete")
+
+
+def model_grader_may_gate(audit: GraderAudit) -> bool:
+    """Apply the predeclared independent-human validation threshold."""
+
+    return (
+        audit.independent_labels >= 100
+        and audit.accuracy >= 0.90
+        and audit.unknown_rate <= 0.05
+        and audit.kappa >= 0.80
+    )
+
+
+def evaluate_counterfactuals(
+    observations: Sequence[CounterfactualObservation],
+) -> dict[str, JsonValue]:
+    """Require the five conditions under one generator and expose causal gaps."""
+
+    by_condition = {observation.condition: observation for observation in observations}
+    if set(by_condition) != CONTEXT_CONDITIONS or len(observations) != len(CONTEXT_CONDITIONS):
+        raise Level3GradingError(
+            "counterfactual matrix must contain each fixed condition exactly once"
+        )
+    generator_hashes = {observation.generator_config_sha256 for observation in observations}
+    prompt_hashes = {observation.prompt_sha256 for observation in observations}
+    task_ids = {observation.trace.task_id for observation in observations}
+    if len(generator_hashes) != 1 or len(prompt_hashes) != 1 or len(task_ids) != 1:
+        raise Level3GradingError("counterfactuals must freeze task, generator, and prompt")
+    coverage = {key: value.required_fact_coverage for key, value in by_condition.items()}
+
+    def gap(left: str, right: str) -> float | None:
+        return (
+            None
+            if coverage[left] is None or coverage[right] is None
+            else cast("float", coverage[left]) - cast("float", coverage[right])
+        )
+
+    payload: dict[str, JsonValue] = {
+        "condition_coverage": cast("dict[str, JsonValue]", coverage),
+        "retrieval_ranking_gap": gap("oracle", "challenger"),
+        "challenger_vs_a0": gap("challenger", "a0"),
+        "a0_ranking_contribution": gap("a0", "dense"),
+        "rag_dependency": gap("challenger", "empty"),
+        "generator_config_sha256": next(iter(generator_hashes)),
+        "prompt_sha256": next(iter(prompt_hashes)),
+    }
+    payload["matrix_sha256"] = hashlib.sha256(canonical_json_bytes(payload)).hexdigest()
+    return payload

sphynx/_full_rag_trace.py

@@ -0,0 +1,221 @@
+"""Versioned full-RAG request payload and untrusted trace validation."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Literal, cast
+
+from typing import Any
+JsonValue = Any
+
+TRACE_SCHEMA_VERSION = "sable.rag.level3-trace.v1"
+CONTEXT_CONDITIONS = frozenset({"oracle", "dense", "a0", "challenger", "empty"})
+
+
+class Level3TraceError(ValueError):
+    """Raised when a Level 3 output is missing causal trace evidence."""
+
+
+@dataclass(frozen=True, slots=True)
+class Citation:
+    citation_id: str
+    evidence_id: str
+    start: int
+    end: int
+
+
+@dataclass(frozen=True, slots=True)
+class Level3Trace:
+    task_id: str
+    expected_invocation: bool
+    actual_rag_call_count: int
+    call_outcome: Literal["error", "no_call", "success"]
+    as_uttered_query: str
+    rewritten_query: str | None
+    retrieved_candidate_ids: tuple[str, ...]
+    retrieved_context_ids: tuple[str, ...]
+    handed_context_ids: tuple[str, ...]
+    answer: str | None
+    citations: tuple[Citation, ...]
+    abstained: bool
+    deferred: bool
+    prompt_tokens: int
+    completion_tokens: int
+    latency_ms: dict[str, float]
+    error: dict[str, JsonValue] | None
+
+
+def make_level3_input(
+    task: Mapping[str, object],
+    *,
+    context_condition: str,
+    context_candidate_ids: list[str],
+) -> dict[str, JsonValue]:
+    if context_condition not in CONTEXT_CONDITIONS:
+        raise Level3TraceError("context condition is not in the fixed counterfactual matrix")
+    query = task.get("query")
+    if not isinstance(query, str) or not query:
+        raise Level3TraceError("task query must be non-empty")
+    return {
+        "operation": "full_rag",
+        "task_id": cast("str", task["task_id"]),
+        "customer_id": cast("str", task["customer_id"]),
+        "query": query,
+        "expected_invocation": bool(task["should_call_rag"]),
+        "context_condition": context_condition,
+        "context_candidate_ids": cast("list[JsonValue]", context_candidate_ids),
+    }
+
+
+def _strings(value: object, context: str) -> tuple[str, ...]:
+    if not isinstance(value, list) or any(not isinstance(item, str) or not item for item in value):
+        raise Level3TraceError(f"{context} must be an array of non-empty IDs")
+    result = tuple(cast("list[str]", value))
+    if len(result) != len(set(result)):
+        raise Level3TraceError(f"{context} must preserve unique identities")
+    return result
+
+
+def validate_level3_trace(raw: object) -> Level3Trace:
+    """Fail closed unless invocation, retrieval, handoff, answer, and latency are observable."""
+
+    if not isinstance(raw, Mapping):
+        raise Level3TraceError("trace must be an object")
+    value = cast("Mapping[str, object]", raw)
+    required = {
+        "schema_version",
+        "task_id",
+        "expected_invocation",
+        "actual_rag_call_count",
+        "call_outcome",
+        "error",
+        "as_uttered_query",
+        "rewritten_query",
+        "retrieved_candidate_ids",
+        "retrieved_context_ids",
+        "handed_context_ids",
+        "answer",
+        "citations",
+        "abstained",
+        "deferred",
+        "token_counts",
+        "latency_ms",
+    }
+    if value.keys() != required:
+        raise Level3TraceError("trace fields differ from the versioned contract")
+    if value["schema_version"] != TRACE_SCHEMA_VERSION:
+        raise Level3TraceError("trace schema version is unsupported")
+    task_id = value["task_id"]
+    query = value["as_uttered_query"]
+    if not isinstance(task_id, str) or not task_id or not isinstance(query, str) or not query:
+        raise Level3TraceError("task and as-uttered query identities are required")
+    expected = value["expected_invocation"]
+    calls = value["actual_rag_call_count"]
+    if (
+        not isinstance(expected, bool)
+        or isinstance(calls, bool)
+        or not isinstance(calls, int)
+        or calls < 0
+    ):
+        raise Level3TraceError("invocation fields are invalid")
+    outcome = value["call_outcome"]
+    if outcome not in {"success", "no_call", "error"}:
+        raise Level3TraceError("call_outcome is invalid")
+    if (outcome == "no_call") != (calls == 0):
+        raise Level3TraceError("call outcome and call count disagree")
+    error_raw = value["error"]
+    if (outcome == "error") != isinstance(error_raw, Mapping):
+        raise Level3TraceError("error outcome must preserve structured error evidence")
+    error: dict[str, JsonValue] | None = None
+    if isinstance(error_raw, Mapping):
+        error_code = error_raw.get("code")
+        error_message = error_raw.get("message")
+        if not isinstance(error_code, str) or not isinstance(error_message, str):
+            raise Level3TraceError("error evidence requires code and message")
+        error = {"code": error_code, "message": error_message}
+    rewritten = value["rewritten_query"]
+    if rewritten is not None and (not isinstance(rewritten, str) or not rewritten):
+        raise Level3TraceError("rewritten_query must be null or non-empty")
+    retrieved = _strings(value["retrieved_candidate_ids"], "retrieved_candidate_ids")
+    contexts = _strings(value["retrieved_context_ids"], "retrieved_context_ids")
+    handed = _strings(value["handed_context_ids"], "handed_context_ids")
+    if not set(contexts) <= set(retrieved):
+        raise Level3TraceError("retrieved contexts must be a subset of retrieved candidates")
+    if [item for item in retrieved if item in set(contexts)] != list(contexts):
+        raise Level3TraceError("retrieved context order must preserve candidate retrieval order")
+    if not set(handed) <= set(contexts):
+        raise Level3TraceError("generator handoff must be a subset of retrieved contexts")
+    if [item for item in contexts if item in set(handed)] != list(handed):
+        raise Level3TraceError("generator handoff order must preserve retrieval order")
+    answer = value["answer"]
+    if answer is not None and not isinstance(answer, str):
+        raise Level3TraceError("answer must be text or null")
+    abstained, deferred = value["abstained"], value["deferred"]
+    if not isinstance(abstained, bool) or not isinstance(deferred, bool):
+        raise Level3TraceError("abstention and deferral must be explicit booleans")
+    citations_raw = value["citations"]
+    if not isinstance(citations_raw, list):
+        raise Level3TraceError("citations must be an array")
+    citations: list[Citation] = []
+    for index, raw_citation in enumerate(citations_raw):
+        if not isinstance(raw_citation, Mapping):
+            raise Level3TraceError(f"citation {index} must be an object")
+        citation = cast("Mapping[str, object]", raw_citation)
+        if citation.keys() != {"citation_id", "evidence_id", "start", "end"}:
+            raise Level3TraceError(f"citation {index} fields differ")
+        start, end = citation["start"], citation["end"]
+        if not isinstance(start, int) or not isinstance(end, int) or start < 0 or end <= start:
+            raise Level3TraceError(f"citation {index} has invalid answer offsets")
+        if not isinstance(answer, str) or end > len(answer):
+            raise Level3TraceError(f"citation {index} is outside the answer")
+        citations.append(
+            Citation(
+                cast("str", citation["citation_id"]),
+                cast("str", citation["evidence_id"]),
+                start,
+                end,
+            )
+        )
+    counts = value["token_counts"]
+    if not isinstance(counts, Mapping) or counts.keys() != {"prompt", "completion"}:
+        raise Level3TraceError("token_counts fields differ")
+    count_map = cast("Mapping[str, object]", counts)
+    prompt_tokens, completion_tokens = count_map["prompt"], count_map["completion"]
+    if any(
+        isinstance(count, bool) or not isinstance(count, int) or count < 0
+        for count in (prompt_tokens, completion_tokens)
+    ):
+        raise Level3TraceError("token counts must be nonnegative integers")
+    latency_raw = value["latency_ms"]
+    required_latency = {"routing", "rewrite", "retrieval", "generation", "total"}
+    if not isinstance(latency_raw, Mapping) or latency_raw.keys() != required_latency:
+        raise Level3TraceError("latency decomposition fields differ")
+    latency = {
+        key: float(cast("int | float", item))
+        for key, item in cast("Mapping[str, object]", latency_raw).items()
+    }
+    if any(not math.isfinite(item) or item < 0 for item in latency.values()):
+        raise Level3TraceError("latency values must be finite and nonnegative")
+    if latency["total"] + 1e-9 < sum(latency[key] for key in required_latency - {"total"}):
+        raise Level3TraceError("total latency cannot be smaller than component latency")
+    return Level3Trace(
+        task_id,
+        expected,
+        calls,
+        cast("Literal['error', 'no_call', 'success']", outcome),
+        query,
+        rewritten,
+        retrieved,
+        contexts,
+        handed,
+        answer,
+        tuple(citations),
+        abstained,
+        deferred,
+        cast("int", prompt_tokens),
+        cast("int", completion_tokens),
+        latency,
+        error,
+    )