urim 0.0.1a1__py3-none-any.whl

urim/__init__.py

@@ -0,0 +1,60 @@
+"""urim (Python port). Same canonical JSON, hashes and envelope as the TypeScript port."""
+
+from .camps import decode_reply, encode_request, request_id_of
+from .canonical import canonicalize, sha256
+from .classify import classify_reply, classify_vendor_reply
+from .client import Client, create_client
+from .cuts import resolve_cuts
+from .define import choice, define_decision, noul, score, threshold, tier
+from .descriptors import DESCRIPTORS, GENERIC_ERRORS, descriptor_for, model_spec_for
+from .emit import emit
+from .envelope import build_envelope
+from .envelope_read import read_envelope
+from .errors import FAILOVER_TYPES, Issue, UrimError
+from .fit import estimate_fit_cost, parse_cases, run_fit
+from .lock import parse_lock, serialize_lock
+from .plan import estimate_input_tokens, explain, next_step, plan_attempts
+from .schema import json_schema_adapter, pydantic_schema
+from .types import CONFIDENCE_RULE, Objective
+
+__all__ = [
+    "CONFIDENCE_RULE",
+    "DESCRIPTORS",
+    "FAILOVER_TYPES",
+    "GENERIC_ERRORS",
+    "Client",
+    "Issue",
+    "Objective",
+    "UrimError",
+    "build_envelope",
+    "canonicalize",
+    "choice",
+    "classify_reply",
+    "classify_vendor_reply",
+    "create_client",
+    "decode_reply",
+    "define_decision",
+    "descriptor_for",
+    "emit",
+    "encode_request",
+    "estimate_fit_cost",
+    "estimate_input_tokens",
+    "explain",
+    "json_schema_adapter",
+    "model_spec_for",
+    "next_step",
+    "noul",
+    "parse_cases",
+    "parse_lock",
+    "plan_attempts",
+    "pydantic_schema",
+    "read_envelope",
+    "request_id_of",
+    "resolve_cuts",
+    "run_fit",
+    "score",
+    "serialize_lock",
+    "sha256",
+    "threshold",
+    "tier",
+]

urim/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m urim`` runs the ``urim`` command."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

urim/adapters.py

