gyoza.models#

gyoza domain models.

Single source of truth for all shared domain types, aggregates, and value objects used by the server, worker, and CLI.

class gyoza.models.Constraints(cpu=None, ram_mb=None, vram_mb=None, gpu_id=None)[source]#

Bases: object

Hardware requirements for execution.

Parameters:

cpu (int | None) – Number of CPU cores required.
ram_mb (int | None) – RAM in megabytes.
vram_mb (int | None) – VRAM in megabytes.
gpu_id (int | None) – Preferred GPU identifier. Filled by scheduler on assignment.

cpu: int | None = None#

ram_mb: int | None = None#

vram_mb: int | None = None#

gpu_id: int | None = None#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Dictionary representation of the constraints.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary with optional keys cpu, ram_mb, vram_mb, gpu_id.
Returns:: Populated instance.
Return type:: Constraints

class gyoza.models.EventDelivery(topic='', attributes=<factory>)[source]#

Bases: object

Event delivery configuration for op runs.

Parameters:

topic (str) – Topic name to publish events to.
attributes (dict[str, Any]) – Additional metadata attached to each event.

topic: str = ''#

attributes: dict[str, Any]#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Dictionary representation of the event delivery config.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary with optional keys topic and attributes.
Returns:: Populated instance.
Return type:: EventDelivery

class gyoza.models.EventEntry(t, type, msg, payload=<factory>)[source]#

Bases: object

A single event in the op run timeline.

Parameters:

t (datetime) – Timestamp when the event occurred.
type (str) – Event type string (see EventType).
msg (str | int) – Human-readable message or progress value (0–100 for PROGRESS events).
payload (dict[str, Any]) – Optional event-specific data.

t: datetime#

type: str#

msg: str | int#

payload: dict[str, Any]#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Dictionary representation of the event entry.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary with keys t, type, msg, optional payload.
Returns:: Populated instance.
Return type:: EventEntry

class gyoza.models.EventType(*values)[source]#

Bases: str, Enum

Event types emitted during an op run.

ASSIGNED = 'ASSIGNED'#

STARTED = 'STARTED'#

INFO = 'INFO'#

PROGRESS = 'PROGRESS'#

COMPLETED = 'COMPLETED'#

FAILED = 'FAILED'#

CANCELLED = 'CANCELLED'#

ERROR = 'ERROR'#

RETRIED = 'RETRIED'#

class gyoza.models.ExecutionSummary(duration_ms=None, worker_id=None, error_message=None, gpu_id=None)[source]#

Bases: object

High-level execution metadata attached to a completed op run.

Parameters:

duration_ms (int | None) – Total execution time in milliseconds.
worker_id (str | None) – Identifier of the worker that ran the operation.
error_message (str | None) – Error description when the run failed.
gpu_id (int | None) – GPU identifier used during execution, if any.

duration_ms: int | None = None#

worker_id: str | None = None#

error_message: str | None = None#

gpu_id: int | None = None#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Dictionary representation of the execution summary.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary with optional keys matching the field names.
Returns:: Populated instance.
Return type:: ExecutionSummary

class gyoza.models.InputSpec(type, required=True, default=None)[source]#

Bases: object

Specification for a single input parameter.

Parameters:

type (str) – Type name (e.g. "string", "float", "int", "boolean").
required (bool) – Whether the input must be provided by the caller.
default (Any | None) – Default value applied when the input is absent and not required.

type: str#

required: bool = True#

default: Any | None = None#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Dictionary representation of the input spec.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary with keys type, optional required and default.
Returns:: Populated instance.
Return type:: InputSpec

class gyoza.models.InputSpecs(specs=<factory>)[source]#

Bases: object

Collection of input specifications keyed by parameter name.

Parameters:: specs (dict[str, InputSpec]) – Mapping of input names to their specifications.

specs: dict[str, InputSpec]#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Mapping of input names to their serialised specs.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Mapping of input names to raw spec dictionaries.
Returns:: Populated instance.
Return type:: InputSpecs

validate(inputs)[source]#

Check that all required inputs are present.

