functualize-decision-jev 0.1.0__tar.gz

functualize_decision_jev-0.1.0/.gitignore

@@ -0,0 +1,150 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Agents
+.spec/archive/
+.spec/scrutiny-reports/
+.spec/verification-reports/
+.spec/proposals/
+.spec/plans/
+.spec/.agentic-coding
+.spec/STATE.md
+# A one-hour spec-gate bypass token, not a repository artifact. The *ledger* of
+# uses (.spec/exemptions.log) is committed and is the real mitigation; the token
+# itself is per-session, and committing it would hand everyone else a live
+# bypass. Ignored because the documented escape hatch otherwise sits in
+# `git status` waiting to be added by accident.
+.spec/EXEMPT
+.opencode/
+
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+.hypothesis/
+snapshot_report.html
+_*_result*.txt
+_debug.txt
+_tui_debug.txt
+_tui_eval_debug.txt
+
+# IDE
+.idea/
+*.swp
+*.swo
+*~
+*.code-workspace
+
+# Coding-agent tooling state (guards — these dirs are not part of the repo)
+.kiro/
+.moai/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# Agent scratch space (test output, temp scripts)
+tmp/
+
+# Local-only files (not for the repo)
+*.local.md
+*.local.*
+
+# Personal notes
+HUMAN_NOTE.md
+
+# Distribution
+dist/
+
+# Documentation site build output
+site/
+
+# uv
+.python-version
+.functualize/cache.json
+.functualize_cache.json
+.todos/
+.sidecar/
+.sidecar-agent
+.sidecar-task
+.sidecar-pr
+.sidecar-start.sh
+.sidecar-base
+.td-root
+.functualize/
+# ...except the committed example plugin, which the blanket rule above swallowed.
+# Git will not descend into an excluded directory, so every level must be un-excluded
+# in turn, and each level re-ignores its own contents so that only the plugin sources
+# become trackable — never the cache, state or lock files a run drops beside them.
+!examples/plugins/file_based_plugin/.functualize/
+examples/plugins/file_based_plugin/.functualize/*
+!examples/plugins/file_based_plugin/.functualize/plugins/
+examples/plugins/file_based_plugin/.functualize/plugins/*
+!examples/plugins/file_based_plugin/.functualize/plugins/*.py
+# Same chain for the monorepo plugin-sharing example. Its whole subject is a
+# plugin living at a shared root, so the one file that must be committed is
+# the one the blanket rule above hides.
+!examples/project/shared_plugins/.functualize/
+examples/project/shared_plugins/.functualize/*
+!examples/project/shared_plugins/.functualize/plugins/
+examples/project/shared_plugins/.functualize/plugins/*
+!examples/project/shared_plugins/.functualize/plugins/*.py
+.import_linter_cache/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# OmO / OpenCode agent run-continuation scratch state
+.omo/
+.mcp.json
+
+# Internal pre-release audit reports (contain session IDs / local infra notes)
+.release/
+.worktrees/
+.claude/settings.local.json
+
+# Agent index directories. Which parts are tracked is decided by ONE property:
+# whether the stored paths are portable.
+#
+#   graphify  graph.json holds only repo-relative paths, so it travels into every
+#             worktree and every ephemeral cloud checkout for free. Tracked.
+#             Its cache/, manifest.json and .graphify_root are machine-local
+#             (mtimes, absolute paths), so the rule below is a whitelist: ignore
+#             everything, then un-ignore the two portable artifacts.
+#   zvec-grep index entries are keyed by ABSOLUTE path — copying one and rewriting
+#             its manifest yields 0% coverage and a full re-embed. Never tracked;
+#             each workspace builds its own (~21s scoped).
+#   serena    cache/ pickles hold absolute file:// URIs, so those and
+#             project.local.yml are machine-local; serena's own
+#             .serena/.gitignore already excludes cache/ and project.local.yml.
+#             memories/ is plain text and portable, but not tracked anyway: it
+#             duplicated contract docs that already have a committed home
+#             (`.claude/rules/spec-workflow.md`, `.spec/ARCHITECTURE.md`,
+#             AGENTS.md) and went stale the moment those changed underneath
+#             it. project.yml stays tracked and portable.
+graphify-out/*
+!graphify-out/graph.json
+!graphify-out/GRAPH_REPORT.md
+.zvec-grep/
+.serena/cache/
+.serena/project.local.yml
+.serena/memories/

functualize_decision_jev-0.1.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.5
+Name: functualize-decision-jev
+Version: 0.1.0
+Summary: Experimental decision-provider plugin for functualize — proposes a choice through the Jev model service
+Author-email: Mohammad Hakim Adiprasetya <viltohmyst@gmail.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: functualize<1.0.0,>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# functualize-decision-jev
+
+> **Status: Tier 3 — experimental.** The Phase 1 decision-provider adapter;
+> requires `OPENCODE_API_KEY`. It proposes a candidate answer to a `choice`
+> question through the Jev model service, and the gate that asked applies its
+> own declared thresholds — the provider never decides whether its proposal is
+> acted on. The package is an empty scaffold today: the provider, its wire
+> mapping and the plugin that registers the `decision` gate strategy arrive in
+> later steps of the same change.

functualize_decision_jev-0.1.0/README.md

@@ -0,0 +1,9 @@
+# functualize-decision-jev
+
+> **Status: Tier 3 — experimental.** The Phase 1 decision-provider adapter;
+> requires `OPENCODE_API_KEY`. It proposes a candidate answer to a `choice`
+> question through the Jev model service, and the gate that asked applies its
+> own declared thresholds — the provider never decides whether its proposal is
+> acted on. The package is an empty scaffold today: the provider, its wire
+> mapping and the plugin that registers the `decision` gate strategy arrive in
+> later steps of the same change.

functualize_decision_jev-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "functualize-decision-jev"
+version = "0.1.0"
+description = "Experimental decision-provider plugin for functualize — proposes a choice through the Jev model service"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [
+    { name = "Mohammad Hakim Adiprasetya", email = "viltohmyst@gmail.com" }
+]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "functualize>=0.1.0,<1.0.0",
+]
+
+[project.entry-points."functualize.plugins"]
+jev = "functualize_decision_jev:JevPlugin"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv.sources]
+functualize = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/functualize_decision_jev"]

functualize_decision_jev-0.1.0/src/functualize_decision_jev/__init__.py

@@ -0,0 +1,10 @@
+"""Functualize decision provider backed by the Jev model service.
+
+Experimental. ``JevPlugin`` is loaded through the ``functualize.plugins`` entry
+point and registers the ``decision`` gate strategy, answered by
+``JevDecisionProvider``; the provider needs ``OPENCODE_API_KEY`` at call time.
+"""
+
+from functualize_decision_jev._plugin import JevPlugin
+
+__all__ = ["JevPlugin"]

functualize_decision_jev-0.1.0/src/functualize_decision_jev/_plugin.py

@@ -0,0 +1,91 @@
+"""The Jev decision plugin — registers the ``decision`` gate strategy.
+
+Registered via entry point ``functualize.plugins`` with name ``"jev"``. At
+``APP_READY`` it resolves ``JevConfig`` from the ``[jev]`` config section and
+registers ``DecisionGateResolver(JevDecisionProvider(config))`` as the
+``decision`` strategy, so a ``Gate(decide=...)`` in any workflow of the app can
+be answered by a proposal that clears the workflow's own thresholds.
+
+It registers nothing else: no preset, no DI provider, and no credential. The
+key is read by the provider at call time, from the environment, never here —
+so an app with the plugin installed and no key still boots, and a decision gate
+records ``not_configured`` and falls through to a person.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from functualize.plugin import DecisionGateResolver
+
+if TYPE_CHECKING:
+    from functualize.plugin import PluginHost
+    from functualize_decision_jev._provider import JevConfig
+
+__all__ = ["JevPlugin"]
+
+logger = logging.getLogger(__name__)
+
+#: The config section `JevConfig` is resolved from.
+_SECTION = "jev"
+
+
+class JevPlugin:
+    """Plugin that answers ``decision`` gates with the Jev provider."""
+
+    name: str = "jev"
+    version: str = "0.1.0"
+    description: str = (
+        "Experimental decision provider — proposes a gate's choice through Jev"
+    )
+
+    def __call__(self, app: PluginHost) -> None:
+        """Defer registration to ``APP_READY``.
+
+        Plugins load before the config resolution chain is built, so resolving
+        ``[jev]`` here would always fall back to the defaults and a configured
+        section would be ignored without a word. Walks start after boot, so a
+        strategy registered at ``APP_READY`` is in place before any gate is
+        reached.
+        """
+        app.hooks.on_ready(self._on_app_ready)
+
+    def _on_app_ready(self, app: PluginHost) -> None:
+        # Imported here, not at module level: the provider's transport pulls in
+        # `urllib.request` and `http.client`, which the loader would otherwise
+        # charge to plugin loading on every boot of every app that has this
+        # package installed.
+        from functualize_decision_jev._provider import JevDecisionProvider
+
+        provider = JevDecisionProvider(self._resolve_config(app))
+        app.gates.register_gate_strategy("decision", DecisionGateResolver(provider))
+
+    def _resolve_config(self, app: PluginHost) -> JevConfig:
+        """``[jev]`` as a ``JevConfig``, or the defaults when it cannot be used.
+
+        An absent section resolves to the defaults without an error. A section
+        that is present but unusable — an unknown key, a timeout that is not a
+        number — falls back to the defaults as the sibling plugins do, but says
+        so at warning level: a misconfiguration that silently changed nothing
+        would be indistinguishable from one that worked.
+        """
+        from functualize_decision_jev._provider import JevConfig
+
+        try:
+            resolved = app.configuration.resolve_model(_SECTION, JevConfig)
+            if not isinstance(resolved, JevConfig):
+                raise TypeError(f"resolved {type(resolved).__name__}, not JevConfig")
+            return JevConfig(
+                model=str(resolved.model),
+                endpoint=str(resolved.endpoint),
+                timeout_seconds=float(resolved.timeout_seconds),
+            )
+        except Exception as exc:
+            logger.warning(
+                "JevPlugin: the [%s] config section could not be used (%s); "
+                "using the defaults",
+                _SECTION,
+                exc,
+            )
+            return JevConfig()

functualize_decision_jev-0.1.0/src/functualize_decision_jev/_provider.py

@@ -0,0 +1,233 @@
+"""The Jev decision provider, and the transport port it sends through.
+
+``JevDecisionProvider.choose`` is one round trip: read the credential, build
+the body (``_wire``), send it once through a ``JevTransport``, and map what came
+back (``_wire`` again). It never waits and never tries again — a rate limit or
+an outage is reported as a ``DecisionUnavailableError`` and the caller decides
+what happens next.
+
+The transport is a port so that everything above the socket is tested with a
+fake that records what it was sent; ``UrllibTransport`` is the production
+implementation, standard library only.
+
+**The credential is read at call time**, through a zero-argument supplier that
+defaults to the ``OPENCODE_API_KEY`` environment variable — never at
+construction, at import, or from a config file — so nothing this module
+constructs holds it, and no ``repr`` can show it.
+"""
+
+from __future__ import annotations
+
+import http.client
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from email.message import Message
+from importlib.metadata import version
+from typing import Protocol, runtime_checkable
+
+from functualize.plugin import (
+    ChoiceRequest,
+    DecisionFailure,
+    DecisionResult,
+    DecisionUnavailableError,
+)
+from functualize_decision_jev import _wire
+
+__all__ = [
+    "JevConfig",
+    "JevDecisionProvider",
+    "JevTransport",
+    "UrllibTransport",
+    "WireResponse",
+]
+
+_PROVIDER = "jev"
+_DISTRIBUTION = "functualize-decision-jev"
+_CREDENTIAL_VARIABLE = "OPENCODE_API_KEY"
+
+
+@runtime_checkable
+class JevTransport(Protocol):
+    """Sends one request and returns the response, whatever its status.
+
+    Raises only for a transport failure — no response at all — and then only
+    ``DecisionUnavailableError`` with ``kind=UNREACHABLE``.
+    """
+
+    def post(
+        self, url: str, body: bytes, headers: Mapping[str, str], timeout: float
+    ) -> WireResponse: ...
+
+
+@dataclass(frozen=True)
+class WireResponse:
+    """One HTTP response, decoded."""
+
+    status: int
+    body: str
+    headers: Mapping[str, str]  # keys lower-cased
+
+
+class UrllibTransport:
+    """The production ``JevTransport``: one ``POST`` through ``urllib.request``.
+
+    A ``4xx``/``5xx`` is a response, not a failure, so ``HTTPError`` is read
+    rather than raised: what it means is ``_wire.failure_for``'s decision.
+    """
+
+    def post(
+        self, url: str, body: bytes, headers: Mapping[str, str], timeout: float
+    ) -> WireResponse:
+        request = urllib.request.Request(
+            url, data=body, headers=dict(headers), method="POST"
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                return _response(response.status, response.read(), response.headers)
+        except urllib.error.HTTPError as error:
+            return _response(error.code, error.read(), error.headers)
+        # URLError and TimeoutError are both OSError; HTTPException is the
+        # connection dropping mid-response (IncompleteRead, BadStatusLine),
+        # which is equally "no usable response" and would otherwise escape the
+        # port as something other than a DecisionUnavailableError.
+        except (OSError, http.client.HTTPException) as error:
+            raise DecisionUnavailableError(
+                kind=DecisionFailure.UNREACHABLE,
+                provider=_PROVIDER,
+                status=None,
+                detail=str(error),
+            ) from error
+
+
+@dataclass(frozen=True)
+class JevConfig:
+    """The provider's settings, resolved from config section ``[jev]``."""
+
+    model: str = "jev-1.13-free"
+    endpoint: str = "https://opencode.ai/zen/v1/systemone"
+    timeout_seconds: float = 30.0
+
+
+class JevDecisionProvider:
+    """A ``DecisionProvider`` that proposes a choice through Jev."""
+
+    name: str = _PROVIDER
+
+    def __init__(
+        self,
+        config: JevConfig = JevConfig(),  # noqa: B008 — frozen, so one shared default is safe
+        *,
+        transport: JevTransport | None = None,
+        credential: Callable[[], str | None] | None = None,
+    ) -> None:
+        self._config = config
+        self._transport = transport if transport is not None else UrllibTransport()
+        # A supplier, not a value: it is called inside `choose`, so the key is
+        # read at call time and never held by this object.
+        self._credential = credential if credential is not None else _from_environment
+        self._user_agent = f"{_DISTRIBUTION}/{version(_DISTRIBUTION)}"
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(config={self._config!r})"
+
+    def choose(self, request: ChoiceRequest) -> DecisionResult[str]:
+        key = self._credential()
+        if not key:
+            raise DecisionUnavailableError(
+                kind=DecisionFailure.NOT_CONFIGURED,
+                provider=_PROVIDER,
+                detail=f"{_CREDENTIAL_VARIABLE} is not set",
+            )
+        config = self._config
+        model = request.model or config.model
+        body = json.dumps(_wire.build_request(request, model=config.model)).encode()
+        headers = {
+            "Authorization": f"Bearer {key}",
+            "Content-Type": "application/json",
+            "User-Agent": self._user_agent,
+        }
+
+        failure: DecisionUnavailableError | None = None
+        try:
+            started = time.monotonic()
+            response = _without(
+                key,
+                self._transport.post(
+                    config.endpoint, body, headers, config.timeout_seconds
+                ),
+            )
+            elapsed = time.monotonic() - started
+
+            if response.status != 200:
+                raise _wire.failure_for(
+                    response.status, response.body, response.headers
+                )
+            try:
+                payload = json.loads(response.body)
+            except ValueError as error:
+                raise DecisionUnavailableError(
+                    kind=DecisionFailure.MALFORMED,
+                    provider=_PROVIDER,
+                    status=200,
+                    detail=f"body is not JSON: {error}",
+                ) from error
+            return _wire.parse_choice(
+                payload, request, requested_model=model, latency_seconds=elapsed
+            )
+        except DecisionUnavailableError as error:
+            # Every failure's text is recorded as a gate rung's detail, so the
+            # key must not survive into it by any route — an echoing body, a
+            # transport message, a parsed value. Rebuilt outside this block so
+            # the original is not kept as the new error's context.
+            failure = _scrubbed(error, key) if key in error.detail else error
+        raise failure
+
+
+_REDACTED = "[redacted]"
+
+
+def _without(key: str, response: WireResponse) -> WireResponse:
+    """The response with the credential removed from its body and headers.
+
+    A service may echo what it was sent — a refusal quoting the rejected
+    ``Authorization`` header is the common case — and everything built from a
+    response can end up in recorded run state.
+    """
+    return WireResponse(
+        status=response.status,
+        body=response.body.replace(key, _REDACTED),
+        headers={
+            name: value.replace(key, _REDACTED)
+            for name, value in response.headers.items()
+        },
+    )
+
+
+def _scrubbed(error: DecisionUnavailableError, key: str) -> DecisionUnavailableError:
+    """``error`` rebuilt with the credential removed from its detail."""
+    return DecisionUnavailableError(
+        kind=error.kind,
+        provider=error.provider,
+        detail=error.detail.replace(key, _REDACTED),
+        status=error.status,
+        retry_after=error.retry_after,
+    )
+
+
+def _from_environment() -> str | None:
+    return os.environ.get(_CREDENTIAL_VARIABLE)
+
+
+def _response(
+    status: int, raw: bytes, headers: Message | Mapping[str, str] | None
+) -> WireResponse:
+    return WireResponse(
+        status=status,
+        body=raw.decode("utf-8", errors="replace"),
+        headers={name.lower(): value for name, value in (headers or {}).items()},
+    )

functualize_decision_jev-0.1.0/src/functualize_decision_jev/_wire.py

@@ -0,0 +1,216 @@
+"""The Jev wire mapping — pure functions between the port's values and JSON.
+
+Three functions and no I/O: ``build_request`` turns a ``ChoiceRequest`` into the
+request body, ``parse_choice`` turns a ``200`` body into a ``DecisionResult``,
+and ``failure_for`` turns any other status into a ``DecisionUnavailableError``.
+Sending the body, the headers and the credential are the provider's business,
+not this module's, so every rule here can be tested against measured bodies
+without a network.
+
+The service's response shape is a discriminated union keyed by ``type`` (a
+``choice`` answer carries ``choice``, ``confidence`` and ``probabilities``; a
+``noul`` answer carries none of them), so a ``200`` is never trusted to be the
+shape that was asked for: every field is checked, and any mismatch is
+``MALFORMED`` rather than a ``KeyError`` or a ``TypeError`` escaping into the
+gate that asked.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from typing import Any
+
+from functualize.plugin import (
+    ChoiceRequest,
+    DecisionFailure,
+    DecisionProvenance,
+    DecisionResult,
+    DecisionUnavailableError,
+)
+
+__all__ = ["QUESTION_ID", "build_request", "failure_for", "parse_choice"]
+
+#: The one question id this adapter sends. ``answers`` is keyed by it.
+QUESTION_ID = "decision"
+
+_PROVIDER = "jev"
+#: The longest body a failure quotes. The error clips again; this keeps the
+#: rule visible where the body is read.
+_DETAIL_LIMIT = 300
+
+
+class _MalformedError(Exception):
+    """A shape rule a ``200`` body broke; carries the rule, for ``detail``."""
+
+
+def build_request(request: ChoiceRequest, *, model: str) -> dict[str, Any]:
+    """The request body for one ``choice`` question.
+
+    ``model`` is the provider's configured default; a model named on the
+    request wins over it.
+    """
+    return {
+        "model": request.model if request.model is not None else model,
+        "state": request.state,
+        "questions": {
+            QUESTION_ID: {
+                "type": "choice",
+                "instructions": request.instructions,
+                "criteria": dict(request.options),
+            }
+        },
+    }
+
+
+def parse_choice(
+    payload: Mapping[str, Any],
+    request: ChoiceRequest,
+    *,
+    requested_model: str,
+    latency_seconds: float,
+) -> DecisionResult[str]:
+    """A ``200`` body as a ``DecisionResult``, or ``MALFORMED``.
+
+    Raises nothing but ``DecisionUnavailableError``: a body that breaks any
+    shape rule, or carries a probability outside ``[0, 1]``, is reported with
+    ``status=200`` and the rule it broke as ``detail``.
+    """
+    try:
+        return _parse_choice(
+            payload,
+            request,
+            requested_model=requested_model,
+            latency_seconds=latency_seconds,
+        )
+    except _MalformedError as broken:
+        detail = str(broken)
+    except ValueError as out_of_range:
+        detail = f"answer is out of range: {out_of_range}"
+    raise DecisionUnavailableError(
+        kind=DecisionFailure.MALFORMED,
+        provider=_PROVIDER,
+        status=200,
+        detail=detail,
+    )
+
+
+def failure_for(
+    status: int, body: str, headers: Mapping[str, str]
+) -> DecisionUnavailableError:
+    """The failure a non-``200`` response stands for.
+
+    ``429`` is ``RATE_LIMITED`` and carries the service's ``Retry-After`` as
+    sent; every other status is ``REFUSED``. The body is quoted, clipped, as
+    the detail — refusal bodies come in several JSON shapes and one plain-text
+    one, and a person reading a blocked gate needs whichever it was.
+    """
+    detail = body[:_DETAIL_LIMIT]
+    if status == 429:
+        return DecisionUnavailableError(
+            kind=DecisionFailure.RATE_LIMITED,
+            provider=_PROVIDER,
+            status=status,
+            retry_after=_retry_after(headers),
+            detail=detail,
+        )
+    return DecisionUnavailableError(
+        kind=DecisionFailure.REFUSED,
+        provider=_PROVIDER,
+        status=status,
+        detail=detail,
+    )
+
+
+def _parse_choice(
+    payload: Mapping[str, Any],
+    request: ChoiceRequest,
+    *,
+    requested_model: str,
+    latency_seconds: float,
+) -> DecisionResult[str]:
+    if not isinstance(payload, Mapping):
+        raise _MalformedError(f"body is {type(payload).__name__}, expected an object")
+    answered_by = payload.get("model")
+    if not isinstance(answered_by, str):
+        raise _MalformedError("body has no string 'model'")
+    answers = _mapping(payload.get("answers"), "'answers'")
+    answer = _mapping(answers.get(QUESTION_ID), f"'answers.{QUESTION_ID}'")
+
+    kind = answer.get("type")
+    if kind != "choice":
+        raise _MalformedError(f"answer type is {kind!r}, expected 'choice'")
+    value = answer.get("choice")
+    if not isinstance(value, str) or value not in request.options:
+        raise _MalformedError(
+            f"answer choice {value!r} is not one of the options "
+            f"{sorted(request.options)}"
+        )
+
+    raw_distribution = _mapping(answer.get("probabilities"), "'probabilities'")
+    distribution: dict[str, float] = {}
+    for option, probability in raw_distribution.items():
+        if not isinstance(option, str):
+            raise _MalformedError(f"'probabilities' key {option!r} is not a string")
+        distribution[option] = _number(probability, f"'probabilities.{option}'")
+    raw_confidence = answer.get("confidence")
+    confidence = (
+        None if raw_confidence is None else _number(raw_confidence, "'confidence'")
+    )
+
+    usage = payload.get("usage")
+    if usage is None:
+        usage = {}
+    usage = _mapping(usage, "'usage'")
+
+    return DecisionResult(
+        value=value,
+        provider=_PROVIDER,
+        model=answered_by,
+        provenance=DecisionProvenance(
+            requested_model=requested_model,
+            latency_seconds=latency_seconds,
+            input_tokens=_tokens(usage, "input_tokens"),
+            output_tokens=_tokens(usage, "output_tokens"),
+        ),
+        distribution=distribution,
+        confidence=confidence,
+    )
+
+
+def _mapping(value: object, name: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise _MalformedError(f"{name} is missing or not an object")
+    return value
+
+
+def _number(value: object, name: str) -> float:
+    # `bool` is an `int` subclass, and `true` is not a probability.
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        raise _MalformedError(f"{name} is {value!r}, expected a number")
+    return float(value)
+
+
+def _tokens(usage: Mapping[str, Any], key: str) -> int | None:
+    count = usage.get(key)
+    if count is None:
+        return None
+    if isinstance(count, bool) or not isinstance(count, int):
+        raise _MalformedError(f"'usage.{key}' is {count!r}, expected an integer")
+    return count
+
+
+def _retry_after(headers: Mapping[str, str]) -> float | None:
+    # Header names are case-insensitive on the wire; the transport may or may
+    # not have normalised them, so this does not rely on it.
+    raw = next(
+        (value for name, value in headers.items() if name.lower() == "retry-after"),
+        None,
+    )
+    if raw is None:
+        return None
+    try:
+        seconds = float(raw)
+    except ValueError:
+        return None
+    return seconds if math.isfinite(seconds) else None