llm-leash 1.3.0__tar.gz

llm_leash-1.3.0/.claude/agent-memory/project-auditor/MEMORY.md

@@ -0,0 +1 @@
+- [agent-guard project context](project_agent_guard.md) — pre-alpha OSS Python library for LLM agent safety (budget caps, audit log, kill switch, HITL); 0 tests, 0 CI, most modules are empty stubs as of 2026-05-16

llm_leash-1.3.0/.claude/agent-memory/project-auditor/project_agent_guard.md

@@ -0,0 +1,17 @@
+---
+name: agent-guard project context
+description: Core facts about the agent-guard repo — pre-alpha OSS library for LLM agent safety (budget caps, audit log, kill switch, HITL)
+type: project
+---
+
+agent-guard is a pre-alpha Python library (v0.0.1) that provides runtime enforcement for LLM agents: hard USD budget caps, append-only hash-chained JSONL audit log, kill switch, and human-in-the-loop webhook. One import, one class: `from agent_guard import Firewall`.
+
+**Why:** Targets the uncontested B2B layer — cost enforcement and compliance evidence — explicitly not competing with content-safety scanners (LlamaFirewall, Invariant, NeMo Guardrails).
+
+**How to apply:** When suggesting implementations, enforce the core constraints: zero runtime deps for core (stdlib only), adapters ≤300 LOC each, async-first sync-compatible, JSONL audit format is a wire contract. The Firewall facade surface (3 properties, 3 methods, 1 constructor) is locked in API.md.
+
+Current state as of 2026-05-16:
+- firewall.py and types.py have ~229 LOC of real code; all other modules (budget, audit, kill, hitl, policy, adapters, cli) are 0-LOC stubs.
+- 0 tests. No CI. No CVE scanner.
+- 5 P0 tasks, 5 P1 tasks, 4 P2 tasks in Beads (prefix: dreamy-swirles-89f100).
+- Next milestone: v0.1 — core firewall + Anthropic/OpenAI adapters + CLI (replay, verify).

llm_leash-1.3.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "claude/**"]
+  pull_request:
+
+jobs:
+  release-check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Release acceptance gate
+        run: bash scripts/release_check.sh

llm_leash-1.3.0/.github/workflows/publish.yml

@@ -0,0 +1,60 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  acceptance:
+    name: Re-run acceptance gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Release acceptance gate
+        run: bash scripts/release_check.sh
+
+  build-and-publish:
+    name: Build & publish
+    needs: acceptance
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # OIDC trusted-publisher to PyPI
+      contents: read
+    environment:
+      name: pypi
+      url: https://pypi.org/p/llm-leash
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Verify tag matches package version
+        run: |
+          PKG_VERSION=$(python -c "import tomllib; print(tomllib.loads(open('pyproject.toml','rb').read().decode())['project']['version'])")
+          TAG_VERSION="${GITHUB_REF#refs/tags/v}"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "::error::Tag v$TAG_VERSION does not match pyproject version $PKG_VERSION"
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI (trusted publisher / OIDC)
+        uses: pypa/gh-action-pypi-publish@release/v1

llm_leash-1.3.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.eggs/
+build/
+dist/
+
+# Test/Coverage
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+
+# Local audit logs created by examples / tests
+*.jsonl
+!docs/**/*.jsonl
+!examples/**/sample-*.jsonl
+
+# Secrets
+.env
+.env.*
+!.env.example
+
+# Hatchling
+.hatch/

llm_leash-1.3.0/.great_cto/PROJECT.md

