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-pythonuv 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",
)| Argumento | Predeterminado | Descripción |
|---|---|---|
api_key | DCISION_API_KEY | dcs_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_url | https://api.dcision.io | Debe usar https; http plano solo para una API en una dirección de loopback. Se admite un prefijo de ruta. |
timeout | 30 | Segundos de espera en cada intento, para la conexión y para cada lectura. |
max_retries | 2 | Reintentos 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.
| Argumento | Descripción |
|---|---|
idempotency_key | El 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_probabilities | Agrega probabilities, la distribución completa de cada pregunta. |
functions | Handlers 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 dedestinations, 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()lanzaDcisionErrorFUNCTION_NOT_REGISTEREDy no se ejecuta ningún handler, a menos que paseson_missing_function="ignore". - Un handler lanza una excepción: los handlers siguientes no se llaman y
decide()lanzaDcisionErrorFUNCTION_FAILED, concause(también__cause__),decisionyfunction_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 adecide()con el mismoidempotency_keyrepite la respuesta guardada y vuelve a despachar sus funciones, así que haz que los handlers sean idempotentes; por ejemplo, usandodecision.execution_idcomo 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 deflanzaFUNCTION_FAILEDen 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| Atributo | Descripción |
|---|---|
code | Un código estable: compáralo a él, no a message. |
message | Una explicación legible (también str(error)). |
status | El estado HTTP; None cuando no hubo respuesta (error de red, timeout) o la comprobación fue local. |
request_id | El request_id de la solicitud (X-Request-ID): cítalo cuando contactes al soporte. |
details | Datos extra para algunos códigos; consulta Errores. |
retry_after | Segundos del header Retry-After, cuando lo hubo. |
idempotency_key | El Idempotency-Key que envió decide(): reutilízalo para reintentar de forma segura más tarde. |
cause | La excepción subyacente (también __cause__). |
decision, function_results | Solo 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 reintenta | No se reintenta |
|---|---|
| Errores de red y timeouts | 500 INTERNAL_ERROR |
409 IDEMPOTENCY_CONFLICT con Retry-After: la primera solicitud con la clave todavía se está ejecutando | 409 sin Retry-After —otra solicitud reutilizó la clave— y los demás 4xx |
429 RATE_LIMITED | 502 ENGINE_AUTH_FAILED y ENGINE_INVALID_REQUEST |
Otros errores 502, 503 y 504 | Errores de función y de firma |
- Hasta
max_retriesreintentos: 2 por defecto, es decir, 3 intentos. - El SDK espera lo que indique
Retry-Aftercuando la API lo envía, hasta 30 s; unRetry-Aftermás largo lanza la excepción de inmediato, conretry_afterdefinido. - 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()yexecutionsse 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) ostr;header: el headerDcision-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 denow;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 headerAuthorizational 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.
SDK de TypeScript
@dcision/sdk para Node.js, Bun, Deno y runtimes edge — compilación desde el código fuente, decide, destinos y funciones, errores, reintentos idempotentes, ejecuciones, me() y verificación de webhooks.
Socios
Ofrece Dcision dentro de tu propia app — un subespacio por cliente, un editor incrustable para tus usuarios finales y el uso facturado a tu workspace.