Parameters:: inputs (dict[str, Any]) – Caller-provided inputs to validate.
Returns:: Validation error messages; empty when inputs are valid.
Return type:: list[str]

apply_defaults(inputs)[source]#

Return a copy of inputs with default values filled in.

Parameters:: inputs (dict[str, Any]) – Caller-provided inputs.
Returns:: Inputs merged with defaults for absent optional parameters.
Return type:: dict[str, Any]

exception gyoza.models.InputValidationError(errors)[source]#

Bases: Exception

Raised when input validation fails against an OpDefinition’s specs.

Parameters:: errors (list[str]) – List of validation error messages.
Return type:: None

class gyoza.models.OpAttempt(id, op_run_id, attempt, state, progress=0, events=<factory>, inputs=<factory>, outputs=<factory>, execution_summary=<factory>, constraints=<factory>, started_at=None, finished_at=None)[source]#

Bases: object

A single execution attempt belonging to an OpRun.

OpRuns can have multiple attempts when retries are configured. Each attempt has its own event timeline, outputs, and execution summary.

Parameters:

id (str) – Unique identifier for the attempt (<run_id>_att_<n>).
op_run_id (str) – Parent OpRun identifier.
attempt (int) – Attempt number (1-indexed).
state (OpRunState) – Current state of this attempt.
progress (int) – Completion percentage (0–100).
events (list[EventEntry]) – Timeline of events during this attempt.
inputs (dict[str, Any]) – Snapshot of inputs at execution time.
outputs (dict[str, Any]) – Outputs produced by this attempt.
execution_summary (ExecutionSummary) – Execution metadata (worker, duration, GPU, error).
constraints (Constraints) – Hardware constraints snapshot for this attempt.
started_at (datetime | None) – When the container started.
finished_at (datetime | None) – When the container exited.

id: str#

op_run_id: str#

attempt: int#

state: OpRunState#

progress: int = 0#

events: list[EventEntry]#

inputs: dict[str, Any]#

outputs: dict[str, Any]#

execution_summary: ExecutionSummary#

constraints: Constraints#

started_at: datetime | None = None#

finished_at: datetime | None = None#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Dictionary with all attempt data.
Return type:: dict[str, Any]

class gyoza.models.OpDefinition(id, version, image, input_specs=<factory>, output_specs=<factory>, constraints=<factory>, retry_policy=<factory>, event_delivery=<factory>, created_at=<factory>, updated_at=<factory>)[source]#

Bases: object

Aggregate root describing an operation and its execution requirements.

Serves as the template from which op runs are created. Holds the full lifecycle of a definition: creation, input validation, defaults, and updates.

Parameters:

id (str) – Unique human-readable identifier (e.g. "sugarcane_lines_product").
version (str) – Semantic version string (e.g. "1.2.0").
image (str) – Docker image reference including registry and tag.
input_specs (InputSpecs) – Accepted input parameters.
output_specs (OutputSpecs) – Output fields produced by the operation.
constraints (Constraints) – Hardware requirements for execution.
retry_policy (RetryPolicy) – Failure recovery rules.
event_delivery (EventDelivery) – Event delivery configuration for runs of this definition.
created_at (datetime) – Timestamp when the definition was registered.
updated_at (datetime) – Timestamp of the most recent update.

id: str#

version: str#

image: str#

input_specs: InputSpecs#

output_specs: OutputSpecs#

constraints: Constraints#

retry_policy: RetryPolicy#

event_delivery: EventDelivery#

created_at: datetime#

updated_at: datetime#

classmethod create(id, version, image, input_specs=None, output_specs=None, constraints=None, retry_policy=None, event_delivery=None)[source]#

Create a new OpDefinition with auto-set timestamps.

Parameters:

id (str) – Unique human-readable identifier.
version (str) – Semantic version of the definition.
image (str) – Docker image reference.
input_specs (InputSpecs | dict[str, Any] | None) – Accepted input parameters.
output_specs (OutputSpecs | dict[str, Any] | None) – Output field definitions.
constraints (Constraints | None) – Hardware requirements.
retry_policy (RetryPolicy | None) – Failure recovery rules.
event_delivery (EventDelivery | None) – Event delivery configuration.

