Metadata-Version: 2.4
Name: ultrastable
Version: 0.4.4
Summary: Local-first runtime governance and policy monitoring for AI agents
Author: Zsolt Döme
License-Expression: MIT
Project-URL: Changelog, https://gitlab.com/domezsolt/ultrastable/-/blob/main/CHANGELOG.md
Project-URL: Documentation, https://domezsolt.gitlab.io/ultrastable/
Project-URL: Issues, https://gitlab.com/domezsolt/ultrastable/-/issues
Project-URL: Repository, https://gitlab.com/domezsolt/ultrastable
Project-URL: Security, https://gitlab.com/domezsolt/ultrastable/-/blob/main/SECURITY.md
Keywords: ai agents,monitoring,runtime governance,homeostasis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Provides-Extra: events
Requires-Dist: pydantic>=2.5; extra == "events"
Provides-Extra: cli
Requires-Dist: rich>=13; extra == "cli"
Requires-Dist: typer>=0.9; extra == "cli"
Provides-Extra: http
Requires-Dist: httpx>=0.25; extra == "http"
Provides-Extra: otlp
Requires-Dist: opentelemetry-sdk>=1.20; extra == "otlp"
Requires-Dist: opentelemetry-exporter-otlp>=1.20; extra == "otlp"
Provides-Extra: robotics
Requires-Dist: gymnasium>=0.29; extra == "robotics"
Requires-Dist: torch>=2.0; extra == "robotics"
Provides-Extra: cortex
Requires-Dist: pydantic>=2.5; extra == "cortex"
Requires-Dist: rich>=13; extra == "cortex"
Requires-Dist: typer>=0.9; extra == "cortex"
Requires-Dist: httpx>=0.25; extra == "cortex"
Requires-Dist: opentelemetry-sdk>=1.20; extra == "cortex"
Requires-Dist: opentelemetry-exporter-otlp>=1.20; extra == "cortex"
Dynamic: license-file

# Ultrastable

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

[![Pipeline](https://gitlab.com/domezsolt/ultrastable/badges/main/pipeline.svg)](https://gitlab.com/domezsolt/ultrastable/-/pipelines)
[![Coverage](https://gitlab.com/domezsolt/ultrastable/badges/main/coverage.svg)](https://gitlab.com/domezsolt/ultrastable/-/graphs/main/charts)
[![PyPI](https://img.shields.io/pypi/v/ultrastable.svg)](https://pypi.org/project/ultrastable/)
[![Python](https://img.shields.io/pypi/pyversions/ultrastable.svg)](https://pypi.org/project/ultrastable/)
[![License](https://img.shields.io/pypi/l/ultrastable.svg)](https://gitlab.com/domezsolt/ultrastable/-/blob/main/LICENSE)

[Documentation](https://domezsolt.gitlab.io/ultrastable/) ·
[Changelog](https://gitlab.com/domezsolt/ultrastable/-/blob/main/CHANGELOG.md) ·
[Security](https://gitlab.com/domezsolt/ultrastable/-/blob/main/SECURITY.md) ·
[Contributing](https://gitlab.com/domezsolt/ultrastable/-/blob/main/CONTRIBUTING.md)

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](https://domezsolt.gitlab.io/ultrastable/assurance-matrix/)
before using evidence or replay results in a security-sensitive workflow.

## Install and verify

Install the minimal package from PyPI:

```bash
python -m pip install ultrastable
ultrastable self-check
```

Expected output:

```text
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:

```bash
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

```text
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

| Goal | Command | Main additions |
| --- | --- | --- |
| Minimal library and installed self-check | `python -m pip install ultrastable` | NumPy |
| CLI, demos, and reports | `python -m pip install "ultrastable[cli]"` | Rich, Typer |
| Agent guard, CLI, HTTP, and OTLP tooling | `python -m pip install "ultrastable[cortex]"` | Pydantic, HTTPX, OpenTelemetry, CLI dependencies |
| Robotics examples and wrappers | `python -m pip install "ultrastable[robotics]"` | Gymnasium, Torch |

Extras can be combined. The separately distributed
[`ultrastable-langchain`](https://gitlab.com/domezsolt/ultrastable/-/tree/main/connectors/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](https://domezsolt.gitlab.io/ultrastable/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](https://domezsolt.gitlab.io/ultrastable/releases/0.4.4-known-limitations/)
and [trust boundaries](https://gitlab.com/domezsolt/ultrastable/-/blob/main/TRUST_BOUNDARIES.md).

## Documentation

- **Start:** [quickstart](https://domezsolt.gitlab.io/ultrastable/quickstart/) and
  [concepts](https://domezsolt.gitlab.io/ultrastable/concepts/)
- **How-to:** [detectors](https://domezsolt.gitlab.io/ultrastable/howto_detectors/),
  [interventions](https://domezsolt.gitlab.io/ultrastable/howto_interventions/),
  [privacy](https://domezsolt.gitlab.io/ultrastable/privacy/), and
  [LangChain migration](https://domezsolt.gitlab.io/ultrastable/langchain_connector_migration/)
- **Reference:** [public API map](https://domezsolt.gitlab.io/ultrastable/api/),
  [CLI](https://domezsolt.gitlab.io/ultrastable/cli/),
  [event schema](https://domezsolt.gitlab.io/ultrastable/event_schema/), and
  [ledger format](https://domezsolt.gitlab.io/ultrastable/ledger_format/)
- **Evidence and assurance:**
  [assurance matrix](https://domezsolt.gitlab.io/ultrastable/assurance-matrix/),
  [replay semantics](https://domezsolt.gitlab.io/ultrastable/replay_semantics/), and
  [security advisory](https://domezsolt.gitlab.io/ultrastable/security/ADV-2026-001-evidence-bundle/)
- **Benchmarks and reproducibility:**
  [AFMB explanation](https://domezsolt.gitlab.io/ultrastable/afmb_explained/),
  [run manifests](https://domezsolt.gitlab.io/ultrastable/benchmark_manifest/), and
  [repository benchmark policy](https://gitlab.com/domezsolt/ultrastable/-/blob/main/benchmarks/README.md)
- **Development:**
  [architecture](https://gitlab.com/domezsolt/ultrastable/-/blob/main/ARCHITECTURE.md),
  [contribution guide](https://gitlab.com/domezsolt/ultrastable/-/blob/main/CONTRIBUTING.md), and
  [release checklist](https://gitlab.com/domezsolt/ultrastable/-/blob/main/RELEASE_CHECKLIST.md)

## 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:

```bash
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](https://gitlab.com/domezsolt/ultrastable/-/issues)
- [Report a vulnerability privately](https://gitlab.com/domezsolt/ultrastable/-/blob/main/SECURITY.md)
- [Contribute a change](https://gitlab.com/domezsolt/ultrastable/-/blob/main/CONTRIBUTING.md)
- [Read the code of conduct](https://gitlab.com/domezsolt/ultrastable/-/blob/main/CODE_OF_CONDUCT.md)
- [Review release history](https://gitlab.com/domezsolt/ultrastable/-/blob/main/CHANGELOG.md)

## License and citation

Ultrastable is released under the
[MIT License](https://gitlab.com/domezsolt/ultrastable/-/blob/main/LICENSE).
For research use, cite the software metadata in
[`CITATION.cff`](https://gitlab.com/domezsolt/ultrastable/-/blob/main/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.
