Governance AI SDK for Python

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

Publicacion objetivo en PyPI:

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

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

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

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:

pip install -e ./sdk/python

Ejecutar tests:

python -m pytest ./sdk/python/tests

Build:

python -m build ./sdk/python

Publicacion:

python -m twine upload dist/*

Semver y changelog

• Version actual: 0.1.0
• Historial: CHANGELOG.md
• Licencia: LICENSE

Referencias

• sdk/README.md
• sdk/javascript/README.md
• sdk/python-agents/README.md
• example_usage.py