@@ -0,0 +1,48 @@
+# llm-leash
+
+## Type
+primary: library-sdk
+secondary: agent-platform
+archetype: devtools
+approval-level: gates-only
+review_mode: auto
+
+## Stack
+- python: 3.11.8 (supports 3.11–3.13)
+- build-backend: hatchling>=1.21
+- test: pytest>=8.0, pytest-asyncio>=0.24, hypothesis>=6.100, vcrpy>=6.0
+- lint: ruff>=0.6
+- types: mypy>=1.10 (strict)
+- optional-anthropic: anthropic>=0.40
+- optional-openai: openai>=1.50
+- optional-langgraph: langgraph>=0.2
+- optional-crewai: crewai>=0.80
+- optional-redis: redis>=5.0
+- infra: none (library, no server infra)
+
+## Domain
+agent-safety, llm-cost-control, audit-compliance, kill-switch, human-in-the-loop
+
+## Compliance signals
+- EU AI Act Article 12 (audit log evidence)
+- SOC 2 Type II (planned v1.0)
+- Zero runtime deps core (non-negotiable per PRODUCT.md)
+
+## Env
+- no runtime env vars required for core
+- AUDIT_LOG_PATH: optional, path to JSONL audit file
+- REDIS_URL: optional, for RedisStore / RedisKillRegistry
+
+## L3
+p0-threshold: test_suite_failures > 0
+p1-threshold: mypy_errors > 0
+error-log: (no server — library; errors raised as LeashBlocked / LeashKilled)
+
+## Team
+size: 1
+authors: avelikiy@users.noreply.github.com
+
+## Last Audit
+date: 2026-05-16
+findings: P0:5 P1:5 P2:4 P3:0
+next-audit: 2026-08-14

llm_leash-1.3.0/AGENTS.md

@@ -0,0 +1,84 @@
+# Agent Instructions
+
+This project uses **bd** (beads) for issue tracking. Run `bd onboard` to get started.
+
+## Quick Reference
+
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --claim  # Claim work atomically
+bd close <id>         # Complete work
+bd dolt push          # Push beads data to remote
+```
+
+## Non-Interactive Shell Commands
+
+**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.
+
+Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.
+
+**Use these forms instead:**
+```bash
+# Force overwrite without prompting
+cp -f source dest           # NOT: cp source dest
+mv -f source dest           # NOT: mv source dest
+rm -f file                  # NOT: rm file
+
+# For recursive operations
+rm -rf directory            # NOT: rm -r directory
+cp -rf source dest          # NOT: cp -r source dest
+```
+
+**Other commands that may prompt:**
+- `scp` - use `-o BatchMode=yes` for non-interactive
+- `ssh` - use `-o BatchMode=yes` to fail instead of prompting
+- `apt-get` - use `-y` flag
+- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var
+
+<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
+## Beads Issue Tracker
+
+This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
+
+### Quick Reference
+
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --claim  # Claim work
+bd close <id>         # Complete work
+```
+
+### Rules
+
+- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
+- Run `bd prime` for detailed command reference and session close protocol
+- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
+
+## Session Completion
+
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
+
+**MANDATORY WORKFLOW:**
+
+1. **File issues for remaining work** - Create issues for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **PUSH TO REMOTE** - This is MANDATORY:
+   ```bash
+   git pull --rebase
+   bd dolt push
+   git push
+   git status  # MUST show "up to date with origin"
+   ```
+5. **Clean up** - Clear stashes, prune remote branches
+6. **Verify** - All changes committed AND pushed
+7. **Hand off** - Provide context for next session
+
+**CRITICAL RULES:**
+- Work is NOT complete until `git push` succeeds
+- NEVER stop before pushing - that leaves work stranded locally
+- NEVER say "ready to push when you are" - YOU must push
+- If push fails, resolve and retry until it succeeds
+<!-- END BEADS INTEGRATION -->

llm_leash-1.3.0/API.md