Returns:

A new OpDefinition instance with timestamps set to now.

Return type:

OpDefinition

validate_inputs(inputs)[source]#

Validate inputs against the definition’s input specs.

Parameters:: inputs (dict[str, Any]) – The inputs to validate.
Raises:: InputValidationError – If required inputs are missing.
Return type:: None

prepare_inputs(inputs)[source]#

Validate inputs and apply defaults.

Parameters:: inputs (dict[str, Any]) – The inputs to prepare.
Returns:: Inputs with defaults applied.
Return type:: dict[str, Any]
Raises:: InputValidationError – If required inputs are missing.

update(version=None, image=None, input_specs=None, output_specs=None, constraints=None, retry_policy=None)[source]#

Update definition fields in place.

Parameters:

version (str | None) – New version string.
image (str | None) – New Docker image reference.
input_specs (InputSpecs | dict[str, Any] | None) – New input specifications.
output_specs (OutputSpecs | dict[str, Any] | None) – New output specifications.
constraints (Constraints | None) – New hardware requirements.
retry_policy (RetryPolicy | None) – New retry policy.

Return type:

None

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Dictionary representation including camelCase timestamp keys for API compatibility.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary as returned by the server API (camelCase or snake_case timestamp keys are both accepted).
Returns:: Populated instance.
Return type:: OpDefinition

class gyoza.models.OpRun(id, state, priority, image, inputs=<factory>, constraints=<factory>, retry_policy=<factory>, event_delivery=<factory>, op_definition=None, created_at=<factory>, updated_at=<factory>, _attempts=<factory>, _current_attempt_index=-1)[source]#

Bases: object

Aggregate root for execution runs.

Encapsulates all attempts internally. Users interact only with OpRun; the current attempt’s data (progress, events, outputs, execution_summary) is exposed directly via properties.

A new OpRun always starts with its first attempt. Additional attempts are created by RETRIED (including after release_assignment()) or automatic retry after FAILED when policy allows.

Parameters:

id (str) – Unique identifier for the run.
state (OpRunState) – Current state of the run.
priority (int) – Execution queue priority.
image (str) – Docker image reference.
inputs (dict[str, Any]) – Input parameters for execution.
constraints (Constraints) – Hardware requirements.
retry_policy (RetryPolicy) – Failure recovery rules.
event_delivery (EventDelivery) – Event delivery configuration.
op_definition (str | None) – Parent OpDefinition name (None for ad-hoc runs).
created_at (datetime) – When the run was created.
updated_at (datetime) – Last state update timestamp.
_attempts (list[OpAttempt])
_current_attempt_index (int)

id: str#

state: OpRunState#

priority: int#

image: str#

inputs: dict[str, Any]#

constraints: Constraints#

retry_policy: RetryPolicy#

event_delivery: EventDelivery#

op_definition: str | None = None#

created_at: datetime#

updated_at: datetime#

classmethod create(image, priority=0, inputs=None, constraints=None, retry_policy=None, event_delivery=None, op_definition=None)[source]#

Create a new OpRun in PENDING state with its first attempt.

Parameters:

image (str) – Docker image reference.
priority (int) – Scheduling priority (default 0).
inputs (dict[str, Any] | None) – Input parameters.
constraints (Constraints | None) – Hardware requirements.
retry_policy (RetryPolicy | None) – Failure recovery rules.
event_delivery (EventDelivery | None) – Event delivery configuration.
op_definition (str | None) – Parent OpDefinition name.

Returns:

A new OpRun in PENDING state with its first attempt created.

Return type:

OpRun

property active_attempt: OpAttempt#: Current attempt (always present for a valid run).

property current_attempt: int#: Current attempt number (1-indexed).

property progress: int#: Current progress percentage (0–100).

property events: list[EventEntry]#: Event timeline from the current attempt.

property outputs: dict[str, Any]#: Outputs from the current attempt.

property execution_summary: ExecutionSummary#: Execution metadata from the current attempt.

property attempts: list[OpAttempt]#: All attempts in order.

property is_locked: bool#: True when the run is in a terminal state.

set_state(new_state)[source]#

Update the run state directly.

