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

uv 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_keyDCISION_API_KEYdcs_live_… или dcs_test_…. Отсутствующий ключ или ключ, не начинающийся с dcs_, сразу вызывает DcisionError INVALID_API_KEY — ничего не отправляется.
base_urlhttps://api.dcision.ioДолжен использовать https — обычный http только для API на loopback-адресе. Префикс пути допустим.
timeout30Секунды ожидания для каждой попытки — на соединение и на каждое чтение.
max_retries2Повторы после сетевой ошибки, тайм-аута, 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_keyIdempotency-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() вызывает DcisionError FUNCTION_NOT_REGISTERED, и ни один обработчик не выполняется — если только вы не передали on_missing_function="ignore".
  • Обработчик выбрасывает исключение: следующие обработчики не вызываются, а decide() вызывает DcisionError FUNCTION_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)).
statusHTTP-статус; None, если ответа не было (сетевая ошибка, тайм-аут) или проверка была локальной.
request_idrequest_id запроса (X-Request-ID): указывайте его при обращении в поддержку.
detailsДополнительные данные для некоторых кодов — см. Ошибки.
retry_afterСекунды из заголовка Retry-After, если он был.
idempotency_keyIdempotency-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_LIMITED502 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 сравнивается за постоянное время, метки времени вне допуска отклоняются, проверка выполняется только по сырым байтам.

На этой странице