decision-toolkit 0.1.0__py3-none-any.whl

decision_toolkit/__init__.py

@@ -0,0 +1,102 @@
+"""decision-toolkit — local-first toolkit for open-weights decision models.
+
+One ONNX engine, one adapter per model contract, three surfaces (library, CLI,
+REST). Decisions, not text: typed ``choice`` / yes-no (``noul``) / ``score``
+questions with a calibrated probability for every option, on CPU.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .adapters import register_adapter
+from .calibration import brier_score, expected_calibration_error, threshold_sweep
+from .catalog import Capabilities, ModelInfo
+from .decision_model import DecisionModel
+from .errors import (
+    AdapterError,
+    AdapterNotAvailableError,
+    AdapterNotImplementedError,
+    BackendFailureError,
+    DecisionToolkitError,
+    InvalidQuestionError,
+    InvalidRequestError,
+    ModelNotDownloadedError,
+    ModelNotFoundError,
+    MultimodalNotSupportedError,
+    ServerBusyError,
+    TruncationError,
+    UnsupportedCapabilityError,
+    VerificationError,
+)
+from .models import ModelStore
+from .observability import (
+    configure_logging,
+    ensure_request_id,
+    get_request_id,
+    request_context,
+)
+from .results import Answer, Classification, Decision, Usage
+from .schema import (
+    Box,
+    Choice,
+    Noul,
+    Score,
+    State,
+    box,
+    choice,
+    normalize_state,
+    noul,
+    score,
+)
+
+__all__ = [
+    # errors
+    "AdapterError",
+    "AdapterNotAvailableError",
+    "AdapterNotImplementedError",
+    # results
+    "Answer",
+    "BackendFailureError",
+    # schema
+    "Box",
+    # catalog
+    "Capabilities",
+    "Choice",
+    "Classification",
+    "Decision",
+    # core
+    "DecisionModel",
+    "DecisionToolkitError",
+    "InvalidQuestionError",
+    "InvalidRequestError",
+    "ModelInfo",
+    "ModelNotDownloadedError",
+    "ModelNotFoundError",
+    "ModelStore",
+    "MultimodalNotSupportedError",
+    "Noul",
+    "Score",
+    "ServerBusyError",
+    "State",
+    "TruncationError",
+    "UnsupportedCapabilityError",
+    "Usage",
+    "VerificationError",
+    "__version__",
+    "box",
+    # calibration
+    "brier_score",
+    "choice",
+    # observability
+    "configure_logging",
+    "ensure_request_id",
+    "expected_calibration_error",
+    "get_request_id",
+    "normalize_state",
+    "noul",
+    "register_adapter",
+    "request_context",
+    "score",
+    "threshold_sweep",
+]

decision_toolkit/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m decision_toolkit`` is the same entry point as the ``dtk`` script."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

decision_toolkit/adapters/__init__.py

@@ -0,0 +1,165 @@
+"""`decision_toolkit.adapters` — the adapter registry.
+
+An adapter is written **only** when a real `.onnx` export demands it, and it is
+named after the model contract it implements (not after a brand or a runtime).
+Adding a model with an existing contract means adding a catalog variant, not an
+adapter.
+
+Third-party adapters can be registered in-process with
+:func:`register_adapter` or discovered through the ``decision_toolkit.adapters``
+entry-point group.  A custom adapter may declare ``required_roles`` (an
+iterable of file roles) so the core can validate a local/custom model before
+loading it.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..errors import AdapterNotAvailableError, AdapterNotImplementedError
+from .base import Adapter
+from .gliner2 import Gliner2Adapter
+from .gliner2_decide import Gliner2DecideAdapter
+from .julia import JuliaAdapter
+from .laya import LayaAdapter
+from .opendecider import OpendeciderAdapter
+
+logger = logging.getLogger(__name__)
+
+ADAPTERS: dict[str, Any] = {
+    "gliner2": Gliner2Adapter,
+    "gliner2-decide": Gliner2DecideAdapter,
+    "julia": JuliaAdapter,
+    "laya": LayaAdapter,
+    "opendecider": OpendeciderAdapter,
+}
+
+#: Fixed role requirements for the adapters that ship with the toolkit.
+#: ``gliner2`` has an alternative layout (one fused ``model`` or split
+#: ``encoder`` + ``classifier``), handled separately below.
+_REQUIRED_ROLES: dict[str, frozenset[str]] = {
+    "gliner2-decide": frozenset({"model", "tokenizer"}),
+    "julia": frozenset({"model", "tokenizer"}),
+    "laya": frozenset({"encoder", "head", "tokenizer", "config"}),
+    "opendecider": frozenset({"model", "tokenizer", "config"}),
+}
+
+_ENTRY_POINTS_LOADED = False
+
+
+def register_adapter(name: str, factory: Any, *, replace: bool = False) -> None:
+    """Register an adapter factory under ``name``.
+
+    ``factory`` is called with the adapter options as keyword arguments and must
+    return an object implementing :class:`~decision_toolkit.adapters.base.Adapter`.
+    """
+    if not isinstance(name, str) or not name.strip():
+        raise ValueError("adapter name must be a non-empty string")
+    if not callable(factory):
+        raise TypeError(f"adapter factory for {name!r} must be callable")
+    if name in ADAPTERS and not replace:
+        raise AdapterNotAvailableError(
+            f"adapter {name!r} is already registered; pass replace=True to override it"
+        )
+    ADAPTERS[name] = factory
+    logger.debug("registered adapter %s -> %r", name, factory)
+
+
+def unregister_adapter(name: str) -> None:
+    """Remove a registered adapter (mostly useful in tests)."""
+    ADAPTERS.pop(name, None)
+
+
+def _load_entry_points() -> None:
+    """Discover third-party adapters once, lazily, without breaking imports."""
+    global _ENTRY_POINTS_LOADED
+    if _ENTRY_POINTS_LOADED:
+        return
+    _ENTRY_POINTS_LOADED = True
+    try:
+        from importlib.metadata import entry_points
+    except ImportError:  # pragma: no cover - Python < 3.10
+        return
+    try:
+        discovered = entry_points(group="decision_toolkit.adapters")
+    except Exception:  # noqa: BLE001 - defensive for odd metadata backends  # pragma: no cover
+        return
+    for entry_point in discovered:
+        try:
+            register_adapter(entry_point.name, entry_point.load())
+        except Exception as error:  # noqa: BLE001 - a bad plugin must not break the toolkit
+            logger.warning(
+                "could not load adapter entry point %s: %s", entry_point.name, error
+            )
+
+
+def create_adapter(name: str, **options: Any) -> Adapter:
+    """Instantiate the adapter ``name``.
+
+    Raises :class:`AdapterNotImplementedError` when the adapter is catalogued but
+    not written yet (no real export has demanded it).
+    """
+    _load_entry_points()
+    adapter_type = ADAPTERS.get(name)
+    if adapter_type is None:
+        raise AdapterNotImplementedError(
+            f"adapter {name!r} is not implemented yet; it is written when its real ONNX export "
+            "is inspected (no speculative adapters)"
+        )
+    return adapter_type(**options)
+
+
+def required_roles(name: str, files: Any = None) -> frozenset[str]:
+    """The file roles an adapter needs, for early custom-model validation."""
+    factory = ADAPTERS.get(name)
+    declared = getattr(factory, "required_roles", None)
+    if declared is not None:
+        return frozenset(str(role) for role in declared)
+    return _REQUIRED_ROLES.get(name, frozenset())
+
+
+def validate_adapter_files(name: str, files: Any) -> None:
+    """Validate a role -> path mapping against the adapter's contract.
+
+    Only role presence and basic shape are checked here; the engine later checks
+    that each path exists and opens.  For ``gliner2`` either a fused ``model``
+    file or the split ``encoder`` + ``classifier`` pair is accepted.
+    """
+    if not isinstance(files, dict) or not files:
+        raise AdapterNotAvailableError(
+            f"adapter {name!r} needs a role -> path mapping (files=...)"
+        )
+    for role, path in files.items():
+        if not isinstance(role, str) or not role.strip():
+            raise AdapterNotAvailableError(f"adapter {name!r}: file roles must be non-empty strings")
+        if not isinstance(path, str) or not path.strip():
+            raise AdapterNotAvailableError(f"adapter {name!r}: file path for {role!r} is empty")
+
+    roles = set(files)
+    if name == "gliner2":
+        if "tokenizer" not in roles:
+            raise AdapterNotAvailableError("adapter 'gliner2' needs a 'tokenizer' file")
+        if "model" not in roles and not {"encoder", "classifier"} <= roles:
+            raise AdapterNotAvailableError(
+                "adapter 'gliner2' needs either a fused 'model' file or 'encoder' + "
+                "'classifier' files"
+            )
+        return
+
+    missing = required_roles(name, files) - roles
+    if missing:
+        raise AdapterNotAvailableError(
+            f"adapter {name!r} needs file roles {sorted(missing)}; got {sorted(roles)}"
+        )
+
+
+__all__ = [
+    "ADAPTERS",
+    "Adapter",
+    "create_adapter",
+    "register_adapter",
+    "required_roles",
+    "unregister_adapter",
+    "validate_adapter_files",
+]