Parameters:: new_state (OpRunState) – New state to apply.
Return type:: None

assign(worker_id, gpu_id=None)[source]#

Allocate this run to a worker (scheduler / internal).

Emits an ASSIGNED event and transitions PENDING → ASSIGNED.

Parameters:

worker_id (str) – Worker that will execute this run.
gpu_id (int | None) – Selected GPU, if any.

Raises:

ValueError – If the run is not PENDING.
OpRunLockedException – If the run is terminal.

Return type:

None

release_assignment()[source]#

Reclaim a run whose worker is gone (reaper / internal).

Validates ASSIGNED or RUNNING, then emits RETRIED with force so a fresh attempt is started without enforcing max_attempts.

Raises:

ValueError – If the run is not ASSIGNED or RUNNING.
OpRunLockedException – If the run is terminal.

Return type:

None

add_event(event_type, msg, payload=None)[source]#

Append an event to the current attempt and react to its type.

Lifecycle transitions are implemented in gyoza.models.op_run_events. Notable types:

ASSIGNED: PENDING → ASSIGNED (requires worker_id in payload)
STARTED: ASSIGNED → RUNNING
PROGRESS: updates progress (msg must be 0–100)
COMPLETED: terminal COMPLETED
FAILED: terminal FAILED; if retries remain, appends RETRIED and starts a new attempt (PENDING)
CANCELLED: terminal CANCELLED
RETRIED: records retry on the current attempt, and create a new attempt

Parameters:

event_type (str) – Type of event (see EventType).
msg (str | int) – Human-readable message or progress value.
payload (dict[str, Any] | None) – Optional event-specific data.

Raises:

OpRunLockedException – If the run is already in a terminal state (except for RETRIED).
ValueError – If a required payload is missing or the event is invalid in the current state.

Return type:

None

can_retry()[source]#

Return True if another attempt is allowed.

Returns:: True when current attempt count is below max_attempts.
Return type:: bool

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Mixed view combining run-level and current-attempt fields.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary as returned by the server API.
Returns:: Reconstructed instance. For full attempt history use the repository.
Return type:: OpRun

exception gyoza.models.OpRunLockedException[source]#

Bases: Exception

Raised when trying to modify a terminal-state OpRun.

class gyoza.models.OpRunState(*values)[source]#

Bases: str, Enum

Lifecycle states for an op run.

PENDING = 'PENDING'#

ASSIGNED = 'ASSIGNED'#

RUNNING = 'RUNNING'#

COMPLETED = 'COMPLETED'#

FAILED = 'FAILED'#

CANCELLED = 'CANCELLED'#

class gyoza.models.OutputSpec(type)[source]#

Bases: object

Specification for a single output field.

Parameters:: type (str) – Type name of the output (e.g. "string", "float").

type: str#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Dictionary representation of the output spec.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary with key type.
Returns:: Populated instance.
Return type:: OutputSpec

class gyoza.models.OutputSpecs(specs=<factory>)[source]#

Bases: object

Collection of output specifications keyed by field name.

Parameters:: specs (dict[str, OutputSpec]) – Mapping of output field names to their specifications.

specs: dict[str, OutputSpec]#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Mapping of output names to their serialised specs.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Mapping of output names to raw spec dictionaries.
Returns:: Populated instance.
Return type:: OutputSpecs

class gyoza.models.RetryPolicy(max_attempts=1)[source]#

Bases: object

Rules for automatic failure recovery.

Only applies to automatic retries when a FAILED event is received. The retry API endpoint ignores max_attempts and always allows a retry.

Parameters:: max_attempts (int) – Maximum number of execution attempts (including the first). When a run fails, it is retried immediately if attempts remain.

max_attempts: int = 1#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Dictionary representation of the retry policy.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary with optional key max_attempts.
Returns:: Populated instance.
Return type:: RetryPolicy

OpDefinition aggregate and input/output specification types.

exception gyoza.models.op_definition.InputValidationError(errors)[source]#

Bases: Exception

Raised when input validation fails against an OpDefinition’s specs.

Parameters:: errors (list[str]) – List of validation error messages.
Return type:: None

