API Essentials¶

Use this page for day-to-day Consist usage. These APIs are the recommended path for new projects and onboarding docs/examples.

Core execution patterns¶

• Cacheable function step: consist.run
• Always-execute traced step: consist.trace
• Workflow composition: consist.scenario, ScenarioContext.run, ScenarioContext.trace

If you already have a resolved binding plan from a planner or orchestrator, pass binding=BindingResult(...) to ScenarioContext.run(...). That envelope is the preferred scenario-level path for complex or externally orchestrated workflows. Keep using consist.ref(...) / consist.refs(...) for direct step-to-step wiring and primitive inputs= kwargs for ordinary scenario code.

Essential helpers¶

• Tracker setup and context: Tracker, consist.use_tracker
• Linking artifacts: consist.ref, consist.refs
• Resolved scenario bindings: consist.BindingResult
• Managed output paths: consist.output_path, consist.output_dir
• Logging/loading: consist.log_output, consist.log_dataframe, consist.load, consist.load_df
• Run lookup: consist.find_run, consist.find_runs, consist.run_set for grouped/aligned multi-run analysis

Identity kwargs (run/trace parity)¶

These run/trace entry points share the same public identity kwargs:

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

This parity applies across:

• consist.run(...) and consist.trace(...)
• Tracker.run(...) and Tracker.trace(...)
• ScenarioContext.run(...) and ScenarioContext.trace(...)

Minimal essentials example¶

from pathlib import Path
import consist
from consist import ExecutionOptions, Tracker

tracker = Tracker(run_dir="./runs", db_path="./provenance.duckdb")

def produce(*, value: int) -> Path:
    out = consist.output_path("value", ext="txt")
    out.write_text(f"{value}\n", encoding="utf-8")
    return out

with consist.use_tracker(tracker):
    result = consist.run(
        fn=produce,
        name="produce",
        config={"value": 42},
        outputs=["value"],
        execution_options=ExecutionOptions(runtime_kwargs={"value": 42}),
    )

    with consist.trace("inspect", inputs={"value": consist.ref(result, key="value")}):
        pass

For lower-level patterns (start_run, begin_run/end_run, define_step, and manual lifecycle wiring), see API Advanced.