Skip to content

Rust API

The core of hlock is a Rust library, published on crates.io as hlock. Two other crates expose the same API:

Crate Use it when
hlock The default: hlock::Manifest, hlock::Tuner, …
harness-lock An alias for hlock, under harness_lock::…
harness-lock-core You depend on the implementation crate directly 
cargo add hlock

The full API documentation, generated from the source, is on docs.rs: docs.rs/hlock (which re-exports docs.rs/harness-lock-core).

Example

Resolve a lock, check it against the manifest, and read the pinned stack and its evidence. This is the same flow as hlock resolve, hlock check, and hlock show.

src/main.rs
use std::path::Path;

use hlock::{Lockfile, Manifest, Tuner};

fn main() -> hlock::Result<()> {
    // Resolve: load the manifest and tune. `tune()` also writes ./harness.lock.
    let manifest = Manifest::load(Path::new("harness.toml"))?;
    let live_hash = manifest.manifest_hash();
    let lock = Tuner::new(manifest, ".harnesslock").tune()?;
    println!("{}", lock.summary());

    // Check: an empty list means the lock matches the manifest.
    let lock = Lockfile::load(Path::new("harness.lock"))?;
    let drift = lock.check_manifest(&live_hash);
    assert!(drift.is_empty(), "drift: {drift:?}");

    // Inspect the pinned stack and its evidence.
    for llm in &lock.llm {
        println!("{} -> {}:{}", llm.role, llm.provider, llm.model);
    }
    let success = lock.evidence.success_rate.get("mean");
    println!("success rate {success:?} over {} trials", lock.evidence.trials);
    Ok(())
}

$ cargo run
stack="demo" harness=reference llm=qwen-7b decision=none success-rate=1.00 trials=2
planner -> reference:qwen-7b
success rate Some(1.0) over 2 trials

Key types

Item What it is
Manifest A parsed harness.toml: load, from_str, manifest_hash, task_packs, backend_target
Tuner The resolver: new, with_backend, enumerate_stacks, run_trial, tune
Lockfile The harness.lock model: load, from_str, save, check_manifest, summary, and public fields for every section
Backend Local, Devbox, or Cluster; Backend::parse("devbox")
Store The content-addressed artifact store under .harnesslock/
HarnessAdapter The trait a harness implements to run trials
Error, Result The error type, with one variant per kind (Manifest, Lockfile, TaskPack, Tuning, …)
LOCK_VERSION, LOCKFILE_PATH, MANIFEST_PATH Schema version 1, "harness.lock", "harness.toml"

Modules

Module Contents
manifest Manifest schema: candidates, objective, budget
lockfile Lockfile schema: stack, policy, evidence, provenance
tuner The resolver: trial execution and lock construction
search Stacks, trial results, Pareto fronts, winner selection
tasks Task packs, the search/holdout split, grading
ops upgrade and optimize, the engines behind those commands
worker Backends and the Python worker bridge (versioned JSON contract)
providers The deterministic reference LLM provider
store, hash Content addressing and hashing

The flyte module is behind the flyte cargo feature and is provisional.

Python users

The Python API is built on this crate through PyO3, so the two behave the same. Most users only need the Python package and the CLI.