@@ -0,0 +1,250 @@
+# API Reference
+
+Stable, semver-guaranteed surface for `llm-leash` v1.0.
+
+Anything imported from `llm_leash` at the top level is **stable**: breaking
+changes require a major-version bump. Everything else (`llm_leash.adapters.*`,
+`llm_leash.audit.*`, `llm_leash.policy.*`) is **public but versioned at the
+minor level**; new methods and parameters can land in minor releases, but
+existing signatures will not change without a deprecation cycle.
+
+## Top-level imports
+
+```python
+from llm_leash import (
+    Firewall,             # facade
+    # exception types
+    LeashKilled, LeashBlocked, LeashRejectedByHuman,
+    # rule types
+    Rule, Decision, Action, PolicyContext, ToolCall, PolicyEngine,
+    # built-in rules
+    BlockedPatterns, BlockedShell, BlockedSql, BudgetThreshold,
+    HitlThreshold, PiiRedactor,
+    # HITL
+    HitlGate, InMemoryHitlGate, WebhookHitlGate,
+    # backing stores
+    RedisBudgetStore, RedisKillRegistry,
+    SQLiteBudgetStore, SQLiteKillRegistry,
+)
+```
+
+## `Firewall`
+
+The single entry point.
+
+```python
+Firewall(
+    *,
+    budget_usd: float | None = None,
+    budget_soft_usd: float | None = None,
+    audit_log: str | None = None,
+    kill_registry: KillRegistry | None = None,
+    session_id: str | None = None,
+    tenant_id: str | None = None,
+    rules: list[Rule] | None = None,
+    pii_redactor: PiiRedactor | None = None,
+    hitl_gate: HitlGate | None = None,
+)
+```
+
+### Methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `wrap(client)` | wrapped client | Dispatches to the right adapter by client shape |
+| `await kill(reason)` | `None` | Marks the session killed; next call raises `LeashKilled` |
+| `await cumulative_usd()` | `float` | Total spend for this session so far |
+| `await aclose()` | `None` | Flushes audit log |
+
+### Adapter dispatch
+
+`fw.wrap(client)` detects the client shape and chooses an adapter:
+
+| Client shape | Adapter |
+|---|---|
+| `client.messages.create(...)` | **Anthropic** |
+| `client.chat.completions.create(...)` | **OpenAI** |
+| `client.invoke(messages)` + `.model_name` or `.model` | **LangChain / LangGraph** |
+| `client.call_tool(name, args)` | **MCP** |
+| `client.call(messages)` + `.model` | **CrewAI** |
+| Unknown | pass-through (no wrapping) |
+
+The wrapped client preserves the original surface — all unrelated attributes
+delegate to the underlying object.
+
+## Exceptions
+
+| Exception | When |
+|---|---|
+| `LeashKilled` | Hard budget cap exceeded **or** kill switch tripped |
+| `LeashBlocked` | A policy rule returned `action="block"` |
+| `LeashRejectedByHuman` | A HITL gate denied (explicitly or by timeout) |
+
+Each carries `rule_id: str` and `reason: str`.
+
+## Rules
+
+A `Rule` is any object implementing the protocol:
+
+```python
+class MyRule:
+    id: str = "my_rule"
+    def evaluate(self, call: ToolCall, ctx: PolicyContext) -> Decision | None: ...
+```
+
+Return `None` to abstain; return `Decision(action=..., rule_id=..., reason=...)`
+to act. The engine evaluates rules in order; the **first non-`None`** decision
+wins.
+
+`Decision.action` is one of: `"allow"`, `"block"`, `"warn"`, `"hitl"`.
+
+### Built-in rules
+
+| Rule | Purpose |
+|---|---|
+| `BlockedPatterns([regex, ...])` | Block requests whose stringified args match any pattern |
+| `BlockedSql(mode="read_only" \| "no_ddl", extra_deny=[...])` | SQL keyword denylist |
+| `BlockedShell()` | 10-pattern shell command blocklist (rm -rf, curl\|bash, etc.) |
+| `BudgetThreshold(threshold_pct=0.8)` | Emit `warn` decisions as the cap approaches |
+| `HitlThreshold(threshold_pct=0.8)` | Trigger HITL approval as the cap approaches |
+| `PiiRedactor()` | Not a rule — passed via `pii_redactor=` to scrub args |
+
+### Custom rule example
+
+```python
+from llm_leash import Decision, Firewall
+
+class DenyToolByName:
+    id = "deny_tool"
+    def __init__(self, names: set[str]) -> None:
+        self._names = names
+    def evaluate(self, call, ctx):
+        if call.tool in self._names:
+            return Decision(action="block", rule_id=self.id,
+                            reason=f"tool {call.tool} is on the denylist")
+        return None
+
+fw = Firewall(rules=[DenyToolByName({"shell_exec", "delete_file"})])
+```
+
+## Human-in-the-loop
+
+```python
+class HitlGate(Protocol):
+    async def request(self, call: ToolCall, decision: Decision) -> None: ...
+```
+
+A call that returns from `request()` is **approved**. To reject, raise
+`LeashRejectedByHuman`.
+
+Built-in implementations:
+
+- **`InMemoryHitlGate(default="approve" | "reject")`** — fixtures and tests.
+- **`WebhookHitlGate(url, timeout_secs=60, poll_interval_secs=2)`** —
+  `POST {url}/requests` then poll `GET {url}/requests/{id}`. Stdlib `urllib`,
+  zero deps.
+
+If a rule returns `Decision(action="hitl")` and **no gate is configured**,
+the call is **default-denied** with `LeashRejectedByHuman`.
+
+## Audit log
+
+Every model call and tool call writes one JSON line, sha256-chained:
+
+```jsonc
+{
+  "kind": "model_call",
+  "ts": "2026-05-16T12:34:56.789Z",
+  "session_id": "s_…", "tenant_id": null,
+  "seq": 42, "prev_hash": "9af…", "hash": "0c1…",
+  "provider": "anthropic", "model": "claude-opus-4-7",
+  "input_tokens": 1024, "output_tokens": 256,
+  "cost_usd": 0.1234,
+  "request_hash": "…", "response_hash": "…"
+}
+```
+
+Event kinds: `model_call`, `tool_call`, `budget`, `kill`.
+
+### CLI
+
+```bash
+llm-leash verify  audit.jsonl                # exits 0 if chain is intact, 2 if broken
+llm-leash replay  audit.jsonl                # prints events as JSON lines
+llm-leash export  audit.jsonl --format csv   # CSV with stable column order
+llm-leash export  audit.jsonl --format json  # full JSON array
+```
+
+### Programmatic access
+
+```python
+from llm_leash.audit.replay import replay, export_csv, export_json
+from llm_leash.audit.verify import verify_chain
+
+verify_chain("audit.jsonl")                  # → int (event count); raises ChainBroken
+list(replay("audit.jsonl"))                  # iterator of event dicts
+export_csv("audit.jsonl", sys.stdout)        # CSV writer
+export_json("audit.jsonl", sys.stdout)       # JSON-array writer
+```
+
+## Backing stores
+
+By default, budget and kill state live in-process and are lost on restart.
+For multi-worker production, swap in a persistent backend:
+
+```python
+from llm_leash import Firewall, SQLiteBudgetStore, SQLiteKillRegistry
+
+budget_store = SQLiteBudgetStore("/var/lib/myapp/budget.db")
+kill_registry = SQLiteKillRegistry("/var/lib/myapp/kill.db")
+
+fw = Firewall(budget_usd=100.0, kill_registry=kill_registry)
+fw._budget._store = budget_store  # explicit swap; constructor wiring lands in v1.1
+```
+
+Redis equivalents — `RedisBudgetStore(redis_client)` / `RedisKillRegistry(redis_client)`
+— accept any duck-typed Redis client (e.g. `redis.Redis`, `fakeredis.FakeRedis`).
+
+## Type definitions
+
+```python
+@dataclass(frozen=True)
+class ToolCall:
+    tool: str
+    args: dict[str, Any]
+    session_id: str
+    tenant_id: str | None
+
+@dataclass(frozen=True)
+class PolicyContext:
+    cumulative_usd: float
+    budget_cap_usd: float | None
+    soft_cap_usd: float | None
+    tenant_id: str | None
+
+@dataclass(frozen=True)
+class Decision:
+    action: Action               # "allow" | "block" | "warn" | "hitl"
+    rule_id: str
+    reason: str
+```
+
+## Version
+
+```python
+import llm_leash
+llm_leash.__version__   # → "1.0.0"
+```
+
+## Stability promise
+
+From v1.0:
+- The top-level exports listed above are **semver-stable**.
+- The audit JSONL schema is **stable**: existing fields will not be removed
+  or change meaning. New fields may be added.
+- The CLI sub-commands `verify`, `replay`, `export` are **stable**.
+- Breaking changes in any of the above require a **major-version** bump.
+- Anything in `llm_leash.adapters.*`, `llm_leash.audit.*`, `llm_leash.policy.*`,
+  `llm_leash.budget.*`, `llm_leash.kill.*` is **public but versioned at the
+  minor level** — back-compat across minor releases unless a deprecation
+  warning was emitted in the prior minor.