Metadata-Version: 2.4
Name: abi-policy
Version: 0.1.2
Summary: Deterministic policy evaluation engine for the ABI ecosystem
Project-URL: Homepage, https://github.com/AbilityBI/abi-policy
Project-URL: Repository, https://github.com/AbilityBI/abi-policy
Project-URL: Documentation, https://abilitybi.github.io/abi-infra/
Project-URL: Changelog, https://github.com/AbilityBI/abi-policy/blob/main/CHANGELOG.md
License-Expression: MIT
License-File: LICENSE
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.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == 'yaml'
Description-Content-Type: text/markdown

# abi-policy

Deterministic policy evaluation engine for AI agent governance. Evaluate routing rules, tool allowlists, and budget thresholds against structured decision requests.

Zero required dependencies.

## Install (after PyPI publication)

```bash
pip install abi-policy
```

> **Status**: Not yet published to PyPI. Install from source: `pip install -e .` from the repo root.

## Quick start

### Policy evaluation

```python
from abi_policy.engine import PolicyEngine
from abi_policy.models import DecisionRequest

# Load a policy bundle with tool allow/deny lists and escalation rules
bundle = {
    "bundle_id": "default",
    "rules": {
        "tools": {"allow": ["web_search", "file_read"], "deny": ["rm_rf"]},
        "escalation": {"risky_actions": {"override:*": "require_approval"}},
    },
}

engine = PolicyEngine(bundle)

# Evaluate a decision
request = DecisionRequest(action="tool_call", resource="web_search", run_id="run-42")
response = engine.evaluate(request)

print(response.decision)    # "allow" | "deny" | "require_approval"
print(response.reason_code) # e.g., "TOOL_ALLOWED"
print(response.explanation) # human-readable explanation
```

### Capability matrix

```python
from abi_policy.capability_matrix import CapabilityMatrix, AgentProfile

# Define agent capabilities with per-task confidence scores
profile = AgentProfile(
    agent_id="claude_code",
    agent_version="claude-sonnet-4",
    confidence_by_task={"code_write": 0.9, "test_run": 0.85},
    failure_patterns=["timeout on large repos"],
)

matrix = CapabilityMatrix()
matrix.add_profile(profile)
best = matrix.get_best_agent("code_write")  # "claude_code"
```

## What's included

- **PolicyEngine** -- deterministic rule evaluation against structured `DecisionRequest`/`DecisionResponse` models
- **Capability matrix** -- agent profile management with capability boundaries
- **Boundary registry** -- track and enforce cross-component access boundaries
- **Escalation rules** -- pattern-matching for risky actions that require approval
- **Tool allowlists** -- declarative control over which tools an agent can invoke

## Use it standalone

`abi-policy` works on its own for any AI agent governance scenario. Define policy bundles, load them into the engine, and evaluate decision requests. No ABI ecosystem integration needed.

Within the ABI ecosystem, it integrates with the orchestrator for pre-flight agent decisions.

## ABI ecosystem

Related packages:

- [abi-control-core](https://github.com/AbilityBI/abi-core) -- contracts and audit trail SDK
- [abi-evals](https://github.com/AbilityBI/abi-evals) -- eval runner and golden management
- [abi-observability](https://github.com/AbilityBI/abi-observability) -- OTLP-compliant telemetry

## Versioning

Follows Semantic Versioning. Current version: `0.1.2`. See CHANGELOG.md for release notes.

## License

MIT License (see LICENSE file).