class gyoza.models.op_definition.InputSpec(type, required=True, default=None)[source]#

Bases: object

Specification for a single input parameter.

Parameters:

type (str) – Type name (e.g. "string", "float", "int", "boolean").
required (bool) – Whether the input must be provided by the caller.
default (Any | None) – Default value applied when the input is absent and not required.

type: str#

required: bool = True#

default: Any | None = None#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Dictionary representation of the input spec.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary with keys type, optional required and default.
Returns:: Populated instance.
Return type:: InputSpec

class gyoza.models.op_definition.InputSpecs(specs=<factory>)[source]#

Bases: object

Collection of input specifications keyed by parameter name.

Parameters:: specs (dict[str, InputSpec]) – Mapping of input names to their specifications.

specs: dict[str, InputSpec]#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Mapping of input names to their serialised specs.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Mapping of input names to raw spec dictionaries.
Returns:: Populated instance.
Return type:: InputSpecs

validate(inputs)[source]#

Check that all required inputs are present.

Parameters:: inputs (dict[str, Any]) – Caller-provided inputs to validate.
Returns:: Validation error messages; empty when inputs are valid.
Return type:: list[str]

apply_defaults(inputs)[source]#

Return a copy of inputs with default values filled in.

Parameters:: inputs (dict[str, Any]) – Caller-provided inputs.
Returns:: Inputs merged with defaults for absent optional parameters.
Return type:: dict[str, Any]

class gyoza.models.op_definition.OutputSpec(type)[source]#

Bases: object

Specification for a single output field.

Parameters:: type (str) – Type name of the output (e.g. "string", "float").

type: str#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Dictionary representation of the output spec.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary with key type.
Returns:: Populated instance.
Return type:: OutputSpec

class gyoza.models.op_definition.OutputSpecs(specs=<factory>)[source]#

Bases: object

Collection of output specifications keyed by field name.

Parameters:: specs (dict[str, OutputSpec]) – Mapping of output field names to their specifications.

specs: dict[str, OutputSpec]#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Mapping of output names to their serialised specs.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Mapping of output names to raw spec dictionaries.
Returns:: Populated instance.
Return type:: OutputSpecs

class gyoza.models.op_definition.OpDefinition(id, version, image, input_specs=<factory>, output_specs=<factory>, constraints=<factory>, retry_policy=<factory>, event_delivery=<factory>, created_at=<factory>, updated_at=<factory>)[source]#

Bases: object

Aggregate root describing an operation and its execution requirements.

Serves as the template from which op runs are created. Holds the full lifecycle of a definition: creation, input validation, defaults, and updates.

Parameters:

id (str) – Unique human-readable identifier (e.g. "sugarcane_lines_product").
version (str) – Semantic version string (e.g. "1.2.0").
image (str) – Docker image reference including registry and tag.
input_specs (InputSpecs) – Accepted input parameters.
output_specs (OutputSpecs) – Output fields produced by the operation.
constraints (Constraints) – Hardware requirements for execution.
retry_policy (RetryPolicy) – Failure recovery rules.
event_delivery (EventDelivery) – Event delivery configuration for runs of this definition.
created_at (datetime) – Timestamp when the definition was registered.
updated_at (datetime) – Timestamp of the most recent update.

id: str#

version: str#

image: str#

input_specs: InputSpecs#

output_specs: OutputSpecs#

constraints: Constraints#

retry_policy: RetryPolicy#

event_delivery: EventDelivery#

created_at: datetime#

updated_at: datetime#

classmethod create(id, version, image, input_specs=None, output_specs=None, constraints=None, retry_policy=None, event_delivery=None)[source]#

Create a new OpDefinition with auto-set timestamps.

Parameters:

id (str) – Unique human-readable identifier.
version (str) – Semantic version of the definition.
image (str) – Docker image reference.
input_specs (InputSpecs | dict[str, Any] | None) – Accepted input parameters.
output_specs (OutputSpecs | dict[str, Any] | None) – Output field definitions.
constraints (Constraints | None) – Hardware requirements.
retry_policy (RetryPolicy | None) – Failure recovery rules.
event_delivery (EventDelivery | None) – Event delivery configuration.

