Metadata-Version: 2.4
Name: raven-guardrail
Version: 0.1.0
Summary: Runtime tool-call authorization, input/output screening for AI-written code.
Author: ahmenders
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: logging
Requires-Dist: raven-logger; extra == "logging"
Dynamic: license-file

# raven-guardrail

Runtime tool-call authorization, input/output screening — the decorator
`raven-decision-map`'s guardrail injector generates calls into:

```python
from raven_guardrail import tool_call

@tool_call(allowlist="vault_client.fetch_secret", input_screen="default", output_screen="default")
def get_vault_data(vault_id):
    return vault_client.fetch_secret(vault_id)
```

## What it does

- **Tool-call authorization** — a deterministic allowlist check read from a project's
  `.raven/manifest.json` `tool_allowlist` key. Deny-by-default: an unconfigured or
  unreadable manifest denies every call, rather than silently allowing it.
- **Input screening** — runs before the wrapped function executes. Ships with a working
  `"default"` screen (a denylist-phrase heuristic); register your own name to use a real
  classifier instead.
- **Output screening** — runs on the wrapped function's return value before the caller
  sees it. Ships with a working `"default"` screen (a secret-pattern scan). Always fails
  closed — an output-screen block (or an unresolvable screen name) always raises.

Zero runtime dependencies. `raven_logger` is optional — install
`raven-guardrail[logging]` to route `tool_call.denied`/`input_screen.evaluated`/
`output_screen.evaluated` events through it; without it, only P1/P2-level events print to
stderr.

## Install

```bash
pip install raven-guardrail
```

## Before you publish this package for real

This source was prepared for `pip install raven-guardrail`, but the following are
deliberately left as open decisions, not filled in with an assumed default:

- [x] **License.** MIT — `LICENSE` file added, `pyproject.toml` declares `license = "MIT"`.
      Copyright holder is set to "Giggso", inferred from the `@giggso.com` addresses used
      elsewhere in this project — correct it in `LICENSE` if that's not the right legal name.
- [ ] **`pyproject.toml`'s `authors` field** currently holds a `TODO` placeholder — replace
      with the real publishing org/contact. There's no `[project.urls]` section yet either
      (a placeholder string there fails setuptools' URL validation at build time, so it was
      left out rather than faked) — add one pointing at your real repo before publishing.
- [ ] **PyPI account + API token.** The actual `twine upload` step needs your own PyPI
      credentials — this was intentionally not run as part of preparing this package (see
      the parent conversation for why).
- [ ] **Confirm the name `raven-guardrail` is still available** on PyPI at the time you
      publish (name availability can change).

## Build

```bash
python -m build        # produces dist/*.whl and dist/*.tar.gz
```

## Publish (the one step this package's preparation does NOT do for you)

```bash
python -m twine upload dist/*
```
