Metadata-Version: 2.4
Name: synthelium-sdk
Version: 2.2.2
Summary: Cliente oficial de Synthelium — gobernanza verificable de agentes de IA.
Author-email: Synthelium <directiva@aletheox.com>
License: Proprietary — Todos los derechos reservados
Project-URL: Homepage, https://api.aletheox.com
Project-URL: Documentation, https://api.aletheox.com/guide
Keywords: ai,safety,compliance,risk,governance,adversarial
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: License :: Other/Proprietary License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Dynamic: license-file

# Synthelium SDK

Cliente oficial para la API de **Aletheox** — gobernanza verificable de agentes
de IA. HTTP puro: solo habla con `https://api.aletheox.com`.

## Instalación (privada)

El SDK se entrega como archivo `.whl` directamente al cliente. **No** está en el
índice público de PyPI. Instálalo desde el archivo que recibiste:

    pip install ./synthelium_sdk-2.2.2-py3-none-any.whl

Única dependencia: `httpx`.

## Uso en 3 líneas

    from synthelium_sdk import SyntheliumClient, Agent

    client = SyntheliumClient(api_key="sk-synthelium-...")
    report = client.run_evaluation(Agent(mi_funcion_llm), sector="banking")
    report.print_report()

Por defecto el cliente apunta a producción. La key se envía en cada llamada
protegida; consíguela en `directiva@aletheox.com`.

## Campo de Riesgos

Evalúa tu agente contra los seis vectores adversariales de tu sector
(`banking`, `clinical`, `telecom`).

**Atajo** — todo de una:

    report = client.run_evaluation(Agent(mi_funcion_llm), sector="banking")
    print(report.summary())

**Granular** — cuando necesitas control fino. Tu agente corre en tu máquina; el
SDK solo envía la acción propuesta:

    s = client.start_session("banking")
    sid = s["session_id"]
    while True:
        step = client.probe(sid)
        if step.get("done"):
            break
        accion = mi_agente(step["system"], step["user"])
        client.act(sid, step["vector_id"], accion)
    result = client.finalize(sid)

Otros métodos: `client.get_certificates(sid)`, `client.verify_certificate(cert)`,
`client.session_status(sid)`, `client.list_sectors()`, `client.list_vectors()`,
`client.health()`.

## Constructor de Procesos

Define tu propio proceso en lenguaje natural mediante `client.builder`:

    proceso = client.builder.parse(
        "El proceso comienza con el registro. Luego se verifica la póliza. "
        "El pago se aprueba tras el dictamen.")
    val = client.builder.validate(proceso)
    if val["valid"]:
        built = client.builder.build(proceso)
        print(built["stability_report"]["tipo_estructura"])

Plantillas:

    client.builder.list_templates()
    plantilla = client.builder.get_template("reclamacion_seguros")
    clon = client.builder.clone_template("reclamacion_seguros", "Mi proceso")

Procesos guardados: `list_processes()`, `get_process(id)`, `rebuild_process(id)`,
`delete_process(id)`. Atajo: `client.builder.build_from_text(texto)`.

## Capa de Consecuencias (gate)

Convierte el veredicto en control activo: antes de una acción crítica, tu agente
consulta el gate y solo procede si Synthelium lo permite. Si se bloquea, queda
pendiente de resolución humana — el interventor aprueba, rechaza o escala, y cada
resolución queda certificada.

    r = client.gate(sid, action="disbursement")
    if r["proceed"]:
        ejecutar_accion()
    else:
        # Bloqueado: el agente se detiene. El interventor decide en su panel.
        cert_id = r["cert_id"]
        client.approve_gate(sid, cert_id, intervenor="ana@banco.com")
        # o: client.reject_gate(...) / client.escalate_gate(...)

Consulta: `client.gate_status(sid, cert_id)`, `client.list_gates(sid)`,
`client.latest_resolution(sid)`.

## Contención activa (guard)

Para impedir que una acción fuera de la estructura llegue a ejecutarse, envuelve tu
proceso con un `guard` y llama `check(...)` **antes** de cada acción. Si está bloqueada,
`check()` lanza `ActionBlocked` y la acción no corre:

    from synthelium_sdk import ActionBlocked

    g = client.guard(process_id="proc-1", session="run-42")
    try:
        g.check("disbursement", payload={"monto": {"value": 6000, "unit": "COP"}})
        ejecutar_accion()                      # solo se ejecuta si el gate lo permitió
    except ActionBlocked as e:
        # e.enforced=True  -> corte VINCULANTE (nodo sellado): no se ejecuta, sin humano.
        # e.requires_human -> bloqueo advisory: el interventor decide en su panel.
        # e.authorized_by  -> hash del cert de config que autorizó el corte (Ed25519);
        #                     prueba verificable offline de que el bloqueo estuvo autorizado.
        manejar_bloqueo(e)

Advisory con espera al interventor: `g.check("disbursement", payload=..., wait_human=True)`
(devuelve cuando se aprueba; lanza si se rechaza/escala/vence).

**Política ante caída del gate (por nodo):** un nodo con corte **sellado** es *fail-closed*
(si no se puede verificar, no se ejecuta); el resto es *fail-open* (procede). El guard cachea
qué nodos están sellados al crearse; refréscalo con `g.refresh()`.

**Sellar el corte de un nodo** (qué nodos cortan de verdad):

    client.set_enforce("proc-1", "disbursement", True)   # sella el corte vinculante
    client.get_enforce("proc-1")                          # {node_id: enforce}

### Shadow mode (observe)

Para validar la política en producción **sin riesgo**: tu IA opera normal y, en paralelo,
`observe()` registra qué decisión habría tomado Synthelium (con su cert Ed25519 OBSERVADO) **sin
bloquear ni interrumpir nunca**. `observe()` NO lanza: ante un fallo de red retorna y tu agente sigue.

    g = client.guard(process_id="proc-1", session="run-42")
    r = g.observe("disbursement", payload={"monto": {"value": 6000, "unit": "COP"}})
    ejecutar_accion()                          # tu IA ejecuta SIEMPRE; observe solo registra
    # r["would_block"]       -> la política HABRÍA bloqueado esta acción
    # r["would_be_binding"]  -> el corte real HABRÍA sido vinculante (nodo sellado)
    # r["cert_id"]           -> registro de la decisión; KPI: "decisiones auditadas"

## Monitoreo 24/7

Recibe alertas en tiempo real (bloqueos, gates vencidos, patrones de ataque) en tu
propio webhook, y consulta el Panel del Interventor:

    client.monitoring.subscribe("https://tu-servidor/webhook")
    client.monitoring.panel()     # gates pendientes, bloqueos 24h, alertas activas
    client.monitoring.health()

Eventos disponibles: `blocked`, `gate_pending`, `gate_expired`, `pattern_detected`.

## Manejo de errores

Todas heredan de `SyntheliumError`:

| Excepción | Cuándo |
|---|---|
| `AuthenticationError` | API key ausente o inválida (401) |
| `RateLimitError` | Límite de uso alcanzado (429), tras reintentos |
| `ServerError` | Error del servidor (5xx), tras reintentos |
| `SyntheliumConnectionError` | No se pudo conectar (red/DNS) |
| `SyntheliumError` | Base — captura cualquier fallo del SDK |

El SDK **reintenta con backoff** ante `429` y timeouts (hasta 3 intentos).

## Privacidad

Tu agente se ejecuta **siempre en tu propia máquina**. El SDK pide cada escenario
al servidor, corre tu función localmente y solo envía la acción propuesta. Tu
código nunca sale de tu host.

## Acceso

`directiva@aletheox.com`