Returns:

A new OpDefinition instance with timestamps set to now.

Return type:

OpDefinition

validate_inputs(inputs)[source]#

Validate inputs against the definition’s input specs.

Parameters:: inputs (dict[str, Any]) – The inputs to validate.
Raises:: InputValidationError – If required inputs are missing.
Return type:: None

prepare_inputs(inputs)[source]#

Validate inputs and apply defaults.

Parameters:: inputs (dict[str, Any]) – The inputs to prepare.
Returns:: Inputs with defaults applied.
Return type:: dict[str, Any]
Raises:: InputValidationError – If required inputs are missing.

update(version=None, image=None, input_specs=None, output_specs=None, constraints=None, retry_policy=None)[source]#

Update definition fields in place.

Parameters:

version (str | None) – New version string.
image (str | None) – New Docker image reference.
input_specs (InputSpecs | dict[str, Any] | None) – New input specifications.
output_specs (OutputSpecs | dict[str, Any] | None) – New output specifications.
constraints (Constraints | None) – New hardware requirements.
retry_policy (RetryPolicy | None) – New retry policy.

Return type:

None

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Dictionary representation including camelCase timestamp keys for API compatibility.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary as returned by the server API (camelCase or snake_case timestamp keys are both accepted).
Returns:: Populated instance.
Return type:: OpDefinition

OpRun aggregate root — execution run lifecycle management.

exception gyoza.models.op_run.OpRunLockedException[source]#

Bases: Exception

Raised when trying to modify a terminal-state OpRun.

class gyoza.models.op_run.OpRun(id, state, priority, image, inputs=<factory>, constraints=<factory>, retry_policy=<factory>, event_delivery=<factory>, op_definition=None, created_at=<factory>, updated_at=<factory>, _attempts=<factory>, _current_attempt_index=-1)[source]#

Bases: object

Aggregate root for execution runs.

Encapsulates all attempts internally. Users interact only with OpRun; the current attempt’s data (progress, events, outputs, execution_summary) is exposed directly via properties.

A new OpRun always starts with its first attempt. Additional attempts are created by RETRIED (including after release_assignment()) or automatic retry after FAILED when policy allows.

Parameters:

id (str) – Unique identifier for the run.
state (OpRunState) – Current state of the run.
priority (int) – Execution queue priority.
image (str) – Docker image reference.
inputs (dict[str, Any]) – Input parameters for execution.
constraints (Constraints) – Hardware requirements.
retry_policy (RetryPolicy) – Failure recovery rules.
event_delivery (EventDelivery) – Event delivery configuration.
op_definition (str | None) – Parent OpDefinition name (None for ad-hoc runs).
created_at (datetime) – When the run was created.
updated_at (datetime) – Last state update timestamp.
_attempts (list[OpAttempt])
_current_attempt_index (int)

id: str#

state: OpRunState#

priority: int#

image: str#

inputs: dict[str, Any]#

constraints: Constraints#

retry_policy: RetryPolicy#

event_delivery: EventDelivery#

op_definition: str | None = None#

created_at: datetime#

updated_at: datetime#

classmethod create(image, priority=0, inputs=None, constraints=None, retry_policy=None, event_delivery=None, op_definition=None)[source]#

Create a new OpRun in PENDING state with its first attempt.

Parameters:

image (str) – Docker image reference.
priority (int) – Scheduling priority (default 0).
inputs (dict[str, Any] | None) – Input parameters.
constraints (Constraints | None) – Hardware requirements.
retry_policy (RetryPolicy | None) – Failure recovery rules.
event_delivery (EventDelivery | None) – Event delivery configuration.
op_definition (str | None) – Parent OpDefinition name.

Returns:

A new OpRun in PENDING state with its first attempt created.

Return type:

OpRun

property active_attempt: OpAttempt#: Current attempt (always present for a valid run).

property current_attempt: int#: Current attempt number (1-indexed).

property progress: int#: Current progress percentage (0–100).

property events: list[EventEntry]#: Event timeline from the current attempt.

property outputs: dict[str, Any]#: Outputs from the current attempt.

