cadrumo.application.local_reader module

The local document reader as one provisioned unit: runtime, role models, readiness.

Invoice extraction reads a text-layer document with the TEXT_EXTRACTION model and a scanned one with the VISION_TRANSCRIPTION model; column mapping and the supply-nature proposal use their own roles. Each role reads the model its setting names, so provisioning, status and the reader itself must resolve the same identifier – configured_role_model() is that single resolution.

Starting, installing and pulling live in provisioning_host and provisioning_runtime; this module turns their measurements into the projections a status surface renders and the per-role probe an ingestion lane consults before spending a document. Its one write is the fitness verdict verify_role_target() records in provisioning_fitness; status reads that record and never probes unless asked.

EXTRACTION_READER_ROLES: tuple[ModelRole, ...]

The roles invoice evidence extraction reads with, text layer first.

FITNESS_PROBED_ROLES: tuple[ModelRole, ...]

Roles whose readiness includes a fitness probe. Presence answers “is the model there”; only the text reader has shown that a model can be present, loaded and answering, and still never produce a parseable extraction – a vision model configured in the text role spends its whole answer budget and returns nothing the parser can read.

class RoleFitnessOutcome(**data)[source]

Bases: ProvisioningOutcome

Whether a model produced a usable answer to its role’s real request shape.

fit is the decision. answer_parseable and grounded say which half failed: a reply the parser could not read at all, or a readable reply whose values did not match the probe document. timed_out marks a model that did not finish its answer within the probe’s bound – a verdict about the model on this host, recorded like any other. transport_failed marks a probe that never got an answer for any other reason, which says nothing about the model and is therefore never recorded.

Parameters:

data (Any)

role: ModelRole
model: str
fit: bool
answer_parseable: bool
grounded: bool
timed_out: bool
transport_failed: bool
output_tokens: int | None
answer_budget_tokens: int
elapsed_ms: int
property settled: bool

Return whether this outcome is a verdict about the model rather than about the transport.

property verdict: RoleFitnessVerdict

Return the recorded verdict kind for a settled outcome.

class RoleFitnessState(*values)[source]

Bases: StrEnum

What a status surface knows about a probed role’s fitness.

NOT_VERIFIED is its own state: no verdict is recorded for the model’s current weights, which is not evidence that the model is unfit.

FIT
UNFIT
TIMED_OUT
NOT_VERIFIED
class LocalReaderDocumentReadiness(*values)[source]

Bases: StrEnum

Which invoice documents this machine can turn into drafts.

Text-layer documents are read by label rules that need no runtime and no model, so they are always readable; the model only fills fields the labels do not print. Every document is readable only when LocalReaderStatus.extraction_ready.

ALL_DOCUMENTS
TEXT_LAYER_ONLY
probe_role_fitness(role, model, settings, *, text_probe)[source]

Run role’s fitness probe against model now, or return None when the role is not probed.

Records nothing; verify_role_target() is the only writer of the recorded verdict.

Return type:

RoleFitnessOutcome | None

Parameters:
recorded_role_fitness(role, model, digest, settings)[source]

Return the recorded fitness of model’s current weights, or None when the role is not probed.

Return type:

RoleFitnessState | None

Parameters:
verify_role_target(target, *, settings=None, text_probe=None)[source]

Verify a provisioning target is loaded, answering and fit for every role it serves.

Readiness first, through verify_model_ready(), then – for a role in FITNESS_PROBED_ROLES and when a probe is supplied – the role’s real request shape. An unfit or too-slow model is reported not ready with its own condition, so verify cannot pass a model the reader will never get an answer from. Every settled probe is recorded against the model’s current digest; status reads that record instead of probing.

Raises:

ValueError – When target carries no model (a refused selection).

Return type:

ReadinessOutcome

Parameters:
local_reader_service(role)[source]

Return the stable diagnostic row id for one role’s local reader.

Return type:

str

Parameters:

role (ModelRole)

configured_role_model(role, settings=None)[source]

