Domain package¶

Kind: reference. This page is generated from the docstrings of typevet.domain. The API index lists the other packages.

typevet.domain ¶

Pure domain types for typed generation and candidate scoring.

Examples:

from typevet.domain import GenerationRequest, compile_json_schema

schema = {
    "type": "object",
    "properties": {"ok": {"type": "boolean"}},
    "required": ["ok"],
}
req = GenerationRequest(
    prompt="Classify sentiment.",
    schema=schema,
    model="gemma-4-31b-24gib-kv11-decoder",
)
assert compile_json_schema(schema)[0].syntax == "Bool"

Attributes¶

Answer `module-attribute` ¶

Answer = NoulAnswer | ChoiceAnswer | ScoreAnswer

Union type for all judgment answers.

Question `module-attribute` ¶

Question = Noul | Choice | Score

A typed judgment question.

Classes¶

CandidateScoringRequest `dataclass` ¶

CandidateScoringRequest(
    model: str,
    prefix: str,
    candidates: tuple[CandidateTokenSpec, ...],
    stage: ScoreStage = PRE_SAMPLING,
    media: tuple[ImageInput, ...] = (),
)

Identify model, prefix, candidates, and required score stage.

Complete candidate coverage is required: adapters must return a score for every requested label and must not invent scores for omitted labels.

prefix must hold exactly one MEDIA_MARKER for each entry in media. An empty media tuple is the text-only ask.

Attributes:

Name	Type	Description
`model`	`str`	Backend model id or alias.
`prefix`	`str`	Rendered prompt prefix ending before candidate tokens.
`candidates`	`tuple[CandidateTokenSpec, ...]`	Ordered candidate set.
`stage`	`ScoreStage`	Required logprob extraction stage.
`media`	`tuple[ImageInput, ...]`	Images the prefix marks, in order.

Examples:

request = CandidateScoringRequest(
    model="m",
    prefix="Q:",
    candidates=(CandidateTokenSpec("a", (1,)),),
)
assert request.stage is ScoreStage.PRE_SAMPLING

Methods:¶

__post_init__ ¶

__post_init__() -> None

Reject empty model, prefix, candidates, duplicate ids, or bad markers.

Raises:

Type	Description
`ScoringValidationError`	When the ask violates coverage rules or the media marker count does not match `len(media)`.

CandidateTokenSpec `dataclass` ¶

CandidateTokenSpec(label: str, token_ids: tuple[int, ...])

One labeled candidate as an ordered token-id sequence.

Attributes:

Name	Type	Description
`label`	`str`	Stable candidate id (for example an enum string).
`token_ids`	`tuple[int, ...]`	Encoded token ids for this candidate.

Examples:

spec = CandidateTokenSpec("yes", (42,))
assert spec.token_ids == (42,)

Methods:¶

__post_init__ ¶

__post_init__() -> None

Reject empty labels or invalid token-id sequences.

Raises:

Type	Description
`ScoringValidationError`	When label or token ids are invalid.

CandidateScoringResult `dataclass` ¶

CandidateScoringResult(
    model: str,
    stage: ScoreStage,
    candidates: tuple[ScoredCandidate, ...],
    usage: TokenUsage = TokenUsage(),
    termination: ScoringTermination | None = None,
)

Complete identity-preserving scores for every requested candidate.

Attributes:

Name	Type	Description
`model`	`str`	Model id that produced the scores.
`stage`	`ScoreStage`	Stage used to obtain logprobs.
`candidates`	`tuple[ScoredCandidate, ...]`	Scores in request order.
`usage`	`TokenUsage`	Optional token usage metadata.
`termination`	`ScoringTermination \| None`	Optional stop metadata.

Examples:

result = CandidateScoringResult(
    model="m",
    stage=ScoreStage.PRE_SAMPLING,
    candidates=(ScoredCandidate("a", (1,), -1.0),),
)
assert len(result.candidates) == 1

ScoredCandidate `dataclass` ¶

ScoredCandidate(label: str, token_ids: tuple[int, ...], logprob: float)

One candidate label, token ids, and raw logprob.

Attributes:

Name	Type	Description
`label`	`str`	Candidate id matching the request label.
`token_ids`	`tuple[int, ...]`	Token sequence matching the request.
`logprob`	`float`	Raw pre-sampling logprob for this candidate.

Examples:

scored = ScoredCandidate("billing", (101,), -0.25)
assert scored.label == "billing"

ScoringTermination `dataclass` ¶

ScoringTermination(finish_reason: str | None = None)

Optional backend termination metadata for a scoring call.

Attributes:

Name	Type	Description
`finish_reason`	`str \| None`	Backend stop reason when reported.

Examples:

meta = ScoringTermination(finish_reason="length")
assert meta.finish_reason == "length"

