Metadata-Version: 2.4
Name: governanceai-guardrails-agent
Version: 0.1.0
Summary: Official Governance AI Agent Guardrails SDK for Python agents and tool execution
Author: Governance AI
License-Expression: MIT
Project-URL: Homepage, https://github.com/governanceai/governanceai-guardrails-agent
Project-URL: Repository, https://github.com/governanceai/governanceai-guardrails-agent
Project-URL: Issues, https://github.com/governanceai/governanceai-guardrails-agent/issues
Project-URL: Changelog, https://github.com/governanceai/governanceai-guardrails-agent/blob/main/CHANGELOG.md
Keywords: governanceai,ai,sdk,agents,guardrails
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Governance AI Agent Guardrails SDK for Python

SDK oficial para instrumentar agentes, tools y pasos LLM con Governance AI Agent Guardrails.

Publicacion objetivo en PyPI:

```bash
pip install governanceai-guardrails-agent
```

Import principal:

```python
import agent_control
from agent_control import ControlViolationError, ControlSteerError, control
```

## API cubierta

- `POST /agent-guardrails/runtime/agents/init`
- `GET /agent-guardrails/runtime/agents/{agent_name}/controls`
- `POST /agent-guardrails/runtime/evaluate`
- `POST /agent-guardrails/runtime/events`

## Autenticacion

El SDK usa:

- `app_number` en requests
- `Authorization: Bearer <APP_API_KEY>`

Puedes configurar por argumentos o por variables:

- `AGENT_CONTROL_URL`
- `AGENT_CONTROL_APP_NUMBER`
- `AGENT_CONTROL_APP_API_KEY`

## Quick start

```python
import asyncio

import agent_control
from agent_control import ControlViolationError, control


@control("query_db", step_type="tool")
async def query_db(query: str, context: dict | None = None) -> str:
    return f"Executed: {query}"


async def main() -> None:
    agent_control.init(
        agent_name="support_bot",
        agent_description="Customer support automation",
        base_url="https://api.governanceai.example",
        app_number=123456,
        app_api_key="ga_live_replace_me",
        default_metadata={"environment": "production"},
    )

    try:
        print(await query_db("SELECT * FROM tickets", context={"tenant": "acme"}))
    except ControlViolationError as exc:
        print(f"Blocked by {exc.control_name}: {exc.message}")


asyncio.run(main())
```

## Que resuelve

- Registro del agente y sus pasos
- Decoradores `@control()` para pasos sync/async
- Evaluacion `pre` y `post` por step
- Eventos de ejecucion, bloqueo, steering y error
- Metadata runtime por trace/span

## Errores, timeout y retry

`AgentControlClient` soporta:

- `timeout_seconds`
- `max_retries`
- `retry_backoff_seconds`
- `retry_status_codes`

Errores del cliente:

- `AgentControlError`
- `status_code`
- `response_body`

## Tests y release

Instalacion editable:

```bash
pip install -e ./sdk/python-agents
```

Tests:

```bash
python -m pytest ./sdk/python-agents/tests
```

Build:

```bash
python -m build ./sdk/python-agents
```

Publicacion:

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

## Semver y changelog

- Version actual: `0.1.0`
- Historial: [`CHANGELOG.md`](./CHANGELOG.md)
- Licencia: [`LICENSE`](./LICENSE)
