Skip to content

Public API (v0.1)

This page defines Consist's public API for the 0.1.x series. Items listed as Advanced are still public but are primarily targeted at advanced users and may be more verbose, lower-level, or easier to misuse.

For tiered guidance:

When to use each run entry point

Entry point Use when Notes
consist.run You want the quickest cache-aware call for one function Convenience wrapper around Tracker.run
consist.trace You need inline with-block execution with run recording Convenience wrapper around Tracker.trace
Tracker.run You want explicit tracker ownership in app/library code Same core behavior as consist.run
Tracker.trace You need inline execution with explicit tracker control Block executes every time
consist.scenario You need multi-step workflows with shared scenario context Returns ScenarioContext
ScenarioContext.run You are inside a scenario and want cache-aware steps Step-level equivalent of Tracker.run; also accepts binding=BindingResult(...) for orchestrator-resolved inputs
ScenarioContext.trace You are inside a scenario and need inline step execution Step-level equivalent of Tracker.trace

Relationship: consist.scenario, consist.run, and Tracker.run

  • consist.run(...) resolves the active/default tracker and then calls Tracker.run(...).
  • Tracker.run(...) is the explicit class method for a single cache-aware step.
  • consist.scenario(...) creates a scenario context; inside it, call sc.run(...) for cache-aware steps or sc.trace(...) for inline blocks that execute each time. If an external planner has already resolved the step bindings, pass binding=BindingResult(...) to sc.run(...) instead of unpacking primitive input kwargs. That is the preferred scenario-level envelope for complex or externally orchestrated workflows.

Run/trace identity kwargs (public surface)

Run/trace APIs share these public identity kwargs:

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

This applies to:

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

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

For cache identity debugging, use run.identity_summary.

Minimal runnable comparison

from pathlib import Path
import consist
from consist import Tracker

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

def write_result() -> Path:
    out = consist.output_path("result", ext="txt")
    out.write_text("ok\n")
    return out

# Convenience helper: resolves tracker from context.
with consist.use_tracker(tracker):
    one = consist.run(fn=write_result, outputs=["result"])

# Explicit class API: same run behavior, explicit object wiring.
two = tracker.run(fn=write_result, outputs=["result"])

# Scenario API: grouped multi-step workflows.
with tracker.scenario("baseline") as sc:
    step = sc.run(fn=write_result, name="step_result", outputs=["result"])

Stable (intended for external users)

Scenario / workflow helpers

Scenario defaults like name_template and cache_epoch are configured via consist.scenario(...) and flow into ScenarioContext.run(...).

Utilities and Introspection

Artifact logging and loading

Querying and views

Run lookup helpers treat stage and phase as first-class run dimensions, so you can filter historical runs with consist.find_runs(...), consist.find_latest_run(...), or Tracker.find_latest_run(...) without treating those values as opaque metadata.

Tracker methods (complete public surface)

This section enumerates all non-underscore Tracker methods. If you're new to Consist, start with the Core and Logging/Loading groups and reach for Advanced only as needed.

Core lifecycle

  • begin_run, start_run, run, trace, scenario, end_run
  • define_step, last_run, is_cached, cached_artifacts, cached_output
  • suspend_cache_options, restore_cache_options, capture_outputs, log_meta

Logging and loading

  • log_artifact, log_artifacts, log_input, log_output, log_dataframe
  • load, materialize, ingest

Querying and history

  • find_runs, run_set, find_run, find_latest_run, get_latest_run_id
  • find_artifacts, get_artifact, get_artifacts_for_run
  • find_artifacts_by_params, get_artifact_kv, register_artifact_facet_parser
  • get_run, get_run_config, get_run_inputs, get_run_outputs
  • get_artifact_lineage, print_lineage, history
  • diff_runs, get_config_facet, get_config_facets, get_run_config_kv
  • get_config_values, get_config_value, find_runs_by_facet_kv

Views and matrices

  • view, create_view, load_matrix, export_schema_sqlmodel
  • netcdf_metadata, openmatrix_metadata, spatial_metadata

Config canonicalization

  • canonicalize_config, prepare_config, apply_config_plan, identity_from_config_plan

Format-specific logging

  • log_h5_container, log_h5_table, log_netcdf_file, log_openmatrix_file

Advanced (power-user / lower-level)

These methods are still public, but are more low-level or easier to misuse.

  • engine, set_run_subdir_fn, run_artifact_dir, resolve_uri
  • run_query, get_run_record, resolve_historical_path, load_input_bundle
  • get_artifact_by_uri, get_run_artifact, load_run_output, find_matching_run
  • on_run_start, on_run_complete, on_run_failed

Stable, but optional extras

These APIs are part of the public surface, but require extra dependencies.