Ultrastable

Local-first runtime governance for Python agent systems, with deterministic policy checks and bounded evidence without a hosted control plane.

Documentation · Changelog · Security · Contributing

Ultrastable monitors agent runs for budget pressure, repeated output, tool loops, retry churn, and context pressure. It evaluates those signals against explicit viability policies, proposes typed interventions, and records privacy-bounded JSONL events for inspection and fixed-trace rescoring. The core is offline-first and depends only on NumPy and the Python standard library.

Status: beta. Version 0.4.x is suitable for evaluation and controlled integration, but public APIs may still change before 1.0. Read the assurance matrix before using evidence or replay results in a security-sensitive workflow.

Install and verify

Install the minimal package from PyPI:

python -m pip install ultrastable
ultrastable self-check

Expected output:

self-check OK

The self-check runs locally, creates no durable output, calls no external service, and exercises only APIs and resources shipped in the installed distribution. Use ultrastable self-check --json for structured diagnostics.

For a visible offline run, install the CLI extra and write a bounded demo ledger:

python -m pip install "ultrastable[cli]"
ultrastable demo budget-cap --output runs/budget-cap.jsonl
ultrastable ledger validate runs/budget-cap.jsonl --hash-chain

The final command checks JSON structure and the ledger's unauthenticated internal-consistency chain. It does not establish who created the file.

What Ultrastable does

agent step metrics
        ↓
essential variables + viability policy
        ↓
detectors and controller decision
        ↓
typed intervention proposal
        ↓
privacy-bounded ledger and optional exporters

• Tracks tokens, spend, retries, tool calls, context utilization, and health distance with explicit limits.
• Detects lexical repetition, tool loops, repeated failures, context pressure, and predicted budget exhaustion without requiring a remote service.
• Produces typed reset, trim, replan, fallback, backoff, and stop proposals for caller-controlled execution.
• Records schema-versioned run, step, trigger, intervention, and health events.
• Supports strict ledger parsing, fixed-trace policy rescoring, reports, and privacy-bounded evidence bundles.
• Keeps CLI, telemetry, LangChain integration, and robotics dependencies behind optional extras.

Choose an installation

Extras can be combined. The separately distributed ultrastable-langchain connector is an alpha monitor integration: callbacks observe framework events but cannot prevent an external side effect.

Compatibility and stability

• Python: CPython 3.10–3.14 is release-tested on Linux. Python 3.15 prereleases are an advisory CI signal.
• Platforms: the pure-Python wheel is platform-independent, but safe bundle creation and extraction are enabled only on the tested Linux/filesystem combinations documented in bundle platform support.
• Core dependency boundary: importing ultrastable.core must not import Torch, OpenTelemetry, HTTPX, Rich, or Pydantic.
• Schemas: event, policy, ledger, benchmark, and evidence formats are versioned independently of the Python API.
• Versioning: releases use PEP 440 versions and v<version> Git tags. Breaking changes before 1.0 are documented in the changelog and migration guide.

Limitations and non-goals

• AgentGuard and framework callbacks are in-process monitors. They propose actions; the caller remains responsible for executing or enforcing them.
• JSONL hashes and legacy evidence are best_effort_unverified consistency evidence, not authentication. A party able to rewrite the complete record can recompute those hashes.
• Replay is fixed_trace_rescoring, not reconstruction of a live agent session or proof of a counterfactual outcome.
• Recursive sanitization enforces bounded project privacy rules; it is not a general data-loss-prevention system. Remote export is opt-in.
• The library does not host agents, schedule tools, manage credentials, or replace an application sandbox, authorization layer, or external deadline.
• Robotics support is optional and heavier than the agent-governance core.

See the complete 0.4.4 known limitations and trust boundaries.

Documentation

• Start: quickstart and concepts
• How-to: detectors, interventions, privacy, and LangChain migration
• Reference: public API map, CLI, event schema, and ledger format
• Evidence and assurance: assurance matrix, replay semantics, and security advisory
• Benchmarks and reproducibility: AFMB explanation, run manifests, and repository benchmark policy
• Development: architecture, contribution guide, and release checklist

Work from a source checkout

The repository uses pyproject.toml plus a committed uv.lock. Make is a thin interface over the same scripts and locked environments used by GitLab CI:

make install
make quality
make test
make test-min
make test-coverage
make docs-check

Run the deterministic AFMB behavior smoke suite with make benchmark-smoke. Run the repository experiment plan with make experiment-smoke. Generated ledgers, reports, documentation, distributions, and benchmark runs are ignored; only their definitions, small reviewed golden references, and release evidence metadata belong in source control.

Support and development

• Report a bug or request a feature
• Report a vulnerability privately
• Contribute a change
• Read the code of conduct
• Review release history

License and citation

Ultrastable is released under the MIT License. For research use, cite the software metadata in CITATION.cff and include the exact package version used.

The name acknowledges W. Ross Ashby's work on ultrastability and homeostatic systems. Those ideas motivate the library's essential-variable and viability models; the software does not claim to reproduce Ashby's complete theory.