Ports package

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

typevet.ports

Ports for typed generation.

Examples:

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

port: GenerationPort = StaticGenerationFake({"ok": True})

See Also

• typevet.ports.generation: GenerationPort protocol
• typevet.ports.async_generation: AsyncGenerationPort protocol
• typevet.ports.framing: ModelFramingPort protocol
• typevet.adapters.outbound: Adapters that implement the port

Attributes:

Name	Type	Description
AsyncGenerationPort	type	Structural protocol for async typed generation.
GenerationPort	type	Structural protocol for typed generation.
JudgmentPort	type	Structural protocol for System One-shaped judgment.
CandidateScoringPort	type	Structural protocol for candidate logprobs.
ModelFramingPort	type	Structural protocol for model turn framing.
ScoringPort	type	Alias for CandidateScoringPort.

Classes

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.

ModelFramingPort

Bases: Protocol

Structural protocol for model-specific scoring-prefix framing.

Examples:

from typevet.ports.framing import ModelFramingPort

framing: ModelFramingPort
_ = framing.compose_prefix

Methods:

compose_prefix

compose_prefix(*, context: str, field_block: str, media: tuple[ImageInput, ...]) -> str

Wrap context and field block in this model's turn markers.

Parameters:

Name	Type	Description	Default
context	str	Rendered state context; holds one media marker per image.	required
field_block	str	Rendered field instructions.	required
media	tuple[ImageInput, ...]	Images the prefix marks, in order.	required

Returns:

Type	Description
str	Scoring prefix ending at the answer boundary. The prefix must keep
str	one media marker per entry in media.

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.

JudgmentPort

Bases: Protocol

Structural protocol for System One-shaped typed judgment.

Examples:

from typevet.ports.judgment import JudgmentPort

port: JudgmentPort
_ = port.judge

Methods:

judge

judge(
    state: str | dict[str, Any] | list[Any],
    questions: Mapping[str, Question | Mapping[str, Any]],
    model: str,
    *,
    media: tuple[ImageInput, ...] | None = None,
) -> JudgmentResponse

Evaluate state against named questions.

None or an empty media tuple is the text path and behaves as it did before images existed. A non-empty tuple conditions every scored field on the same images.

Parameters:

Name	Type	Description	Default
state	str | dict[str, Any] | list[Any]	Content under evaluation (text, JSON object, or array).	required
questions	Mapping[str, Question | Mapping[str, Any]]	Question names to typed questions or raw wire dictionaries.	required
model	str	Backend model id or alias.	required
media	tuple[ImageInput, ...] | None	Images to condition every scored field on, in order.	None

Returns:

Type	Description
JudgmentResponse	Typed JudgmentResponse with one answer per question.

Raises:

Type	Description
JudgmentError	When the call fails before answers exist. Concrete subclasses depend on the adapter.

CandidateScoringPort

Bases: Protocol

Structural protocol for complete candidate logprob scoring.

Examples:

from typevet.ports.scoring import CandidateScoringPort

port: CandidateScoringPort
_ = port.score_candidates

Methods:

score_candidates

score_candidates(request: CandidateScoringRequest) -> CandidateScoringResult

Score every requested candidate at the contracted stage.

Parameters:

Name	Type	Description	Default
request	CandidateScoringRequest	Model id, rendered prefix, ordered candidates, and stage.	required

Returns:

Type	Description
CandidateScoringResult	Identity-preserving CandidateScoringResult with one raw logprob
CandidateScoringResult	per requested candidate label.

Raises:

Type	Description
ScoringError	When the call fails before a valid result exists. Concrete subclasses depend on the adapter.
ScoringValidationError	Missing, duplicate, or unexpected candidate labels, or non-finite logprobs (fail-closed; remaining candidates are never renormalized to fill gaps).
ScoringUnsupportedCapabilityError	When the backend or adapter cannot honor request.stage.