property execution_summary: ExecutionSummary#: Execution metadata from the current attempt.

property attempts: list[OpAttempt]#: All attempts in order.

property is_locked: bool#: True when the run is in a terminal state.

set_state(new_state)[source]#

Update the run state directly.

Parameters:: new_state (OpRunState) – New state to apply.
Return type:: None

assign(worker_id, gpu_id=None)[source]#

Allocate this run to a worker (scheduler / internal).

Emits an ASSIGNED event and transitions PENDING → ASSIGNED.

Parameters:

worker_id (str) – Worker that will execute this run.
gpu_id (int | None) – Selected GPU, if any.

Raises:

ValueError – If the run is not PENDING.
OpRunLockedException – If the run is terminal.

Return type:

None

release_assignment()[source]#

Reclaim a run whose worker is gone (reaper / internal).

Validates ASSIGNED or RUNNING, then emits RETRIED with force so a fresh attempt is started without enforcing max_attempts.

Raises:

ValueError – If the run is not ASSIGNED or RUNNING.
OpRunLockedException – If the run is terminal.

Return type:

None

add_event(event_type, msg, payload=None)[source]#

Append an event to the current attempt and react to its type.

Lifecycle transitions are implemented in gyoza.models.op_run_events. Notable types:

ASSIGNED: PENDING → ASSIGNED (requires worker_id in payload)
STARTED: ASSIGNED → RUNNING
PROGRESS: updates progress (msg must be 0–100)
COMPLETED: terminal COMPLETED
FAILED: terminal FAILED; if retries remain, appends RETRIED and starts a new attempt (PENDING)
CANCELLED: terminal CANCELLED
RETRIED: records retry on the current attempt, and create a new attempt

Parameters:

event_type (str) – Type of event (see EventType).
msg (str | int) – Human-readable message or progress value.
payload (dict[str, Any] | None) – Optional event-specific data.

Raises:

OpRunLockedException – If the run is already in a terminal state (except for RETRIED).
ValueError – If a required payload is missing or the event is invalid in the current state.

Return type:

None

can_retry()[source]#

Return True if another attempt is allowed.

Returns:: True when current attempt count is below max_attempts.
Return type:: bool

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Mixed view combining run-level and current-attempt fields.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary as returned by the server API.
Returns:: Reconstructed instance. For full attempt history use the repository.
Return type:: OpRun

OpAttempt entity — a single execution attempt within an OpRun.

class gyoza.models.op_attempt.OpAttempt(id, op_run_id, attempt, state, progress=0, events=<factory>, inputs=<factory>, outputs=<factory>, execution_summary=<factory>, constraints=<factory>, started_at=None, finished_at=None)[source]#

Bases: object

A single execution attempt belonging to an OpRun.

OpRuns can have multiple attempts when retries are configured. Each attempt has its own event timeline, outputs, and execution summary.

Parameters:

id (str) – Unique identifier for the attempt (<run_id>_att_<n>).
op_run_id (str) – Parent OpRun identifier.
attempt (int) – Attempt number (1-indexed).
state (OpRunState) – Current state of this attempt.
progress (int) – Completion percentage (0–100).
events (list[EventEntry]) – Timeline of events during this attempt.
inputs (dict[str, Any]) – Snapshot of inputs at execution time.
outputs (dict[str, Any]) – Outputs produced by this attempt.
execution_summary (ExecutionSummary) – Execution metadata (worker, duration, GPU, error).
constraints (Constraints) – Hardware constraints snapshot for this attempt.
started_at (datetime | None) – When the container started.
finished_at (datetime | None) – When the container exited.

id: str#

op_run_id: str#

attempt: int#

state: OpRunState#

progress: int = 0#

events: list[EventEntry]#

inputs: dict[str, Any]#

outputs: dict[str, Any]#

execution_summary: ExecutionSummary#

constraints: Constraints#

started_at: datetime | None = None#

finished_at: datetime | None = None#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Dictionary with all attempt data.
Return type:: dict[str, Any]

Shared value objects for the gyoza domain.

Contains hardware requirements, policy types, op run states, event types, and execution metadata — all pure data structures with no dependencies on other model files, making them safe to import from anywhere.