decision_toolkit/adapters/base.py

@@ -0,0 +1,134 @@
+"""`decision_toolkit.adapters.base` — the adapter contract and shared helpers.
+
+An adapter is the only place that knows a model's **usage contract**: how to
+build its input from a System One state/questions and how to read its output
+back into probabilities. Several models can share an adapter when they share
+that contract (e.g. the GLiNER2.5 family); a model with a different layout
+gets its own adapter. No adapter is written without a real `.onnx` behind it.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import Mapping, Sequence
+from typing import Any, Protocol, runtime_checkable
+
+from ..engine import OnnxEngine
+from ..errors import AdapterError, InvalidQuestionError
+from ..schema import State
+
+
+@runtime_checkable
+class Adapter(Protocol):
+    """What :class:`~decision_toolkit.decision_model.DecisionModel` needs."""
+
+    name: str
+
+    def system_one(
+        self, engine: OnnxEngine, state: Any, questions: Mapping[str, Mapping[str, Any]]
+    ) -> Mapping[str, Mapping[str, Any]]: ...
+
+
+def state_to_text(state: Any) -> str:
+    """Render a System One ``state`` as text for text-based model families."""
+    if isinstance(state, State):
+        return state.text
+    if isinstance(state, str):
+        return state
+    if isinstance(state, (Mapping, list, tuple)):
+        return json.dumps(state, ensure_ascii=False, sort_keys=True)
+    if state is None:
+        raise AdapterError("state cannot be None")
+    return str(state)
+
+
+def softmax(scores: Sequence[float]) -> list[float]:
+    """Numerically stable softmax over raw scores."""
+    if not scores:
+        raise AdapterError("softmax needs at least one score")
+    top = max(float(score) for score in scores)
+    exponentials = [math.exp(float(score) - top) for score in scores]
+    total = sum(exponentials)
+    return [value / total for value in exponentials]
+
+
+def question_options(question: Mapping[str, Any]) -> tuple[str, list[str], list[str | None]]:
+    """Extract ``(kind, labels, descriptions)`` from a System One question.
+
+    * ``choice``: labels and descriptions come from the question's ``criteria``.
+    * ``noul``: labels are ``["yes", "no"]``; ``criteria.true``/``criteria.false``
+      become their descriptions.
+    * ``score``: labels are the ordered levels; no descriptions.
+    """
+    kind = str(question.get("type"))
+    if kind == "choice":
+        criteria = question.get("criteria")
+        if not isinstance(criteria, Mapping) or not criteria:
+            raise InvalidQuestionError("a choice needs criteria (option labels) for this adapter")
+        labels = [str(label) for label in criteria]
+        descriptions = [None if value is None else str(value) for value in criteria.values()]
+        return kind, labels, descriptions
+    if kind == "noul":
+        criteria = question.get("criteria") or {}
+        if not isinstance(criteria, Mapping):
+            criteria = {}
+        true_description = criteria.get("true")
+        false_description = criteria.get("false")
+        return kind, ["yes", "no"], [
+            None if true_description is None else str(true_description),
+            None if false_description is None else str(false_description),
+        ]
+    if kind == "score":
+        levels = question.get("criteria")
+        if not isinstance(levels, Sequence) or isinstance(levels, (str, bytes)) or len(levels) < 2:
+            raise InvalidQuestionError("a score needs its ordered levels in 'criteria'")
+        labels = [str(level) for level in levels]
+        return kind, labels, [None] * len(labels)
+    raise InvalidQuestionError(f"unsupported question type {kind!r}")
+
+
+def build_choice_answer(labels: Sequence[str], probabilities: Sequence[float]) -> dict[str, Any]:
+    best = max(range(len(labels)), key=lambda index: probabilities[index])
+    return {
+        "type": "choice",
+        "choice": labels[best],
+        "probabilities": {label: float(p) for label, p in zip(labels, probabilities)},
+        "confidence": float(probabilities[best]),
+        "confidence_kind": "probability",
+    }
+
+
+def build_noul_answer(probability_yes: float, probability_no: float) -> dict[str, Any]:
+    return {
+        "type": "noul",
+        "noul": float(probability_yes),
+        "probabilities": {"true": float(probability_yes), "false": float(probability_no)},
+        "confidence": float(max(probability_yes, probability_no)),
+        "confidence_kind": "probability",
+    }
+
+
+def build_score_answer(labels: Sequence[str], probabilities: Sequence[float]) -> dict[str, Any]:
+    expected = sum(index * probability for index, probability in enumerate(probabilities))
+    best = max(range(len(labels)), key=lambda index: probabilities[index])
+    return {
+        "type": "score",
+        "score": float(expected),
+        "level": int(best),
+        "legend": {str(index): label for index, label in enumerate(labels)},
+        "probabilities": {str(index): float(p) for index, p in enumerate(probabilities)},
+        "confidence": float(probabilities[best]),
+        "confidence_kind": "probability",
+    }
+
+
+__all__ = [
+    "Adapter",
+    "build_choice_answer",
+    "build_noul_answer",
+    "build_score_answer",
+    "question_options",
+    "softmax",
+    "state_to_text",
+]

decision_toolkit/adapters/gliner2.py

@@ -0,0 +1,144 @@
+"""`decision_toolkit.adapters.gliner2` — the GLiNER2.5 classifier layout.
+
+Contract implemented by the GLiNER2.5 exports (split encoder + classifier):
+
+    schema = ( [P] <task> [DESCRIPTION] label: … ( [C] label … ) ) [SEP_TEXT] <words>
+    encoder(input_ids, attention_mask) -> hidden states
+    classifier(hidden_state at each [C]) -> one logit per option
+
+Validated against the local mininvox export (15 routing cases, 9/15, 215 ms
+on CPU). This adapter only runs models whose files follow that layout.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from collections.abc import Mapping
+from typing import Any
+
+from ..engine import OnnxEngine, encode
+from ..errors import AdapterError
+from .base import (
+    build_choice_answer,
+    build_noul_answer,
+    build_score_answer,
+    question_options,
+    softmax,
+    state_to_text,
+)
+
+logger = logging.getLogger(__name__)
+
+#: Reference word pattern of the GLiNER2 schema (urls, emails, handles, words, punctuation).
+WORD_PATTERN = re.compile(
+    r"(?:https?://[^\s]+|www\.[^\s]+)"
+    r"|[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}"
+    r"|@[a-z0-9_]+"
+    r"|[\w]+(?:[-_][\w]+)*"
+    r"|\S",
+    re.IGNORECASE | re.UNICODE,
+)
+
+
+class Gliner2Adapter:
+    """System One over a GLiNER2.5 classifier export (encoder + classifier)."""
+
+    name = "gliner2"
+
+    def __init__(self, *, task: str = "classify", use_descriptions: bool = True) -> None:
+        self._task = task
+        self._use_descriptions = bool(use_descriptions)
+        self._cache: dict[str, list[int]] = {}
+
+    # ------------------------------------------------------------- tokenizing
+    def _tokenize(self, tokenizer: Any, token: str) -> list[int]:
+        ids = self._cache.get(token)
+        if ids is None:
+            ids = encode(tokenizer, token)
+            self._cache[token] = ids
+        return ids
+
+    # --------------------------------------------------------------- inference
+    def _scores(
+        self,
+        engine: OnnxEngine,
+        text: str,
+        options: list[tuple[str, str | None]],
+        task: str,
+    ) -> list[float]:
+        import numpy as np  # only the real ONNX path needs arrays
+
+        text = text if text.endswith((".", "!", "?")) else text + "."
+        words = [match.group(0).lower() for match in WORD_PATTERN.finditer(text)]
+        tokenizer = engine.tokenizer
+
+        parent = task
+        if self._use_descriptions:
+            for label, description in options:
+                if description:
+                    parent += f" [DESCRIPTION] {label}: {description}"
+
+        schema = ["(", "[P]", parent, "("]
+        for label, _ in options:
+            schema += ["[C]", label]
+        schema += [")", ")"]
+
+        input_ids: list[int] = []
+        positions: list[int] = []
+        for token in schema:
+            if token == "[C]":
+                positions.append(len(input_ids))
+            input_ids.extend(self._tokenize(tokenizer, token))
+        input_ids.extend(self._tokenize(tokenizer, "[SEP_TEXT]"))
+        for word in words:
+            input_ids.extend(self._tokenize(tokenizer, word))
+
+        ids = np.asarray([input_ids], dtype=np.int64)
+        attention = np.ones_like(ids)
+
+        # Fused export (e.g. onnx-community/GLiNER2.5-Decide-ONNX): one graph with
+        # marker_positions and one logit per marker. Split export (e.g. the multi-v1
+        # repo): encoder + classifier, with the classifier input name read from the graph.
+        if "model" in engine.files:
+            session = engine.session("model")
+            input_names = {item.name for item in session.get_inputs()}
+            feeds = {"input_ids": ids, "attention_mask": attention}
+            if "marker_positions" in input_names:
+                feeds["marker_positions"] = np.asarray([positions], dtype=np.int64)
+            logits = session.run(None, feeds)[0]
+            return [float(value) for value in np.asarray(logits)[0][: len(options)]]
+
+        hidden = engine.session("encoder").run(
+            None, {"input_ids": ids, "attention_mask": attention}
+        )[0]
+        queries = hidden[0][positions].astype(np.float32)
+        classifier = engine.session("classifier")
+        input_name = classifier.get_inputs()[0].name
+        logits = classifier.run(None, {input_name: queries})[0].reshape(-1)
+        return [float(value) for value in logits]
+
+    def system_one(
+        self, engine: OnnxEngine, state: Any, questions: Mapping[str, Mapping[str, Any]]
+    ) -> Mapping[str, Mapping[str, Any]]:
+        state_text = state_to_text(state)
+        answers: dict[str, dict[str, Any]] = {}
+        for name, question in questions.items():
+            kind, labels, descriptions = question_options(question)
+            task = str(question.get("task") or self._task)
+            scores = self._scores(engine, state_text, list(zip(labels, descriptions)), task)
+            if len(scores) != len(labels):
+                raise AdapterError(
+                    f"the classifier returned {len(scores)} scores for {len(labels)} options"
+                )
+            probabilities = softmax(scores)
+            if kind == "choice":
+                answers[name] = build_choice_answer(labels, probabilities)
+            elif kind == "noul":
+                answers[name] = build_noul_answer(probabilities[0], probabilities[1])
+            else:
+                answers[name] = build_score_answer(labels, probabilities)
+        return answers
+
+
+__all__ = ["Gliner2Adapter"]

