# Agent Permissions Python Library

This package provides utilities for discovering, fetching, validating, and enforcing [`agent-permissions.json`](design/standard.md) manifest files exposed by websites. It is designed to plug into agentic frameworks that need to respect site-defined automation policies.

## Features
- Discover manifests from HTML via `<link rel="agent-permissions">`
- Fetch and cache manifests over HTTP (sync and async)
- Validate manifests against the published JSON Schema along with semantic checks
- Check planned UI interactions against resource rules
- Generate prompt text for higher-level action guidelines

## Installation
```bash
pip install agent-permissions
```

## Quick Start
```python
import httpx
from lxml import html

from agent_permissions import fetch_manifest, validate_interaction

manifest = fetch_manifest("https://example.com/.well-known/agent-permissions.json")

# Fetch the current page HTML remotely (or inject your own source).
page_html = httpx.get("https://example.com/products").text

root = html.fromstring(page_html)
element = root.cssselect("#buy")[0]
validation = validate_interaction(
    manifest,
    verb="click_element",
    element=element,
)

print(validation.allowed)            # -> True or False
print(validation.requirements)       # -> e.g. {"human_in_the_loop": True}
```

Check out `samples/demo.html` with its paired `samples/agent-permissions.json` for a realistic playground to experiment with validation.

### Action guidelines and API info

```python
manifest = fetch_manifest("https://example.com/.well-known/agent-permissions.json")

# Action guidelines are in manifest.action_guidelines
for guideline in manifest.action_guidelines:
    print(f"{guideline.directive}: {guideline.description}")
    if guideline.exceptions:
        print(f"  Exceptions: {guideline.exceptions}")

# API integrations are in manifest.api
for api_ref in manifest.api:
    print(f"{api_ref.type} endpoint: {api_ref.endpoint} — {api_ref.description}")
    if api_ref.docs:
        print(f"  Docs: {api_ref.docs}")
```

For more detailed documentation, consult `design/library.md`.