SDK de Python

El paquete dcision para Python 3.9+ — compilación desde el código fuente, decide, destinos y funciones, errores, reintentos idempotentes, ejecuciones, me() y verificación de webhooks con Flask o FastAPI.

dcision es el SDK oficial de Python. Necesita Python 3.9+ y nada más —solo la biblioteca estándar (urllib, json, hmac)— y está completamente tipado (py.typed, sin errores con mypy --strict).

Instalación

Todavía no está en PyPI

dcision no está publicado en PyPI. Instálalo desde una copia local del repositorio de Dcision; hasta que esta página diga que está publicado, un paquete con este nombre en PyPI no proviene de Dcision.

# From a checkout of the Dcision repository, in your project's environment
pip install ./packages/sdk-python

uv pip install ./packages/sdk-python funciona igual. Para distribuirlo en otro lugar, compila un wheel —python -m build packages/sdk-python lo escribe en packages/sdk-python/dist— e instala ese archivo, o apunta tus requirements a la carpeta: dcision @ file:///path/to/dcision/packages/sdk-python.

Inicio rápido

Crea una clave de API en API Keys y defínela como DCISION_API_KEY en el entorno de tu servidor.

from dcision import Dcision

client = Dcision()  # reads DCISION_API_KEY

decision = client.decide(
    "lead-qualification",
    {"message": "We need pricing for 500 users and want to start next month.", "company_size": 500},
)

decision.result["route"]      # "sales"
decision.confidence["route"]  # 0.85
decision.action               # "continue" | "block" | "escalate" | "fallback"
decision.destinations         # what happens next: replies, queued deliveries, functions…

Configuración

client = Dcision(
    api_key=os.environ["DCISION_API_KEY"],  # default: the DCISION_API_KEY environment variable
    base_url="https://api.dcision.io",
    timeout=30,
    max_retries=2,
    user_agent="acme-crm/2.1",
)
ArgumentoPredeterminadoDescripción
api_keyDCISION_API_KEYdcs_live_… o dcs_test_…. Una clave ausente, o una que no empieza por dcs_, lanza DcisionError INVALID_API_KEY de inmediato: no se envía nada.
base_urlhttps://api.dcision.ioDebe usar https; http plano solo para una API en una dirección de loopback. Se admite un prefijo de ruta.
timeout30Segundos de espera en cada intento, para la conexión y para cada lectura.
max_retries2Reintentos tras un error de red, un timeout, 429, 502, 503 o 504.
user_agent—Solo por palabra clave. El identificador de tu app, antepuesto al del SDK: acme-crm/2.1 dcision-sdk-python/0.1.0.

Crea un solo cliente y compártelo, también entre hilos: no guarda estado por solicitud. Se respeta la variable de entorno HTTPS_PROXY. Los argumentos no válidos lanzan ValueError o TypeError.

Ejecuta una decisión

decision = client.decide(slug, state, idempotency_key=None, include_probabilities=False,
                         functions=None, on_missing_function="raise")

state es un str, un dict o una list, según lo que declare la decisión. El slug se comprueba localmente (letras minúsculas, dígitos y guiones simples) antes de enviar nada.

ArgumentoDescripción
idempotency_keyEl Idempotency-Key: de 1 a 128 caracteres de A–Z a–z 0–9 . _ : -. Por defecto: un UUID nuevo por llamada, reutilizado por todos sus reintentos.
include_probabilitiesAgrega probabilities, la distribución completa de cada pregunta.
functionsHandlers para los destinos de función, por nombre de función.
on_missing_function"raise" (por defecto) o "ignore".

decide() devuelve un Decision. Cada campo de la respuesta de la API es un atributo: decision_id, execution_id, schema (el slug), version, result, confidence, scores, composites, action, action_reason, probabilities, metrics y destinations (siempre una lista: [] cuando ninguno se disparó). decision.raw es la respuesta exactamente como la envió la API, y decision.function_results lista los handlers que se ejecutaron.

Una decisión con onEngineError: "fallback" responde con su acción de fallback cuando el motor falla: entonces decision.action_reason["type"] es "engine_error" y result y confidence están vacíos.

Destinos

Cada entrada de decision.destinations es un dict; consulta las entradas:

for destination in decision.destinations:
    status = destination.get("status")
    if destination["type"] == "reply":
        chat.send(destination["text"], destination["buttons"])
    elif destination["type"] in ("llm", "agent") and status == "completed":
        chat.send(destination.get("text") or destination.get("reply") or "")
    elif status == "failed":
        log.warning("%s: %s", destination["key"], destination["error"])
    elif status == "queued":
        log.info("%s queued as %s", destination["key"], destination["delivery_id"])
    elif status == "skipped":
        log.info("%s skipped: %s", destination["key"], destination["reason"])

Destinos de función

