Metadata-Version: 2.4
Name: governanceai
Version: 0.1.0
Summary: Official Governance AI SDK for Python runtimes and guardrails instrumentation
Author: Governance AI
License-Expression: MIT
Project-URL: Homepage, https://github.com/governanceai/governanceai-python
Project-URL: Repository, https://github.com/governanceai/governanceai-python
Project-URL: Issues, https://github.com/governanceai/governanceai-python/issues
Project-URL: Changelog, https://github.com/governanceai/governanceai-python/blob/main/CHANGELOG.md
Keywords: governanceai,ai,sdk,guardrails,security
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 SDK for Python

SDK oficial de Python para integrar runtimes con Governance AI Guardrails.

Publicacion objetivo en PyPI:

```bash
pip install governanceai
```

El paquete mantiene compatibilidad con el import legado `governance_guardrails_sdk`, pero el nombre canonico nuevo es `governanceai`.

## API cubierta

- `POST /guardrails/install`
- `POST /guardrails/evaluate`
- `POST /guardrails/heartbeat`
- `POST /guardrails/events`

## Autenticacion

El SDK usa:

- `app_number` en el body
- `Authorization: Bearer <APP_API_KEY>` en cada request

## Quick start

```python
from governanceai import GovernanceAIClient, GovernanceAIError

client = GovernanceAIClient(
    base_url="https://api.governanceai.example",
    app_number=123456,
    app_api_key="ga_live_replace_me",
    timeout_seconds=10,
    max_retries=2,
)

try:
    client.install(mode="monitor", metadata={"environment": "production"})
    client.heartbeat()

    decision = client.apply("Summarize this support ticket", stage="input")
    print(decision.allowed, decision.findings, decision.selected_validators)
except GovernanceAIError as exc:
    print(exc.status_code, exc)
```

## Ejemplo real de flujo runtime

```python
from governanceai import GovernanceAIClient

client = GovernanceAIClient(
    base_url="https://api.governanceai.example",
    app_number=123456,
    app_api_key="ga_live_replace_me",
    default_policy_id="default-runtime-policy",
)

decision_in = client.apply(user_prompt, stage="input")
if not decision_in.allowed:
    raise RuntimeError(decision_in.findings)

model_reply = llm.invoke(user_prompt)
decision_out = client.apply(model_reply, stage="output")
if not decision_out.allowed:
    raise RuntimeError(decision_out.findings)
```

## Manejo de errores, timeout y retry

`GovernanceAIClient` expone:

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

Los errores del SDK levantan `GovernanceAIError` con:

- `status_code`
- `response_body`

Los retries se aplican a errores de red y a respuestas transientes como `408`, `429`, `500`, `502`, `503` y `504`.

## Capabilities

### `install()`

Registra el runtime y devuelve el estado efectivo de guardrails.

### `heartbeat()`

Mantiene la señal de vida del runtime y puede enviar telemetría agregada del SDK.

### `apply()`

Evalua texto runtime con soporte para:

- `policy_id`
- `mode`
- `stage`
- `tool_calls`
- `metadata`
- `include_telemetry`

Respuesta:

- `allowed`
- `output_text`
- `findings`
- `selected_validators`
- `effective_scope`
- `mode`

### `record_event()`

Emite eventos custom al backend.

### `report_redteam_probe()`

Atajo para registrar `event_type=redteam_probe`.

## Ejemplo con tool calls

```python
decision = client.apply(
    "Open the customer export",
    stage="tool",
    tool_calls=[
        {
            "tool_name": "browser.fetch",
            "url": "https://example.com/private-report",
        }
    ],
)
print(decision.allowed)
```

Si el dominio no esta permitido por la configuracion de la aplicacion, el backend puede responder bloqueando la operacion.

## Tests y release

Instalacion editable:

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

Ejecutar tests:

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

Build:

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

Publicacion:

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

## Semver y changelog

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

## Referencias

- [`sdk/README.md`](../README.md)
- [`sdk/javascript/README.md`](../javascript/README.md)
- [`sdk/python-agents/README.md`](../python-agents/README.md)
- [`example_usage.py`](./example_usage.py)
