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-python

uv 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",
)
ArgumentoPadrãoDescrição
api_keyDCISION_API_KEYdcs_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_urlhttps://api.dcision.ioPrecisa usar https — http simples só para uma API num endereço de loopback. Um prefixo de caminho é aceito.
timeout30Segundos de espera em cada tentativa — para a conexão e para cada leitura.
max_retries2Retries 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.

ArgumentoDescrição
idempotency_keyO 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_probabilitiesAcrescenta probabilities, a distribuição completa de cada pergunta.
functionsHandlers 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 de destinations, 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ça DcisionError FUNCTION_NOT_REGISTERED e nenhum handler roda — a menos que você passe on_missing_function="ignore".
  • Um handler lança exceção: os handlers seguintes não são chamados e decide() lança DcisionError FUNCTION_FAILED, com cause (também __cause__), decision e function_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. Chamar decide() de novo com o mesmo idempotency_key repete a resposta armazenada e despacha as suas funções de novo, então faça handlers idempotentes — por exemplo, usando decision.execution_id como 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 def lança FUNCTION_FAILED em 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
AtributoDescrição
codeUm código estável: compare-o, não a message.
messageUma explicação legível (também str(error)).
statusO status HTTP; None quando não houve resposta (erro de rede, timeout) ou a verificação foi local.
request_idO request_id da requisição (X-Request-ID): informe-o ao falar com o suporte.
detailsDados extras para alguns códigos — veja Erros.
retry_afterSegundos do header Retry-After, quando houve um.
idempotency_keyO Idempotency-Key que decide() enviou: reutilize-o para tentar de novo com segurança mais tarde.
causeA exceção de origem (também __cause__).
decision, function_resultsSó 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 retrySem retry
Erros de rede e timeouts500 INTERNAL_ERROR
409 IDEMPOTENCY_CONFLICT com Retry-After: a primeira requisição com a chave ainda está rodando409 sem Retry-After — uma requisição diferente reutilizou a chave — e os demais 4xx
429 RATE_LIMITED502 ENGINE_AUTH_FAILED e ENGINE_INVALID_REQUEST
Outros erros 502, 503 e 504Erros de função e de assinatura
  • Até max_retries retries: 2 por padrão, ou seja, 3 tentativas.
  • O SDK espera o Retry-After quando a API o envia, até 30 s; um Retry-After maior lança na hora, com retry_after preenchido.
  • 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() e executions tê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) ou str;
  • header — o header Dcision-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 e now;
  • 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 header Authorization para 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.

Nesta página