CategoricalExecutionResult `dataclass` ¶

CategoricalExecutionResult(
    decision: Decision,
    value: Any,
    probabilities: tuple[tuple[Any, float], ...],
    logprobs: tuple[float, ...],
    model: str,
    usage: TokenUsage,
)

Greedy categorical decision outcome with full softmax distribution.

Attributes:

Name	Type	Description
`decision`	`Decision`	The categorical field that was executed.
`value`	`Any`	Selected choice value from `decision.choices`.
`probabilities`	`tuple[tuple[Any, float], ...]`	Ordered choice/probability pairs aligned with `decision.choices` after softmax.
`logprobs`	`tuple[float, ...]`	Raw pre-sampling logprobs in choice order.
`model`	`str`	Model id from the scoring port result.
`usage`	`TokenUsage`	Token usage metadata from the scoring port.

Examples:

# Constructed by execute_categorical_decision; not built by callers.

Decision `dataclass` ¶

Decision(
    name: str,
    question: str,
    choices: tuple[Any, ...],
    syntax: str = "Choice",
    numeric_type: str | None = None,
    minimum: int | float | None = None,
    maximum: int | float | None = None,
    text_type: bool = False,
    max_length: int | None = None,
    permutations: int | str = 1,
    return_probabilities: bool = False,
    depends_on: tuple[str, ...] | None = None,
    nullable: bool = False,
)

One tokenizer-independent field compiled from JSON Schema.

Attributes:

Name	Type	Description
`name`	`str`	Property name in the output object.
`question`	`str`	Model-facing prompt for this field.
`choices`	`tuple[Any, ...]`	Closed choices; empty for open numeric or text.
`syntax`	`str`	TypeLLM syntax label (Choice, Bool, Integer, Number, Text).
`numeric_type`	`str \| None`	`integer` or `number` when syntax is numeric.
`minimum`	`int \| float \| None`	Lower bound for open numeric fields.
`maximum`	`int \| float \| None`	Upper bound for open numeric fields.
`text_type`	`bool`	True when the field is open-ended text.
`max_length`	`int \| None`	Optional max string length for text fields.
`permutations`	`int \| str`	Enum permutation budget or `all`.
`return_probabilities`	`bool`	Whether to request choice probabilities.
`depends_on`	`tuple[str, ...] \| None`	Prior fields that must be set first.
`nullable`	`bool`	Whether JSON null is allowed for this field.

Examples:

from typevet.domain.decisions import Decision

Decision("x", "Pick one.", ("a", "b"), syntax="Choice")

SchemaError ¶

Bases: ValueError

The schema mapping is outside the supported compile subset.

Examples:

from typevet.domain import SchemaError, compile_json_schema

try:
    compile_json_schema({"type": "array"})
except SchemaError:
    pass

BackendHttpError ¶

BackendHttpError(message: str, *, status_code: int, body_snippet: str)

Bases: GenerationError

llama.cpp returned an HTTP error status (400 or above).

Attributes:

Name	Type	Description
`status_code`	`int`	HTTP status from the router.
`body_snippet`	`str`	Truncated response body text for diagnostics.

Examples:

from typevet.domain.errors import BackendHttpError

raise BackendHttpError(
    "llama.cpp HTTP 500: internal",
    status_code=500,
    body_snippet="internal",
)

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable summary including status and snippet.	required
`status_code`	`int`	HTTP status from llama.cpp.	required
`body_snippet`	`str`	Truncated response body text.	required

Methods:¶

DecisionExecutionError ¶

Bases: GenerationError

A categorical decision could not be executed in-domain.

Examples:

from typevet.domain.errors import DecisionExecutionError

raise DecisionExecutionError("nullable categorical decisions are unsupported")

GemmaTemplateError ¶

Bases: JudgmentError

Gemma served-template or answer-prefix rules were violated.

Examples:

from typevet.domain.errors import GemmaTemplateError

raise GemmaTemplateError("unsupported served template family")

GenerationError ¶

Bases: Exception

A typed generation call failed before a valid result existed.

Examples:

from typevet.domain.errors import GenerationError

raise GenerationError("transport failed")

GenerationUnsupportedCapabilityError ¶

Bases: GenerationError

The generation backend cannot honor a part of the request.

An adapter raises it before any HTTP call, for example when a request carries images the backend adapter cannot send. The adapter never drops the unsupported part silently.

Examples:

from typevet.domain.errors import GenerationUnsupportedCapabilityError

raise GenerationUnsupportedCapabilityError("images are not supported")

JudgmentError ¶

Bases: GenerationError

A typed judgment call failed before a valid response existed.

Examples:

from typevet.domain.errors import JudgmentError

raise JudgmentError("judgment failed")

JudgmentValidationError ¶

Bases: JudgmentError

An answer or option list failed judgment validation rules.

