dev-double 0.1.0__py3-none-any.whl

dev_double/apps/server/transport/choice_use_cases.py

@@ -0,0 +1,121 @@
+"""/v1/route, /v1/gate, /v1/classify: the use cases answered by one choice question."""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Union
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from ....core.decision.defaults import DEFAULT_CLASSIFY_QUESTION
+from ....core.decision.t_classify import TClassifyRequest, TClassifyResponse
+from ....core.decision.t_gate import TGateRequest, TGateResponse, TToolCall
+from ....core.decision.t_question import MAX_OPTIONS, check_option_keys
+from ....core.decision.t_route import TRouteRequest, TRouteResponse
+from .common import InputValue, Meta
+
+
+class _CoreValidated(BaseModel):
+    """Constructs the core type after field validation, so core invariants give a 422."""
+
+    @model_validator(mode="after")
+    def _core_invariants(self):  # type: ignore[no-untyped-def]
+        self.to_core()  # type: ignore[attr-defined]
+        return self
+
+
+def _distinct_keys(v: Optional[dict[str, str]]) -> Optional[dict[str, str]]:
+    # Checked per field too, so the 422 points at the offending field.
+    if v is not None:
+        check_option_keys(v)
+    return v
+
+
+class RouteRequest(_CoreValidated):
+    input: InputValue = Field(description="The prompt or task to route.")
+    routes: Optional[dict[str, str]] = Field(
+        None,
+        min_length=2,
+        max_length=MAX_OPTIONS,
+        description="Route name -> when to use it. Defaults to small / medium / large model tiers.",
+    )
+
+    _routes = field_validator("routes")(_distinct_keys)
+
+    def to_core(self) -> TRouteRequest:
+        return TRouteRequest(input=self.input, routes=self.routes)
+
+
+class RouteResponse(BaseModel):
+    route: str
+    probabilities: dict[str, float]
+    confidence: float
+    meta: Meta
+
+    @classmethod
+    def from_core(cls, t: TRouteResponse) -> "RouteResponse":
+        return cls(route=t.route, probabilities=t.probabilities, confidence=t.confidence, meta=Meta.from_core(t.meta))
+
+
+class ToolCall(BaseModel):
+    name: str
+    arguments: Union[dict[str, Any], str] = Field(default_factory=dict)
+
+
+class GateRequest(_CoreValidated):
+    tool_call: ToolCall
+    context: Optional[InputValue] = Field(None, description="What the user asked for, or the recent conversation.")
+    policy: Optional[str] = Field(None, description="Your rules for tool use, in plain language.")
+    outcomes: Optional[dict[str, str]] = Field(
+        None,
+        min_length=2,
+        max_length=MAX_OPTIONS,
+        description="Outcome -> when it applies. Defaults to allow / ask / deny.",
+    )
+
+    _outcomes = field_validator("outcomes")(_distinct_keys)
+
+    def to_core(self) -> TGateRequest:
+        call = TToolCall(name=self.tool_call.name, arguments=self.tool_call.arguments)
+        return TGateRequest(tool_call=call, context=self.context, policy=self.policy, outcomes=self.outcomes)
+
+
+class GateResponse(BaseModel):
+    decision: str
+    probabilities: dict[str, float]
+    confidence: float
+    meta: Meta
+
+    @classmethod
+    def from_core(cls, t: TGateResponse) -> "GateResponse":
+        return cls(decision=t.decision, probabilities=t.probabilities, confidence=t.confidence, meta=Meta.from_core(t.meta))
+
+
+class ClassifyRequest(_CoreValidated):
+    input: Optional[InputValue] = Field(None, description="One item. Use `inputs` for a batch.")
+    inputs: Optional[list[InputValue]] = Field(None, description="Many items, labeled in parallel.")
+    labels: dict[str, str] = Field(min_length=2, max_length=MAX_OPTIONS)
+    question: str = DEFAULT_CLASSIFY_QUESTION
+
+    _labels = field_validator("labels")(_distinct_keys)
+
+    def to_core(self) -> TClassifyRequest:
+        return TClassifyRequest(labels=self.labels, input=self.input, inputs=self.inputs, question=self.question)
+
+
+class Classification(BaseModel):
+    label: str
+    probabilities: dict[str, float]
+    confidence: float
+
+
+class ClassifyResponse(BaseModel):
+    results: list[Classification]
+    meta: Meta
+
+    @classmethod
+    def from_core(cls, t: TClassifyResponse) -> "ClassifyResponse":
+        results = [
+            Classification(label=r.label, probabilities=r.probabilities, confidence=r.confidence)
+            for r in t.results
+        ]
+        return cls(results=results, meta=Meta.from_core(t.meta))

