- Package:
krun-aion PyPI (import namekrun) - Source: github.com/krun-ai/krun-python
- Version: 0.3.0, Python 3.10 or later, Apache-2.0
- Clients:
Krun(sync) andAsyncKrun(async), with the same methods and types
Install
Basic decision
decide() returns a DecisionResult:
result.choice(id), result.noul(id) and result.score(id) return the typed answer of a question (and raise
TypeError if the question has another type).
Each ChoiceAnswer has type, choice (str | None), confidence, probabilities, abstain and abstention_status. See Questions and answers.
When the model abstains,
choice is None. The SDK never replaces it with the most likely option. Read probabilities for a best guess. See Abstention.decide() arguments:
Multiple questions
Ask several questions about the same context in one call:Tool routing
Settask_type="tool" on the question:
ChoiceQuestion:
Decision primitives
noul and score questions can be dicts or objects, and mixed with choice in one call:
NoulAnswer has type and noul. ScoreAnswer has type, score, confidence, legend and probabilities. See
Decision primitives. When iterating over result.answers, branch on
answer.type or isinstance(answer, ScoreAnswer).
Multimodal inputs and multi
Requireskrun-ai 0.3.0 or later (pip install -U krun-ai). Upload media with client.assets, then pass context as
a list of content parts:
ImagePart and AudioPart work the same way. client.assets.get(asset_id) returns the asset’s metadata. Uploads and
deletes are never retried. See Multimodal inputs.
Feedback
expected_decision="billing" (choice only) is still accepted.
feedback() returns a Feedback object with id, request_id, question_id and created_at. It raises NotFoundError if the request id was not decided by your project. See Feedback.
Models
Async client
AsyncKrun has the same arguments, methods and return types as Krun, as coroutines:
Configuration
client.close(), to release connections:
KRUN_API_KEY is not set, Krun() raises KrunError. The key never appears in repr(client), error messages or logs.
Timeouts
The default timeout is 180 seconds per attempt fromkrun-ai 0.3.0 (70 seconds in earlier versions), because a serverless cold start can take up to about 2 minutes and the API waits up to 150 seconds for the model. Upgrade with pip install -U krun-ai, or set timeout=180.0 on an earlier version. The timeout can’t be disabled: None, 0 and infinity are rejected. When it elapses, the SDK raises APITimeoutError.
Retries
The API already retries its model backend, so the SDK retries only a little:- The wait follows
Retry-Afterwhen the API sends it, up to 10 seconds. Otherwise it is 0.5 s, then 1 s, 2 s, and so on, with jitter. - The SDK’s own timeout (
APITimeoutError) is not retried. - Other 4xx errors and 500 are not retried.
- A retried
decide()can count one extra decision against usage if the first attempt reached the model. - Set
max_retries=0to disable retries.
Errors
All errors inherit fromkrun.KrunError and expose message, request_id, status_code and error_code when available.
context=None, raise TypeError before any request is sent. See Errors for the API error codes.
Logging
The SDK is silent by default and has no telemetry. It logs to thekrun logger at DEBUG level: method, path, status, request id and retries only. It never logs the API key, context, options, instructions, levels or answers.
Types
Thekrun package exports typed request and response types: ChoiceQuestion, NoulQuestion, ScoreQuestion (and their ...Param dict forms), QuestionsParam, DecisionResult, Answer, ChoiceAnswer, NoulAnswer, ScoreAnswer, ExpectedParam, Usage, Feedback, Model, QuestionType, TaskType and AbstentionStatus. The package ships with py.typed, so type checkers like mypy and pyright use them.