Un destino de función nombra una función y sus params. Pasa los handlers en functions y el SDK los llama después de la decisión:

def assign_to_sales(params, decision):
    return crm.assign(params["email"], decision.result["route"])


decision = client.decide(
    "lead-qualification",
    {"message": message, "email": email},
    functions={"assignToSales": assign_to_sales, "notifySlack": lambda params, decision: slack.post(params["text"])},
)

decision.function_results
# [FunctionResult(key="assign_owner", function="assignToSales", result=<what the handler returned>)]
  • Los handlers se llaman como functions[name](params, decision), en el orden de destinations, de uno en uno. Solo se llaman las entradas de función que se dispararon.
  • Handler ausente: todos los handlers se buscan antes de que se ejecute el primero. Si falta uno, decide() lanza DcisionError FUNCTION_NOT_REGISTERED y no se ejecuta ningún handler, a menos que pases on_missing_function="ignore".
  • Un handler lanza una excepción: los handlers siguientes no se llaman y decide() lanza DcisionError FUNCTION_FAILED, con cause (también __cause__), decision y function_results (los handlers que terminaron). La decisión ya se ejecutó, y se facturó.
  • Los handlers se ejecutan una vez por llamada a decide(), después de la respuesta final. Llamar de nuevo a decide() con el mismo idempotency_key repite la respuesta guardada y vuelve a despachar sus funciones, así que haz que los handlers sean idempotentes; por ejemplo, usando decision.execution_id como clave.
  • Los nombres de función son claves de diccionario, así que funciona cualquier nombre configurado en Dcision, $ incluido.
  • El cliente es síncrono: un handler async def lanza FUNCTION_FAILED en lugar de omitirse en silencio.

Despacha más tarde, o en otro proceso, con dispatch():

decision = client.decide("lead-qualification", state)  # no functions: nothing is called
queue.push(json.dumps(decision.raw))

# in a worker
from dcision import Decision

results = Decision(json.loads(job.payload)).dispatch(handlers, on_missing_function="ignore")

Errores

Todo lo que el SDK lanza por una respuesta de la API, una falla de red, un handler o una firma es un DcisionError:

from dcision import DcisionError

try:
    client.decide("lead-qualification", state)
except DcisionError as error:
    if error.code == "INVALID_STATE":
        report_bad_input(error.message)
    else:
        raise
AtributoDescripción
codeUn código estable: compáralo a él, no a message.
messageUna explicación legible (también str(error)).
statusEl estado HTTP; None cuando no hubo respuesta (error de red, timeout) o la comprobación fue local.
request_idEl request_id de la solicitud (X-Request-ID): cítalo cuando contactes al soporte.
detailsDatos extra para algunos códigos; consulta Errores.
retry_afterSegundos del header Retry-After, cuando lo hubo.
idempotency_keyEl Idempotency-Key que envió decide(): reutilízalo para reintentar de forma segura más tarde.
causeLa excepción subyacente (también __cause__).
decision, function_resultsSolo FUNCTION_NOT_REGISTERED y FUNCTION_FAILED.

Los códigos de la API se listan en Errores. El SDK agrega NETWORK_ERROR y TIMEOUT (ambos se reintentan), FUNCTION_NOT_REGISTERED, FUNCTION_FAILED e INVALID_SIGNATURE. Las comprobaciones locales reutilizan los códigos de la API con status=None: INVALID_API_KEY para una clave ausente o mal formada, INVALID_REQUEST para un slug o un idempotency_key incorrectos o un estado ausente. Una respuesta que no proviene de la API —una página HTML de un proxy, una redirección— conserva su estado HTTP, con un código de respaldo (NOT_FOUND, PAYLOAD_TOO_LARGE, INTERNAL_ERROR…). DcisionError se puede serializar con pickle para multiprocessing y colas de tareas.

Reintentos e idempotencia

decide() envía un Idempotency-Key, generado una vez por llamada y reutilizado por cada reintento, así que los reintentos nunca ejecutan, ni facturan, una decisión dos veces.

Se reintentaNo se reintenta
Errores de red y timeouts500 INTERNAL_ERROR
409 IDEMPOTENCY_CONFLICT con Retry-After: la primera solicitud con la clave todavía se está ejecutando409 sin Retry-After —otra solicitud reutilizó la clave— y los demás 4xx
429 RATE_LIMITED502 ENGINE_AUTH_FAILED y ENGINE_INVALID_REQUEST
Otros errores 502, 503 y 504Errores de función y de firma
  • Hasta max_retries reintentos: 2 por defecto, es decir, 3 intentos.
  • El SDK espera lo que indique Retry-After cuando la API lo envía, hasta 30 s; un Retry-After más largo lanza la excepción de inmediato, con retry_after definido.
  • Sin él, las esperas son 0.5 s, 1 s, 2 s…, duplicándose hasta un máximo de 8 s, más hasta un 25% de jitter aleatorio.
  • me() y executions se reintentan de la misma forma.

