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

sphynx/reviewer_audit.py

@@ -0,0 +1,266 @@
+"""Audit a recorded Jev non-call reviewer against its own initial decisions.
+
+Stage evidence is supplied by the candidate. Capture hashes and consistency are
+verified locally; this does not promote a run beyond LOCAL_UNVERIFIED.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .invocation import (InvocationError, InvocationRunRef, _percentile,
+                         _verified_run, load_invocation_pack)
+
+_ORDER = ("call_rag", "clarify_first", "do_not_call_rag")
+_ACTION = {"call_rag": "CALL_RAG", "clarify_first": "ASK_BUYER",
+           "do_not_call_rag": "ANSWER_FROM_CONTEXT"}
+
+
+def _hash(value: object, *, ensure_ascii: bool = True) -> str:
+    raw = json.dumps(value, sort_keys=True, separators=(",", ":"),
+                     ensure_ascii=ensure_ascii, allow_nan=False).encode()
+    return hashlib.sha256(raw).hexdigest()
+
+
+def _events(capture: dict[str, Any]) -> list[dict[str, Any]]:
+    if capture["status"] != "success":
+        raise InvocationError("reviewer audit requires complete successful stage evidence")
+
+    def unique(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+        obj: dict[str, Any] = {}
+        for key, value in pairs:
+            if key in obj:
+                raise ValueError("duplicate event field")
+            obj[key] = value
+        return obj
+
+    def invalid_constant(value: str) -> None:
+        raise ValueError("non-finite event value")
+
+    try:
+        events = [json.loads(line, object_pairs_hook=unique,
+                             parse_constant=invalid_constant)
+                  for line in capture["stderr_utf8"].splitlines() if line]
+        if len(events) not in (1, 2):
+            raise ValueError("wrong stage count")
+        for event in events:
+            if (not isinstance(event, dict)
+                    or event.get("schema_version") != "sphynx.rag.invoke.candidate_stage.v1"
+                    or event.get("case_id") != capture["case_id"]
+                    or not isinstance(event.get("request"), dict)
+                    or not isinstance(event.get("response"), dict)
+                    or event.get("request_sha256") != _hash(event["request"],
+                        ensure_ascii=event.get("stage") != "jev")
+                    or event.get("response_sha256") != _hash(event["response"])):
+                raise ValueError("stage identity or digest differs")
+            timing = event.get("candidate_reported_latency_ms")
+            if type(timing) not in (int, float) or not math.isfinite(timing) or timing < 0:
+                raise ValueError("stage timing invalid")
+    except (KeyError, TypeError, ValueError, json.JSONDecodeError) as exc:
+        raise InvocationError("candidate stage evidence is invalid") from exc
+    return events
+
+
+def _initial(capture: dict[str, Any], events: list[dict[str, Any]]) -> str:
+    first = events[0]
+    request, response = first["request"], first["response"]
+    state = request.get("state", {})
+    if not isinstance(state, dict):
+        raise InvocationError("Jev stage state is invalid")
+    question = capture["request"]
+    if (first.get("stage") != "jev" or first.get("model") != "jev-1.13.0"
+            or request.get("model") != "jev-1.13.0" or response.get("model") != "jev-1.13.0"
+            or state.get("latest_user_message") != question["user_turn"]
+            or state.get("recent_conversation") != question["conversation_context"]
+            or state.get("assistant_context") !=
+            f"An enterprise agent can optionally retrieve from the frozen {question['company_id']} company knowledge base."):
+        raise InvocationError("Jev stage does not match the recorded candidate input")
+    answers = response.get("answers", {})
+    if not isinstance(answers, dict) or not isinstance(answers.get("invocation_action"), dict):
+        raise InvocationError("Jev stage answer is invalid")
+    answer = answers["invocation_action"]
+    probabilities = answer.get("probabilities")
+    if (answer.get("type") != "choice" or not isinstance(probabilities, dict)
+            or set(probabilities) != set(_ORDER)
+            or any(type(p) not in (int, float) or not math.isfinite(p) or not 0 <= p <= 1
+                   for p in probabilities.values())
+            or abs(sum(probabilities.values()) - 1) > 0.031
+            or probabilities != first.get("probabilities")):
+        raise InvocationError("Jev stage probability vector is invalid")
+    choice = max(_ORDER, key=lambda action: probabilities[action])
+    if first.get("decision") != choice:
+        raise InvocationError("Jev stage decision differs from its probability vector")
+    return _ACTION[choice]
+
+
+def _review(capture: dict[str, Any], events: list[dict[str, Any]], first: str) -> str:
+    if first == "CALL_RAG":
+        if len(events) != 1 or capture["action"] != first:
+            raise InvocationError("a Jev call must bypass the non-call reviewer")
+        return first
+    if len(events) != 2:
+        raise InvocationError("a Jev non-call requires a recorded reviewer stage")
+    event = events[1]
+    request, response = event["request"], event["response"]
+    question = capture["request"]
+    messages = request.get("input", [])
+    expected = [dict(turn) for turn in question["conversation_context"]]
+    expected.append({"role": "user", "content": question["user_turn"]})
+    try:
+        observed = [{"role": turn["role"], "content": turn["content"][0]["text"]}
+                    for turn in messages[1:]]
+        output = [item.get("text", "") for message in response.get("output", [])
+                  if isinstance(message, dict) and message.get("type") == "message"
+                  for item in message.get("content", [])
+                  if isinstance(item, dict) and item.get("type") == "output_text"]
+        def unique(pairs):
+            result = {}
+            for key, value in pairs:
+                if key in result:
+                    raise ValueError("duplicate reviewer field")
+                result[key] = value
+            return result
+        # The source reviewer joins output_text parts before parsing its JSON.
+        result = json.loads("".join(output), object_pairs_hook=unique)
+    except (AttributeError, KeyError, IndexError, TypeError, ValueError) as exc:
+        raise InvocationError("reviewer response or input structure is invalid") from exc
+    if (event.get("stage") != "noncall_reviewer" or event.get("model") != "gpt-6-sol"
+            or request.get("model") != "gpt-6-sol" or response.get("model") != "gpt-6-sol"
+            or response.get("status") != "completed" or not messages
+            or messages[0].get("role") != "developer" or observed != expected
+            or not isinstance(result, dict) or set(result) != {"route", "brief_reason"}
+            or result["route"] not in {"REQUIRE_RAG", "KEEP_NONCALL"}
+            or not isinstance(result["brief_reason"], str)
+            or result["route"] != event.get("decision")):
+        raise InvocationError("reviewer stage does not match its recorded request or output")
+    final = "CALL_RAG" if result["route"] == "REQUIRE_RAG" else first
+    if final != capture["action"]:
+        raise InvocationError("final candidate action differs from the two-stage composition")
+    return final
+
+
+def _quality(gold: list[str], actions: list[str]) -> dict[str, Any]:
+    def rate(numerator: int, denominator: int, direction: str = "higher") -> dict[str, Any]:
+        return {"value": numerator / denominator if denominator else None,
+                "numerator": numerator, "denominator": denominator, "direction": direction}
+
+    required = sum(g == "CALL_RAG" for g in gold)
+    noncalls = len(gold) - required
+    return {
+        "three_way_accuracy": rate(sum(a == g for a, g in zip(actions, gold)), len(gold)),
+        "binary_rag_accuracy": rate(sum((a == "CALL_RAG") == (g == "CALL_RAG")
+                                       for a, g in zip(actions, gold)), len(gold)),
+        "required_lookup_recall": rate(sum(g == "CALL_RAG" and a == "CALL_RAG"
+                                          for a, g in zip(actions, gold)), required),
+        "unnecessary_call_rate": rate(sum(g != "CALL_RAG" and a == "CALL_RAG"
+                                          for a, g in zip(actions, gold)), noncalls, "lower"),
+        "clarification_accuracy": rate(sum(g == "ASK_BUYER" and a == g
+                                           for a, g in zip(actions, gold)), sum(g == "ASK_BUYER" for g in gold)),
+        "answer_from_context_accuracy": rate(sum(g == "ANSWER_FROM_CONTEXT" and a == g
+                                                  for a, g in zip(actions, gold)),
+                                             sum(g == "ANSWER_FROM_CONTEXT" for g in gold)),
+    }
+
+
+@dataclass(frozen=True)
+class ReviewerAudit:
+    """Aggregate report without case IDs, question text, or source content."""
+
+    data: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        return json.loads(self.to_json())
+
+    def to_json(self) -> str:
+        return json.dumps(self.data, sort_keys=True, ensure_ascii=False, allow_nan=False)
+
+    def to_markdown(self) -> str:
+        lines = ["# Jev reviewer audit", "", "LOCAL_UNVERIFIED; paired initial and final decisions from one recorded run.", "",
+                 "| Metric | Initial Jev | After reviewer |", "| --- | ---: | ---: |"]
+        for name, item in self.data["initial_metrics"].items():
+            after = self.data["final_metrics"][name]
+            def label(value: dict[str, Any]) -> str:
+                return ("unavailable" if value["value"] is None else
+                        f"{value['numerator']}/{value['denominator']} ({value['value']:.1%})")
+            lines.append(f"| {name} | {label(item)} | {label(after)} |")
+        lines += ["", f"Reviews: {self.data['reviewer_call_count']}; corrections: {self.data['corrected_count']}; regressions: {self.data['regressed_count']}." ]
+        if "independent_raw_run" in self.data:
+            independent = self.data["independent_raw_run"]
+            lines += ["", f"The independent raw run differs on {independent['initial_decision_difference_count']} Jev initial decisions. Its difference from the final result includes sampling variation."]
+        return "\n".join(lines) + "\n"
+
+
+def audit_invocation_reviewer(
+    run_ref: InvocationRunRef | str | os.PathLike[str],
+    data_dir: str | os.PathLike[str],
+    *, raw_run_ref: InvocationRunRef | str | os.PathLike[str] | None = None,
+) -> ReviewerAudit:
+    """Measure the reviewer intervention using the same recorded Jev decisions.
+
+    Optionally show why a separately sampled raw run differs. No provider calls
+    are made. Requires successful, complete Jev and non-call reviewer evidence.
+    """
+
+    pack = load_invocation_pack(data_dir)
+    manifest, captures, _ = _verified_run(run_ref, pack)
+    gold = [pack.gold[case.case_id] for case in pack.cases]
+    initial, final, stages = [], [], []
+    for capture in captures:
+        events = _events(capture)
+        first = _initial(capture, events)
+        initial.append(first)
+        final.append(_review(capture, events, first))
+        stages.append(events)
+    corrected = sum(a != g and b == g for a, b, g in zip(initial, final, gold))
+    regressed = sum(a == g and b != g for a, b, g in zip(initial, final, gold))
+    stage_totals = sorted(sum(event["candidate_reported_latency_ms"] for event in events)
+                          for events in stages)
+    result: dict[str, Any] = {
+        "schema_version": "sphynx.rag.invoke.reviewer_audit.v1",
+        "scope": "same_recorded_jev_first_stage_before_and_after_noncall_review",
+        "trust_tier": "local_unverified", "development_only": True,
+        "evidence_source": "hash_verified_candidate_reported_stage_events",
+        "run_id": manifest["run_id"], "candidate": manifest["candidate"],
+        "input_sha256": pack.input_sha256, "gold_sha256": pack.gold_sha256,
+        "case_count": len(gold), "reviewer_call_count": sum(len(events) == 2 for events in stages),
+        "changed_count": sum(a != b for a, b in zip(initial, final)),
+        "corrected_count": corrected, "regressed_count": regressed,
+        "net_correct_count_delta": corrected - regressed,
+        "required_lookup_rescued_count": sum(g == "CALL_RAG" and a != "CALL_RAG" and b == "CALL_RAG"
+                                             for a, b, g in zip(initial, final, gold)),
+        "new_unnecessary_call_count": sum(g != "CALL_RAG" and a != "CALL_RAG" and b == "CALL_RAG"
+                                           for a, b, g in zip(initial, final, gold)),
+        "initial_metrics": _quality(gold, initial), "final_metrics": _quality(gold, final),
+        "candidate_reported_serial_stage_latency_ms": {
+            "p50": _percentile(stage_totals, .5), "p95": _percentile(stage_totals, .95),
+        },
+    }
+    if raw_run_ref is not None:
+        raw_manifest, raw_captures, _ = _verified_run(raw_run_ref, pack)
+        for key in ("execution", "runner"):
+            if raw_manifest[key] != manifest[key]:
+                raise InvocationError(f"independent raw run differs in {key}")
+        raw_actions = []
+        for capture in raw_captures:
+            events = _events(capture)
+            first = _initial(capture, events)
+            if len(events) != 1 or capture["action"] != first:
+                raise InvocationError("independent raw run must contain exactly one Jev stage")
+            raw_actions.append(first)
+        raw_correct = sum(a == g for a, g in zip(raw_actions, gold))
+        initial_correct = sum(a == g for a, g in zip(initial, gold))
+        result["independent_raw_run"] = {
+            "run_id": raw_manifest["run_id"], "candidate": raw_manifest["candidate"],
+            "metrics": _quality(gold, raw_actions),
+            "initial_decision_difference_count": sum(a != b for a, b in zip(raw_actions, initial)),
+            "sampling_correct_count_delta": initial_correct - raw_correct,
+            "final_correct_count_delta_vs_independent_raw": initial_correct + corrected - regressed - raw_correct,
+            "scope": "independent_jev_samples_same_questions_does_not_isolate_reviewer_effect",
+        }
+    return ReviewerAudit(result)

sphynx/routing_policies.py

@@ -0,0 +1,375 @@
+"""Frozen routing rules and provider request builders, ported from verified sources.
+
+No source checkout is imported at runtime. Binary counterfactual cascades retain
+binary semantics and are not promoted to three-way invocation decisions.
+"""
+from __future__ import annotations
+import json
+import math
+import re
+from typing import Any, cast
+from collections.abc import Mapping
+from types import MappingProxyType
+
+
+SOURCE_DIGESTS = MappingProxyType({'rule': 'sha256:7436e619e247905df92b74ef921d61171aec146c9ae6907fe73231d1d5202660', 'questions': 'sha256:116c6958e9a4558a2209c9c708702915389d7f751e9c15227efa02e63d73eb86', 'jev': 'sha256:1b56234bc39b8052e64e32c97750152760461f2ec2eff4e1abf1e0de34570200', 'typed': 'sha256:3d56b6c154f056c2c2c5afb9934988bfc335bdd5621cfe79a0483bb97e673964', 'narrow': 'sha256:ecc78a7b685ebde8f93953813447f04d532e02e6415192ba38c1a142d12dbb20', 'hybrid': 'sha256:d14af4ae252b8aa9d645a4cbdc0b6ea0ca7861cfb24b432718954aacb375fbf2', 'reviewer': 'sha256:102876c0ce907572d9dbc42e11258684b46108da8bebff1f6ff55d67bdedb4ee', 'cascade': 'sha256:a1cd3170e59f448abf5db157b9c012317c8398a3fbd22a02b2121d22be2bfce2'})
+
+ORDER = ("call_rag", "clarify_first", "do_not_call_rag")
+ACTION = {"call_rag": "CALL_RAG", "clarify_first": "ASK_BUYER", "do_not_call_rag": "ANSWER_FROM_CONTEXT"}
+MODEL = "gpt-6-sol"
+JEV_MODEL = "jev-1.13.0"
+
+COMPANIES = {'tipalti': 'Tipalti', 'vanta': 'Vanta', 'monday': 'Monday.com', 'notion': 'Notion', 'figma': 'Figma'}
+
+_CLARIFY_PATTERN_TEXT = ('\\bwhich one\\b', '\\bdoes this apply\\b', '\\bwhen is it due\\b', '\\bwhy was it rejected\\b', '\\bcan they approve\\b', '\\bwhat changed\\b', '\\bhow do i fix it\\b', '\\bsame way as before\\b', '\\bis this allowed\\b', '\\bwhich policy\\b', '\\bcheck the exception\\b', '\\bgive me the steps\\b', '\\bwhat is the limit for it\\b')
+
+_NO_CALL_PATTERN_TEXT = ('\\brewrite\\b', '\\bsummarize\\b', '\\bcalculate\\b', '\\bformat\\b', '\\bextract\\b', '\\btranslate\\b', '\\bdraft\\b', '\\bcompare\\b', '\\bbrainstorm\\b', '\\bthanks\\b', '\\bwhat did you just complete\\b', '\\bmultiplied by\\b', '\\bturn that json\\b')
+
+_CLARIFY_PATTERNS = tuple(re.compile(p, re.IGNORECASE) for p in _CLARIFY_PATTERN_TEXT)
+_NO_CALL_PATTERNS = tuple(re.compile(p, re.IGNORECASE) for p in _NO_CALL_PATTERN_TEXT)
+
+def simple_rule_action(latest_user_message: str) -> str:
+    """Execute the exact frozen T-022 keyword/context rule."""
+
+    if any(pattern.search(latest_user_message) for pattern in _CLARIFY_PATTERNS):
+        return "clarify_first"
+    if any(pattern.search(latest_user_message) for pattern in _NO_CALL_PATTERNS):
+        return "do_not_call_rag"
+    return "call_rag"
+
+
+def jev_080_action(direct: float, clarify: float) -> str:
+    """Apply the frozen inclusive 0.80 high-confidence non-call policy."""
+
+    _validate_score(direct, "direct")
+    _validate_score(clarify, "clarify")
+    if max(direct, clarify) < 0.8:
+        return "call_rag"
+    return "do_not_call_rag" if direct >= clarify else "clarify_first"
+
+
+def t023_asymmetric_action(direct: float, clarify: float) -> str:
+    """Apply the exact T-023 arbitration, including simultaneous-boundary behavior."""
+
+    _validate_score(direct, "direct")
+    _validate_score(clarify, "clarify")
+    if direct >= 0.65 and (clarify < 0.75 or direct >= clarify):
+        return "do_not_call_rag"
+    if clarify >= 0.75:
+        return "clarify_first"
+    return "call_rag"
+
+
+def _validate_score(value: float, name: str) -> None:
+    if isinstance(value, bool) or not isinstance(value, float | int):
+        raise ValueError(f"{name} score must be numeric")
+    if not math.isfinite(value) or not 0 <= value <= 1:
+        raise ValueError(f"{name} score must be finite and in [0, 1]")
+
+
+TYPED_POLICY = "You are a decision-only router for an enterprise agent's next response.\nReturn one route; do not answer the user's question. A company knowledge base is\navailable, but no company documents or product facts are preloaded here.\n\nPriority order:\n1. Resolve references using the prior conversation. Do not call a detail\n   missing if the user already supplied it.\n2. ASK_BUYER when a specific, buyer-owned detail is absent and different\n   values of that detail would materially change which answer is useful. A\n   product document cannot reveal the buyer's requirements, environment,\n   intended use, or acceptance threshold. Ask one focused question naming the\n   missing detail. This takes precedence over a lookup that would merely give\n   generic product facts while leaving the user's actual question unanswered.\n3. Otherwise CALL_RAG when answering requires an unverified fact about the\n   company's products, integrations, capabilities, limitations, pricing, or\n   competitors. Do not answer such facts from model memory. Name the fact and\n   give a targeted search query.\n4. Otherwise ANSWER_FROM_CONTEXT when the request is conversational or the\n   information needed is already present in the conversation.\n\nDo not ask the buyer for details that are optional to answer a concrete product\nquestion. When both buyer context and a product fact are missing, clarify first\nonly if the buyer detail changes the search target or answer; otherwise retrieve.\nBe concise. Use empty strings for fields that do not apply to the chosen route."
+
+
+ROUTE_SCHEMA = {'type': 'object', 'properties': {'route': {'type': 'string', 'enum': ['CALL_RAG', 'ASK_BUYER', 'ANSWER_FROM_CONTEXT']}, 'missing_buyer_detail': {'type': 'string'}, 'needed_product_fact': {'type': 'string'}, 'rag_query': {'type': 'string'}, 'clarifying_question': {'type': 'string'}, 'brief_reason': {'type': 'string'}}, 'required': ['route', 'missing_buyer_detail', 'needed_product_fact', 'rag_query', 'clarifying_question', 'brief_reason'], 'additionalProperties': False}
+
+
+NARROW_POLICY = "You are a decision-only router for an enterprise agent's next response.\nReturn one route; do not answer the user's question. A company knowledge base is\navailable, but no company documents or product facts are preloaded here.\n\nPriority order:\n1. Resolve references using the prior conversation. Do not call a detail\n   missing if the user already supplied it.\n2. CALL_RAG when a named company product, capability, integration, procedure,\n   limitation, price, or competitor gives a useful factual lookup target, even\n   if the buyer has not finalized their own configuration. Retrieve the\n   general evidence first; the agent may ask a follow-up afterward. Do not\n   answer unverified product facts from model memory. Name the fact and give\n   a targeted search query.\n3. ASK_BUYER when the missing buyer-owned detail is necessary to identify any\n   useful retrieval target, or the user requests a buyer-specific choice or\n   judgment that cannot be made from general product evidence alone. Ask one\n   focused question naming that detail. Do not call RAG solely to collect\n   generic facts that cannot advance the actual request.\n4. Otherwise ANSWER_FROM_CONTEXT when the request is conversational or the\n   information needed is already present in the conversation.\n\nDo not ask the buyer for details that are optional to answer a concrete product\nquestion. When both buyer context and a product fact are missing, retrieve if\nthe named product fact could advance the request without that context; otherwise\nclarify. Be concise. Use empty strings for fields that do not apply to the\nchosen route."
+
+
+HYBRID_POLICY = "You are the first-decision router for an enterprise agent. Select exactly one route, and do not answer the user. A company knowledge base is configured, but no company documents or product facts are preloaded.\n\nDecide what information the user is asking for, not merely whether the conversation mentions an unfinished buyer setup.\n1. ANSWER_FROM_CONTEXT if prior conversation already supplies the requested fact, or the next response needs no company lookup. Resolve references in the conversation before deciding.\n2. ASK_BUYER if the requested fact is a buyer-owned choice, approval, requirement, or event that the buyer has not stated. Product documentation cannot reveal which option this particular buyer selected. Ask one focused question. Also clarify if a missing buyer detail makes every plausible lookup target useless.\n3. CALL_RAG if the user asks for a company-product fact or documented procedure that is not in the conversation. A named product, feature, integration, limitation, or procedure is a sufficient retrieval target. Incomplete buyer configuration does not block a useful general lookup; retrieve now and clarify later if the answer still needs buyer context. Do not invent product facts from model memory.\n\nWhen product facts and buyer context are both missing, choose CALL_RAG if the named documented fact or procedure would advance the user's actual request; choose ASK_BUYER when the user is asking for their own unstated decision. Give a targeted search query only for CALL_RAG. Use empty strings for nonapplicable fields."
+
+
+REVIEWER_POLICY = "You are a safety reviewer of an enterprise agent's proposed decision NOT to search its company knowledge base. Choose one action. Do not answer the user.\n\nREQUIRE_RAG when the user's requested deliverable includes a concrete, company-specific product fact, documented procedure, API operation, setup step, capability, limitation, or integration fact that can usefully be looked up. A buyer's unfinished configuration does not block retrieving general documentation when the user asks how the named feature works or is set up.\n\nKEEP_NONCALL when the user asks whether a product will work for their particular needs but has not provided the requirements, environment, or acceptance criteria necessary to judge suitability. Merely finding general feature information would not settle that buyer-specific question; the next action should clarify. Also keep non-call if the requested fact is already supplied in the conversation or the request needs no company-specific evidence.\n\nDecide from what the user actually asks to know, not simply whether a feature is named or a buyer detail is missing. A general how/what/where question about a documented operation differs from a fit-for-us judgment. If a useful company lookup is required to answer the stated request, require RAG; otherwise preserve the proposed non-call."
+
+
+REVIEWER_SCHEMA = {'type': 'object', 'properties': {'route': {'type': 'string', 'enum': ['REQUIRE_RAG', 'KEEP_NONCALL']}, 'brief_reason': {'type': 'string'}}, 'required': ['route', 'brief_reason'], 'additionalProperties': False}
+
+
+def _jev_questions() -> dict[str, Any]:
+    return {
+        "invocation_action": {
+            "type": "choice",
+            "instructions": (
+                "Before retrieving anything, choose the enterprise agent's best next action. "
+                "Judge whether private workspace knowledge is needed, whether the supplied "
+                "conversation is already sufficient, or whether missing information prevents a "
+                "useful retrieval query. A knowledge-seeking request may still require retrieval "
+                "even when the knowledge base could ultimately lack the answer."
+            ),
+            "criteria": {
+                "call_rag": (
+                    "Retrieval from the private workspace knowledge base is needed before "
+                    "a useful, "
+                    "grounded answer or action can be produced."
+                ),
+                "do_not_call_rag": (
+                    "The request can be handled from supplied conversation, general reasoning, "
+                    "calculation, transformation, or ordinary conversation without private "
+                    "retrieval."
+                ),
+                "clarify_first": (
+                    "A key entity, referent, scope, role, record, process, or constraint is "
+                    "missing or "
+                    "ambiguous, so the agent should ask a clarifying question before retrieval."
+                ),
+            },
+        },
+        "primary_basis": {
+            "type": "choice",
+            "instructions": "Choose the primary basis for the invocation decision.",
+            "criteria": {
+                "internal_knowledge_required": (
+                    "The requested answer or action depends on facts, policies, procedures, "
+                    "records, "
+                    "or state from the private workspace knowledge base."
+                ),
+                "provided_context_sufficient": (
+                    "The user or conversation already supplies the facts needed for the requested "
+                    "answer, extraction, calculation, or transformation."
+                ),
+                "general_or_transformative": (
+                    "The request is conversational or can be completed with general reasoning or "
+                    "language transformation and no private facts."
+                ),
+                "underspecified_or_ambiguous": (
+                    "The request lacks enough identifying or scoping information to form a useful "
+                    "private-knowledge retrieval query."
+                ),
+            },
+        },
+    }
+
+
+def _typed_body(case: dict) -> bytes:
+    company = COMPANIES[case["company_id"]]
+    context = (
+        f"Company: {company}. The company's RAG fact source is configured, "
+        "but no company facts are preloaded. No shared screen is supplied."
+    )
+    messages = [{
+        "role": "developer",
+        "content": [{"type": "input_text", "text": TYPED_POLICY + "\n\n" + context}],
+    }]
+    for prior in case["conversation_context"]:
+        content_type = "output_text" if prior["role"] == "assistant" else "input_text"
+        messages.append({
+            "role": prior["role"],
+            "content": [{"type": content_type, "text": prior["content"]}],
+        })
+    messages.append({
+        "role": "user",
+        "content": [{"type": "input_text", "text": case["user_turn"]}],
+    })
+    body = {
+        "model": MODEL,
+        "input": messages,
+        "text": {
+            "format": {
+                "type": "json_schema",
+                "name": "sphynx_rag_invocation_route",
+                "strict": True,
+                "schema": ROUTE_SCHEMA,
+            }
+        },
+        "reasoning": {"effort": "none"},
+        "service_tier": "fast",
+        "max_output_tokens": 800,
+        "store": False,
+    }
+    return json.dumps(body, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+
+def jev_body(request: dict) -> bytes:
+    body = {"model": JEV_MODEL, "state": {
+        "assistant_context": f"An enterprise agent can optionally retrieve from the frozen {request['company_id']} company knowledge base.",
+        "recent_conversation": request["conversation_context"],
+        "latest_user_message": request["user_turn"],
+    }, "questions": _jev_questions()}
+    return json.dumps(body, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False).encode("utf-8")
+
+
+def route_body(request: dict, policy: str = "typed") -> bytes:
+    body = json.loads(_typed_body(request))
+    policies = {"typed": TYPED_POLICY, "narrow": NARROW_POLICY, "hybrid": HYBRID_POLICY, "reviewer": REVIEWER_POLICY}
+    original = body["input"][0]["content"][0]["text"]
+    body["input"][0]["content"][0]["text"] = policies[policy] + original[len(TYPED_POLICY):]
+    if policy == "reviewer":
+        body["text"]["format"]["name"] = "sphynx_jev_noncall_safety_review"
+        body["text"]["format"]["schema"] = REVIEWER_SCHEMA
+        body["max_output_tokens"] = 300
+    return json.dumps(body, sort_keys=True, separators=(",", ":"), allow_nan=False).encode("utf-8")
+
+
+def jev_legacy(probs: dict[str, float]) -> bool:
+    """Existing Jev 0.80 binary policy, not a newly fitted threshold."""
+    return max(probs["do_not_call_rag"], probs["clarify_first"]) < 0.8
+
+
+def jev_confident(probs: dict[str, float]) -> bool | None:
+    """First gate exits only when one three-way action reaches 0.80."""
+    action = max(probs, key=probs.get)
+    if probs[action] < 0.8:
+        return None
+    return action == "call_rag"
+
+
+def jev_confident_clarification(probs: dict[str, float]) -> bool:
+    return probs["clarify_first"] >= 0.8 and probs["clarify_first"] == max(probs.values())
+
+
+def binary_cascade(name: str, full: bool | None, cheap: bool | None, probs: dict[str, float]) -> tuple[bool | None, tuple[str, ...]]:
+    if name == "incumbent":
+        return full, ("full",)
+    if name == "jev_080":
+        return jev_legacy(probs), ("jev",)
+    if name == "gpt6sol_only":
+        return cheap, ("cheap",)
+    if name == "jev_first":
+        stages = ["jev"]
+        confident = jev_confident(probs)
+        if confident is not None:
+            return confident, tuple(stages)
+        stages.append("cheap")
+        if cheap is not None:
+            return cheap, tuple(stages)
+        stages.append("full")
+        return (full if full is not None else True), tuple(stages)
+    if name == "cheap_first":
+        stages = ["cheap"]
+        if cheap is False:
+            return False, tuple(stages)
+        stages.append("jev")
+        if cheap is None:
+            confident = jev_confident(probs)
+            if confident is not None:
+                return confident, tuple(stages)
+            stages.append("full")
+            return (full if full is not None else jev_legacy(probs)), tuple(stages)
+        if jev_legacy(probs):
+            return True, tuple(stages)
+        stages.append("full")
+        return (full if full is not None else True), tuple(stages)
+    if name == "consensus_escalate":
+        stages = ["cheap", "jev"]
+        j = jev_legacy(probs)
+        if cheap is None:
+            return j, tuple(stages)
+        if cheap == j:
+            return j, tuple(stages)
+        stages.append("full")
+        return (full if full is not None else True), tuple(stages)
+    if name == "either_calls":
+        stages = ("cheap", "jev")
+        return (jev_legacy(probs) if cheap is None else cheap or jev_legacy(probs)), stages
+    if name == "jev_clarify_only_posthoc":
+        stages = ["jev"]
+        if jev_confident_clarification(probs):
+            return False, tuple(stages)
+        stages.append("cheap")
+        if cheap is not None:
+            return cheap, tuple(stages)
+        stages.append("full")
+        return (full if full is not None else jev_legacy(probs)), tuple(stages)
+    if name == "cheap_jev_clarify_posthoc":
+        stages = ["cheap"]
+        if cheap is not None:
+            if not cheap:
+                return False, tuple(stages)
+            stages.append("jev")
+            return (not jev_confident_clarification(probs)), tuple(stages)
+        stages.append("jev")
+        if jev_confident_clarification(probs):
+            return False, tuple(stages)
+        stages.append("full")
+        return (full if full is not None else jev_legacy(probs)), tuple(stages)
+    raise ValueError(f"Unknown policy: {name}")
+
+
+def jev_probabilities(response: dict) -> dict[str, float]:
+    if not isinstance(response, dict) or response.get("model") != JEV_MODEL:
+        raise ValueError("Jev model identity differs")
+    answers = response.get("answers")
+    if not isinstance(answers, dict) or not isinstance(answers.get("invocation_action"), dict):
+        raise ValueError("Jev answer is invalid")
+    _extract_jev_scores(response)
+    answer = answers["invocation_action"]
+    p = answer.get("probabilities")
+    if (answer.get("type") != "choice" or not isinstance(p, dict) or set(p) != set(ORDER)
+            or any(type(v) not in (int, float) or not math.isfinite(v) or not 0 <= v <= 1 for v in p.values())
+            or abs(sum(p.values()) - 1) > 0.031):
+        raise ValueError("Jev probabilities are invalid")
+    return dict(p)
+
+
+def route_result(response: dict, *, reviewer: bool = False) -> dict:
+    if not isinstance(response, dict) or response.get("model") != MODEL or response.get("status") != "completed":
+        raise ValueError("router model or completion identity differs")
+    texts = [c.get("text", "") for o in response.get("output", []) if isinstance(o, dict) and o.get("type") == "message"
+             for c in o.get("content", []) if isinstance(c, dict) and c.get("type") == "output_text"]
+    def unique(pairs):
+        d = {}
+        for k, v in pairs:
+            if k in d: raise ValueError("duplicate router field")
+            d[k] = v
+        return d
+    value = json.loads("".join(texts), object_pairs_hook=unique)
+    schema = REVIEWER_SCHEMA if reviewer else ROUTE_SCHEMA
+    if not isinstance(value, dict) or set(value) != set(schema["properties"]) or not all(isinstance(v, str) for v in value.values()):
+        raise ValueError("router schema differs")
+    if value["route"] not in schema["properties"]["route"]["enum"]:
+        raise ValueError("router route differs")
+    if not reviewer:
+        required = {"ASK_BUYER": ("missing_buyer_detail", "clarifying_question"), "CALL_RAG": ("needed_product_fact", "rag_query")}.get(value["route"], ())
+        if any(not value[k].strip() for k in required): raise ValueError("router required route details absent")
+    return value
+
+
+JEV_BASIS_OPTIONS = ('internal_knowledge_required', 'provided_context_sufficient', 'general_or_transformative', 'underspecified_or_ambiguous')
+ACTIONS = ORDER
+
+def _extract_jev_scores(response: Any | None) -> tuple[tuple[float, float], str | None]:
+    if not isinstance(response, Mapping):
+        raise ValueError("Jev response must be an object")
+    if response.get("model") != JEV_MODEL:
+        raise ValueError("Jev response model mismatch")
+    answers = response.get("answers")
+    if not isinstance(answers, Mapping):
+        raise ValueError("Jev answers must be an object")
+    action = answers.get("invocation_action")
+    if (
+        not isinstance(action, Mapping)
+        or set(action) != {"type", "choice", "confidence", "probabilities"}
+        or action.get("type") != "choice"
+        or action.get("choice") not in ACTIONS
+    ):
+        raise ValueError("Jev invocation_action must be a choice")
+    _validate_score(cast("float", action.get("confidence")), "invocation_action confidence")
+    probabilities = action.get("probabilities")
+    if not isinstance(probabilities, Mapping) or set(probabilities) != set(ACTIONS):
+        raise ValueError("Jev action probabilities have the wrong identity set")
+    values = {name: cast("float", probabilities[name]) for name in ACTIONS}
+    for name, value in values.items():
+        _validate_score(value, name)
+    if abs(sum(values.values()) - 1) > 0.031:
+        raise ValueError("Jev action probabilities do not sum to one")
+    basis = answers.get("primary_basis")
+    if (
+        not isinstance(basis, Mapping)
+        or set(basis) != {"type", "choice", "confidence", "probabilities"}
+        or basis.get("type") != "choice"
+        or basis.get("choice") not in JEV_BASIS_OPTIONS
+    ):
+        raise ValueError("Jev primary_basis must be a registered choice")
+    _validate_score(cast("float", basis.get("confidence")), "primary_basis confidence")
+    basis_probabilities = basis.get("probabilities")
+    if not isinstance(basis_probabilities, Mapping) or set(basis_probabilities) != set(
+        JEV_BASIS_OPTIONS
+    ):
+        raise ValueError("Jev basis probabilities have the wrong identity set")
+    basis_values = {name: cast("float", basis_probabilities[name]) for name in JEV_BASIS_OPTIONS}
+    for basis_name, value in basis_values.items():
+        _validate_score(value, basis_name)
+    if abs(sum(basis_values.values()) - 1) > 0.031:
+        raise ValueError("Jev basis probabilities do not sum to one")
+    basis_value = cast("str", basis["choice"])
+    return (values["do_not_call_rag"], values["clarify_first"]), basis_value