Return the runtime model id the on-host reader for role actually loads.

The three document and table roles read their own settings; the supply-nature proposer resolves through catalogue selection, so it returns whatever that selection names, or None when nothing is selectable.

Return type:

str | None

Parameters:
class RoleModelTarget(**data)[source]

Bases: BaseModel

One distinct model to provision with every role it serves, or one role’s refusal.

model is None exactly when catalogue selection refused the role; the selection’s facts and verdict are then carried so the caller reports why nothing will be fetched for it.

Parameters:

data (Any)

model: str | None
roles: tuple[ModelRole, ...]
requirement_bytes: int | None
selection_facts: Mapping[str, ProvisioningFactValue]
selection_verdict: PreconditionVerdict | None
select_role_model(role, settings, *, explicit=None)[source]

Resolve role through catalogue selection, honouring an operator-set model.

The configured setting is passed as an override only when it differs from the catalogue default, so a default configuration keeps every selection bar – context window, licence, headroom – and an operator’s choice is honoured with its advisories. explicit outranks both.

Return type:

ModelSelection

Parameters:
role_model_targets(roles=None, settings=None, *, explicit_model=None)[source]

Return the distinct models to provision for roles (every role by default).

Roles sharing one model yield one target, so provisioning every role pulls each model once. A role whose selection refuses yields its own target with no model and the refusal attached.

Return type:

tuple[RoleModelTarget, ...]

Parameters:
probe_local_reader(role, settings=None, *, installed=None)[source]

Report whether the on-host reader for role can run right now.

Unavailable when the runtime does not answer, or when it answers without the model this role’s reader loads. An ingestion lane consults this per role, so a missing vision model never stops text-layer reads and a missing text model is not hidden behind an installed vision model.

Parameters:

  • role (ModelRole) – The reader role a document needs.

  • settings (Settings | None) – Settings carrying the endpoint and role models.

  • installed (tuple[InstalledModel, ...] | None) – An inventory already read; read from the runtime when omitted.

Return type:

DependencyStatus

Returns:

A DependencyStatus on the local-reader:<role> row. Never raises.

class LocalReaderRoleStatus(**data)[source]

Bases: BaseModel

One role’s reader: which model it loads, and what the runtime says about it.

installed, resident and load_admitted are None when the answer could not be measured – an unreachable runtime has no inventory, and None must not render as “not installed”.

Parameters:

data (Any)

role: ModelRole
model: str | None
installed: bool | None
resident: bool | None
load_admitted: bool | None
contention_causes: tuple[ContentionCause, ...]
fitness: RoleFitnessState | None
fit_for_role: bool | None
ready: bool
failed_condition_id: str | None
class LocalReaderStatus(**data)[source]

Bases: BaseModel

The whole local reader at one moment, for a status area or doctor row.

extraction_ready is true only when the runtime answers, both invoice-extraction roles have their models installed and the text model’s current weights carry a recorded fit verdict; it is the single claim a surface may use to say every document can be read on this machine. document_readiness says which documents can be read either way, and text_layer_model_fill_available whether text-layer fields the labels do not print can be filled by the text model.

Parameters:

data (Any)

host: RuntimeHostStatus
roles: tuple[LocalReaderRoleStatus, ...]
last_pull: RuntimePullRecord | None
extraction_ready: bool
document_readiness: LocalReaderDocumentReadiness
text_layer_model_fill_available: bool
read_local_reader_status(settings=None, *, roles=None, assess_load=True, which=None, pull_record=<function last_runtime_pull>, text_probe=None)[source]

Measure the runtime host and every role’s model into one projection.

Reads only: nothing is started, pulled or loaded. assess_load adds the admission check for installed models that are not yet resident, which reads hardware counters and can be skipped by a surface that refreshes often. Without text_probe the text model’s fitness is the verdict verify recorded for its current digest, and a model with no recorded verdict is not verified rather than unfit. With text_probe the check runs now and its answer is reported without being recorded.

Return type:

LocalReaderStatus

Parameters: