cadrumo.application.local_reader_operation module

Supervised operation for provisioning the local document reader from any frontend.

One definition, local-reader.provision, carries every action a status area or the command line offers – install, start, pull, load, verify, remove, and the one-shot setup that runs the first five in order – so a TUI button and aeat config provision <verb> run the same implementation. Installing runs a package manager and therefore requires consent on the request; every frontend gathers that consent explicitly before submitting.

Process control is injected. The application layer never spawns a process itself; the entrypoint composition binds the outbound adapters.

LOCAL_READER_OPERATION_SUBJECT

The runtime is one per host, so every provisioning request shares one subject and the definition-subject lease serialises them.

class LocalReaderProvisionAction(*values)

Bases: StrEnum

What one provisioning operation does.

INSTALL

START

PULL

LOAD

VERIFY

REMOVE

SETUP

class LocalReaderSetupStep(*values)

Bases: StrEnum

The ordered steps of a one-shot setup.

INSTALL

START

PULL

LOAD

VERIFY

class LocalReaderSetupStepState(*values)

Bases: StrEnum

What one setup step did: nothing needed, a change, a refusal, or not run.

UNCHANGED

CHANGED

FAILED

NOT_REACHED

local_reader_setup_phase(step)

Return the declared phase code a setup publishes when step begins.

Return type:

str

Parameters:

step (LocalReaderSetupStep)

class LocalReaderProvisionRequest(**data)

Bases: CredentialFreeOperationRequest

One provisioning action, over one role’s model, a named model, or every role’s.

consent is the operator’s explicit agreement to run the package-manager install and is accepted only by the actions that may install. model names a model outright and is accepted only by load and remove; remove requires a role or a model so it never deletes every model by default.

Parameters:

data (Any)

action: LocalReaderProvisionAction

role: ModelRole | None

model: str | None

consent: bool

build_local_reader_install_request(*, consent)

Build the request that installs the runtime; nothing is installed without consent.

Return type:

OperationRequest[LocalReaderProvisionRequest]

Parameters:

consent (bool)

build_local_reader_start_request()

Build the request that starts the local runtime when it is not answering.

Return type:

OperationRequest[LocalReaderProvisionRequest]

build_local_reader_pull_request(role=None)

Build the request that pulls role’s model, or every reader role’s model.

Return type:

OperationRequest[LocalReaderProvisionRequest]

Parameters:

role (ModelRole | None)

build_local_reader_load_request(role=None, model=None)

Build the request that loads role’s model, a named model, or every role’s model.

Return type:

OperationRequest[LocalReaderProvisionRequest]

Parameters:

• role (ModelRole | None)

• model (str | None)

build_local_reader_verify_request(role=None)

Build the request that verifies role’s model, or every reader role’s model.

Return type:

OperationRequest[LocalReaderProvisionRequest]

Parameters:

role (ModelRole | None)

build_local_reader_remove_request(role=None, model=None)

Build the request that removes role’s model or a named model from the runtime’s store.

Return type:

OperationRequest[LocalReaderProvisionRequest]

Parameters:

• role (ModelRole | None)

• model (str | None)

build_local_reader_setup_request(*, consent)

Build the one-shot setup request: install (with consent), start, pull, load, verify.

Return type:

OperationRequest[LocalReaderProvisionRequest]

Parameters:

consent (bool)

class LocalReaderModelOutcome(**data)

Bases: BaseModel

What happened to one model, or to one role whose selection refused.

already_satisfied marks a model that needed nothing: already pulled for a pull, already resident for a load. step names the setup step that produced the item, and is absent outside setup.

Parameters:

data (Any)

model: str | None

roles: tuple[ModelRole, ...]

succeeded: bool

already_satisfied: bool

step: LocalReaderSetupStep | None

bytes_fetched: int | None

freed_bytes: int | None

was_installed: bool

resident: bool

answered: bool

elapsed_ms: int | None

facts: Mapping[str, ProvisioningFactValue]

precondition_verdict: PreconditionVerdict | None