dev_double/apps/server/transport/common.py

@@ -0,0 +1,37 @@
+"""Shared transport pieces: input values and response metadata."""
+
+from __future__ import annotations
+
+from typing import Any, Union
+
+from pydantic import BaseModel, Field
+
+from ....core.decision.t_meta import TMeta
+
+InputValue = Union[str, dict[str, Any], list[Any]]
+
+
+class Usage(BaseModel):
+    input_tokens: int = 0
+    output_tokens: int = 0
+
+
+class Meta(BaseModel):
+    engine: str
+    model: str
+    latency_ms: int
+    usage: Usage
+    warnings: list[str] = Field(
+        default_factory=list,
+        description="Where this answer may be less faithful than a real decision model.",
+    )
+
+    @classmethod
+    def from_core(cls, t: TMeta) -> "Meta":
+        return cls(
+            engine=t.engine,
+            model=t.model,
+            latency_ms=t.latency_ms,
+            usage=Usage(input_tokens=t.usage.input_tokens, output_tokens=t.usage.output_tokens),
+            warnings=list(t.warnings),
+        )

dev_double/apps/server/transport/decide.py

@@ -0,0 +1,131 @@
+"""/v1/decide: three question types, answered about one input.
+
+Invariants (option counts, distinct keys) live in the core types; the
+validators below construct them so a violation becomes a 422.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal, Optional, Union
+
+from pydantic import BaseModel, Field, model_validator
+
+from ....core.decision.t_answer import TAnswer, TBinaryAnswer, TChoiceAnswer
+from ....core.decision.t_decide import TDecideRequest, TDecideResponse
+from ....core.decision.t_question import (
+    MAX_LEVELS,
+    MAX_OPTIONS,
+    TBinaryQuestion,
+    TChoiceQuestion,
+    TQuestion,
+    TScaleQuestion,
+)
+from .common import InputValue, Meta
+
+
+class BinaryQuestion(BaseModel):
+    type: Literal["binary"]
+    question: str = Field(description="A yes/no question or a statement to verify.")
+    yes: Optional[str] = Field(None, description="Optional: what counts as yes.")
+    no: Optional[str] = Field(None, description="Optional: what counts as no.")
+
+    def to_core(self) -> TBinaryQuestion:
+        return TBinaryQuestion(question=self.question, yes=self.yes, no=self.no)
+
+
+class ChoiceQuestion(BaseModel):
+    type: Literal["choice"]
+    question: str
+    options: dict[str, str] = Field(
+        min_length=2,
+        max_length=MAX_OPTIONS,
+        description="Option key -> description. Keys are returned as the answer.",
+    )
+
+    @model_validator(mode="after")
+    def _core_invariants(self) -> "ChoiceQuestion":
+        self.to_core()
+        return self
+
+    def to_core(self) -> TChoiceQuestion:
+        return TChoiceQuestion(question=self.question, options=dict(self.options))
+
+
+class ScaleQuestion(BaseModel):
+    type: Literal["scale"]
+    question: str
+    levels: list[str] = Field(
+        min_length=2,
+        max_length=MAX_LEVELS,
+        description="Ordered level descriptions, lowest first. Level i is returned as i.",
+    )
+
+    def to_core(self) -> TScaleQuestion:
+        return TScaleQuestion(question=self.question, levels=list(self.levels))
+
+
+Question = Annotated[
+    Union[BinaryQuestion, ChoiceQuestion, ScaleQuestion], Field(discriminator="type")
+]
+
+
+class DecideRequest(BaseModel):
+    input: InputValue = Field(description="The content to decide about: text, an object, or a list.")
+    questions: dict[str, Question] = Field(min_length=1)
+    model: Optional[str] = Field(None, description="Ignored; the server's configured model is used.")
+
+    def to_core(self) -> TDecideRequest:
+        questions: dict[str, TQuestion] = {k: q.to_core() for k, q in self.questions.items()}
+        return TDecideRequest(input=self.input, questions=questions)
+
+
+class BinaryAnswer(BaseModel):
+    type: Literal["binary"] = "binary"
+    value: bool
+    probability: float = Field(description="Probability that the answer is yes.")
+    confidence: float
+
+
+class ChoiceAnswer(BaseModel):
+    type: Literal["choice"] = "choice"
+    value: str
+    probabilities: dict[str, float]
+    confidence: float
+
+
+class ScaleAnswer(BaseModel):
+    type: Literal["scale"] = "scale"
+    value: float = Field(description="Probability-weighted level, from 0 to len(levels) - 1.")
+    level: int = Field(description="The single most likely level.")
+    probabilities: dict[str, float]
+    legend: dict[str, str]
+    confidence: float
+
+
+Answer = Annotated[Union[BinaryAnswer, ChoiceAnswer, ScaleAnswer], Field(discriminator="type")]
+
+
+def answer_from_core(a: TAnswer) -> Union[BinaryAnswer, ChoiceAnswer, ScaleAnswer]:
+    if isinstance(a, TBinaryAnswer):
+        return BinaryAnswer(value=a.value, probability=a.probability, confidence=a.confidence)
+    if isinstance(a, TChoiceAnswer):
+        return ChoiceAnswer(value=a.value, probabilities=a.probabilities, confidence=a.confidence)
+    return ScaleAnswer(
+        value=a.value,
+        level=a.level,
+        probabilities=a.probabilities,
+        legend=a.legend,
+        confidence=a.confidence,
+    )
+
+
+class DecideResponse(BaseModel):
+    answers: dict[str, Answer]
+    meta: Meta
+
+    @classmethod
+    def from_core(cls, t: TDecideResponse) -> "DecideResponse":
+        return cls(
+            answers={k: answer_from_core(a) for k, a in t.answers.items()},
+            meta=Meta.from_core(t.meta),
+        )

dev_double/apps/server/transport/extract.py

@@ -0,0 +1,93 @@
+"""/v1/extract: typed fields pulled out of one input.
+
+Invariants (field types, enum options, field counts) live in the core types;
+the validators below construct them so a violation becomes a 422 that points
+at the offending field.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Optional, Union
+
+from pydantic import BaseModel, Field, model_serializer, model_validator
+
+from ....core.decision.t_extract import (
+    MAX_FIELDS,
+    TExtractField,
+    TExtractRequest,
+    TExtractResponse,
+    TFieldValue,
+)
+from ....core.decision.t_question import MAX_OPTIONS
+from .common import InputValue, Meta
+
+Value = Optional[Union[bool, int, float, str]]
+
+
+class ExtractField(BaseModel):
+    type: Literal["string", "number", "integer", "boolean", "enum"] = Field(
+        description="string, number, and integer values are generated; enum and boolean are scored."
+    )
+    description: Optional[str] = Field(None, description="What the field means and how to format it.")
+    options: Optional[Union[list[str], dict[str, str]]] = Field(
+        None,
+        min_length=2,
+        max_length=MAX_OPTIONS,
+        description="Enum only: option names, or option -> description. The chosen name is returned.",
+    )
+
+    @model_validator(mode="after")
+    def _core_invariants(self) -> "ExtractField":
+        self.to_core()
+        return self
+
+    def to_core(self) -> TExtractField:
+        options = list(self.options) if isinstance(self.options, list) else self.options
+        return TExtractField(type=self.type, description=self.description, options=options)
+
+
+class ExtractRequest(BaseModel):
+    input: InputValue = Field(description="The content to extract from: text, an object, or a list.")
+    fields: dict[str, ExtractField] = Field(
+        min_length=1, max_length=MAX_FIELDS, description="Field name -> type and description."
+    )
+
+    @model_validator(mode="after")
+    def _core_invariants(self) -> "ExtractRequest":
+        self.to_core()
+        return self
+
+    def to_core(self) -> TExtractRequest:
+        return TExtractRequest(input=self.input, fields={k: f.to_core() for k, f in self.fields.items()})
+
+
+class FieldValue(BaseModel):
+    value: Value = Field(None, description="The extracted value; null when the input doesn't contain it.")
+    confidence: float
+    probabilities: Optional[dict[str, float]] = Field(None, description="Enum fields only.")
+    probability: Optional[float] = Field(None, description="Boolean fields only: probability of true.")
+
+    @model_serializer(mode="wrap")
+    def _omit_absent(self, handler: Any) -> dict[str, Any]:
+        # `value: null` is an answer; a missing probability is not, so omit only those.
+        data = handler(self)
+        rest = {k: v for k, v in data.items() if k != "value" and v is not None}
+        return {"value": self.value, **rest}
+
+    @classmethod
+    def from_core(cls, t: TFieldValue) -> "FieldValue":
+        return cls(value=t.value, confidence=t.confidence, probabilities=t.probabilities, probability=t.probability)
+
+
+class ExtractResponse(BaseModel):
+    values: dict[str, Value] = Field(description="Field name -> value, for direct use.")
+    fields: dict[str, FieldValue] = Field(description="Field name -> value with its confidence.")
+    meta: Meta
+
+    @classmethod
+    def from_core(cls, t: TExtractResponse) -> "ExtractResponse":
+        return cls(
+            values=dict(t.values),
+            fields={k: FieldValue.from_core(f) for k, f in t.fields.items()},
+            meta=Meta.from_core(t.meta),
+        )

