API Guide

Overview

Quick Start

from invarlock.adapters import HF_Auto_Adapter
from invarlock.core.api import RunConfig
from invarlock.core.runner import CoreRunner
from invarlock.edits import RTNQuantEdit
from invarlock.guards import InvariantsGuard, SpectralGuard

adapter = HF_Auto_Adapter()
model = adapter.load_model("gpt2", device="auto")

edit = RTNQuantEdit(bitwidth=8, per_channel=True, group_size=128, clamp_ratio=0.005)
guards = [InvariantsGuard(), SpectralGuard(sigma_quantile=0.95, deadband=0.10)]

config = RunConfig(device="auto")
report = CoreRunner().execute(model, adapter, edit, guards, config)

print("status:", report.status)
print("primary metric:", report.metrics.get("primary_metric"))

For real primary-metric values, pass calibration_data (see Concepts). Without it, the runner falls back to lightweight mock metrics so the pipeline can still finish.

Concepts

• Pipeline phases: prepare → guard prepare → edit → guard validate → eval → finalize/rollback.
• Calibration data: indexable batches (list/sequence) with input_ids, optional attention_mask, and optional labels. Preview/final windows are sliced from this sequence.
• Auto configuration: auto_config controls tier/policy resolution and is recorded under report.meta["auto"] for report generation.
• Snapshots: retries use snapshot/restore; configure via context.snapshot.* when using YAML configs.
• reports: generated from RunReport + baseline report via invarlock.reporting.report_builder.make_report.

Responsibility lanes

Note: CoreRunner coordinates each lane.

Reference

CoreRunner.execute

CoreRunner.execute is the only supported entry point for programmatic runs.

report = CoreRunner().execute(
    model,
    adapter,
    edit,
    guards,
    config,
    calibration_data=calibration_data,
    auto_config=auto_config,
    edit_config=edit_config,
    preview_n=preview_n,
    final_n=final_n,
)

RunConfig

RunConfig controls runtime behavior in the core runner.

Auto config hints

auto_config is recorded in report.meta["auto"] and used for tier resolution.

RunReport fields

Failure outcomes

Interfaces

ModelAdapter, ModelEdit, and Guard are defined in invarlock.core.api.

from invarlock.core.api import Guard, ModelAdapter, ModelEdit

class CustomGuard(Guard):
    name = "custom_guard"

    def prepare(self, model, adapter, calib, policy):
        return {"ready": True}

    def validate(self, model, adapter, context):
        return {"passed": True, "action": "warn", "metrics": {"ok": 1}}

Notes:

• The runner calls prepare(...) when the guard implements it (GuardWithPrepare).
• validate(...) is always called during the guard phase.
• Optional lifecycle helpers (before_edit, after_edit, finalize) are only invoked when you manage guards manually (for example via GuardChain).

GuardChain helper

GuardChain provides lifecycle helpers for manually coordinating guard calls:

from invarlock.core.api import GuardChain

chain = GuardChain([guard])
chain.prepare_all(model, adapter, calib, policy_config)
chain.before_edit_all(model)
chain.after_edit_all(model)
chain.finalize_all(model)

Calibration data format

Calibration batches should be indexable and yield dict-like objects:

batch = {
    "input_ids": [[101, 102, 103]],
    "attention_mask": [[1, 1, 1]],
    # optional
    "labels": [[101, 102, 103]],
}

If your calibration data is an iterator without __len__, set INVARLOCK_ALLOW_CALIBRATION_MATERIALIZE=1 to allow the runner to materialize it.

Evaluation window helpers

You can build calibration batches from dataset providers:

from invarlock.eval.data import get_provider

provider = get_provider("wikitext2")
preview, final = provider.windows(
    tokenizer,
    preview_n=64,
    final_n=64,
    seq_len=512,
    stride=512,
)

calibration = [
    {"input_ids": ids, "attention_mask": mask}
    for ids, mask in zip(
        preview.input_ids + final.input_ids,
        preview.attention_masks + final.attention_masks,
        strict=False,
    )
]

reports (canonical helpers)

from invarlock.reporting.render import render_report_markdown
from invarlock.reporting.report_builder import make_report
from invarlock.reporting.report_schema import validate_report

report = make_report(report, baseline_report)
validate_report(report)
print(render_report_markdown(report))

Exceptions

Core exceptions live in invarlock.core.exceptions:

• ModelLoadError, AdapterError, EditError, GuardError, ConfigError
• InvarlockError (base class)

Troubleshooting

• DEPENDENCY-MISSING during adapter load: install the matching extra (e.g., pip install "invarlock[adapters]") and retry.
• No calibration data provided warnings: pass calibration_data to CoreRunner.execute (or use the CLI, which handles datasets automatically).
• Calibration data not indexable: pass a list/sequence or set INVARLOCK_ALLOW_CALIBRATION_MATERIALIZE=1 to allow materialization.
• Guard prepare failures in CI/Release: adjust guard policies or set context.run.strict_guard_prepare: false for local debugging only.

Observability

• RunReport.meta, RunReport.guards, RunReport.metrics, and RunReport.evaluation_windows are the canonical inspection points (windows can be omitted when INVARLOCK_STORE_EVAL_WINDOWS=0).
• If RunConfig.event_path is set, an event log is written as JSONL.
• reports from make_report can be validated with invarlock.reporting.report_schema.validate_report or the CLI invarlock verify.

Related Documentation

• Programmatic Quickstart
• CLI Reference
• Configuration Schema
• Dataset Providers
• Guards
• reports — Schema, telemetry, and HTML export
• Determinism Contracts — Reproducibility guarantees
• Observability — Monitoring and telemetry