property failed_condition_id: str | None

Return the refused condition, when there is one.

class LocalReaderInstallOutcome(**data)

Bases: BaseModel

What the install request found and did.

Parameters:

data (Any)

installed: bool

already_installed: bool

installer: RuntimeInstaller

consented: bool

installer_exit_code: int | None

class LocalReaderSetupStepOutcome(**data)

Bases: BaseModel

One setup step’s state and, when it failed, the refused condition.

Parameters:

data (Any)

step: LocalReaderSetupStep

state: LocalReaderSetupStepState

failed_condition_id: str | None

class LocalReaderProvisionOutcome(**data)

Bases: BaseModel

The settled result of one provisioning operation.

facts and precondition_verdict describe the runtime-level action (install or start); per-model detail is in models. For setup, steps lists every step in order and stopped_step names the step that failed, after which every later step is not_reached.

Parameters:

data (Any)

action: LocalReaderProvisionAction

succeeded: bool

runtime_started: bool

already_running: bool

started_pid: int | None

install: LocalReaderInstallOutcome | None

models: tuple[LocalReaderModelOutcome, ...]

steps: tuple[LocalReaderSetupStepOutcome, ...]

stopped_step: LocalReaderSetupStep | None

facts: Mapping[str, ProvisioningFactValue]

precondition_verdict: PreconditionVerdict | None

property failed_condition_id: str | None

Return the first refused condition across the runtime action, steps and models.

class LocalReaderFactV1(**data)

Bases: BaseModel

One locale-neutral provisioning fact, as an immutable key/value pair.

Parameters:

• key (str)

• value (str | int | bool)

key: str

value: str | int | bool

local_reader_fact_mapping(facts)

Return published facts as the mapping a frontend payload carries.

Return type:

dict[str, str | int | bool]

Parameters:

facts (tuple[LocalReaderFactV1, ...])

local_reader_public_verdict(failed_condition_id, verdict_facts)

Rebuild the provisioning refusal a public result names, or None when nothing was refused.

Every provisioning refusal is a no-recovery runtime observation over its condition and facts, so the condition and the evidence facts are the whole verdict; the projector refuses to publish one that would not rebuild exactly.

Return type:

PreconditionVerdict | None

Parameters:

• failed_condition_id (str | None)

• verdict_facts (tuple[LocalReaderFactV1, ...])

class LocalReaderModelOutcomeV1(**data)

Bases: BaseModel

Public projection of one model outcome.

Parameters:

• model (str | None)

• roles (tuple[ModelRole, ...])

• succeeded (bool)

• already_satisfied (bool)

• step (LocalReaderSetupStep | None)

• bytes_fetched (Annotated[int, Ge(ge=0)] | None)

• freed_bytes (Annotated[int, Ge(ge=0)] | None)

• was_installed (bool)

• resident (bool)

• answered (bool)

• elapsed_ms (Annotated[int, Ge(ge=0)] | None)

• failed_condition_id (str | None)

• facts (tuple[LocalReaderFactV1, ...])

• verdict_condition_id (str | None)

• verdict_facts (tuple[LocalReaderFactV1, ...])

model: str | None

roles: tuple[ModelRole, ...]

succeeded: bool

already_satisfied: bool

step: LocalReaderSetupStep | None

bytes_fetched: NonNegativeInt | None

freed_bytes: NonNegativeInt | None

was_installed: bool

resident: bool

answered: bool

elapsed_ms: NonNegativeInt | None

failed_condition_id: str | None

facts: tuple[LocalReaderFactV1, ...]

verdict_condition_id: str | None

verdict_facts: tuple[LocalReaderFactV1, ...]

class LocalReaderInstallOutcomeV1(**data)

Bases: BaseModel

Public projection of the install request.

Parameters:

• installed (bool)

• already_installed (bool)

• installer (RuntimeInstaller)

• consented (bool)

• installer_exit_code (int | None)

installed: bool

already_installed: bool

installer: RuntimeInstaller

consented: bool

installer_exit_code: int | None