dev_double/apps/server/transport/guard_judge.py

@@ -0,0 +1,97 @@
+"""/v1/guard (binary questions per policy) and /v1/judge (one scale question)."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field, model_validator
+
+from ....core.decision.defaults import DEFAULT_GUARD_THRESHOLD, DEFAULT_JUDGE_CRITERIA
+from ....core.decision.t_guard import TGuardRequest, TGuardResponse
+from ....core.decision.t_judge import TJudgeRequest, TJudgeResponse
+from ....core.decision.t_question import MAX_LEVELS
+from .common import InputValue, Meta
+
+
+class GuardRequest(BaseModel):
+    input: InputValue
+    policies: Optional[dict[str, str]] = Field(
+        None,
+        min_length=1,
+        description="Policy name -> description of a violation. Defaults to prompt_injection and abuse.",
+    )
+    scope: Optional[str] = Field(
+        None, description="Optional: what the assistant is for. Adds an off_topic check."
+    )
+    threshold: float = Field(
+        DEFAULT_GUARD_THRESHOLD, ge=0, le=1, description="Block when any violation probability reaches this."
+    )
+
+    @model_validator(mode="after")
+    def _core_invariants(self) -> "GuardRequest":
+        self.to_core()
+        return self
+
+    def to_core(self) -> TGuardRequest:
+        return TGuardRequest(input=self.input, policies=self.policies, scope=self.scope, threshold=self.threshold)
+
+
+class GuardCheck(BaseModel):
+    probability: float
+    flagged: bool
+
+
+class GuardResponse(BaseModel):
+    allowed: bool
+    flagged: list[str]
+    checks: dict[str, GuardCheck]
+    meta: Meta
+
+    @classmethod
+    def from_core(cls, t: TGuardResponse) -> "GuardResponse":
+        return cls(
+            allowed=t.allowed,
+            flagged=list(t.flagged),
+            checks={k: GuardCheck(probability=c.probability, flagged=c.flagged) for k, c in t.checks.items()},
+            meta=Meta.from_core(t.meta),
+        )
+
+
+class JudgeRequest(BaseModel):
+    output: InputValue = Field(description="The answer being judged.")
+    input: Optional[InputValue] = Field(None, description="The prompt or task that produced the output.")
+    reference: Optional[InputValue] = Field(None, description="Optional reference answer.")
+    criteria: str = DEFAULT_JUDGE_CRITERIA
+    levels: Optional[list[str]] = Field(
+        None,
+        min_length=2,
+        max_length=MAX_LEVELS,
+        description="Ordered rubric levels, worst first. Defaults to a 5-level rubric (0-4).",
+    )
+
+    def to_core(self) -> TJudgeRequest:
+        return TJudgeRequest(
+            output=self.output, input=self.input, reference=self.reference, criteria=self.criteria, levels=self.levels
+        )
+
+
+class JudgeResponse(BaseModel):
+    score: float = Field(description="Probability-weighted level, from 0 to len(levels) - 1.")
+    normalized: float = Field(description="score / (len(levels) - 1), from 0 to 1.")
+    level: int
+    probabilities: dict[str, float]
+    legend: dict[str, str]
+    confidence: float
+    meta: Meta
+
+    @classmethod
+    def from_core(cls, t: TJudgeResponse) -> "JudgeResponse":
+        return cls(
+            score=t.score,
+            normalized=t.normalized,
+            level=t.level,
+            probabilities=t.probabilities,
+            legend=t.legend,
+            confidence=t.confidence,
+            meta=Meta.from_core(t.meta),
+        )

dev_double/apps/server/transport/rerank.py

@@ -0,0 +1,55 @@
+"""/v1/rerank: Cohere-style wire format, the de facto standard shared by
+Hugging Face TEI, Infinity, Jina, and vLLM."""
+
+from __future__ import annotations
+
+from typing import Optional, Union
+
+from pydantic import BaseModel, Field
+
+from ....core.decision.t_rerank import TRerankRequest, TRerankResponse
+from .common import Meta
+
+
+class RerankDocument(BaseModel):
+    text: str
+
+
+class RerankRequest(BaseModel):
+    query: str
+    documents: list[Union[str, RerankDocument]] = Field(min_length=1)
+    top_n: Optional[int] = Field(None, ge=1)
+    return_documents: bool = False
+    model: Optional[str] = Field(None, description="Ignored; the server's configured model is used.")
+
+    def texts(self) -> list[str]:
+        return [d if isinstance(d, str) else d.text for d in self.documents]
+
+    def to_core(self) -> TRerankRequest:
+        return TRerankRequest(
+            query=self.query, documents=self.texts(), top_n=self.top_n, return_documents=self.return_documents
+        )
+
+
+class RerankResult(BaseModel):
+    index: int
+    relevance_score: float
+    document: Optional[RerankDocument] = None
+
+
+class RerankResponse(BaseModel):
+    id: str
+    results: list[RerankResult]
+    meta: Meta
+
+    @classmethod
+    def from_core(cls, t: TRerankResponse) -> "RerankResponse":
+        results = [
+            RerankResult(
+                index=r.index,
+                relevance_score=r.relevance_score,
+                document=RerankDocument(text=r.document) if r.document is not None else None,
+            )
+            for r in t.results
+        ]
+        return cls(id=t.id, results=results, meta=Meta.from_core(t.meta))

dev_double/client.py

@@ -0,0 +1,5 @@
+"""Re-export of the sync HTTP client, kept for ``from dev_double.client import DevDouble``."""
+
+from .apps.client.http_client import DevDouble
+
+__all__ = ["DevDouble"]

dev_double/core/__init__.py

@@ -0,0 +1 @@
+"""Core layer: interfaces, domain types, and pure decision logic. No third-party imports."""

dev_double/core/decision/__init__.py

@@ -0,0 +1,62 @@
+"""Decision core: interfaces, domain types, prompts, and the use cases.
+
+Zero third-party dependencies. Side effects (model calls, time, ids) arrive
+through the ports ``IEngine`` / ``IDecider``, ``IClock``, and ``IIdProvider``.
+Optional capabilities (``IGenerator``, ``IRecordReader``, ``IExtractor``,
+``IReranker``) are detected with ``isinstance`` and used when present.
+"""
+
+from .confidence import DIGITS, confidence
+from .decider_basic_impl import DeciderBasicImpl
+from .decision_service_basic_impl import DecisionServiceBasicImpl
+from .defaults import DEFAULT_OUTCOMES, DEFAULT_POLICIES, DEFAULT_ROUTES, DEFAULT_RUBRIC
+from .errors import EngineError
+from .i_clock import IClock
+from .i_decider import IDecider
+from .i_decision_service import IDecisionService
+from .i_engine import IEngine
+from .i_extractor import IExtractor
+from .i_generator import IGenerator
+from .i_id_provider import IIdProvider
+from .i_record_reader import IRecordReader
+from .i_reranker import IReranker
+from .t_answer import TAnswer, TBinaryAnswer, TChoiceAnswer, TScaleAnswer
+from .t_classify import TClassification, TClassifyRequest, TClassifyResponse
+from .t_decide import TDecideRequest, TDecideResponse
+from .t_extract import MAX_FIELDS, TExtractField, TExtractRequest, TExtractResponse, TFieldValue
+from .t_gate import TGateRequest, TGateResponse, TToolCall
+from .t_generate import TGenerateQuery, TGenerateResult
+from .t_guard import TGuardCheck, TGuardRequest, TGuardResponse
+from .t_input import TInputValue
+from .t_judge import TJudgeRequest, TJudgeResponse
+from .t_label_query import TLabelQuery, TLabelResult, TPosition
+from .t_meta import TMeta
+from .t_question import (
+    MAX_LEVELS,
+    MAX_OPTIONS,
+    TBinaryQuestion,
+    TChoiceQuestion,
+    TQuestion,
+    TScaleQuestion,
+)
+from .t_rerank import TRerankRequest, TRerankResponse, TRerankResult
+from .t_route import TRouteRequest, TRouteResponse
+from .t_usage import TUsage
+from .tracker import Tracker
+
+__all__ = [
+    "DEFAULT_OUTCOMES", "DEFAULT_POLICIES", "DEFAULT_ROUTES", "DEFAULT_RUBRIC", "DIGITS",
+    "MAX_FIELDS", "MAX_LEVELS", "MAX_OPTIONS",
+    "DeciderBasicImpl", "DecisionServiceBasicImpl", "EngineError",
+    "IClock", "IDecider", "IDecisionService", "IEngine", "IExtractor",
+    "IGenerator", "IIdProvider", "IRecordReader", "IReranker",
+    "TExtractField", "TExtractRequest", "TExtractResponse", "TFieldValue",
+    "TGenerateQuery", "TGenerateResult",
+    "TAnswer", "TBinaryAnswer", "TBinaryQuestion", "TChoiceAnswer", "TChoiceQuestion",
+    "TClassification", "TClassifyRequest", "TClassifyResponse", "TDecideRequest",
+    "TDecideResponse", "TGateRequest", "TGateResponse", "TGuardCheck", "TGuardRequest",
+    "TGuardResponse", "TInputValue", "TJudgeRequest", "TJudgeResponse", "TLabelQuery",
+    "TLabelResult", "TMeta", "TPosition", "TQuestion", "TRerankRequest", "TRerankResponse",
+    "TRerankResult", "TRouteRequest", "TRouteResponse", "TScaleAnswer", "TScaleQuestion",
+    "TToolCall", "TUsage", "Tracker", "confidence",
+]

dev_double/core/decision/answer_shaping.py

@@ -0,0 +1,48 @@
+"""Turns a distribution over a question's labels into its typed answer.
+
+Labels are "yes"/"no" for binary questions, option keys for choice questions,
+and "0".."n-1" for scale questions (see ``question_labels``).
+"""
+
+from __future__ import annotations
+
+from .confidence import DIGITS, confidence, round_probabilities
+from .t_answer import TAnswer, TBinaryAnswer, TChoiceAnswer, TScaleAnswer
+from .t_question import TBinaryQuestion, TChoiceQuestion, TQuestion
+
+
+def question_labels(question: TQuestion) -> dict[str, str]:
+    """Label -> description, in the order the question defines them."""
+    if isinstance(question, TBinaryQuestion):
+        return {"yes": question.yes or "The answer is yes.", "no": question.no or "The answer is no."}
+    if isinstance(question, TChoiceQuestion):
+        return dict(question.options)
+    return {str(i): text for i, text in enumerate(question.levels)}
+
+
+def shape_answer(question: TQuestion, probs: dict[str, float], round_probs: bool = True) -> TAnswer:
+    """``round_probs=False`` passes choice/scale probabilities through as given."""
+    if isinstance(question, TBinaryQuestion):
+        p_yes = probs["yes"]
+        return TBinaryAnswer(
+            value=p_yes >= 0.5,
+            probability=round(p_yes, DIGITS),
+            confidence=round(confidence([p_yes, 1 - p_yes]), DIGITS),
+        )
+
+    shown = round_probabilities(probs) if round_probs else probs
+    if isinstance(question, TChoiceQuestion):
+        return TChoiceAnswer(
+            value=max(probs, key=probs.__getitem__),
+            probabilities=shown,
+            confidence=round(confidence(list(probs.values())), DIGITS),
+        )
+
+    expected = sum(int(level) * p for level, p in probs.items())
+    return TScaleAnswer(
+        value=round(expected, DIGITS),
+        level=int(max(probs, key=probs.__getitem__)),
+        probabilities=shown,
+        legend={str(i): text for i, text in enumerate(question.levels)},
+        confidence=round(confidence(list(probs.values())), DIGITS),
+    )

dev_double/core/decision/confidence.py

@@ -0,0 +1,19 @@
+"""How concentrated a distribution is, and output rounding."""
+
+from __future__ import annotations
+
+DIGITS = 4
+
+
+def confidence(probabilities: list[float]) -> float:
+    """How concentrated a distribution is: 1.0 when all mass is on one label,
+    0.0 when it is spread evenly. Normalized max probability: (n*max - 1) / (n - 1).
+    """
+    n = len(probabilities)
+    if n < 2:
+        return 1.0
+    return max(0.0, (n * max(probabilities) - 1) / (n - 1))
+
+
+def round_probabilities(probs: dict[str, float]) -> dict[str, float]:
+    return {k: round(v, DIGITS) for k, v in probs.items()}