Metadata-Version: 2.4
Name: raven-guardrail
Version: 0.1.1
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
```

Published: [pypi.org/project/raven-guardrail](https://pypi.org/project/raven-guardrail/) — MIT
licensed. See `pyproject.toml`'s `version` (or the PyPI page itself) for the current release.

## Releasing a new version

1. Bump `version` in `pyproject.toml` (PyPI rejects re-uploading an existing version number —
   there's no overwrite).
2. Rebuild:
   ```bash
   rm -rf dist build src/raven_guardrail.egg-info
   python -m build
   ```
3. Upload with an account- or project-scoped API token, using the literal string `__token__`
   as the username (not your PyPI username — token auth requires this exact value):
   ```bash
   python -m twine upload -u __token__ -p <your-token> dist/*
   ```

Still open, not yet set:

- **A contact email** on the `authors` entry in `pyproject.toml` (currently name-only —
  unset is valid, a placeholder string isn't).
- **A `[project.urls]` section** (Homepage/Repository/Issues) pointing at this project's
  real repo.
