osrforge.providers.base

The provider protocol and its request/response types.

Exactly one seam wide: a single generate method taking a structured-output request. Schema enforcement is the provider's contract — generate either returns data that validates against request.schema or raises SchemaValidationError after its retry budget, so callers trust response.data.

ImagePart dataclass

ImagePart(png: bytes)

One ordered image content part of a request — a page render.

Preprocessing emits PNG; adapters do their own base64/data-URL packaging.

png instance-attribute

png: bytes

ModelProvider

Bases: Protocol

The one seam between the pipeline and any model vendor.

Any object with a conforming generate method is a provider — no subclassing, no registration. The provider owns schema enforcement: validate with ensure_schema (and retry as needed) before returning, so callers can trust response.data.

Examples:

from osrforge.contracts.run import TokenUsage
from osrforge.providers.base import ModelRequest, ModelResponse, ensure_schema

class MyVendorProvider:
    def generate(self, request: ModelRequest) -> ModelResponse:
        data = my_vendor_call(request.system, request.parts, request.schema)
        ensure_schema(data, request.schema, request.tag)
        return ModelResponse(data=data, usage=TokenUsage(), model_id="my-model")

generate

generate(request: ModelRequest) -> ModelResponse

Run one structured-output completion.

Parameters:

Name	Type	Description	Default
request	ModelRequest	System text, ordered content parts, and the JSON Schema the response must satisfy.	required

Returns:

Type	Description
ModelResponse	The parsed, schema-validated response with token usage.

Raises:

Type	Description
ProviderError	On transport, auth, or rate-limit exhaustion.
SchemaValidationError	If no schema-valid response was obtained within the provider's retry budget.

ModelRequest dataclass

ModelRequest(tag: str, system: str, parts: tuple[TextPart | ImagePart, ...], schema: dict[str, object])

One structured-output completion request.

Attributes:

Name	Type	Description
tag	str	A short stable label like survey or probe.image-limits — a pipeline stage name or capability-probe id, never free prose. It names fixture files, attributes usage, and participates in the fingerprint (it is part of request identity).
system	str	The system text.
parts	tuple[TextPart | ImagePart, ...]	The ordered text and image content parts.
schema	dict[str, object]	The JSON Schema the response data must satisfy.

tag instance-attribute

tag: str

system instance-attribute

system: str

parts instance-attribute

parts: tuple[TextPart | ImagePart, ...]

schema instance-attribute

schema: dict[str, object]

fingerprint

fingerprint() -> str

Return the request's identity hash, shared by fixtures and future run-caching.

The fingerprint is the sha256 hex of the canonical JSON (sorted keys, compact separators, UTF-8) of the request with each image part replaced by {"sha256": ..., "bytes": ...}.

Returns:

Type	Description
str	A 64-character sha256 hex digest.

ModelResponse dataclass

ModelResponse(data: object, usage: TokenUsage, model_id: str)

One completion's parsed, schema-valid result.

Attributes:

Name	Type	Description
data	object	The parsed JSON, already validated against the request's schema.
usage	TokenUsage	Token consumption as the provider reported it.
model_id	str	The model identifier the service returned.

data instance-attribute

data: object

usage instance-attribute

usage: TokenUsage

model_id instance-attribute

model_id: str

TextPart dataclass

TextPart(text: str)

One ordered text content part of a request.

A page's extracted text layer, or prompt text like a batch header.

text instance-attribute

text: str

ensure_schema

ensure_schema(data: object, schema: dict[str, object], context: str) -> None

Validate response data against a request's JSON Schema.

Parameters:

Name	Type	Description	Default
data	object	The parsed response JSON.	required
schema	dict[str, object]	The JSON Schema from the request.	required
context	str	Where the data came from, for the error message (e.g. a tag or a fixture path).	required

Raises:

Type	Description
SchemaValidationError	If the data doesn't satisfy the schema.