Skip to content

Run

consist.run options contract

consist.run(...) rejects legacy direct policy kwargs (for example cache_mode, output_missing, inject_context) with a TypeError.

Use options objects instead:

  • cache_options=CacheOptions(...)
  • output_policy=OutputPolicyOptions(...)
  • execution_options=ExecutionOptions(...)

For migration details, see Options Objects Migration Guide.

Identity kwargs for run/trace surfaces

Public identity kwargs for consist.run(...), consist.trace(...), Tracker.run(...), Tracker.trace(...), ScenarioContext.run(...), and ScenarioContext.trace(...) are:

  • adapter=...
  • identity_inputs=[...]

config_plan= and hash_inputs= are not accepted on these run/trace surfaces. Passing them raises TypeError (unexpected keyword argument ...).

Run/trace parity is implemented through a shared invocation-resolution path (resolve_run_invocation), so identity and cache-option validation rules are consistent across both execution styles.

Execute a computational task as a tracked and cached Consist run.

This high-level entrypoint encapsulates the execution of a callable within a managed provenance context. It automates the lifecycle of the run, including signature computation for cache identity, artifact capture, and result persistence.

Parameters:

Name Type Description Default
fn Optional[Callable]

The computational function to execute.

 None
name Optional[str]

A semantic identifier for the run. If omitted, the function's __name__ is utilized as the default.

 None
tracker Optional[Tracker]

The Tracker instance responsible for provenance and caching. If None, the active global tracker is resolved.

 None
adapter Optional[ConfigAdapter]

Config adapter used to resolve adapter-driven identity for the run.

 None
identity_inputs IdentityInputs

Additional hash-only identity inputs that contribute to cache keys.

 None
cache_options Optional[CacheOptions]

Grouped cache controls for run execution.

 None
output_policy Optional[OutputPolicyOptions]

Grouped output mismatch/missing policy controls.

 None
execution_options Optional[ExecutionOptions]

Grouped runtime execution controls.

 None
**kwargs Any

Arguments forwarded to Tracker.run, including inputs, config, tags, and other core run metadata.

Legacy direct policy kwargs are rejected (for example cache_mode, output_missing, inject_context). Use options objects instead: cache_options=CacheOptions(...), output_policy=OutputPolicyOptions(...), and execution_options=ExecutionOptions(...).

 {}

Returns:

Type Description
RunResult

A container holding the function's return value and the immutable Run record.

Raises:

Type Description
TypeError

Raised when legacy run-policy kwargs are provided directly instead of via options objects.

Run model

Use run.identity_summary to debug cache identity composition (config_hash, input_hash, code_hash, adapter metadata, and identity_inputs digests).

Bases: SQLModel

Primary run table in the Consist database.

Each run captures execution metadata (status, timing, identity hashes, tags) and links to artifacts through run_artifact_link. Full configuration details live in the JSON run snapshot on disk, while the database stores hashes and a queryable subset of metadata for caching and discovery.

Attributes: id (str): A unique identifier for the run, often combining model name, year, and a UUID. parent_run_id (Optional[str]): The ID of the parent run, if this is a nested execution. status (str): The current state of the run (e.g., "running", "completed", "failed"). model_name (str): The name of the model or workflow being executed. description (Optional[str]): Human-readable description of the run's purpose or outcome. year (Optional[int]): The simulation or data year, if applicable. iteration (Optional[int]): The iteration number, if applicable. stage (Optional[str]): The workflow stage, if applicable. phase (Optional[str]): The lifecycle phase, if applicable. tags (List[str]): A list of string labels for categorization and filtering (e.g., ["production", "urbansim"]). config_hash (Optional[str]): A hash of the run's configuration, used for caching. git_hash (Optional[str]): The Git commit hash of the code version used for the run. meta (Dict[str, Any]): A flexible dictionary for storing arbitrary metadata (e.g., hostname). started_at (datetime): The timestamp when the run execution began. ended_at (Optional[datetime]): The timestamp when the run execution completed or failed. created_at (datetime): The timestamp when the run record was created. updated_at (datetime): The timestamp when the run record was last updated.

duration_seconds property

Calculate the duration of the run in seconds.

Returns the elapsed time between started_at and ended_at if both are set, otherwise returns None (e.g., if the run is still in progress).

Returns:

Type Description
Optional[float]

The duration in seconds, or None if the run hasn't ended.

identity_summary property

Return a structured cache-identity breakdown for this run.

The summary is intended for debugging cache behavior and explains the component hashes that form the run signature, plus identity-relevant metadata persisted on the run.