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

Instálalo desde PyPI:

pip install synthelium-sdk

Alternativa offline / distribución privada — desde el archivo .whl 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().

Esa política solo se aplica si el guard alcanzó a leer los sellos. Si el gate ya estaba caído al crear el guard (no se sabe qué nodos están sellados), todo es fail-closed: no se puede descartar que la acción tenga corte sellado, y ante lo desconocido se corta. Antes se asumía "ninguno sellado" y el proceso entero procedía sin control — un fail-open silencioso.

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:

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