Python SDK

pip install krun-ai

export KRUN_API_KEY=krun_live_...

from krun import Krun

client = Krun()  # reads KRUN_API_KEY

result = client.decide(
    context="Customer wants to return an item.",
    questions={
        "department": {
            "type": "choice",
            "options": {
                "shipping": "Shipping and delivery issues",
                "returns": "Returns and refunds",
                "billing": "Billing and payment issues",
            },
        }
    },
)

answer = result.answers["department"]
answer.choice             # "returns", or None if the model abstains
answer.confidence         # 0.967536: top-1 minus top-2 probability
answer.probabilities      # {"shipping": 0.011351, "returns": 0.978886, "billing": 0.009763}
answer.abstain            # False
answer.abstention_status  # "advisory"
result.usage.input_tokens # 49
result.request_id         # "req_...", from the X-Request-ID header

result = client.decide(
    context="My package never arrived and I need it for a wedding this Saturday.",
    questions={
        "department": {
            "type": "choice",
            "options": {"shipping": "", "returns": "", "billing": ""},
        },
        "priority": {
            "type": "choice",
            "options": {"low": "Can wait", "normal": "Normal priority", "high": "Needs quick attention"},
        },
        "sentiment": {
            "type": "choice",
            "options": {"positive": "", "neutral": "", "negative": ""},
        },
    },
)

for question_id, answer in result.answers.items():
    print(question_id, answer.choice, answer.confidence)

result = client.decide(
    context="Find my meetings tomorrow.",
    questions={
        "tool": {
            "type": "choice",
            "task_type": "tool",
            "options": {
                "calendar_search": "Search calendar events",
                "send_email": "Send an email",
            },
        }
    },
)

result.answers["tool"].choice             # "calendar_search"
result.answers["tool"].abstention_status  # "advisory"

from krun import ChoiceQuestion

questions = {
    "tool": ChoiceQuestion(
        options={"calendar_search": "Search calendar events", "send_email": "Send an email"},
        task_type="tool",
    )
}

client.feedback(
    request_id=result.request_id,
    question_id="department",
    correct=False,
    expected_decision="billing",
    metadata={"ticket": "T-1234"},  # optional JSON object, up to 8 KiB, no personal data
)

for model in client.models():
    print(model.id, model.status)  # krun-one-v0 available

import asyncio

from krun import AsyncKrun

QUESTIONS = {
    "department": {
        "type": "choice",
        "options": {
            "shipping": "Shipping and delivery issues",
            "returns": "Returns and refunds",
            "billing": "Billing and payment issues",
        },
    }
}

MESSAGES = [
    "Where is my package? It was due on Monday.",
    "I want to send these shoes back.",
    "Why is there a second charge on my card?",
]


async def main() -> None:
    async with AsyncKrun() as client:
        results = await asyncio.gather(
            *(client.decide(context=m, questions=QUESTIONS) for m in MESSAGES)
        )
        for message, result in zip(MESSAGES, results):
            print(result.answers["department"].choice, "<-", message)


asyncio.run(main())

from krun import Krun

client = Krun(
    api_key="krun_live_...",   # default: the KRUN_API_KEY environment variable
    base_url="https://api.krun.ai",  # default
    timeout=70.0,              # seconds per attempt (default 70)
    max_retries=1,             # decide() and models() only (default 1)
    http_client=None,          # optional httpx.Client, for proxies or custom transports
)

with Krun() as client:
    result = client.decide(context="...", questions={...})

client = Krun(timeout=30.0)                    # for all calls
client.decide(..., timeout=10.0)               # for one call

KrunError
├── APIError                     the API answered with an error (status_code always set)
│   ├── InvalidRequestError      400/413  INVALID_REQUEST, INVALID_OPTIONS, PAYLOAD_TOO_LARGE
│   ├── AuthenticationError      401      UNAUTHORIZED
│   ├── NotFoundError            404      NOT_FOUND
│   ├── RateLimitError           429      RATE_LIMITED           (.retry_after)
│   ├── QuotaExceededError       429      QUOTA_EXCEEDED
│   ├── InferenceFailedError     502      INFERENCE_FAILED
│   ├── ServiceUnavailableError  503      UPSTREAM_UNAVAILABLE   (.retry_after)
│   ├── UpstreamTimeoutError     504      UPSTREAM_TIMEOUT
│   └── InternalServerError      500      INTERNAL_ERROR
├── APIConnectionError           no HTTP response (DNS, refused, reset, TLS)
│   └── APITimeoutError          the SDK timeout elapsed
└── APIResponseValidationError   a 2xx response did not match the contract

import time

import krun

try:
    result = client.decide(context="...", questions={...})
except krun.InvalidRequestError as e:
    print(e.error_code, e.message, e.request_id)  # fix the request
except krun.RateLimitError as e:
    time.sleep(e.retry_after or 1)
except krun.QuotaExceededError:
    ...  # the monthly quota is exhausted: retrying will not help
except krun.KrunError as e:
    print("Krun request failed:", e)

import logging

logging.getLogger("krun").setLevel(logging.DEBUG)