Examples:

from typevet.domain.errors import JudgmentValidationError

raise JudgmentValidationError("choice not in criteria")

SchemaValidationError ¶

SchemaValidationError(message: str, *, payload: object | None = None)

Bases: GenerationError

The model output did not validate against the requested schema.

Attributes:

Name	Type	Description
`payload`	`object \| None`	Parsed value that failed validation, when set.
`args`	`tuple`	Standard exception args (message first).

Examples:

from typevet.domain.errors import SchemaValidationError

raise SchemaValidationError("missing key", payload={})

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable validation summary.	required
`payload`	`object \| None`	Parsed value that failed validation, when available.	`None`

Methods:¶

ScoringError ¶

Bases: GenerationError

A candidate scoring call failed before a valid result existed.

Examples:

from typevet.domain.errors import ScoringError

raise ScoringError("scoring failed")

ScoringUnsupportedCapabilityError ¶

Bases: ScoringError

The backend cannot honor the requested score stage or capability.

Examples:

from typevet.domain.errors import ScoringUnsupportedCapabilityError

raise ScoringUnsupportedCapabilityError("unsupported score stage")

ScoringValidationError ¶

Bases: ScoringError

Scores failed fail-closed coverage or finiteness rules.

Examples:

from typevet.domain.errors import ScoringValidationError

raise ScoringValidationError("missing scores for requested candidates")

TransportError ¶

TransportError(message: str)

Bases: GenerationError

The HTTP client failed before a usable llama.cpp response arrived.

Attributes:

Name	Type	Description
`status_code`	`None`	Always `None` for transport failures.
`body_snippet`	`None`	Always `None` when no response body was read.

Examples:

from typevet.domain.errors import TransportError

raise TransportError("llama.cpp request failed: connection refused")

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable summary of the client failure.	required

Methods:¶

ChoiceAnswer `dataclass` ¶

ChoiceAnswer(choice: str, confidence: float, probabilities: dict[str, float])

A selected choice with probabilities and confidence.

Attributes:

Name	Type	Description
`choice`	`str`	The name of the selected option.
`confidence`	`float`	Confidence in the selected choice, from 0 to 1.
`probabilities`	`dict[str, float]`	Probability of each choice by name.

Examples:

answer = ChoiceAnswer(
    choice="yes",
    confidence=0.8,
    probabilities={"yes": 0.8, "no": 0.2},
)
assert answer.choice in answer.probabilities

Methods:¶

__post_init__ ¶

__post_init__() -> None

Reject invalid confidence, probabilities, or a missing choice key.

Raises:

Type	Description
`TypeError`	When numeric fields are not numeric types.
`ValueError`	When values are out of range or probabilities do not sum to one.

NoulAnswer `dataclass` ¶

NoulAnswer(noul: float)

A yes/no answer with probability of true.

Attributes:

Name	Type	Description
`noul`	`float`	Probability of a yes answer, from 0 to 1.

Examples:

answer = NoulAnswer(noul=0.75)
assert 0.0 <= answer.noul <= 1.0

Methods:¶

__post_init__ ¶

__post_init__() -> None

Reject non-finite or out-of-range noul values.

Raises:

Type	Description
`TypeError`	When `noul` is not a numeric type.
`ValueError`	When `noul` is not finite or not in `[0.0, 1.0]`.

ScoreAnswer `dataclass` ¶

ScoreAnswer(
    score: float,
    confidence: float,
    legend: dict[int, str],
    probabilities: dict[int, float],
)

A scored response with rubric and probabilities.

Attributes:

Name	Type	Description
`score`	`float`	Expected score within the legend range.
`confidence`	`float`	Confidence in the score, from 0 to 1.
`legend`	`dict[int, str]`	Rubric descriptions keyed by integer level.
`probabilities`	`dict[int, float]`	Probability of each level.

Examples:

answer = ScoreAnswer(
    score=2.0,
    confidence=0.9,
    legend={0: "poor", 1: "fair", 2: "good"},
    probabilities={0: 0.1, 1: 0.2, 2: 0.7},
)
assert set(answer.legend) == set(answer.probabilities)

Methods:¶

__post_init__ ¶

__post_init__() -> None

Reject mismatched legend keys, bad probabilities, or out-of-range score.

Raises:

Type	Description
`TypeError`	When numeric fields or dict keys have wrong types.
`ValueError`	When values are out of range or probabilities do not sum to one.

Choice ¶

Choice(
    *,
    criteria: Mapping[str, str | dict[str, Any] | Sequence[Any] | None],
    instructions: str | dict[str, Any] | Sequence[Any] | None = None,
)

A question that selects between named alternatives.

Construction is keyword-only.

Attributes:

Name	Type	Description
`criteria`	`Mapping[str, str \| dict \| Sequence \| None]`	Labels mapped to descriptions or `None` when undescribed.
`instructions`	`str \| dict \| Sequence \| None`	The question to ask.

Examples:

question = Choice(
    criteria={"a": "Option A", "b": "Option B"},
    instructions="Choose one:",
)
assert len(question.criteria) == 2

Parameters:

Name	Type	Description	Default
`criteria`	`Mapping[str, str \| dict[str, Any] \| Sequence[Any] \| None]`	Labels mapped to descriptions.	required
`instructions`	`str \| dict[str, Any] \| Sequence[Any] \| None`	The question to ask.	`None`

Methods:¶

repr ¶

__repr__() -> str

Return a debug representation.

Noul ¶

Noul(
    *,
    instructions: str | dict[str, Any] | Sequence[Any] | None = None,
    criteria: dict[str, Any] | None = None,
)

A yes/no question with optional descriptions for either outcome.

Construction is keyword-only.

Attributes:

Name	Type	Description
`instructions`	`str \| dict \| Sequence \| None`	Question or statement to evaluate.
`criteria`	`dict \| None`	Optional `true` and `false` outcome descriptions.

Examples:

question = Noul(
    instructions="Is this valid?",
    criteria={"true": "Valid", "false": "Invalid"},
)
assert question.instructions is not None

Parameters:

Name	Type	Description	Default
`instructions`	`str \| dict[str, Any] \| Sequence[Any] \| None`	The yes/no question or statement to evaluate.	`None`
`criteria`	`dict[str, Any] \| None`	Optional descriptions of the yes and no outcomes.	`None`

Methods:¶

repr ¶

__repr__() -> str

Return a debug representation.

Score ¶

Score(
    *,
    criteria: Sequence[str | dict[str, Any] | Sequence[Any]],
    instructions: str | dict[str, Any] | Sequence[Any] | None = None,
)

A question that assigns a score using an ordered rubric.

Construction is keyword-only.

Attributes:

Name	Type	Description
`criteria`	`Sequence[str \| dict \| Sequence]`	Ordered rubric descriptions.
`instructions`	`str \| dict \| Sequence \| None`	What the model should rate.

Examples:

question = Score(
    criteria=["Poor", "Fair", "Good"],
    instructions="Rate the response:",
)
assert len(question.criteria) >= 2

Parameters:

Name	Type	Description	Default
`criteria`	`Sequence[str \| dict[str, Any] \| Sequence[Any]]`	Ordered descriptions, one per score from zero.	required
`instructions`	`str \| dict[str, Any] \| Sequence[Any] \| None`	What the model should rate.	`None`

Methods:¶

repr ¶

__repr__() -> str

Return a debug representation.

JudgmentResponse `dataclass` ¶

JudgmentResponse(
    model: str, usage: TokenUsage = TokenUsage(), answers: dict[str, Answer] = dict()
)

Answers grouped by question type with model and optional usage metadata.

Attributes:

Name	Type	Description
`model`	`str`	The model id that produced the answers.
`usage`	`TokenUsage`	Token usage metadata for the call.
`answers`	`dict[str, Answer]`	Answer objects keyed by question name.

Examples:

from typevet.domain.judgment_answers import NoulAnswer

response = JudgmentResponse(
    model="local-test",
    answers={"q1": NoulAnswer(noul=0.5)},
)
assert response.model == "local-test"

Attributes¶

nouls `property` ¶

nouls: dict[str, NoulAnswer]

Return yes/no answers keyed by question id.

Returns:

Type	Description
`dict[str, NoulAnswer]`	Subset of `answers` whose values are `NoulAnswer` instances.

choices `property` ¶

choices: dict[str, ChoiceAnswer]

Return choice answers keyed by question id.

Returns:

Type	Description
`dict[str, ChoiceAnswer]`	Subset of `answers` whose values are `ChoiceAnswer` instances.

scores `property` ¶

scores: dict[str, ScoreAnswer]

Return score answers keyed by question id.

Returns:

Type	Description
`dict[str, ScoreAnswer]`	Subset of `answers` whose values are `ScoreAnswer` instances.

TokenUsage `dataclass` ¶

TokenUsage(input_tokens: int | None = None, output_tokens: int | None = None)

Token counts for one judgment call when an adapter reports them.

Attributes:

Name	Type	Description
`input_tokens`	`int \| None`	Prompt tokens, when known.
`output_tokens`	`int \| None`	Completion tokens, when known.

Examples:

usage = TokenUsage(input_tokens=12, output_tokens=3)
assert usage.input_tokens == 12

ImageInput `dataclass` ¶

ImageInput(data: bytes, mime_type: str)

One decoded image to condition a judgment on.

The domain holds bytes only. URL and file resolution belongs to an adapter at the edge.

Attributes:

Name	Type	Description
`data`	`bytes`	Encoded image bytes in `mime_type` format.
`mime_type`	`str`	One of `SUPPORTED_IMAGE_MIME_TYPES`, matched exactly.

Examples:

from typevet.domain.media import ImageInput

ImageInput(data=png_bytes, mime_type="image/png")

Methods:¶

__post_init__ ¶

__post_init__() -> None

Reject empty bytes and mime types outside the v1 set.

Raises:

Type	Description
`ScoringValidationError`	When bytes are empty or the mime type is not in `SUPPORTED_IMAGE_MIME_TYPES`.

GenerationRequest `dataclass` ¶

GenerationRequest(
    prompt: str,
    schema: Mapping[str, Any],
    model: str,
    media: tuple[ImageInput, ...] = (),
)

One typed generation ask.

Attributes:

Name	Type	Description
`prompt`	`str`	Natural-language instruction for the model.
`schema`	`Mapping[str, Any]`	JSON Schema object as a mapping.
`model`	`str`	Backend model id or alias.
`media`	`tuple[ImageInput, ...]`	Images the prompt marks, one `MEDIA_MARKER` each, in marker order. Empty for a text ask.

Examples:

from typevet.domain.models import GenerationRequest

GenerationRequest(
    prompt="Return JSON.",
    schema={"type": "object", "additionalProperties": False},
    model="fake",
)

Methods:¶

__post_init__ ¶

__post_init__() -> None

Reject a blank field, a non-object schema root or a marker mismatch.

Stores media as a tuple, so a list input becomes immutable.

Raises:

Type	Description
`ValueError`	When prompt or model is blank, schema type is not object, or the media marker count differs from `len(media)`.
`TypeError`	When schema is not a mapping, or a media item is not an `ImageInput`.

GenerationResult `dataclass` ¶

GenerationResult(value: Mapping[str, Any], model: str, raw_text: str | None = None)

A value that validated against the request schema.

Attributes:

Name	Type	Description
`value`	`Mapping[str, Any]`	Validated JSON-compatible mapping.
`model`	`str`	Model id that produced the value.
`raw_text`	`str \| None`	Optional raw model text before parse.

Examples:

from typevet.domain.models import GenerationResult

GenerationResult(value={"ok": True}, model="fake")

ScoreStage ¶

Bases: StrEnum

When logits are read relative to sampler state.

Attributes:

Name	Type	Description
`PRE_SAMPLING`	`ScoreStage`	Softmax over full pre-sample logits (#116).
`POST_SAMPLING`	`ScoreStage`	After sampler candidate list (not M1 stock).

Examples:

stage = ScoreStage.PRE_SAMPLING
assert stage == "pre_sampling"

Functions:¶

build_and_validate_result ¶

build_and_validate_result(
    request: CandidateScoringRequest,
    *,
    raw_logprobs: Mapping[str, float],
    model: str,
    stage: ScoreStage | None = None,
    usage: TokenUsage | None = None,
    termination: ScoringTermination | None = None,
) -> CandidateScoringResult

Build a result with request order and fail-closed coverage checks.

Parameters:

Name	Type	Description	Default
`request`	`CandidateScoringRequest`	Original scoring ask.	required
`raw_logprobs`	`Mapping[str, float]`	Mapping from candidate label to raw logprob.	required
`model`	`str`	Model id recorded on the result.	required
`stage`	`ScoreStage \| None`	Stage recorded on the result; defaults to `request.stage`.	`None`
`usage`	`TokenUsage \| None`	Optional token usage metadata.	`None`
`termination`	`ScoringTermination \| None`	Optional termination metadata.	`None`

Returns:

Type	Description
`CandidateScoringResult`	Validated `CandidateScoringResult`.

Raises:

Type	Description
`ScoringValidationError`	Missing, duplicate, or unexpected labels, non-finite logprobs, or a positive logprob above `1e-6`.

compile_json_schema ¶

compile_json_schema(schema: Mapping[str, Any]) -> list[Decision]

Compile an ordered JSON Schema object into TypeLLM decisions.

Parameters:

Name	Type	Description	Default
`schema`	`Mapping[str, Any]`	Root object schema with `type`, `properties`, and optional `required`.	required

Returns:

Type	Description
`list[Decision]`	Decisions in property declaration order, with `depends_on` resolved
`list[Decision]`	and dependency layers validated.

Raises:

Type	Description
`SchemaError`	When the schema is invalid or unsupported.
`NotImplementedError`	For unsupported types without a finite enum.

Examples:

from typevet.domain.decision_compile import compile_json_schema

compile_json_schema(
    {
        "type": "object",
        "properties": {"n": {"type": "integer", "enum": [1, 2]}},
        "required": ["n"],
    }
)

execute_categorical_decision ¶

execute_categorical_decision(
    decision: Decision,
    *,
    prefix: str,
    candidates: tuple[CandidateTokenSpec, ...],
    port: CandidateScoringPort,
    model: str,
    temperature: float = 1.0,
    media: tuple[ImageInput, ...] = (),
) -> CategoricalExecutionResult

Score candidates, softmax logprobs, and pick the greedy choice.

Probabilities are the conditional distribution over the declared candidate set at temperature temperature (default 1) via log-sum-exp softmax.

Parameters:

Name	Type	Description	Default
`decision`	`Decision`	Closed categorical field (`Choice` or `Bool` syntax).	required
`prefix`	`str`	Rendered prompt prefix before candidate tokens.	required
`candidates`	`tuple[CandidateTokenSpec, ...]`	Single-token specs aligned 1:1 with `decision.choices`.	required
`port`	`CandidateScoringPort`	Scoring port; `ScoreStage.PRE_SAMPLING` is required.	required
`model`	`str`	Model id forwarded to the scoring request.	required
`temperature`	`float`	Softmax temperature; must be finite and strictly positive.	`1.0`
`media`	`tuple[ImageInput, ...]`	Images the `prefix` marks, one `MEDIA_MARKER` each.	`()`

Returns:

Type	Description
`CategoricalExecutionResult`	`CategoricalExecutionResult` with the input `decision`, selected
`CategoricalExecutionResult`	value, full probability table, and raw logprobs.

Raises:

Type	Description
`DecisionExecutionError`	Unsupported syntax, nullable field, permutations other than `1`, alignment, candidate shape, or invalid temperature.
`ScoringValidationError`	Propagated when the port result does not match the exact request (stage, count, label order, token ids) or holds a non-finite logprob, or when `prefix` markers do not match `media`. The check runs before softmax normalization.

dependency_layers ¶

dependency_layers(decisions: Sequence[Decision]) -> list[list[Decision]]

Return stable topological layers and validate dependencies.

Parameters:

Name	Type	Description	Default
`decisions`	`Sequence[Decision]`	Compiled decisions, typically from `compile_json_schema`.	required

Returns:

Type	Description
`list[list[Decision]]`	Lists of decisions that may run in parallel within each layer.

Raises:

Type	Description
`SchemaError`	For unknown dependencies, self-deps, or cycles.

Examples:

from typevet.domain.decisions import Decision, dependency_layers

a = Decision("a", "q", ())
b = Decision("b", "q", (), depends_on=("a",))
dependency_layers([b, a])

bind_control_candidates ¶

bind_control_candidates(
    original_labels: Sequence[Any], tokenize_content: Callable[[str], Sequence[int]]
) -> tuple[CandidateTokenSpec, ...]

Bind ordinal control strings to original labels via tokenize_content.

Uses control_binding_pairs for ("0", label) … ordering, then attaches single-token ids from tokenize_content.

Parameters:

Name	Type	Description	Default
`original_labels`	`Sequence[Any]`	Labels preserved on each `CandidateTokenSpec`.	required
`tokenize_content`	`Callable[[str], Sequence[int]]`	Tokenizer hook; each control `"0"`, `"1"`, … must encode to exactly one token id.	required

Returns:

Type	Description
`tuple[CandidateTokenSpec, ...]`	Single-token candidate specs in original-label order.

Raises:

Type	Description
`JudgmentValidationError`	Duplicate or empty labels, or multi-token controls. When leading controls are single tokens and a later one is not, the message states the tokenizer capacity: `native Choice supports N options on this tokenizer; got M`. The capacity message applies only when at least one control bound; a failure at control `"0"` keeps the per-control message.

judgment_original_labels ¶

judgment_original_labels(question: Question) -> tuple[str, ...]

Return ordered original labels for control binding.

Parameters:

Name	Type	Description	Default
`question`	`Question`	Native Noul, Choice, or Score question.	required

Returns:

Type	Description
`tuple[str, ...]`	Original label strings in scoring order.

Raises:

Type	Description
`JudgmentValidationError`	Empty or duplicate labels, or too few score levels.

normalize_choice ¶

normalize_choice(question: Choice, *, field_name: str) -> Decision

Map a Choice question to a Choice Decision preserving key order.

Parameters:

Name	Type	Description	Default
`question`	`Choice`	Multi-option judgment question.	required
`field_name`	`str`	Compiled property name on the output object.	required

Returns:

Type	Description
`Decision`	Executable Choice decision with criteria key order preserved.

Raises:

Type	Description
`JudgmentValidationError`	Invalid instructions or empty criteria.

normalize_noul ¶

normalize_noul(question: Noul, *, field_name: str) -> Decision

Map a Noul question to a Bool Decision with (False, True) choices.

Parameters:

Name	Type	Description	Default
`question`	`Noul`	Yes/no judgment question.	required
`field_name`	`str`	Compiled property name on the output object.	required

Returns:

Type	Description
`Decision`	Executable Bool decision with `return_probabilities=True`.

Raises:

Type	Description
`JudgmentValidationError`	When `instructions` is not a string or None.

normalize_question ¶

normalize_question(question: Question, *, field_name: str) -> Decision

Normalize any supported native question to an executable Decision.

Parameters:

Name	Type	Description	Default
`question`	`Question`	Native Noul, Choice, or Score question.	required
`field_name`	`str`	Compiled property name on the output object.	required

Returns:

Type	Description
`Decision`	Executable decision for categorical scoring.

Raises:

Type	Description
`JudgmentValidationError`	Unsupported question type or invalid payload.

normalize_score ¶

normalize_score(question: Score, *, field_name: str) -> Decision

Map a Score rubric to a Choice Decision over 0..n-1 levels.

Parameters:

Name	Type	Description	Default
`question`	`Score`	Ordered rubric judgment question.	required
`field_name`	`str`	Compiled property name on the output object.	required

Returns:

Type	Description
`Decision`	Executable Choice decision whose choices are integer rubric indices.

Raises:

Type	Description
`JudgmentValidationError`	Invalid instructions or fewer than two levels.

question_types ¶

question_types(questions: Mapping[str, Any]) -> dict[str, str | None]

Map each question id to its wire type name.

Typed questions map to noul, choice or score. Raw wire dictionaries map to their type value when that value is a string.

Parameters:

Name	Type	Description	Default
`questions`	`Mapping[str, Any]`	Question objects or raw wire dictionaries keyed by id.	required

Returns:

Type	Description
`dict[str, str \| None]`	The id to type mapping; `None` where a raw question has no string type.

count_media_markers ¶

count_media_markers(text: str) -> int

Count MEDIA_MARKER occurrences in a rendered prefix.

Parameters:

Name	Type	Description	Default
`text`	`str`	Rendered prompt prefix.	required

Returns:

Type	Description
`int`	Number of documented media markers in `text`.

Examples:

from typevet.domain.media import MEDIA_MARKER, count_media_markers

assert count_media_markers(f"{MEDIA_MARKER} caption") == 1

compile_question_records ¶

compile_question_records(
    records: Sequence[Mapping[str, Any]], *, additional_properties: bool = False
) -> list[Decision]

Compile question records to TypeLLM Decision values.

Parameters:

Name	Type	Description	Default
`records`	`Sequence[Mapping[str, Any]]`	Loader-shaped question list.	required
`additional_properties`	`bool`	Forwarded to `question_records_to_json_schema`.	`False`

Returns:

Type	Description
`list[Decision]`	Decisions from `compile_json_schema` in property order.

question_record_to_property ¶

question_record_to_property(record: Mapping[str, Any]) -> tuple[str, dict[str, Any]]

Map one System One-style question record to a JSON Schema property.

Parameters:

Name	Type	Description	Default
`record`	`Mapping[str, Any]`	Mapping with `name`, `syntax`, and `instructions`. Choice and Score require `labels`. Noul uses boolean when `labels` is omitted; two string labels yield a closed string enum (BoolQ-style).	required

Returns:

Type	Description
`tuple[str, dict[str, Any]]`	Field name and property schema object.

Raises:

Type	Description
`ValueError`	When the record shape or labels are invalid.
`TypeError`	When `record` or `labels` have the wrong type.

question_records_to_json_schema ¶

question_records_to_json_schema(
    records: Sequence[Mapping[str, Any]], *, additional_properties: bool = False
) -> dict[str, Any]

Build a root object schema from ordered question records.

Parameters:

Name	Type	Description	Default
`records`	`Sequence[Mapping[str, Any]]`	Non-empty sequence of question mappings (loader export order).	required
`additional_properties`	`bool`	Value for `additionalProperties` on the root.	`False`

Returns:

Type	Description
`dict[str, Any]`	Object schema with `properties`, `required`, and `type: object`.

Raises:

Type	Description
`ValueError`	When `records` is empty or contains duplicate names.

Name	Type	Description
`Decision`	`type`	One compiled TypeLLM field from JSON Schema.
`BackendHttpError`	`type`	llama.cpp HTTP status 400 or above.
`CandidateScoringRequest`	`type`	Prompt and candidate tokens to score.
`ImageInput`	`type`	One image to condition a judgment on.
`MEDIA_MARKER`	`str`	Documented media placeholder in a scoring prefix.
`SUPPORTED_IMAGE_MIME_TYPES`	`frozenset`	Accepted v1 image mime types.
`count_media_markers`	`callable`	Count media markers in a prefix.
`CandidateScoringResult`	`type`	Fail-closed scored candidates.
`CategoricalExecutionResult`	`type`	Greedy categorical execute outcome.
`DecisionExecutionError`	`type`	Categorical execute rejected inputs.
`GemmaTemplateError`	`type`	Gemma served-template or answer-prefix violation.
`GenerationError`	`type`	Base failure for a generation call.
`GenerationUnsupportedCapabilityError`	`type`	Backend cannot honor the ask.
`TransportError`	`type`	HTTP client failure before a response.
`GenerationRequest`	`type`	Prompt, schema and model ask.
`GenerationResult`	`type`	Validated structured value.
`JudgmentResponse`	`type`	Typed answers from a judgment call.
`MAX_ENUM_CHOICES`	`int`	Upper bound on enum size when compiling.
`Noul`	`type`	Yes/no judgment question.
`Question`	`type`	Union of judgment question types.
`MAX_PERMUTATIONS`	`int`	Upper bound on enum permutation budget.
`SchemaError`	`type`	Invalid or unsupported schema for compilation.
`SchemaValidationError`	`type`	Output failed the requested schema.
`ScoringError`	`type`	Base failure for a candidate-scoring call.
`compile_json_schema`	`callable`	Compile object schema to decisions.
`dependency_layers`	`callable`	Topological layers for decision dependencies.
`execute_categorical_decision`	`callable`	Choice/Bool execution through the injected scoring port; no I/O of its own.
`bind_control_candidates`	`callable`	Ordinal control tokens for native labels.
`judgment_original_labels`	`callable`	Ordered labels for a native question.
`normalize_question`	`callable`	Native question to executable Decision.
`compile_question_records`	`callable`	Question records to decisions.
`question_record_to_property`	`callable`	One question record to a JSON Schema property.
`question_records_to_json_schema`	`callable`	Question records to an object schema.

Domain package¶

typevet.domain ¶

Attributes¶

Answer module-attribute ¶

Question module-attribute ¶

Classes¶

CandidateScoringRequest dataclass ¶

Methods:¶

__post_init__ ¶

CandidateTokenSpec dataclass ¶

Methods:¶

__post_init__ ¶

CandidateScoringResult dataclass ¶

ScoredCandidate dataclass ¶

ScoringTermination dataclass ¶

CategoricalExecutionResult dataclass ¶

Decision dataclass ¶

SchemaError ¶

BackendHttpError ¶

Methods:¶

DecisionExecutionError ¶

GemmaTemplateError ¶

GenerationError ¶

GenerationUnsupportedCapabilityError ¶

JudgmentError ¶

JudgmentValidationError ¶

SchemaValidationError ¶

Methods:¶

ScoringError ¶

ScoringUnsupportedCapabilityError ¶

ScoringValidationError ¶

TransportError ¶

Methods:¶

ChoiceAnswer dataclass ¶

Methods:¶

__post_init__ ¶

NoulAnswer dataclass ¶

Methods:¶

__post_init__ ¶

ScoreAnswer dataclass ¶

Methods:¶

__post_init__ ¶

Choice ¶

Methods:¶

__repr__ ¶

Noul ¶

Methods:¶

__repr__ ¶

Score ¶

Methods:¶

__repr__ ¶

JudgmentResponse dataclass ¶

Attributes¶

nouls property ¶

choices property ¶

scores property ¶

TokenUsage dataclass ¶

ImageInput dataclass ¶

Methods:¶

__post_init__ ¶

GenerationRequest dataclass ¶

Methods:¶

__post_init__ ¶

GenerationResult dataclass ¶

ScoreStage ¶

Functions:¶

build_and_validate_result ¶

compile_json_schema ¶

execute_categorical_decision ¶

dependency_layers ¶

bind_control_candidates ¶

judgment_original_labels ¶

normalize_choice ¶

normalize_noul ¶

normalize_question ¶

normalize_score ¶

question_types ¶

count_media_markers ¶

compile_question_records ¶

question_record_to_property ¶

Answer `module-attribute` ¶

Question `module-attribute` ¶

CandidateScoringRequest `dataclass` ¶

CandidateTokenSpec `dataclass` ¶

CandidateScoringResult `dataclass` ¶

ScoredCandidate `dataclass` ¶

ScoringTermination `dataclass` ¶

CategoricalExecutionResult `dataclass` ¶

Decision `dataclass` ¶

ChoiceAnswer `dataclass` ¶

NoulAnswer `dataclass` ¶

ScoreAnswer `dataclass` ¶

repr ¶

repr ¶

repr ¶

JudgmentResponse `dataclass` ¶

nouls `property` ¶

choices `property` ¶

scores `property` ¶

TokenUsage `dataclass` ¶

ImageInput `dataclass` ¶

GenerationRequest `dataclass` ¶

GenerationResult `dataclass` ¶