@@ -0,0 +1,80 @@
+"""A: real HTTP adapters over httpx (opt-in: ``from urim.adapters import typesafe_jev, openai_decisions``).
+
+Nothing here runs unless you import it AND pass it to ``create_client``. The credential arrives from the client,
+which reads the env var named by ``credential_env`` at send time. It is put in one request header and never
+logged, stored, or placed in any error message. Pass ``create_client(http=httpx.AsyncClient(...))`` to share a
+connection pool (tests use ``httpx.MockTransport``); otherwise one client is opened per send.
+Requires the optional extra: ``pip install urim[httpx]``. Mirrors urim-ts src/adapters/index.ts.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from .descriptors import DESCRIPTORS, AuthSpec, Descriptor
+from .errors import UrimError
+from .jsonfmt import stringify
+from .testing import SendIO
+from .types import WireReply, WireRequest
+
+
+def _reject_constant(name: str) -> Any:
+    raise ValueError(name)  # NaN/Infinity are not JSON (JSON.parse rejects them too)
+
+
+def _read_body(text: str) -> Any:
+    try:
+        return json.loads(text, parse_constant=_reject_constant)
+    except ValueError:
+        return text  # non-JSON -> the decoder reports nonconformant_response
+
+
+@dataclass(frozen=True)
+class HttpAdapter:
+    provider: str
+    credential_env: str
+    _url: str
+    _auth: AuthSpec
+
+    async def send(self, req: WireRequest, io: SendIO) -> WireReply:
+        if io.credential == "":
+            raise UrimError("auth", f"missing credential: set {self.credential_env}", tier=req.tier_id)
+        value = io.credential if self._auth.scheme is None else f"{self._auth.scheme} {io.credential}"
+        headers = {"content-type": "application/json", self._auth.header: value}
+        content = stringify(req.body).encode("utf-8")
+        started = time.monotonic()
+        if io.http is not None:
+            res = await io.http.post(req.url, content=content, headers=headers)
+        else:
+            import httpx  # optional extra, imported only when a real send happens
+
+            async with httpx.AsyncClient() as http:
+                res = await http.post(req.url, content=content, headers=headers)
+        return WireReply(
+            res.status_code,
+            {k.lower(): v for k, v in res.headers.items()},
+            _read_body(res.text),
+            (time.monotonic() - started) * 1000,
+        )
+
+
+def http_adapter(d: Descriptor) -> HttpAdapter:
+    """One adapter per descriptor whose URL needs no caller-supplied placeholders."""
+    if not d.auth or "{" in d.url:
+        raise UrimError(
+            "invalid_definition", f"{d.provider}: descriptor needs URL/auth options this slice does not support"
+        )
+    return HttpAdapter(d.provider, d.auth[0].env, d.url, d.auth[0])
+
+
+def typesafe_jev() -> HttpAdapter:
+    """TypeSafe Jev, systemone camp. Bearer TYPESAFE_API_KEY -> the descriptor URL."""
+    return http_adapter(DESCRIPTORS["typesafe"])
+
+
+def openai_decisions() -> HttpAdapter:
+    """OpenAI, decisions camp. Bearer OPENAI_API_KEY -> the descriptor URL."""
+    return http_adapter(DESCRIPTORS["openai"])

urim/boundary.py

@@ -0,0 +1,100 @@
+"""C: the ONE place Python snake_case meets the camelCase JSON urim-ts writes (contract, lock, envelope, settled).
+
+Rules:
+- Only dataclass attribute names are mapped. Mapping keys (question names, tier ids, threshold names, vendor
+  ``native`` data, raw bodies) are user/vendor data and are never re-cased.
+- ``json_name``: snake -> lowerCamel for every member (no exceptions since slice 7), plus keyword escapes (``from_``).
+- ``ABSENT`` attributes are omitted; ``interpret_failed`` is written only when true (as in urim-ts).
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import types as _pytypes
+import typing
+from collections.abc import Mapping
+from functools import cache
+from types import MappingProxyType
+from typing import Any, Literal, TypeVar, Union
+
+from .freeze import deep_freeze
+from .types import ABSENT, PriceTable, _Absent
+
+_T = TypeVar("_T")
+_ESCAPES = {"from_": "from"}
+_OMIT_IF_FALSE = frozenset({"interpret_failed"})
+
+
+@cache
+def json_name(attr: str) -> str:
+    """The JSON member name for dataclass attribute ``attr``."""
+    if attr in _ESCAPES:
+        return _ESCAPES[attr]
+    if "_" not in attr:
+        return attr
+    head, *rest = attr.split("_")
+    return head + "".join(p[:1].upper() + p[1:] for p in rest)
+
+
+def _omitted(name: str, value: Any) -> bool:
+    return value is ABSENT or (name in _OMIT_IF_FALSE and value is False)
+
+
+def to_json(value: Any) -> Any:
+    """Python data -> plain JSON-ready data with urim-ts member names."""
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return {
+            json_name(f.name): to_json(v)
+            for f in dataclasses.fields(value)
+            if not _omitted(f.name, v := getattr(value, f.name))
+        }
+    if isinstance(value, Mapping):
+        return {k: to_json(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [to_json(v) for v in value]
+    return value
+
+
+@cache
+def _hints(cls: type) -> dict[str, Any]:
+    return typing.get_type_hints(cls)
+
+
+def _convert(tp: Any, v: Any) -> Any:
+    origin = typing.get_origin(tp)
+    if origin in (Union, _pytypes.UnionType):
+        args = [a for a in typing.get_args(tp) if a is not _Absent]
+        if v is None and type(None) in args:
+            return None
+        concrete = [a for a in args if a is not type(None)]
+        return _convert(concrete[0], v) if len(concrete) == 1 else deep_freeze(v)
+    if isinstance(tp, type) and dataclasses.is_dataclass(tp):
+        return from_json(tp, v)
+    if origin is tuple:
+        (item, *_rest) = typing.get_args(tp)
+        return tuple(_convert(item, x) for x in v)
+    if origin in (Mapping, dict) or tp is Mapping:
+        kv = typing.get_args(tp)
+        return MappingProxyType({k: _convert(kv[1] if kv else Any, x) for k, x in v.items()})
+    if origin is Literal or tp in (str, int, float, bool):
+        return v
+    return deep_freeze(v)
+
+
+def from_json(cls: type[_T], data: Mapping[str, Any]) -> _T:
+    """Plain JSON (already validated by its reader) -> frozen snake_case dataclass. Unknown members ignored."""
+    dc: Any = cls  # a dataclass type; the checker cannot see that through a TypeVar
+    hints = _hints(dc)
+    kwargs = {}
+    for f in dataclasses.fields(dc):
+        key = json_name(f.name)
+        if key in data:
+            kwargs[f.name] = _convert(hints[f.name], data[key])
+        elif f.default is dataclasses.MISSING:
+            raise KeyError(f"{cls.__name__}: missing member {key!r}")
+    return cls(**kwargs)
+
+
+def parse_price_table(data: Mapping[str, Any]) -> PriceTable:
+    """The shared PriceTable JSON (camelCase, as urim-ts) -> PriceTable."""
+    return from_json(PriceTable, data)

urim/camps/__init__.py

@@ -0,0 +1,81 @@
+"""C: camp dispatch. URL, wire model, error map, aliases and request-id header all come from descriptor data."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from ..classify import classify_vendor_reply
+from ..descriptors import descriptor_for, explicit_model_spec, header, model_spec_for
+from ..errors import UrimError
+from ..types import Definition, Tier, WireReply, WireRequest
+from . import decisions, systemone
+from .shared import Decoded, DecodedFail, DecodedOk, TokenUsage
+
+__all__ = ["Decoded", "DecodedFail", "DecodedOk", "TokenUsage", "decode_reply", "encode_request", "request_id_of"]
+
+
+class _Codec(Protocol):
+    PATH: str
+
+    def encode(self, d: Definition, wire: str, input: Any) -> Any: ...
+    def decode(self, d: Definition, tier: Tier, body: Any, *, unavailable_sentinel: bool = False) -> Decoded: ...
+
+
+def _codec(tier: Tier) -> _Codec:
+    return systemone if tier.camp == "systemone" else decisions
+
+
+def encode_request(d: Definition, tier: Tier, input: Any) -> WireRequest:
+    desc = descriptor_for(tier)
+    wire = model_spec_for(desc, tier).wire
+    codec = _codec(tier)
+    return WireRequest(tier.id, tier.camp, codec.PATH, desc.url.replace("{model}", wire), codec.encode(d, wire, input))
+
+
+def request_id_of(tier: Tier, reply: WireReply) -> str | None:
+    name = descriptor_for(tier).request_id_header
+    return None if name is None else header(reply.headers, name)
+
+
+def _with_request_id(e: UrimError, rid: str | None) -> UrimError:
+    if rid is None or e.request_id is not None:
+        return e
+    return UrimError(
+        e.type,
+        e.message,
+        tier=e.tier,
+        status=e.status,
+        request_id=rid,
+        retry_after_ms=e.retry_after_ms,
+        issues=e.issues,
+        cause=e.__cause__,
+    )
+
+
+def decode_reply(d: Definition, tier: Tier, reply: WireReply) -> Decoded:
+    desc = descriptor_for(tier)
+    rid = request_id_of(tier, reply)
+    failure = classify_vendor_reply(desc, reply)
+    if failure.type is not None:
+        return DecodedFail(
+            UrimError(
+                failure.type,
+                f"HTTP {reply.status} from {tier.id}",
+                tier=tier.id,
+                status=reply.status,
+                request_id=rid,
+                retry_after_ms=failure.retry_after_ms,
+            )
+        )
+    decoded = _codec(tier).decode(d, tier, reply.body, unavailable_sentinel=desc.confidence_unavailable_sentinel)
+    if isinstance(decoded, DecodedFail):
+        return DecodedFail(_with_request_id(decoded.error, rid))
+    # Only tiers with an explicit descriptor model row are checked (accepted 2026-10-28).
+    spec = explicit_model_spec(desc, tier)
+    if spec is not None and decoded.model is not None and decoded.model not in spec.answered_as:
+        return DecodedFail(
+            UrimError(
+                "lock_violation", f'{tier.id} was answered by model "{decoded.model}"', tier=tier.id, request_id=rid
+            )
+        )
+    return decoded

urim/camps/decisions.py

@@ -0,0 +1,89 @@
+"""C: the OpenAI decisions body. Sources as in urim-ts src/camps/decisions.ts (checked 2026-10-28 EDT).
+TODO(vendor-fact): OpenAI's confidence formula is undocumented; native choice/score confidence passes through."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..errors import UrimError
+from ..types import Definition, Question, Tier
+from .shared import (
+    Decoded,
+    DecodedFail,
+    RawAnswer,
+    argmax,
+    binary_confidence,
+    binary_label,
+    nonconformant,
+    num,
+    to_answers,
+    vendor_confidence,
+)
+
+PATH = "/v1/decisions"
+_NATIVE_TYPE = {"noul": "predicate", "choice": "choice", "score": "score"}
+
+
+def _encode_question(name: str, q: Question) -> dict[str, Any]:
+    base: dict[str, Any] = {"type": _NATIVE_TYPE[q.type], "name": name, "instructions": q.prompt}
+    if q.type == "choice":
+        return {**base, "choices": [{"value": v, "description": t} for v, t in q.options.items()]}
+    if q.type == "score":
+        return {**base, "levels": [{"label": v, "description": t} for v, t in q.options.items()]}
+    return base  # predicates carry no yes/no descriptions (O2; accepted 2026-10-28)
+
+
+def encode(d: Definition, wire_model: str, input: Any) -> Any:
+    return {
+        "model": wire_model,
+        # TODO(vendor-fact): exact message item wrapper is medium confidence.
+        "input": [{"role": "user", "content": [{"type": "input_json", "data": input}]}],
+        "questions": [_encode_question(n, q) for n, q in d.questions.items()],
+    }
+
+
+def _decode_one(name: str, a: dict[str, Any], sentinel: bool) -> RawAnswer | None:
+    t = a.get("type")
+    if t == "predicate":
+        p = num(a.get("probability"))
+        # OpenAI returns no predicate confidence: Urim derives |2p - 1| and says so (urim_derived).
+        return None if p is None else RawAnswer(name, binary_label(p), binary_confidence(p), p, None, "urim_derived")
+    if t == "choice":  # a boolean choice never equals a string label -> nonconformant later
+        return RawAnswer(
+            name, a.get("choice"), vendor_confidence(a, sentinel), a.get("choice"), a.get("confidence"), "native"
+        )
+    if t == "score":
+        probs = (
+            [p for p in a.get("probabilities", []) if isinstance(p, dict)]
+            if isinstance(a.get("probabilities"), list)
+            else []
+        )
+        top = probs[argmax([-1.0 if (x := num(p.get("probability"))) is None else x for p in probs])] if probs else None
+        return RawAnswer(
+            name,
+            None if top is None else top.get("label"),
+            vendor_confidence(a, sentinel),
+            a.get("score"),
+            a.get("confidence"),
+            "native",
+        )
+    return None
+
+
+def decode(d: Definition, tier: Tier, body: Any, *, unavailable_sentinel: bool = False) -> Decoded:
+    if not isinstance(body, dict) or not isinstance(body.get("answers"), list):
+        return nonconformant(tier, "response has no answers array")
+    names = list(d.questions.keys())
+    raws: dict[str, RawAnswer] = {}
+    for i, a in enumerate(body["answers"]):
+        if not isinstance(a, dict):
+            continue
+        name = a["name"] if isinstance(a.get("name"), str) else (names[i] if i < len(names) else None)
+        if name is None or name not in d.questions:
+            continue
+        if a.get("type") == "refusal":
+            return DecodedFail(UrimError("refused", f'{tier.id} refused question "{name}"', tier=tier.id))
+        raw = _decode_one(name, a, unavailable_sentinel)
+        if raw is not None:
+            raws[name] = raw
+    return to_answers(d, tier, raws, body)

urim/camps/shared.py

@@ -0,0 +1,124 @@
+"""C: helpers shared by the camp codecs: label-space checks, the binary confidence rule, usage."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from ..errors import UrimError
+from ..types import Answer, ConfidenceSource, Definition, Question, Tier
+
+
+@dataclass(frozen=True)
+class RawAnswer:
+    """A decoded native answer, already reduced to a candidate label."""
+
+    name: str
+    label: Any
+    confidence: float | None
+    native_value: Any
+    native_confidence: Any
+    confidence_source: ConfidenceSource
+
+
+@dataclass(frozen=True)
+class TokenUsage:
+    input_tokens: int | float | None
+    output_tokens: int | float | None
+
+
+@dataclass(frozen=True)
+class DecodedOk:
+    answers: Mapping[str, Answer]
+    usage: TokenUsage | None
+    model: str | None
+    ok: Literal[True] = True
+
+
+@dataclass(frozen=True)
+class DecodedFail:
+    error: UrimError
+    ok: Literal[False] = False
+
+
+Decoded = DecodedOk | DecodedFail
+
+
+def num(v: Any) -> float | int | None:
+    if isinstance(v, bool) or not isinstance(v, (int, float)):
+        return None
+    return v if math.isfinite(v) else None
+
+
+def vendor_confidence(a: Mapping[str, Any], unavailable_sentinel: bool) -> float | int | None:
+    """A vendor confidence. With the sentinel flag, 0 plus present-but-empty probabilities is "unavailable" -> None."""
+    c = num(a.get("confidence"))
+    if not unavailable_sentinel or c != 0:
+        return c
+    p = a.get("probabilities")
+    empty = isinstance(p, (list, dict)) and len(p) == 0
+    return None if empty else c
+
+
+def _unit(v: Any) -> float | int | None:
+    n = num(v)
+    return n if n is not None and 0 <= n <= 1 else None
+
+
+def nonconformant(tier: Tier, message: str) -> DecodedFail:
+    return DecodedFail(UrimError("nonconformant_response", message, tier=tier.id))
+
+
+def binary_label(p: float) -> str:
+    """P(yes) -> label. A tie (0.5) reads "yes"; its confidence is 0, so no threshold can pass on it."""
+    return "yes" if p >= 0.5 else "no"
+
+
+def binary_confidence(p: float) -> float:
+    """The normalized confidence (p_max - 1/n)/(1 - 1/n), n = 2, i.e. |2p - 1|, computed client-side.
+    Rounded to 12 dp exactly as urim-ts does (Math.round(x * 1e12) / 1e12; half rounds up)."""
+    x = ((max(p, 1 - p) - 0.5) / 0.5) * 1e12
+    return math.floor(x + 0.5) / 1e12
+
+
+def argmax(ps: list[float]) -> int:
+    """Index of the largest value; first wins on a tie."""
+    best = 0
+    for i, p in enumerate(ps):
+        if p > ps[best]:
+            best = i
+    return best
+
+
+def usage_of(body: Mapping[str, Any]) -> TokenUsage | None:
+    u = body.get("usage")
+    return TokenUsage(num(u.get("input_tokens")), num(u.get("output_tokens"))) if isinstance(u, dict) else None
+
+
+def to_answers(d: Definition, tier: Tier, raws: Mapping[str, RawAnswer], body: Mapping[str, Any]) -> Decoded:
+    """Checks every question is answered inside its label space; never alters native values."""
+    answers: dict[str, Answer] = {}
+    for name, q in d.questions.items():
+        raw = raws.get(name)
+        if raw is None:
+            return nonconformant(tier, f'question "{name}" not answered')
+        if not isinstance(raw.label, str) or raw.label not in q.options:
+            return nonconformant(tier, f'question "{name}" answered outside its labels')
+        conf = _unit(raw.confidence)
+        answers[name] = Answer(
+            raw.label,
+            conf,
+            None if conf is None else raw.confidence_source,
+            confidence_formula=None
+            if conf is None
+            else ("systemone_normalized" if raw.confidence_source == "urim_derived" else "vendor_unspecified"),
+            native={"name": raw.name, "value": raw.native_value, "confidence": raw.native_confidence},
+        )
+    model = body.get("model")
+    return DecodedOk(answers, usage_of(body), model if isinstance(model, str) else None)
+
+
+def score_labels(q: Question) -> list[str]:
+    return list(q.options.keys())

urim/camps/systemone.py

@@ -0,0 +1,71 @@
+"""C: the systemone body (spoken by every descriptor whose camp is systemone).
+Body shape per the systemone descriptors' vendor sources (checked 2026-10-28 EDT)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..types import Definition, Question, Tier
+from .shared import (
+    Decoded,
+    RawAnswer,
+    argmax,
+    binary_confidence,
+    binary_label,
+    nonconformant,
+    num,
+    score_labels,
+    to_answers,
+    vendor_confidence,
+)
+
+PATH = "/v1/systemone"
+
+
+def _criteria(q: Question) -> Any:
+    if q.type == "choice":
+        return dict(q.options)
+    if q.type == "score":
+        return list(q.options.values())  # ordered; index = level from 0
+    return {"true": q.options["yes"], "false": q.options["no"]}
+
+
+def encode(d: Definition, wire_model: str, state: Any) -> Any:
+    return {
+        "model": wire_model,
+        "state": state,
+        "questions": {
+            name: {"type": q.type, "instructions": q.prompt, "criteria": _criteria(q)}
+            for name, q in d.questions.items()
+        },
+    }
+
+
+def _decode_one(name: str, q: Question, a: Any, sentinel: bool) -> RawAnswer | None:
+    if not isinstance(a, dict):
+        return None
+    if q.type == "noul":
+        p = num(a.get("noul"))
+        return None if p is None else RawAnswer(name, binary_label(p), binary_confidence(p), p, None, "urim_derived")
+    if q.type == "choice":
+        return RawAnswer(
+            name, a.get("choice"), vendor_confidence(a, sentinel), a.get("choice"), a.get("confidence"), "native"
+        )
+    labels = score_labels(q)
+    given = a.get("probabilities")
+    probs: dict[str, Any] = given if isinstance(given, dict) else {}
+    ps = [num(probs.get(str(i))) for i in range(len(labels))]
+    vals = [-1.0 if p is None else p for p in ps]
+    label = None if all(v < 0 for v in vals) else labels[argmax(vals)]
+    return RawAnswer(name, label, vendor_confidence(a, sentinel), a.get("score"), a.get("confidence"), "native")
+
+
+def decode(d: Definition, tier: Tier, body: Any, *, unavailable_sentinel: bool = False) -> Decoded:
+    if not isinstance(body, dict) or not isinstance(body.get("answers"), dict):
+        return nonconformant(tier, "response has no answers map")
+    raws = {}
+    for name, q in d.questions.items():
+        raw = _decode_one(name, q, body["answers"].get(name), unavailable_sentinel)
+        if raw is not None:
+            raws[name] = raw
+    return to_answers(d, tier, raws, body)

urim/canonical.py

@@ -0,0 +1,18 @@
+"""C: canonical JSON (sorted keys, no whitespace) + sha256. Byte-identical to urim-ts src/canonical.ts."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+
+from .jsonfmt import canonical, js_units
+
+
+def canonicalize(value: Any) -> str:
+    return canonical(value)
+
+
+def sha256(text: str) -> str:
+    # Node's update(text, "utf8") writes a lone surrogate as U+FFFD; canonical output escapes them anyway.
+    clean = "".join("\ufffd" if 0xD800 <= ord(c) <= 0xDFFF else c for c in js_units(text))
+    return "sha256:" + hashlib.sha256(clean.encode("utf-8")).hexdigest()