Python SDK
Пакет dcision для Python 3.9+ — сборка из исходников, decide, назначения и функции, ошибки, идемпотентные повторы, выполнения, me() и проверка вебхуков во Flask или FastAPI.
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 — обычный http только для API на loopback-адресе. Префикс пути допустим. |
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(), после итогового ответа. Повторный вызовdecide()с тем жеidempotency_keyвоспроизводит сохранённый ответ и снова вызывает его функции, поэтому делайте обработчики идемпотентными — например, с ключом по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 | Idempotency-Key, который отправил decide(): используйте его повторно, чтобы безопасно повторить позже. |
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 для отсутствующего или повреждённого ключа, INVALID_REQUEST для неверного slug, idempotency_key или отсутствующего state. Ответ, пришедший не от API, — HTML-страница от прокси, редирект — сохраняет свой HTTP-статус с запасным кодом (NOT_FOUND, PAYLOAD_TOO_LARGE, INTERNAL_ERROR…). DcisionError можно сериализовать через pickle для multiprocessing и очередей задач.
Повторы и идемпотентность
decide() отправляет Idempotency-Key, генерируемый один раз на вызов и используемый каждым повтором, поэтому повторы никогда не выполняют и не оплачивают решение дважды.
| Повторяется | Не повторяется |
|---|---|
| Сетевые ошибки и тайм-ауты | 500 INTERNAL_ERROR |
409 IDEMPOTENCY_CONFLICT с Retry-After: первый запрос с этим ключом ещё выполняется | 409 без Retry-After — другой запрос использовал тот же ключ — и прочие 4xx |
429 RATE_LIMITED | 502 ENGINE_AUTH_FAILED и ENGINE_INVALID_REQUEST |
Прочие ошибки 502, 503 и 504 | Ошибки функций и подписи |
- До
max_retriesповторов: по умолчанию 2, то есть 3 попытки. - SDK ждёт
Retry-After, когда API его присылает, до 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() — это генератор: он запрашивает следующую страницу, только когда вы до неё доходите. Чтение никогда не тарифицируется и имеет собственное окно rate limit.
Режим партнёра
Партнёры держат по одному подпространству на клиента. 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"]Вебхуки
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 в секундах, для тестов.
Функция вызывает DcisionError INVALID_SIGNATURE, когда заголовок отсутствует или повреждён, ни одна подпись не совпадает (сравнение через hmac.compare_digest), метка времени вне допуска или тело не является JSON-событием, — отвечайте 400. Неправильное использование, например отсутствие секрета или разобранный dict вместо payload, вызывает TypeError или ValueError — пусть это станет 500, чтобы Dcision продолжал повторы, пока исправление не будет развёрнуто.
verify_signature(...) выполняет те же проверки без разбора тела: используйте её для API-запросов и агентов. Получатели на Flask и FastAPI приведены в разделе Вебхуки.
Типизация
Ответы — это обычные словари, описанные TypedDict в dcision.types: 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() не выполняет ввода-вывода и может вызываться напрямую:
decision = await asyncio.to_thread(client.decide, "lead-qualification", state)Замечания о безопасности
- API-ключ остаётся закрытым. Его никогда нет в
repr()или в сообщении об ошибке, а значение, не являющееся ключом Dcision, отклоняется до любого запроса. - Транспорт. Только
https, и редиректы никогда не выполняются: urllib переслал бы заголовокAuthorizationна новый хост. - Пути. Slug проверяется и кодируется: ничто другое не может попасть в путь URL.
- Вебхуки. HMAC-SHA256 сравнивается за постоянное время, метки времени вне допуска отклоняются, проверка выполняется только по сырым байтам.
TypeScript SDK
@dcision/sdk для Node.js, Bun, Deno и edge-сред — сборка из исходников, decide, назначения и функции, ошибки, идемпотентные повторы, executions, me() и проверка вебхуков.
Партнёры
Предложите Dcision внутри своего приложения — отдельное подпространство на каждого клиента, встраиваемый редактор для ваших пользователей и оплата использования из вашего рабочего пространства.