API Essentials¶

Use this page for day-to-day Consist usage. These are the preferred execution patterns for new projects and onboarding docs/examples.

Core execution patterns¶

• Cacheable function step: Tracker.run
• Always-execute traced step: Tracker.trace
• Workflow composition: consist.scenario, ScenarioContext.run, ScenarioContext.trace
• Compatibility wrappers: consist.run and consist.trace remain available, but they now warn and simply resolve a tracker before forwarding to the explicit APIs.

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. ResolvedBinding is a separate, advanced opt-in for a planner that needs execution-exact pinned inputs and durable admission/cache evidence; it does not change the preferred Coupler path.

The advanced V1 contract binds only named callable parameters. Dynamic workspace-only artifacts are not yet strict binding inputs; see the advanced workflow contract before using it for restart closures.

Essential helpers¶

• Tracker setup and context: Tracker, consist.use_tracker
• Linking artifacts: consist.ref, consist.refs
• Resolved scenario bindings: consist.BindingResult; consist.ResolvedBindingBuilder for verified, execution-exact advanced bindings
• 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 Tracker.run(...), Tracker.trace(...), ScenarioContext.run(...), ScenarioContext.trace(...), and the deprecated consist.run(...) / consist.trace(...) compatibility wrappers.

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

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

with tracker.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.