class gyoza.models.resources.Constraints(cpu=None, ram_mb=None, vram_mb=None, gpu_id=None)[source]#

Bases: object

Hardware requirements for execution.

Parameters:

cpu (int | None) – Number of CPU cores required.
ram_mb (int | None) – RAM in megabytes.
vram_mb (int | None) – VRAM in megabytes.
gpu_id (int | None) – Preferred GPU identifier. Filled by scheduler on assignment.

cpu: int | None = None#

ram_mb: int | None = None#

vram_mb: int | None = None#

gpu_id: int | None = None#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Dictionary representation of the constraints.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary with optional keys cpu, ram_mb, vram_mb, gpu_id.
Returns:: Populated instance.
Return type:: Constraints

class gyoza.models.resources.RetryPolicy(max_attempts=1)[source]#

Bases: object

Rules for automatic failure recovery.

Only applies to automatic retries when a FAILED event is received. The retry API endpoint ignores max_attempts and always allows a retry.

Parameters:: max_attempts (int) – Maximum number of execution attempts (including the first). When a run fails, it is retried immediately if attempts remain.

max_attempts: int = 1#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Dictionary representation of the retry policy.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary with optional key max_attempts.
Returns:: Populated instance.
Return type:: RetryPolicy

class gyoza.models.resources.EventDelivery(topic='', attributes=<factory>)[source]#

Bases: object

Event delivery configuration for op runs.

Parameters:

topic (str) – Topic name to publish events to.
attributes (dict[str, Any]) – Additional metadata attached to each event.

topic: str = ''#

attributes: dict[str, Any]#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Dictionary representation of the event delivery config.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary with optional keys topic and attributes.
Returns:: Populated instance.
Return type:: EventDelivery

class gyoza.models.resources.OpRunState(*values)[source]#

Bases: str, Enum

Lifecycle states for an op run.

PENDING = 'PENDING'#

ASSIGNED = 'ASSIGNED'#

RUNNING = 'RUNNING'#

COMPLETED = 'COMPLETED'#

FAILED = 'FAILED'#

CANCELLED = 'CANCELLED'#

class gyoza.models.resources.EventType(*values)[source]#

Bases: str, Enum

Event types emitted during an op run.

ASSIGNED = 'ASSIGNED'#

STARTED = 'STARTED'#

INFO = 'INFO'#

PROGRESS = 'PROGRESS'#

COMPLETED = 'COMPLETED'#

FAILED = 'FAILED'#

CANCELLED = 'CANCELLED'#

ERROR = 'ERROR'#

RETRIED = 'RETRIED'#

class gyoza.models.resources.EventEntry(t, type, msg, payload=<factory>)[source]#

Bases: object

A single event in the op run timeline.

Parameters:

t (datetime) – Timestamp when the event occurred.
type (str) – Event type string (see EventType).
msg (str | int) – Human-readable message or progress value (0–100 for PROGRESS events).
payload (dict[str, Any]) – Optional event-specific data.

t: datetime#

type: str#

msg: str | int#

payload: dict[str, Any]#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Dictionary representation of the event entry.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary with keys t, type, msg, optional payload.
Returns:: Populated instance.
Return type:: EventEntry

class gyoza.models.resources.ExecutionSummary(duration_ms=None, worker_id=None, error_message=None, gpu_id=None)[source]#

Bases: object

High-level execution metadata attached to a completed op run.

Parameters:

duration_ms (int | None) – Total execution time in milliseconds.
worker_id (str | None) – Identifier of the worker that ran the operation.
error_message (str | None) – Error description when the run failed.
gpu_id (int | None) – GPU identifier used during execution, if any.

duration_ms: int | None = None#

worker_id: str | None = None#

error_message: str | None = None#

gpu_id: int | None = None#

to_dict()[source]#

Serialise to a JSON-compatible dictionary.

Returns:: Dictionary representation of the execution summary.
Return type:: dict[str, Any]

classmethod from_dict(data)[source]#

Deserialise from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary with optional keys matching the field names.
Returns:: Populated instance.
Return type:: ExecutionSummary