Metadata-Version: 2.4
Name: airlock-hitl
Version: 0.1.0
Summary: A human-approval gate for the dangerous things an AI agent does.
Project-URL: Homepage, https://github.com/fedorello/airlock
Project-URL: Repository, https://github.com/fedorello/airlock
Project-URL: Issues, https://github.com/fedorello/airlock/issues
Author: Fedor Chishchin
License-Expression: MIT
Keywords: agent,ai,approval,guardrails,human-in-the-loop,llm,tool-use
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: pydantic>=2.13.4
Requires-Dist: redis>=8.0.1
Description-Content-Type: text/markdown

# airlock (Python)

A human-approval gate for the dangerous things an AI agent does. This is the
Python package; see the [repository root](../../README.md) for the full story, the
quickstart, and the TypeScript package. It mirrors the TypeScript package
one-to-one (same design, same names).

## Install

```bash
pip install airlock-hitl      # or: uv add airlock-hitl
```

The distribution is named `airlock-hitl`; the import is `airlock`:

```python
from airlock import Agent, RiskTier
```

Requires Python 3.13+.

## What you get

- An `Agent` that runs a tool-use loop and **pauses** before any tool you mark
  `RiskTier.SENSITIVE`, until a human approves, edits, or rejects it.
- Model-agnostic providers (`AnthropicProvider`, `OpenAiProvider`) over an injected
  `httpx` client — no SDKs.
- Redis store and Pub/Sub bus for pause/resume across processes, plus in-memory
  fakes for tests and demos.

See the [root quickstart](../../README.md#quickstart) for a ~20-line example.

## Layout (hexagonal — imports point inward)

- `src/airlock/domain` — tools, risk tiers, messages, runs, events, errors. No I/O.
- `src/airlock/application` — the agent loop, the gate policy, and the ports
  (`Protocol`s).
- `src/airlock/infrastructure` — adapters: providers, the Redis store and bus,
  audit sinks, clocks, id generators, and the in-memory fakes.
- `src/airlock/interface` — driving adapters: the runner and the approver.
- `src/airlock/core` — `Settings` (pydantic-settings).
- `examples/support_agent` — a runnable demo (see its
  [README](./examples/support_agent/README.md)).

## Commands

| Command | What it does |
| --- | --- |
| `uv run ruff check . && uv run ruff format --check .` | lint + format |
| `uv run mypy` | `mypy --strict` |
| `uv run lint-imports` | hexagonal import contracts |
| `uv run pytest` | unit + eval tests with coverage (≥ 90%) |
| `uv run pytest tests/integration --no-cov` | Redis integration tests |

Built and tested to [CODING_PRINCIPLES.md](../../CODING_PRINCIPLES.md). From the
repo root, `make py-check` runs the full gate.
