Root package

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

typevet

typevet: type-safe structured generation under hexagonal architecture.

Examples:

from typevet import GenerationRequest, GenerationResult
from typevet.adapters.outbound import FakeGenerationAdapter

schema = {
    "type": "object",
    "properties": {"ok": {"type": "boolean"}},
    "required": ["ok"],
    "additionalProperties": False,
}
port = FakeGenerationAdapter(value={"ok": True})
result = port.generate(
    GenerationRequest(prompt="Say ok.", schema=schema, model="fake")
)
assert result.value["ok"] is True

See Also

• typevet._version: Resolves __version__ from distribution metadata
• typevet.domain: Request, result and error types
• typevet.ports: GenerationPort protocol
• typevet.adapters.outbound: llama.cpp and fake adapters
• typevet.runtime: Source of the decide_categorical re-export

Attributes:

Name	Type	Description
BackendHttpError	type	llama.cpp HTTP error status with body snippet.
GenerationError	type	Base failure for a generation call.
TransportError	type	HTTP client failure before a response.
AsyncGenerationPort	type	Structural protocol for async typed generation.
GenerationPort	type	Structural protocol for typed generation.
GenerationRequest	type	Prompt, schema and model ask.
GenerationResult	type	Validated structured value.
SchemaValidationError	type	Output failed the requested schema.
decide_categorical	callable	M1 categorical decision via scoring port; re-exported from typevet.runtime.categorical.
__version__	str	Installed distribution version; matches importlib.metadata.version("typevet") when the package is on PYTHONPATH. Exported in __all__.

Classes

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:

GenerationError

Bases: Exception

A typed generation call failed before a valid result existed.

Examples:

from typevet.domain.errors import GenerationError

raise GenerationError("transport failed")

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:

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:

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")

AsyncGenerationPort

Bases: Protocol

Structural protocol for async typed structured generation.

Examples:

from typevet.ports.async_generation import AsyncGenerationPort
from typevet.adapters.outbound import AsyncFakeGenerationAdapter

port: AsyncGenerationPort = AsyncFakeGenerationAdapter(value={"a": 1})

Methods:

generate async

generate(request: GenerationRequest) -> GenerationResult

Produce a value that validates against request.schema.

Parameters:

Name	Type	Description	Default
request	GenerationRequest	Prompt, JSON Schema mapping, model id and optional images that the prompt marks.	required

Returns:

Type	Description
GenerationResult	A validated GenerationResult.

Raises:

Type	Description
TransportError	HTTP client failure (no response).
BackendHttpError	llama.cpp HTTP status 400+.
GenerationUnsupportedCapabilityError	The backend cannot send the request images; raised before any call.
GenerationError	Other parse or shape failure.
SchemaValidationError	Output fails the schema (fail-fast; not retried in-repo).
SchemaError	Not raised here; raised by compile_json_schema when the schema cannot be compiled.

GenerationPort

Bases: Protocol

Structural protocol for typed structured generation.

Examples:

from typevet.ports.generation import GenerationPort
from typevet.testing import StaticGenerationFake

port: GenerationPort = StaticGenerationFake({"a": 1})

Methods:

generate

generate(request: GenerationRequest) -> GenerationResult

Produce a value that validates against request.schema.

Parameters:

Name	Type	Description	Default
request	GenerationRequest	Prompt, JSON Schema mapping, model id and optional images that the prompt marks.	required

Returns:

Type	Description
GenerationResult	A validated GenerationResult.

Raises:

Type	Description
TransportError	HTTP client failure (no response).
BackendHttpError	llama.cpp HTTP status 400+.
GenerationUnsupportedCapabilityError	The backend cannot send the request images; raised before any call.
GenerationError	Other parse or shape failure.
SchemaValidationError	Output fails the schema (fail-fast; not retried in-repo).
SchemaError	Not raised here; raised by compile_json_schema when the schema cannot be compiled.

Functions:

decide_categorical

decide_categorical(
    *,
    scoring_port: CandidateScoringPort,
    model: str,
    candidates: tuple[CandidateTokenSpec, ...],
    field: Decision | Mapping[str, Any],
    context: str = "",
    inject_prefix: bool = False,
    temperature: float = 1.0,
    **legacy: Any,
) -> CategoricalExecutionResult

Score categorical candidates and return the greedy choice plus distribution.

Validates the ask before any scoring IO. Compiles schema when given; accepts a pre-compiled Decision instead. Injected scoring_port values are never closed by this function (construct and own LlamaCppCandidateScoringAdapter at the call site when needed).

By default the library composes the scoring prefix from context plus rendered field instructions. Set inject_prefix=True and pass prefix= to score an exact caller-owned prefix (context does not alter it).

Parameters:

Name	Type	Description	Default
scoring_port	CandidateScoringPort	Offline fake or llama.cpp adapter implementing scoring.	required
model	str	Backend model id forwarded to the scorer.	required
candidates	tuple[CandidateTokenSpec, ...]	Single-token specs aligned with the decision choices.	required
field	Decision | Mapping[str, Any]	Compiled Decision or JSON Schema with one categorical property.	required
context	str	User or task text for the judgment (native path).	''
inject_prefix	bool	When true, require prefix= and score it verbatim.	False
temperature	float	Softmax temperature for the executor (default 1.0).	1.0

Other Parameters:

Name	Type	Description
legacy	Any	prefix for inject mode; prompt as deprecated context alias. Other keys raise DecisionExecutionError.

Returns:

Type	Description
CategoricalExecutionResult	Greedy value, full probability table, and raw logprobs from the executor.

Raises:

Type	Description
DecisionExecutionError	Invalid ask, unsupported M1 shape, permutations other than 1, or unknown kwargs.
SchemaError	Schema cannot be compiled.
ScoringValidationError	Propagated from the scoring port or executor.