Python SDK
适用于 Python 3.9+ 的 dcision 包——从源码构建、decide、目的地和函数、错误、幂等重试、执行记录、me(),以及使用 Flask 或 FastAPI 验证 webhook。
dcision 是官方的 Python SDK。它需要 Python 3.9+,除此之外不需要任何东西——只使用标准库(urllib、json、hmac)——并且完全类型化(py.typed,通过 mypy --strict 检查)。
安装
尚未发布到 PyPI
dcision 尚未发布到 PyPI。请从 Dcision 仓库的检出副本安装;在本页说明它已发布之前,PyPI 上同名的包并非来自 Dcision。
# From a checkout of the Dcision repository, in your project's environment
pip install ./packages/sdk-pythonuv pip install ./packages/sdk-python 的用法相同。要在其他地方分发,请构建一个 wheel——python -m build packages/sdk-python 会把它写入 packages/sdk-python/dist——然后安装该文件,或者在你的 requirements 中指向该文件夹:dcision @ file:///path/to/dcision/packages/sdk-python。
快速开始
在 API 密钥中创建一个 API 密钥,并在服务器环境中将其设置为 DCISION_API_KEY。
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…配置
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",
)| 参数 | 默认值 | 说明 |
|---|---|---|
api_key | DCISION_API_KEY | dcs_live_… 或 dcs_test_…。缺少密钥,或密钥不以 dcs_ 开头时,会立即抛出 DcisionError INVALID_API_KEY——不会发送任何请求。 |
base_url | https://api.dcision.io | 必须使用 https——仅当 API 位于回环地址时才允许普通 http。可以带路径前缀。 |
timeout | 30 | 每次尝试的等待秒数——适用于连接和每次读取。 |
max_retries | 2 | 在网络错误、超时、429、502、503 或 504 之后的重试次数。 |
user_agent | — | 仅限关键字参数。你的应用标识,会加在 SDK 标识之前:acme-crm/2.1 dcision-sdk-python/0.1.0。 |
创建一个客户端并共享它——跨线程也可以:它不保留任何按请求的状态。会遵循 HTTPS_PROXY 环境变量。无效参数会抛出 ValueError 或 TypeError。
运行决策
decision = client.decide(slug, state, idempotency_key=None, include_probabilities=False,
functions=None, on_missing_function="raise")state 是 str、dict 或 list,取决于决策的声明。slug 在发送任何请求之前会在本地检查(小写字母、数字和单个短横线)。
| 参数 | 说明 |
|---|---|
idempotency_key | Idempotency-Key:1 到 128 个字符,取自 A–Z a–z 0–9 . _ : -。默认:每次调用一个新的 UUID,所有重试都复用它。 |
include_probabilities | 添加 probabilities,即每个问题的完整分布。 |
functions | 函数目的地的处理函数,按函数名提供。 |
on_missing_function | "raise"(默认)或 "ignore"。 |
decide() 返回一个 Decision。API 响应的每个字段都是一个属性——decision_id、execution_id、schema(slug)、version、result、confidence、scores、composites、action、action_reason、probabilities、metrics 和 destinations(始终是列表:没有触发任何目的地时为 [])。decision.raw 是 API 发送的原样响应,decision.function_results 列出已运行的处理函数。
带有 onEngineError: "fallback" 的决策在引擎失败时会以其 fallback 行动作答:此时 decision.action_reason["type"] 为 "engine_error",result 和 confidence 为空。
目的地
decision.destinations 的每个条目都是一个 dict——参见条目说明:
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"])函数目的地
函数目的地指定一个函数及其参数。在 functions 中传入处理函数,SDK 会在决策之后调用它们:
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>)]- 处理函数以
functions[name](params, decision)的形式调用,按destinations的顺序,一次一个。只会调用已触发的函数条目。 - 缺少处理函数:在第一个处理函数运行之前,会先查找所有处理函数。如果缺少某个,
decide()会抛出DcisionErrorFUNCTION_NOT_REGISTERED,且不会运行任何处理函数——除非你传入on_missing_function="ignore"。 - 处理函数抛出异常:后续处理函数不会被调用,
decide()抛出DcisionErrorFUNCTION_FAILED,带有cause(也是__cause__)、decision和function_results(已完成的处理函数)。决策已经运行——并且已计费。 - 处理函数每次
decide()调用运行一次,在最终回答之后。使用相同的idempotency_key再次调用decide()会重放已存储的回答并再次分发其函数,因此请让处理函数具备幂等性——例如以decision.execution_id作为键。 - 函数名是字典的键,因此在 Dcision 中配置的任何名称都可以使用,包括
$。 - 客户端是同步的:
async def处理函数会抛出FUNCTION_FAILED,而不是被静默跳过。
使用 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")错误
SDK 因 API 回答、网络故障、处理函数或签名而抛出的一切都是 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| 属性 | 说明 |
|---|---|
code | 稳定的错误码:比较它,而不是 message。 |
message | 人类可读的说明(也是 str(error))。 |
status | HTTP 状态码;没有响应(网络错误、超时)或检查在本地进行时为 None。 |
request_id | 请求的 request_id(X-Request-ID):联系支持时请提供它。 |
details | 某些错误码的额外数据——参见错误。 |
retry_after | 来自 Retry-After 响应头的秒数(如果有)。 |
idempotency_key | decide() 发送的 Idempotency-Key:之后复用它即可安全重试。 |
cause | 底层异常(也是 __cause__)。 |
decision、function_results | 仅限 FUNCTION_NOT_REGISTERED 和 FUNCTION_FAILED。 |
API 的错误码列在错误中。SDK 额外添加了 NETWORK_ERROR 和 TIMEOUT(两者都会重试)、FUNCTION_NOT_REGISTERED、FUNCTION_FAILED 和 INVALID_SIGNATURE。本地检查复用 API 的错误码,并带 status=None:缺少或格式错误的密钥为 INVALID_API_KEY,错误的 slug、idempotency_key 或缺少状态为 INVALID_REQUEST。并非来自 API 的回答——代理返回的 HTML 页面、重定向——会保留其 HTTP 状态,并带有一个兜底错误码(NOT_FOUND、PAYLOAD_TOO_LARGE、INTERNAL_ERROR…)。DcisionError 可以被 pickle,适用于多进程和任务队列。
重试与幂等性
decide() 会发送一个 Idempotency-Key,每次调用生成一次并被每次重试复用,因此重试永远不会让一个决策运行或计费两次。
| 会重试 | 不会重试 |
|---|---|
| 网络错误和超时 | 500 INTERNAL_ERROR |
带有 Retry-After 的 409 IDEMPOTENCY_CONFLICT:使用该键的第一个请求仍在运行 | 不带 Retry-After 的 409——另一个请求复用了该键——以及其他 4xx |
429 RATE_LIMITED | 502 ENGINE_AUTH_FAILED 和 ENGINE_INVALID_REQUEST |
其他 502 错误、503 和 504 | 函数和签名错误 |
- 最多重试
max_retries次:默认 2 次,即共 3 次尝试。 - 当 API 发送
Retry-After时,SDK 会等待它,最多 30 秒;更长的Retry-After会立即抛出异常,并设置retry_after。 - 没有它时,等待时间为 0.5 秒、1 秒、2 秒……——每次翻倍,最多 8 秒——外加最多 25% 的随机抖动。
me()和executions以同样的方式重试。
传入你自己的键,使重试在跨进程或重启时也是安全的:
client.decide("support-routing", ticket, idempotency_key=f"ticket-{ticket['id']}")让 timeout 大于决策自身的 timeoutMs(默认 5 秒,最多 30 秒)加上其最慢的 LLM 或 sync 智能体目的地的超时时间,这样在重试之前,一次尝试在 Dcision 一侧确实已经结束。如果仍然超时,重试会发现该键已被预留,等待 Retry-After: 1 后得到已存储的回答。
账户与执行记录
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() 是一个生成器:只有当你遍历到下一页时才会获取它。读取永远不计费,并有自己的速率限制窗口。
合作伙伴模式
合作伙伴为每个客户维护一个子工作区。with_workspace() 返回一个在其中某个子工作区中操作的客户端(请求头 Dcision-Workspace);workspaces 和 embed 用于管理它们——在服务器端,使用你的 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——原始请求体:bytes(推荐)或str;header——Dcision-Signature请求头;secret——签名密钥(whsec_…,位于设置 → 目的地),或在轮换期间提供一个密钥列表;tolerance——签名的时间戳与now之间允许相差的秒数;now——以秒为单位的 Unix 时间,用于测试。
当请求头缺失或格式错误、没有任何签名匹配(使用 hmac.compare_digest 比较)、时间戳超出容差范围,或请求体不是 JSON 事件时,它会抛出 DcisionError INVALID_SIGNATURE——请返回 400。误用,例如没有提供密钥或把解析后的 dict 作为 payload,会抛出 TypeError 或 ValueError——让它变成 500,这样 Dcision 会持续重试,直到修复被部署。
verify_signature(...) 执行相同的检查,但不解析请求体:将它用于 API 请求和智能体。Flask 和 FastAPI 接收端示例见 Webhooks。
类型
响应是普通的 dict,由 dcision.types 中的 TypedDict 描述——DecisionResponse、Destination 及其变体(ReplyDestination、LlmDestination、AgentDestination、FailedDestination、QueuedDestination、SkippedDestination、FunctionDestination…)、WebhookEvent、Me、Execution 和 ExecutionPage:
from dcision.types import WebhookEvent
def handle(event: WebhookEvent) -> None:
route = event["data"]["result"]["route"]异步应用
客户端是同步的。在 asyncio 代码中,请在线程中运行它——verify_webhook() 不做任何 I/O,可以直接调用:
decision = await asyncio.to_thread(client.decide, "lead-qualification", state)安全说明
- API 密钥保持私密。它从不出现在
repr()或错误消息中,并且不是 Dcision 密钥的值会在发出任何请求之前被拒绝。 - 传输。仅限
https,并且从不跟随重定向:urllib 会把Authorization请求头转发给新的主机。 - 路径。slug 经过验证和编码:URL 路径中不会出现其他任何内容。
- Webhooks。HMAC-SHA256 以恒定时间比较,超出容差的时间戳会被拒绝,验证仅基于原始字节。