SDK Python
O pacote dcision para Python 3.9+ — build a partir do código-fonte, decide, destinos e funções, erros, retries idempotentes, execuções, me() e verificação de webhooks com Flask ou FastAPI.
dcision é o SDK oficial para Python. Ele precisa de Python 3.9+ e de mais nada — só da biblioteca padrão (urllib, json, hmac) — e é totalmente tipado (py.typed, sem erros no mypy --strict).
Instalação
Ainda não está no PyPI
dcision não está publicado no PyPI. Instale-o a partir de um checkout do repositório da Dcision; até esta página dizer que ele foi publicado, um pacote com esse nome no PyPI não vem da Dcision.
# From a checkout of the Dcision repository, in your project's environment
pip install ./packages/sdk-pythonuv pip install ./packages/sdk-python funciona do mesmo jeito. Para levá-lo a outro lugar, gere um wheel — python -m build packages/sdk-python o grava em packages/sdk-python/dist — e instale esse arquivo, ou aponte os seus requirements para a pasta: dcision @ file:///path/to/dcision/packages/sdk-python.
Início rápido
Crie uma API key em API Keys e defina-a como DCISION_API_KEY no ambiente do seu 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…Configuração
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 | Padrão | Descrição |
|---|---|---|
api_key | DCISION_API_KEY | dcs_live_… ou dcs_test_…. Uma chave ausente, ou que não comece com dcs_, lança DcisionError INVALID_API_KEY na hora — nada é enviado. |
base_url | https://api.dcision.io | Precisa usar https — http simples só para uma API num endereço de loopback. Um prefixo de caminho é aceito. |
timeout | 30 | Segundos de espera em cada tentativa — para a conexão e para cada leitura. |
max_retries | 2 | Retries depois de um erro de rede, um timeout, 429, 502, 503 ou 504. |
user_agent | — | Só por palavra-chave. O identificador do seu app, colocado antes do identificador do SDK: acme-crm/2.1 dcision-sdk-python/0.1.0. |
Crie um client e compartilhe-o — entre threads também: ele não guarda estado por requisição. A variável de ambiente HTTPS_PROXY é respeitada. Argumentos inválidos lançam ValueError ou TypeError.
Executar uma decisão
decision = client.decide(slug, state, idempotency_key=None, include_probabilities=False,
functions=None, on_missing_function="raise")state é um str, um dict ou uma list, conforme a decisão declara. O slug é conferido localmente (letras minúsculas, dígitos e hífens simples) antes de qualquer envio.
| Argumento | Descrição |
|---|---|
idempotency_key | O Idempotency-Key: 1 a 128 caracteres de A–Z a–z 0–9 . _ : -. Padrão: um novo UUID por chamada, reutilizado por todos os seus retries. |
include_probabilities | Acrescenta probabilities, a distribuição completa de cada pergunta. |
functions | Handlers para destinos de função, pelo nome da função. |
on_missing_function | "raise" (padrão) ou "ignore". |
decide() retorna um Decision. Cada campo da resposta da API é um atributo — decision_id, execution_id, schema (o slug), version, result, confidence, scores, composites, action, action_reason, probabilities, metrics e destinations (sempre uma lista: [] quando nenhum disparou). decision.raw é a resposta exatamente como a API a enviou, e decision.function_results lista os handlers que rodaram.
Uma decisão com onEngineError: "fallback" responde com a sua ação de fallback quando o engine falha: nesse caso decision.action_reason["type"] é "engine_error" e result e confidence vêm vazios.
Destinos
Cada item de decision.destinations é um dict — veja os itens:
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 função
Um destino de função indica uma função e os seus params. Passe os handlers em functions e o SDK os chama depois da decisão:
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>)]- Os handlers são chamados como
functions[name](params, decision), na ordem dedestinations, um de cada vez. Só os itens de função que dispararam são chamados. - Handler ausente: todos os handlers são procurados antes de o primeiro rodar. Se faltar algum,
decide()lançaDcisionErrorFUNCTION_NOT_REGISTEREDe nenhum handler roda — a menos que você passeon_missing_function="ignore". - Um handler lança exceção: os handlers seguintes não são chamados e
decide()lançaDcisionErrorFUNCTION_FAILED, comcause(também__cause__),decisionefunction_results(os handlers que concluíram). A decisão já rodou — e foi cobrada. - Os handlers rodam uma vez por chamada a
decide(), depois da resposta final. Chamardecide()de novo com o mesmoidempotency_keyrepete a resposta armazenada e despacha as suas funções de novo, então faça handlers idempotentes — por exemplo, usandodecision.execution_idcomo chave. - Nomes de função são chaves de dicionário, então qualquer nome configurado na Dcision funciona, inclusive com
$. - O client é síncrono: um handler
async deflançaFUNCTION_FAILEDem vez de ser ignorado silenciosamente.
Despache depois, ou em outro processo, com 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")Erros
Tudo o que o SDK lança por uma resposta da API, uma falha de rede, um handler ou uma assinatura é um 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 | Descrição |
|---|---|
code | Um código estável: compare-o, não a message. |
message | Uma explicação legível (também str(error)). |
status | O status HTTP; None quando não houve resposta (erro de rede, timeout) ou a verificação foi local. |
request_id | O request_id da requisição (X-Request-ID): informe-o ao falar com o suporte. |
details | Dados extras para alguns códigos — veja Erros. |
retry_after | Segundos do header Retry-After, quando houve um. |
idempotency_key | O Idempotency-Key que decide() enviou: reutilize-o para tentar de novo com segurança mais tarde. |
cause | A exceção de origem (também __cause__). |
decision, function_results | Só em FUNCTION_NOT_REGISTERED e FUNCTION_FAILED. |
Os códigos da API estão listados em Erros. O SDK acrescenta NETWORK_ERROR e TIMEOUT (ambos com retry), FUNCTION_NOT_REGISTERED, FUNCTION_FAILED e INVALID_SIGNATURE. Verificações locais reutilizam os códigos da API com status=None: INVALID_API_KEY para uma chave ausente ou malformada, INVALID_REQUEST para um slug ou idempotency_key inválido ou um state ausente. Uma resposta que não vem da API — uma página HTML de um proxy, um redirecionamento — mantém o seu status HTTP, com um código de fallback (NOT_FOUND, PAYLOAD_TOO_LARGE, INTERNAL_ERROR…). DcisionError pode ser serializado com pickle para multiprocessing e filas de tarefas.
Retries e idempotência
decide() envia um Idempotency-Key, gerado uma vez por chamada e reutilizado por todos os retries, então os retries nunca executam, nem cobram, uma decisão duas vezes.
| Com retry | Sem retry |
|---|---|
| Erros de rede e timeouts | 500 INTERNAL_ERROR |
409 IDEMPOTENCY_CONFLICT com Retry-After: a primeira requisição com a chave ainda está rodando | 409 sem Retry-After — uma requisição diferente reutilizou a chave — e os demais 4xx |
429 RATE_LIMITED | 502 ENGINE_AUTH_FAILED e ENGINE_INVALID_REQUEST |
Outros erros 502, 503 e 504 | Erros de função e de assinatura |
- Até
max_retriesretries: 2 por padrão, ou seja, 3 tentativas. - O SDK espera o
Retry-Afterquando a API o envia, até 30 s; umRetry-Aftermaior lança na hora, comretry_afterpreenchido. - Sem ele, as esperas são 0,5 s, 1 s, 2 s… — dobrando, no máximo 8 s — mais até 25% de jitter aleatório.
me()eexecutionstêm retry da mesma forma.
Passe a sua própria chave para tornar os retries seguros entre processos ou reinícios:
client.decide("support-routing", ticket, idempotency_key=f"ticket-{ticket['id']}")Mantenha timeout acima do próprio timeoutMs da decisão (5 s por padrão, 30 s no máximo) mais o timeout do seu destino LLM ou de agente sync mais lento, para que uma tentativa tenha de fato terminado do lado da Dcision antes do retry. Se mesmo assim der timeout, o retry encontra a chave reservada, espera o Retry-After: 1 e recebe a resposta armazenada.
Conta e execuções
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() é um generator: ele busca a próxima página só quando você chega nela. Leituras nunca são cobradas e têm a sua própria janela de rate limit.
Modo parceiro
Parceiros mantêm um sub-workspace por cliente. with_workspace() retorna um client que atua em um deles (header Dcision-Workspace); workspaces e embed os gerenciam — no servidor, com a sua API key.
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— o body bruto:bytes(recomendado) oustr;header— o headerDcision-Signature;secret— o segredo de assinatura (whsec_…, em Configurações → Destinos), ou uma lista de segredos enquanto você faz a rotação;tolerance— a distância máxima, em segundos, entre o timestamp da assinatura enow;now— horário Unix em segundos, para testes.
Ele lança DcisionError INVALID_SIGNATURE quando o header está ausente ou malformado, nenhuma assinatura confere (comparada com hmac.compare_digest), o timestamp está fora da tolerância ou o body não é um evento JSON — responda 400. Uso incorreto, como nenhum segredo ou um dict já parseado como payload, lança TypeError ou ValueError — deixe isso virar um 500, para que a Dcision continue tentando até a correção ser publicada.
verify_signature(...) faz as mesmas verificações sem parsear o body: use-o para requisições de API e agentes. Receptores com Flask e FastAPI estão em Webhooks.
Tipagem
As respostas são dicts simples descritos por TypedDicts em dcision.types — DecisionResponse, Destination e as suas variantes (ReplyDestination, LlmDestination, AgentDestination, FailedDestination, QueuedDestination, SkippedDestination, FunctionDestination…), WebhookEvent, Me, Execution e ExecutionPage:
from dcision.types import WebhookEvent
def handle(event: WebhookEvent) -> None:
route = event["data"]["result"]["route"]Aplicações assíncronas
O client é síncrono. Em código asyncio, rode-o numa thread — verify_webhook() não faz I/O e pode ser chamado diretamente:
decision = await asyncio.to_thread(client.decide, "lead-qualification", state)Notas de segurança
- A API key fica privada. Ela nunca aparece no
repr()nem numa mensagem de erro, e um valor que não é uma chave da Dcision é recusado antes de qualquer requisição. - Transporte. Só
https, e redirecionamentos nunca são seguidos: o urllib encaminharia o headerAuthorizationpara o novo host. - Caminhos. O slug é validado e codificado: nada mais pode acabar no caminho da URL.
- Webhooks. HMAC-SHA256 comparado em tempo constante, timestamps fora da tolerância rejeitados, verificação apenas sobre os bytes brutos.
SDK TypeScript
@dcision/sdk para Node.js, Bun, Deno e runtimes edge — compilar do código-fonte, decide, destinos e funções, erros, retries idempotentes, execuções, me() e verificação de webhooks.
Parceiros
Ofereça a Dcision dentro do seu próprio app — um sub-workspace por cliente, um editor incorporável para os seus usuários finais e o uso cobrado no seu workspace.