Pasa tu propia clave para que los reintentos sean seguros entre procesos o reinicios:

client.decide("support-routing", ticket, idempotency_key=f"ticket-{ticket['id']}")

Mantén timeout por encima del propio timeoutMs de la decisión (5 s por defecto, 30 s como máximo) más el timeout de su destino LLM o de agente sync más lento, para que un intento haya terminado de verdad del lado de Dcision antes de reintentarse. Si aun así se agota el tiempo, el reintento encuentra la clave reservada, espera Retry-After: 1 y obtiene la respuesta guardada.

Cuenta y ejecuciones

me = client.me()
me["plan"]["rate_limit_per_minute"]
me["usage"]["used"] / me["usage"]["included"]

# one page, newest first
page = client.executions.list(decision="lead-qualification", status="error", limit=100)
page["data"]         # the runs: answers, action, metrics — never the inputs
page["next_cursor"]  # pass it as cursor= for the next page; None on the last one

# every page
for run in client.executions.iterate(decision="lead-qualification", limit=100):
    print(run["created_at"], (run["result"] or {}).get("route"), run["action"])

iterate() es un generador: obtiene la página siguiente solo cuando llegas a ella. Las lecturas nunca se facturan y tienen su propia ventana de rate limit.

Modo socio

Los socios mantienen un subespacio por cliente. with_workspace() devuelve un cliente que actúa en uno de ellos (header Dcision-Workspace); workspaces y embed los gestionan, del lado del servidor, con tu clave de API.

client.workspaces.upsert("acme", "Acme Inc", seed={"decisions": ["lead-qualification"], "deploy": True})
client.with_workspace("ext:acme").decide("lead-qualification", {"message": "Pricing?"})
url = client.embed.create_session("ext:acme", {"id": user.id, "name": user.name})["url"]

Webhooks

from dcision import DcisionError, verify_webhook

event = verify_webhook(raw_body, signature_header, os.environ["DCISION_WEBHOOK_SECRET"])
event["type"]                     # "decision.completed"
event["id"]                       # "dlv_…": the same on every delivery attempt
event["data"]["result"]["route"]  # "sales"
event["data"]["params"]           # the params mapped in the destination (the state itself is never sent)

verify_webhook(payload, header, secret, tolerance=300, now=None):

  • payload: el cuerpo sin procesar, bytes (recomendado) o str;
  • header: el header Dcision-Signature;
  • secret: el secreto de firma (whsec_…, en Configuración → Destinos), o una lista de secretos mientras lo rotas;
  • tolerance: cuánto, en segundos, puede alejarse el timestamp de la firma de now;
  • now: tiempo Unix en segundos, para pruebas.

Lanza DcisionError INVALID_SIGNATURE cuando el header falta o está mal formado, ninguna firma coincide (comparadas con hmac.compare_digest), el timestamp está fuera de la tolerancia o el cuerpo no es un evento JSON: responde 400. Un uso incorrecto, como no pasar secreto o pasar un dict ya parseado como payload, lanza TypeError o ValueError: deja que se convierta en un 500, para que Dcision siga reintentando hasta que la corrección esté desplegada.

verify_signature(...) hace las mismas comprobaciones sin parsear el cuerpo: úsalo para las solicitudes a APIs y los agentes. Los receptores con Flask y FastAPI están en Webhooks.

Tipado

Las respuestas son dicts simples descritos por TypedDicts en dcision.types: DecisionResponse, Destination y sus variantes (ReplyDestination, LlmDestination, AgentDestination, FailedDestination, QueuedDestination, SkippedDestination, FunctionDestination…), WebhookEvent, Me, Execution y ExecutionPage:

from dcision.types import WebhookEvent


def handle(event: WebhookEvent) -> None:
    route = event["data"]["result"]["route"]

Aplicaciones asíncronas

El cliente es síncrono. En código asyncio, ejecútalo en un hilo; verify_webhook() no hace I/O y se puede llamar directamente:

decision = await asyncio.to_thread(client.decide, "lead-qualification", state)

Notas de seguridad

  • La clave de API se mantiene privada. Nunca aparece en repr() ni en un mensaje de error, y un valor que no es una clave de Dcision se rechaza antes de cualquier solicitud.
  • Transporte. Solo https, y las redirecciones nunca se siguen: urllib reenviaría el header Authorization al nuevo host.
  • Rutas. El slug se valida y se codifica: nada más puede acabar en la ruta de la URL.
  • Webhooks. HMAC-SHA256 comparado en tiempo constante, timestamps fuera de la tolerancia rechazados, verificación solo sobre los bytes sin procesar.

En esta página