Skip to content

Programmatic Quickstart

Overview

Aspect Details
Purpose Minimal Python example for running InvarLock without the CLI.
Audience Developers running small scripted experiments.
Supported surface Stable contract surfaces remain CLI/report/contract-read paths; CoreRunner.execute is an advanced/non-stable integration surface.
Requires invarlock[adapters] for HF adapters; invarlock[edits] for built-in edits; invarlock[guards] for guard math.
Network Offline by default; CLI runs use evaluate --allow-network, while programmatic callers set INVARLOCK_ALLOW_NETWORK=1 for downloads.

Quick Start

from invarlock.adapters.auto import HF_Auto_Adapter
from invarlock.core.api import RunConfig
from invarlock.core.runner import CoreRunner
from invarlock.edits import RTNQuantEdit
from invarlock.guards.invariants import InvariantsGuard

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()]

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

print("status:", report.status)

Concepts

  • Prefer the CLI for stable workflows (pairing, reports, reproducibility).
  • Programmatic runs follow the same pipeline phases and produce a RunReport object.
  • Treat CoreRunner.execute and surrounding orchestration helpers as an advanced/non-stable Python lane that can evolve faster than the CLI/report contracts.
  • Pass calibration_data to CoreRunner.execute for real primary-metric values.
  • CLI workflows use evaluate --allow-network; programmatic runs set INVARLOCK_ALLOW_NETWORK=1 when using remote model IDs.

Reference

Troubleshooting

  • Dependency missing: install invarlock[adapters] or invarlock[guards].
  • Downloads blocked: for the CLI, rerun with evaluate --allow-network; for programmatic code, set INVARLOCK_ALLOW_NETWORK=1.

Observability

  • Inspect report.meta, report.guards, and report.metrics.
  • For report generation, use invarlock.reporting.make_report, then persist the evaluation bundle with invarlock.reporting.report_bundle.save_evaluation_bundle.