decision_toolkit/adapters/gliner2_decide.py

@@ -0,0 +1,117 @@
+"""`decision_toolkit.adapters.gliner2_decide` — the fused GLiNER2.5-Decide export.
+
+The fused ONNX export (`onnx-community/GLiNER2.5-Decide-ONNX`) differs from the
+split multi-v1 layout: it expects the GLiNER2 classification sequence with
+``[L]`` label markers and a ``[SEP_STRUCT]`` structural separator, and returns
+one logit per marker in a single graph:
+
+    ( [P] prompt [DESCRIPTION] … ( [L] label … ) ) [SEP_STRUCT] [SEP_TEXT] words
+    inputs: input_ids, attention_mask, marker_positions
+    output: logits [batch, markers] → softmax per question
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from typing import Any
+
+from ..engine import OnnxEngine, encode
+from ..errors import AdapterError
+from .base import (
+    build_choice_answer,
+    build_noul_answer,
+    build_score_answer,
+    question_options,
+    softmax,
+    state_to_text,
+)
+from .gliner2 import WORD_PATTERN
+
+logger = logging.getLogger(__name__)
+
+
+class Gliner2DecideAdapter:
+    """System One over the fused GLiNER2.5-Decide ONNX export."""
+
+    name = "gliner2-decide"
+
+    def __init__(self, *, use_descriptions: bool = True) -> None:
+        self._use_descriptions = bool(use_descriptions)
+        self._cache: dict[str, list[int]] = {}
+
+    def _tokenize(self, tokenizer: Any, token: str) -> list[int]:
+        ids = self._cache.get(token)
+        if ids is None:
+            ids = encode(tokenizer, token)
+            self._cache[token] = ids
+        return ids
+
+    def _scores(
+        self,
+        engine: OnnxEngine,
+        text: str,
+        prompt: str,
+        options: list[tuple[str, str | None]],
+    ) -> list[float]:
+        import numpy as np
+
+        tokenizer = engine.tokenizer
+        text = text if text.endswith((".", "!", "?")) else text + "."
+        words = [match.group(0).lower() for match in WORD_PATTERN.finditer(text)]
+
+        parent = prompt
+        if self._use_descriptions:
+            for label, description in options:
+                if description:
+                    parent += f" [DESCRIPTION] {label}: {description}"
+
+        schema = ["(", "[P]", parent, "("]
+        for label, _ in options:
+            schema += ["[L]", label]
+        schema += [")", ")", "[SEP_STRUCT]", "[SEP_TEXT]"]
+
+        input_ids: list[int] = []
+        positions: list[int] = []
+        for token in schema:
+            if token == "[L]":
+                positions.append(len(input_ids))
+            input_ids.extend(self._tokenize(tokenizer, token))
+        for word in words:
+            input_ids.extend(self._tokenize(tokenizer, word))
+
+        ids = np.asarray([input_ids], dtype=np.int64)
+        logits = engine.session("model").run(None, {
+            "input_ids": ids,
+            "attention_mask": np.ones_like(ids),
+            "marker_positions": np.asarray([positions], dtype=np.int64),
+        })[0][0]
+        return [float(value) for value in np.asarray(logits)[: len(positions)]]
+
+    def system_one(
+        self, engine: OnnxEngine, state: Any, questions: Mapping[str, Mapping[str, Any]]
+    ) -> Mapping[str, Mapping[str, Any]]:
+        state_text = state_to_text(state)
+        answers: dict[str, dict[str, Any]] = {}
+        for name, question in questions.items():
+            kind, labels, descriptions = question_options(question)
+            prompt = str(question.get("instructions") or "classify")
+            scores = self._scores(
+                engine, state_text, prompt, list(zip(labels, descriptions))
+            )
+            if len(scores) != len(labels):
+                raise AdapterError(
+                    f"{name!r}: the graph returned {len(scores)} logits for {len(labels)} labels"
+                )
+            probabilities = softmax(scores)
+            if kind == "choice":
+                answers[name] = build_choice_answer(labels, probabilities)
+            elif kind == "noul":
+                # question_options maps noul to labels ["yes", "no"]
+                answers[name] = build_noul_answer(probabilities[0], probabilities[1])
+            else:
+                answers[name] = build_score_answer(labels, probabilities)
+        return answers
+
+
+__all__ = ["Gliner2DecideAdapter"]