API Reference

Task Decorator

dagreon.task(cls)

Decorate a class as a Dagreon task.

The decorated class must define its own __call__ method. Every __call__ input parameter after self and the return value must be a Python 3.12 type alias, for example type Samples = list[float]. Dagreon uses those alias objects as dependency graph nodes.

Parameters:

cls (T) – Class to convert into a task.

Returns:

The decorated class, converted to a frozen dataclass with Dagreon task metadata.

Raises:

TypeError – If the class does not define __call__, if an input or output annotation is missing, if an annotation is not a Python 3.12 type alias, if an input type is repeated, or if the output type is also used as an input type.

Return type:

T

Workflow

class dagreon.Workflow(tasks, use_ray=False, db_dir=None, lmdb_args=None, db_flush_interval_s=5.0)

A workflow composed of tasks that form a DAG.

Parameters:

  • tasks (Iterable[Any]) – Task instances that make up the base workflow.

  • use_ray (bool) – Execute workflow plans through Ray when set.

  • db_dir (str | Path | None) – Optional LMDB directory for persisted final target results.

  • lmdb_args (dict[str, Any] | None) – Optional keyword arguments passed to lmdb.open.

  • db_flush_interval_s (float) – Minimum time between buffered LMDB flushes.

profile(target, overrides=None, ray_remote_args=None)

Execute the workflow to compute the target type and return profiling data.

Parameters:

  • target (TypeAliasType) – The output type to compute.

  • overrides (Iterable[Any] | None) – Optional task instances to replace or add for this profile run.

  • ray_remote_args (dict[str, Any] | None) – Optional Ray task options for this execution.

Returns:

A profiling report for the workflow execution.

Raises:
Return type:

ProfilingReport

run(target, overrides=None, load_only=False, ray_remote_args=None)

Execute the workflow to compute the target type using recursive execution.

Parameters:

  • target (TypeAliasType) – The output type to compute.

  • overrides (Iterable[Any] | None) – Optional task instances to replace or add for this run.

  • load_only (bool) – Return a persisted result without computing. Returns None when no stored result exists or no database is configured.

  • ray_remote_args (dict[str, Any] | None) – Optional Ray task options for this execution.

Returns:

The computed or loaded result of the target type.

Raises:
Return type:

Any

run_variants(target, variants, overrides=None, load_only=False, ray_remote_args=None, tqdm_args=None)

Run multiple variants of this workflow and return all results.

Parameters:

  • target (TypeAliasType) – The output type to run for each variant.

  • variants (Iterable[tuple[Any, ...] | Any]) – Variants to evaluate. Each variant is either a single task instance or a tuple of task instances.

  • overrides (Iterable[Any] | None) – Optional task instances applied to every variant.

  • load_only (bool) – Return persisted results without computing missing variants. Missing results are returned as None.

  • ray_remote_args (dict[str, Any] | None) – Optional Ray task options for variant executions.

  • tqdm_args (dict[str, Any] | None) – Optional arguments passed to tqdm. total is set automatically and cannot be supplied.

Returns:

List of results, one per variant.

Return type:

Any

validate(target)

Validate the workflow for correctness.

Parameters:

target (TypeAliasType) – The output type to validate reachability for

Raises:
Return type:

None

Profiling

class dagreon.ProfilingReport

Timing and result-size data from dagreon.Workflow.profile().

compute_times

Mapping from each produced type alias to the time spent computing that result, in seconds.

sizes

Mapping from each produced type alias to sys.getsizeof for that result, in bytes.

end_to_end_time

Total elapsed profiling time, including planning and execution overhead, in seconds.

summary(sort_by='compute_time', threshold=0.98)

Format profiling data as a text table.

Parameters:

  • sort_by (str) – Metric used to order rows. Must be "compute_time" or "size".

  • threshold (float) – Fraction of the selected metric to show before grouping remaining rows into an Other row. Use 1.0 to show all rows.

Returns:

A multi-line text report containing per-type compute times, result sizes, percentages, and totals.

Raises:

ValueError – If sort_by or threshold is invalid.

Return type:

str

Validation Errors

class dagreon.ValidationError

Base exception for workflow validation errors.

class dagreon.DuplicateOutputError

Raised when multiple tasks produce the same output type.

class dagreon.MissingProducerError

Raised when a required input type has no producer.

class dagreon.CycleError

Raised when the workflow contains a cycle.