governanceai 0.1.0

Official Governance AI SDK for Python runtimes and guardrails instrumentation

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