warrantd 0.1.0__tar.gz

warrantd-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Type-check
+        run: uv run mypy --strict warrantd
+
+      - name: Test (with coverage gate on graduation.py and decision.py)
+        run: >
+          uv run pytest
+          --cov=warrantd
+          --cov-report=term-missing
+          --cov-fail-under=90
+          --cov=warrantd/graduation.py
+          --cov=warrantd/decision.py

warrantd-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,71 @@
+name: release
+
+# Publishes warrantd to PyPI via OIDC trusted publishing — no API tokens.
+#
+# Setup (one-time, on PyPI):
+#   1. Create the `warrantd` project's trusted publisher pointing at this repo,
+#      workflow `release.yml`, and environment `pypi`.
+#   2. (Optional) Do the same on TestPyPI with environment `testpypi`.
+#
+# Usage:
+#   - Cut a GitHub Release -> builds and publishes to PyPI.
+#   - Run manually (workflow_dispatch) and pick `testpypi` to rehearse first.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Package index to publish to"
+        type: choice
+        options: [testpypi, pypi]
+        default: testpypi
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uvx twine check dist/*
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # A GitHub Release always targets PyPI; a manual run uses the chosen index.
+    environment: ${{ github.event_name == 'release' && 'pypi' || inputs.target }}
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        if: ${{ github.event_name == 'release' || inputs.target == 'pypi' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Publish to TestPyPI
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

warrantd-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Virtual envs
+.venv/
+venv/

warrantd-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-09
+
+Initial public release.
+
+### Added
+- `TrustLayer` facade with a pure `evaluate()` decision flow
+  (kill switch → earned autonomy state → caps/value → verdict) and a
+  deterministic `idempotency_key`.
+- Pure, deterministic `GraduationEngine` computing the highest earned
+  `AutonomyState` from eval metrics, clamped by a per-class policy ceiling.
+- Core value types: `RiskTier`, `AutonomyState`, `Verdict`, `ActionClass`,
+  `ActionRequest`, `EvalMetrics`, `Decision`, `TrustPolicy`,
+  `GraduationThresholds`, `AuditEntry`.
+- Boundary protocols implemented by the consuming app: `MetricsProvider`,
+  `ApprovalGate`, `AuditSink`.
+- `KillSwitch` with global and per-action trips; configurable tripped verdict
+  (`BLOCK` or `REQUIRE_APPROVAL`).
+- `py.typed` marker; ships fully typed and `mypy --strict` clean.
+- Runnable `examples/quickstart.py` with in-memory stubs.
+
+[Unreleased]: https://github.com/moritzkazooba-wq/warrantd/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/moritzkazooba-wq/warrantd/releases/tag/v0.1.0

warrantd-0.1.0/CLAUDE.md

@@ -0,0 +1,33 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working in this repository.
+
+## Source of truth
+
+[`warrantd-spec.md`](./warrantd-spec.md) is the authoritative build spec for this
+project — architecture, the core decision model, and the public API. **Read it
+before making changes** and implement to the interfaces it defines. Do not
+improvise the decision or graduation model; follow the signatures and decision
+flow in the spec.
+
+## Quick orientation
+
+`warrantd` is a standalone, framework-agnostic trust-layer library: it decides
+whether an agent action is **ALLOW**, **REQUIRE_APPROVAL**, or **BLOCK**, and
+governs how an action class *earns* more autonomy over time.
+
+- It must **not** depend on or know about Slack, Stripe, Anthropic, OpenAI,
+  FastAPI, or any concrete transport/provider/store. Those belong in the
+  consuming app, which implements `MetricsProvider`, `ApprovalGate`, and
+  `AuditSink`.
+- The graduation function is **pure and deterministic** — no LLM, no
+  randomness — and must be unit-testable in isolation.
+
+## Conventions
+
+- Tooling: `uv`, `ruff`, `pytest`, `mypy --strict`; ship `py.typed`.
+- Keep runtime deps to the stdlib where possible (this is a trust primitive).
+- Coverage gate on `graduation.py` and `decision.py` — keep these near-100%.
+
+See `warrantd-spec.md` for the full repo layout, milestones, and boundary
+contract.

warrantd-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moritz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

warrantd-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: warrantd
+Version: 0.1.0
+Summary: A warrant daemon for agent actions — earned autonomy with an audit trail.
+Project-URL: Homepage, https://github.com/moritzkazooba-wq/warrantd
+Project-URL: Repository, https://github.com/moritzkazooba-wq/warrantd
+Author: Moritz
+License: MIT
+License-File: LICENSE
+Keywords: agents,approval,audit,autonomy,guardrails,trust
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# warrantd
+
+[![PyPI version](https://img.shields.io/pypi/v/warrantd.svg)](https://pypi.org/project/warrantd/)
+[![Python versions](https://img.shields.io/pypi/pyversions/warrantd.svg)](https://pypi.org/project/warrantd/)
+[![CI](https://github.com/moritzkazooba-wq/warrantd/actions/workflows/ci.yml/badge.svg)](https://github.com/moritzkazooba-wq/warrantd/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+
+> A warrant daemon for agent actions — earned autonomy with an audit trail.
+
+`warrantd` answers one question for an agent that wants to take an action:
+**ALLOW, REQUIRE_APPROVAL, or BLOCK?** — and governs how an action class *earns*
+more autonomy over time. It is a standalone, framework-agnostic trust primitive:
+it knows nothing about Slack, Stripe, OpenAI, Anthropic, FastAPI, or any
+transport/provider/store. Your app supplies those by implementing three small
+protocols.
+
+See [`warrantd-spec.md`](./warrantd-spec.md) for the authoritative design.
+
+## Install
+
+```bash
+uv add warrantd        # or: pip install warrantd
+```
+
+## Define a policy
+
+```python
+from decimal import Decimal
+from warrantd import (
+    ActionClass, AutonomyState, GraduationThresholds, RiskTier, TrustPolicy,
+)
+
+policy = TrustPolicy(
+    actions={
+        "read_ledger": ActionClass(name="read_ledger", risk=RiskTier.READ),
+        "issue_refund": ActionClass(
+            name="issue_refund",
+            risk=RiskTier.REVERSIBLE_WRITE,
+            auto_cap=Decimal("100"),    # auto-approve at/below this
+            hard_cap=Decimal("1000"),   # never auto-approve above this
+        ),
+    },
+    thresholds=GraduationThresholds(
+        pass_rate={AutonomyState.SUPERVISED: 0.80, AutonomyState.AUTONOMOUS: 0.95},
+        adversarial_pass_rate={AutonomyState.SUPERVISED: 0.70, AutonomyState.AUTONOMOUS: 0.90},
+        min_samples={AutonomyState.SUPERVISED: 50, AutonomyState.AUTONOMOUS: 200},
+    ),
+)
+```
+
+## Gate an action
+
+Implement `MetricsProvider` and `AuditSink` (and optionally `ApprovalGate`),
+then call `evaluate()` before every tool execution and `record()` after:
+
+```python
+from warrantd import ActionRequest, TrustLayer, Verdict
+
+trust = TrustLayer(policy=policy, metrics=my_metrics, audit=my_audit)
+
+decision = trust.evaluate(ActionRequest("issue_refund", tenant_id="acme", value=Decimal("250")))
+if decision.verdict is Verdict.ALLOW:
+    ...  # execute
+elif decision.verdict is Verdict.REQUIRE_APPROVAL:
+    ...  # route to your ApprovalGate
+else:
+    ...  # BLOCK
+```
+
+A runnable end-to-end example with in-memory stubs lives in
+[`examples/quickstart.py`](./examples/quickstart.py).
+
+## How autonomy is earned
+
+Each action class advances `MANUAL → SUPERVISED → AUTONOMOUS` only when its eval
+metrics clear the thresholds for the target state, subject to a per-class policy
+ceiling (`max_state`) and a risk ceiling for `CONSEQUENTIAL` actions. The
+graduation function is pure and deterministic — no LLM, no randomness — so the
+same metrics always yield the same allowed state.
+
+## Documentation
+
+A comprehensive, self-contained reference lives at
+[`docs/warrantd-notebooklm.md`](./docs/warrantd-notebooklm.md). It explains the
+concepts, the graduation model, the decision flow, the full API, worked
+examples, a glossary, and an FAQ in prose form — written to be dropped into
+NotebookLM (or any RAG system) as a single knowledge source.
+
+## Development
+
+```bash
+uv sync --all-extras --dev
+uv run ruff check .
+uv run mypy --strict warrantd
+uv run pytest --cov=warrantd
+```
+
+## Releasing
+
+Releases publish to PyPI via [OIDC trusted publishing][tp] — no API tokens are
+stored. One-time setup: register the `warrantd` trusted publisher on PyPI
+(repo `moritzkazooba-wq/warrantd`, workflow `release.yml`, environment `pypi`).
+Then:
+
+1. Bump the version in `pyproject.toml` and `warrantd/__init__.py`, update
+   `CHANGELOG.md`, and tag (`vX.Y.Z`).
+2. (Optional) Run the **release** workflow manually with target `testpypi` to
+   rehearse the upload.
+3. Cut a GitHub Release — the workflow builds, runs `twine check`, and publishes
+   to PyPI.
+
+[tp]: https://docs.pypi.org/trusted-publishers/
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

warrantd-0.1.0/README.md

@@ -0,0 +1,116 @@
+# warrantd
+
+[![PyPI version](https://img.shields.io/pypi/v/warrantd.svg)](https://pypi.org/project/warrantd/)
+[![Python versions](https://img.shields.io/pypi/pyversions/warrantd.svg)](https://pypi.org/project/warrantd/)
+[![CI](https://github.com/moritzkazooba-wq/warrantd/actions/workflows/ci.yml/badge.svg)](https://github.com/moritzkazooba-wq/warrantd/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+
+> A warrant daemon for agent actions — earned autonomy with an audit trail.
+
+`warrantd` answers one question for an agent that wants to take an action:
+**ALLOW, REQUIRE_APPROVAL, or BLOCK?** — and governs how an action class *earns*
+more autonomy over time. It is a standalone, framework-agnostic trust primitive:
+it knows nothing about Slack, Stripe, OpenAI, Anthropic, FastAPI, or any
+transport/provider/store. Your app supplies those by implementing three small
+protocols.
+
+See [`warrantd-spec.md`](./warrantd-spec.md) for the authoritative design.
+
+## Install
+
+```bash
+uv add warrantd        # or: pip install warrantd
+```
+
+## Define a policy
+
+```python
+from decimal import Decimal
+from warrantd import (
+    ActionClass, AutonomyState, GraduationThresholds, RiskTier, TrustPolicy,
+)
+
+policy = TrustPolicy(
+    actions={
+        "read_ledger": ActionClass(name="read_ledger", risk=RiskTier.READ),
+        "issue_refund": ActionClass(
+            name="issue_refund",
+            risk=RiskTier.REVERSIBLE_WRITE,
+            auto_cap=Decimal("100"),    # auto-approve at/below this
+            hard_cap=Decimal("1000"),   # never auto-approve above this
+        ),
+    },
+    thresholds=GraduationThresholds(
+        pass_rate={AutonomyState.SUPERVISED: 0.80, AutonomyState.AUTONOMOUS: 0.95},
+        adversarial_pass_rate={AutonomyState.SUPERVISED: 0.70, AutonomyState.AUTONOMOUS: 0.90},
+        min_samples={AutonomyState.SUPERVISED: 50, AutonomyState.AUTONOMOUS: 200},
+    ),
+)
+```
+
+## Gate an action
+
+Implement `MetricsProvider` and `AuditSink` (and optionally `ApprovalGate`),
+then call `evaluate()` before every tool execution and `record()` after:
+
+```python
+from warrantd import ActionRequest, TrustLayer, Verdict
+
+trust = TrustLayer(policy=policy, metrics=my_metrics, audit=my_audit)
+
+decision = trust.evaluate(ActionRequest("issue_refund", tenant_id="acme", value=Decimal("250")))
+if decision.verdict is Verdict.ALLOW:
+    ...  # execute
+elif decision.verdict is Verdict.REQUIRE_APPROVAL:
+    ...  # route to your ApprovalGate
+else:
+    ...  # BLOCK
+```
+
+A runnable end-to-end example with in-memory stubs lives in
+[`examples/quickstart.py`](./examples/quickstart.py).
+
+## How autonomy is earned
+
+Each action class advances `MANUAL → SUPERVISED → AUTONOMOUS` only when its eval
+metrics clear the thresholds for the target state, subject to a per-class policy
+ceiling (`max_state`) and a risk ceiling for `CONSEQUENTIAL` actions. The
+graduation function is pure and deterministic — no LLM, no randomness — so the
+same metrics always yield the same allowed state.
+
+## Documentation
+
+A comprehensive, self-contained reference lives at
+[`docs/warrantd-notebooklm.md`](./docs/warrantd-notebooklm.md). It explains the
+concepts, the graduation model, the decision flow, the full API, worked
+examples, a glossary, and an FAQ in prose form — written to be dropped into
+NotebookLM (or any RAG system) as a single knowledge source.
+
+## Development
+
+```bash
+uv sync --all-extras --dev
+uv run ruff check .
+uv run mypy --strict warrantd
+uv run pytest --cov=warrantd
+```
+
+## Releasing
+
+Releases publish to PyPI via [OIDC trusted publishing][tp] — no API tokens are
+stored. One-time setup: register the `warrantd` trusted publisher on PyPI
+(repo `moritzkazooba-wq/warrantd`, workflow `release.yml`, environment `pypi`).
+Then:
+
+1. Bump the version in `pyproject.toml` and `warrantd/__init__.py`, update
+   `CHANGELOG.md`, and tag (`vX.Y.Z`).
+2. (Optional) Run the **release** workflow manually with target `testpypi` to
+   rehearse the upload.
+3. Cut a GitHub Release — the workflow builds, runs `twine check`, and publishes
+   to PyPI.
+
+[tp]: https://docs.pypi.org/trusted-publishers/
+
+## License
+
+MIT — see [LICENSE](./LICENSE).