class LocalReaderSetupStepOutcomeV1(**data)

Bases: BaseModel

Public projection of one setup step.

Parameters:

• step (LocalReaderSetupStep)

• state (LocalReaderSetupStepState)

• failed_condition_id (str | None)

step: LocalReaderSetupStep

state: LocalReaderSetupStepState

failed_condition_id: str | None

class LocalReaderProvisionPublicResultV1(**data)

Bases: BaseModel

Public projection of a settled provisioning operation.

Parameters:

• action (LocalReaderProvisionAction)

• succeeded (bool)

• runtime_started (bool)

• already_running (bool)

• started_pid (Annotated[int, Ge(ge=0)] | None)

• install (LocalReaderInstallOutcomeV1 | None)

• failed_condition_id (str | None)

• models (tuple[LocalReaderModelOutcomeV1, ...])

• steps (tuple[LocalReaderSetupStepOutcomeV1, ...])

• stopped_step (LocalReaderSetupStep | None)

• facts (tuple[LocalReaderFactV1, ...])

• verdict_condition_id (str | None)

• verdict_facts (tuple[LocalReaderFactV1, ...])

action: LocalReaderProvisionAction

succeeded: bool

runtime_started: bool

already_running: bool

started_pid: NonNegativeInt | None

install: LocalReaderInstallOutcomeV1 | None

failed_condition_id: str | None

models: tuple[LocalReaderModelOutcomeV1, ...]

steps: tuple[LocalReaderSetupStepOutcomeV1, ...]

stopped_step: LocalReaderSetupStep | None

facts: tuple[LocalReaderFactV1, ...]

verdict_condition_id: str | None

verdict_facts: tuple[LocalReaderFactV1, ...]

class LocalReaderProvisionEvents(*args, **kwargs)

Bases: Protocol

Where a provisioning run reports its progress; the supervised operation journals it.

async step(step)

Report that a setup step begins.

Return type:

None

Parameters:

step (LocalReaderSetupStep)

async progress(*, completed, total)

Report fetched bytes of the model being pulled.

Return type:

None

Parameters:

• completed (int)

• total (int)

local_reader_provision_effect(outcome)

Return the committed extent a settled provisioning outcome represents.

Return type:

OperationEffect

Parameters:

outcome (LocalReaderProvisionOutcome)

async provision_local_reader(payload, *, spawn, run_installer, text_probe, events=None)

Run one provisioning action and return its settled outcome.

The single implementation of install, start, pull, load, verify, remove and setup. The supervised operation wraps it with journaled progress for frontends that hold a profile session; a host-level caller such as the command line runs it directly, because provisioning the machine’s runtime needs no profile. Never raises for a refusal: every refusal is a typed verdict on the outcome.

Return type:

LocalReaderProvisionOutcome

Parameters:

• payload (LocalReaderProvisionRequest)

• spawn (RuntimeSpawner)

• run_installer (InstallerRunner)

• text_probe (TextExtractionFitnessProbe)

• events (LocalReaderProvisionEvents | None)

class LocalReaderProvisionExecutor(*, spawn, run_installer, text_probe)

Bases: object

Supervise provision_local_reader(): journal its progress and persist its outcome.

Parameters:

• spawn (RuntimeSpawner)

• run_installer (InstallerRunner)

• text_probe (TextExtractionFitnessProbe)

async execute(request, context)

Execute the requested action and persist its settled outcome.

Return type:

str

Parameters:

• request (OperationRequest[LocalReaderProvisionRequest])

• context (OperationExecutorContext)

build_local_reader_operation_definition(*, spawn, run_installer, text_probe)

Bind the injected process and fitness ports to the canonical provisioning operation.

Return type:

OperationDefinition

Parameters:

• spawn (RuntimeSpawner)

• run_installer (InstallerRunner)

• text_probe (TextExtractionFitnessProbe)

build_local_reader_operation_registration(definition)

Bind the provisioning definition to its stable public schemas.

Return type:

OperationPublicDefinitionRegistrationV1

Parameters:

definition (OperationDefinition)