Krun Python SDK
Official Python SDK for the Krun API.
pip install krun-ai
The distribution is krun-ai (the name krun belongs to an unrelated PyPI project); the import name is krun.
- Python 3.10+
- One runtime dependency:
httpx - Sync (
Krun) and async (AsyncKrun) clients with the same methods - Fully typed (
py.typed), frozen dataclasses for results, plain dicts for requests - Supports Krun API v1 (
/v1/*, OpenAPI1.0.0-beta)
Quickstart
from krun import Krun
client = Krun(api_key="krun_live_...") # or Krun() to read 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"]
print(answer.choice) # "returns", or None if the model abstains
print(answer.confidence) # 0.9788: top-1 minus top-2 probability
print(answer.probabilities) # {"shipping": 0.0056, "returns": 0.9866, "billing": 0.0078}
print(result.request_id) # "req_...": pass it to feedback()
Reading an answer
Every question gets one answer of its own type: ChoiceAnswer, NoulAnswer or ScoreAnswer (see
Decision primitives). result.choice("id"), result.noul("id") and result.score("id")
return the typed answer; result.answers holds them all. A ChoiceAnswer:
| field | type | meaning |
|---|---|---|
type |
"choice" |
question type |
choice |
str | None |
selected option id, None when abstain is true |
confidence |
float |
top-1 probability − top-2 probability, in [0, 1] |
probabilities |
dict[str, float] |
calibrated probability per option id, keys exactly as sent, in request order |
abstain |
bool |
confidence is below the model's abstention threshold |
abstention_status |
"calibrated" | "advisory" |
how much to trust abstain (below) |
confidence is a margin, not "the probability that the answer is correct". It measures how clearly the best
option beats the runner-up: 0.97 means a clear winner, 0.02 means a near tie. It is the score the abstention
threshold is applied to.
choice can be None. When the model abstains, choice is None and the SDK does not replace it with the most
likely option. The ranking is still in probabilities if you want a best guess:
if answer.abstain:
best_guess = max(answer.probabilities, key=answer.probabilities.__getitem__)
route_to_human(best_guess)
else:
route(answer.choice)
abstention_status:
calibrated: intent questions with label-only options (""/Nonedescriptions). Abstention was validated for this setup.advisory: tool routing and options with descriptions.abstainis a hint, not a validated guarantee.
result.usage.input_tokens is the number of input tokens the model processed, summed over questions. Krun scores
options and does not generate text, so there are no output tokens.
Multiple questions
Ask several questions about the same context in one call. Answers come back under the same ids, in request order:
result = client.decide(
context="My card was charged twice and I need the money back today!",
questions={
"department": {"type": "choice", "options": {"shipping": "", "returns": "", "billing": ""}},
"priority": {"type": "choice", "options": {"low": "Can wait", "normal": "", "high": "Urgent"}},
"risk": {"type": "choice", "options": {"low": "", "high": ""}},
},
)
result.choice("department").choice # "billing"
result.choice("priority").choice # "high"
result.choice("risk").choice
Limits (enforced by the API, reported as InvalidRequestError before any inference): 1–16 questions, 2–64 options
per question, context 1–8,000 characters. Option descriptions can be a string, "" or None (label-only).
Question and option ids are yours: they are sent and returned verbatim (transaction_charged_twice,
calendar_search, ...).
Tool routing
Set task_type: "tool" to pick a tool or function:
from krun import ChoiceQuestion
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",
},
}
},
)
# or, as an object: {"tool": ChoiceQuestion(options={...}, task_type="tool")}
answer = result.choice("tool")
answer.choice # "calendar_search"
answer.abstention_status # "advisory": tool abstention is a hint, keep your own fallback
Decision primitives
Three question types, which can be mixed in one call (one question = one decision for billing and quota):
| type | use when | returns |
|---|---|---|
choice |
pick one of several alternatives | choice + probabilities |
noul |
evaluate a yes/no proposition | noul: probability in [0, 1] |
score |
rate on ordered levels | score (expected level) + probabilities per level |
from krun import NoulQuestion, ScoreQuestion
result = client.decide(
context="Customer says this is the third time exports failed and wants a human immediately.",
questions={
"department": {"type": "choice", "options": {"billing": "", "support": "", "sales": ""}},
"needs_human": {
"type": "noul",
"instructions": "Is the customer asking to speak with a human?",
"criteria": {"true": "Explicitly requests a person"}, # optional
},
"severity": ScoreQuestion(
"How severe is the reported issue?",
["Minor issue", "Feature degraded", "Blocking issue"], # lowest first; order is meaning
),
},
)
result.noul("needs_human").noul # 0.973: probability that the proposition holds
severity = result.score("severity")
severity.score # 1.43 = Σ index × probability (not the most likely level)
severity.probabilities # {"0": 0.0, "1": 0.57, "2": 0.43}
severity.legend # {"0": "Minor issue", "1": "Feature degraded", "2": "Blocking issue"}
severity.confidence # 1 − variance / max variance: 1 = one level, 0 = split between the extremes
- noul:
instructionsis the proposition phrased as a yes/no question;criteria(true/falsetexts) is optional.noulis a probability, so it has no separate confidence. It is well calibrated on the kinds of propositions Krun was evaluated on, but calibration is not guaranteed for every domain — validate the threshold you act on with your own data. - score: 2–16
levels, lowest first. Prefer descriptive levels ("Blocking issue; no workaround") over bare numbers. The levels are sent exactly in the order given. - Use
isinstance(answer, ScoreAnswer)oranswer.type == "score"to branch onresult.answersvalues.
Krun One V1 (multimodal)
Krun One V1 (krun-one-v1) is live on api.krun.ai and is the API's default model: multimodal contexts, multi
questions and /v1/assets. The previous ids krun-one-v0 and krun-one-v0.3 keep working as aliases. Text-only
usage is unchanged: context="..." sends exactly the same request as before.
Content parts. context can be a list of 1–16 parts instead of a string. Media parts reference an uploaded
asset. Every modality is input only: the answer is always the structured decision.
from krun import DocumentPart, ImagePart, Krun, MultiQuestion, NoulQuestion, TextPart
client = Krun()
invoice = client.assets.create("invoice.pdf") # MIME type inferred from the extension
# client.assets.create(png_bytes, mime_type="image/png") or client.assets.create(open("a.wav", "rb"))
result = client.decide(
context=[TextPart("Is this invoice paid?"), DocumentPart(invoice.id)],
# or plain dicts: [{"type": "text", "text": "..."}, {"type": "document", "asset_id": invoice.id}]
questions={
"paid": NoulQuestion("Is the document marked as paid?"),
"tags": MultiQuestion({"invoice": None, "receipt": None, "overdue": None}),
},
)
tags = result.multi("tags")
print(tags.values) # ['invoice', 'overdue'] (request order, may be empty)
print(tags.probabilities) # {'invoice': 0.97, 'receipt': 0.04, 'overdue': 0.81} (independent, not a distribution)
client.assets.delete(invoice.id) # optional: assets expire after 24 h (asset.expires_at)
- Part types:
TextPart(text),ImagePart(PNG / JPEG / WebP, ≤ 10 MB, ≤ 4 per request),DocumentPart(PDF / DOCX / text / Markdown / HTML, ≤ 25 MB and 20 pages, or a page image; ≤ 2 per request) andAudioPart(WAV / MP3 / FLAC / OGG, ≤ 10 MB and 30 s — speech over 20 s may be transcribed only partially; 1 per request). Each part takes an optionalid. Limits are enforced by the API, not the SDK. client.assets.create(file, mime_type=None)uploads bytes, a path or a binary file object as the raw body, withContent-Type=mime_type. Withoutmime_type, it is inferred from the file name extension. It returns anAsset(id,mime_type,size_bytes,sha256,created_at,expires_at).client.assets.get(id)andclient.assets.delete(id)complete the set;AsyncKrunhas the same methods. Uploads and deletes are never retried;get()is retried likemodels().multiquestion:{"type": "multi", "options": {...}, "instructions": "..."}(2–64 options,instructionsoptional) orMultiQuestion(...). The answer is aMultiAnswer(values,probabilities).- New error codes reuse the existing classes; read
e.error_code(or its aliase.code) to tell them apart:UNSUPPORTED_MODALITY,UNSUPPORTED_MIME_TYPE(415),ASSET_TOO_LARGE(413),TOO_MANY_IMAGES/TOO_MANY_DOCUMENTS/TOO_MANY_AUDIO,DOCUMENT_TOO_MANY_PAGES,AUDIO_TOO_LONG,DECODE_FAILED(422) →InvalidRequestError;ASSET_NOT_FOUND(404),ASSET_EXPIRED(410) →NotFoundError;ASSET_FORBIDDEN→PermissionDeniedError;OCR_FAILED/ASR_FAILED/VISION_FAILED(502) →InferenceFailedError;MULTIMODAL_INFERENCE_FAILED(500) →InternalServerError. - The SDK adds no dependencies: it never decodes images, audio or PDFs.
Feedback
Tell Krun whether an answer was right. question_id is always required. expected is typed like the question:
client.feedback(
request_id=result.request_id,
question_id="needs_human",
correct=False,
expected={"type": "noul", "value": False}, # or {"type": "score", "value": 2}, {"type": "choice", "value": "billing"}
metadata={"ticket": "T-1234"}, # optional JSON object, ≤ 8 KiB; no personal data
)
expected_decision="billing" (choice only) is still accepted.
Feedback for a request_id this project never decided raises NotFoundError.
Models
for model in client.models():
print(model.id, model.status) # krun-one-v1 available
Async
import asyncio
from krun import AsyncKrun
async def main() -> None:
async with AsyncKrun() as client:
result = await client.decide(context="...", questions={...})
await client.feedback(request_id=result.request_id, question_id="department", correct=True)
asyncio.run(main())
Krun and AsyncKrun take the same arguments and return the same types.
Configuration
client = Krun(
api_key="krun_live_...", # default: KRUN_API_KEY
base_url="http://localhost:8080", # default: https://api.krun.ai
timeout=180.0, # seconds per attempt (default 180)
max_retries=1, # decide()/models() only (default 1)
http_client=None, # optional httpx.Client (proxies, custom transport, ...)
)
Per call: client.decide(..., timeout=10.0, request_id="my-trace-id"). Use with Krun() as client: or
client.close() to release connections.
Timeouts
The default is 180 seconds because a Krun One V1 cold start can take up to ~150 s (the API waits up to 150 s for
the model), plus room for the response. The timeout applies to each attempt (connect and read). It cannot be disabled:
None, 0 and inf are rejected. When it elapses you get APITimeoutError.
Retries
The API already retries its model backend, so the SDK retries only a little:
| call | retried on | default |
|---|---|---|
decide(), models() |
connection errors, HTTP 502 / 503 / 504 | 1 retry (max_retries) |
feedback() |
never: it writes a row and the API has no idempotency key | – |
assets.get() |
same as models() |
1 retry |
assets.create(), assets.delete() |
never | – |
- The wait between attempts follows
Retry-Afterwhen the API sends it (capped at 10 s). Otherwise it is 0.5 s, then 1 s, 2 s, and so on. - SDK timeouts (
APITimeoutError) are not retried. - 4xx errors and 500 are not retried.
- A retried
decide()can count one extra decision against usage if the first attempt reached the model. - Use
max_retries=0to disable retries.
Request IDs
Every decision gets an id from the X-Request-ID response header. The SDK puts it on result.request_id. Errors
carry it too (exc.request_id, from the error body or the header), so you can quote it to support. You can send your
own with decide(..., request_id="...") (1–128 characters of [A-Za-z0-9._:-]). The API keeps it and returns it.
Errors
All errors inherit from krun.KrunError and expose message, request_id, status_code and error_code (alias
code) when available. The Krun One V1 multimodal codes map onto these classes (see
Krun One V1):
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
│ ├── InsufficientCreditsError 402 INSUFFICIENT_CREDITS
│ ├── PermissionDeniedError 403 FORBIDDEN, SIGNUP_RESTRICTED
│ ├── NotFoundError 404 NOT_FOUND
│ ├── ConflictError 409 CONFLICT
│ ├── 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 krun
try:
client.decide(context="...", questions={...})
except krun.InvalidRequestError as e:
print(e.error_code, e.message, e.request_id) # INVALID_OPTIONS questions.q: 1 options given; ...
except krun.RateLimitError as e:
time.sleep(e.retry_after or 1)
except krun.KrunError as e:
log.warning("krun failed: %s", e)
Wrong argument types (e.g. context=None) raise TypeError before any request is made.
Privacy and logging
- No telemetry: the SDK sends requests only to the Krun API and records nothing itself. Usage is recorded by the API.
- Silent by default. The SDK logs to the
krunlogger at DEBUG, and only method, path, status, request id and retries. It never logs the API key, context, options, instructions, levels or answers. To see these logs:logging.getLogger("krun").setLevel(logging.DEBUG). - The API key never appears in
repr(client), error messages or logs. - Requests carry
User-Agent: krun-python/<version>.
Examples
examples/: basic_decision.py, multiple_questions.py, decision_primitives.py, tool_routing.py,
feedback.py, async_decision.py, error_handling.py.
export KRUN_API_KEY=krun_live_...
python examples/basic_decision.py
Development
uv sync # Python 3.10+ venv with dev tools
uv run ruff check . && uv run ruff format --check .
uv run mypy
uv run pytest # unit + contract + mock-server integration tests (no network)
uv build # dist/krun_ai-0.3.0-py3-none-any.whl + .tar.gz
uv run python scripts/bench.py # SDK overhead vs raw httpx on a local mock server
Tests
-
tests/test_client.py: unit tests withhttpx.MockTransport. Covers auth header, serialization, parsing,choice=None,input_tokens,X-Request-ID, the full error mapping, retries, timeouts, base URL, feedback, models, key redaction and the absence of output tokens. -
tests/test_integration.py: real HTTP againsttests/mock_server.py, a local server that validates every request body against the OpenAPI snapshot. Covers sync and async clients, real timeouts, connection refused and retry after 503. -
tests/test_contract.py: offline checks that the hand-written models matchopenapi/openapi.json(every error code mapped, answer/usage/feedback fields, OpenAPI examples round-trip). -
tests/test_live.py: opt-in production checks, never run in CI:KRUN_LIVE_TESTS=1 KRUN_API_KEY=krun_live_... uv run pytest tests/test_live.py -v # 1 real decision KRUN_API_KEY=krun_live_... uv run python scripts/smoke.py # manual smoke, 1 real decision
OpenAPI contract and drift
The public API is hand-written, and https://api.krun.ai/openapi.json is the reference:
openapi/openapi.jsonis the snapshot this release was written against. Its version and hash are pinned insrc/krun/_constants.py, andtests/test_contract.pyfails if they disagree.python scripts/check_openapi.pycompares production with the snapshot. It exits 1 on drift and prints what changed.--updaterefreshes the snapshot.- The
contract-driftworkflow runs that check weekly and on demand. The unit tests never use the network.
Versioning and releases
SemVer, starting at 0.1.0. SDK versions are independent of model versions (krun-one-v1) and of the API version
(v1). See CHANGELOG.md.
Release flow:
- Bump
versioninpyproject.tomlandsrc/krun/_version.py, and updateCHANGELOG.md. - Merge to
main. CI runs lint, type check, tests on 3.10–3.13 and the package build. - Tag
vX.Y.Zand publish a GitHub Release. .github/workflows/publish.ymlruns on the release. It checks that the tag matches the package version, builds the wheel and sdist, and uploads them to PyPI with Trusted Publishing (OIDC, no stored token).
Trusted Publishing is configured on PyPI (owner krun-ai, repo krun-python, workflow publish.yml, environment
pypi); the pypi environment exists in the GitHub repo settings.
License
Metadata
Release files for krun-ai 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| krun_ai-0.3.0.tar.gz | 57.2 kB | With provenance | Details for krun_ai-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| krun_ai-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for krun_ai-0.3.0-py3-none-any.whl |
Total release size: 89.5 kB
Release files / krun_ai-0.3.0.tar.gz
| Download URL | krun_ai-0.3.0.tar.gz |
|---|---|
| Size | 57.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
63cb66a0f3724f9b9ef8146d5c2b365e7a66990657cba43bf9ab771c97c4b0a3
|
|
BLAKE2b-256 checksum How to use checksums |
75c67818b880eca2a7b6f1c439d5fe2c824969a9df298b531e07c966d42f2260
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / krun_ai-0.3.0-py3-none-any.whl
| Download URL | krun_ai-0.3.0-py3-none-any.whl |
|---|---|
| Size | 32.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
249a0f7c87a331efc4b76ac9fa49475faa43b5fc35ac8a5395193d2a62563067
|
|
BLAKE2b-256 checksum How to use checksums |
a295e75d5716467317b892a96aff49c8d9834eb883fe6ed5768ff223070ce909
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logSecurity for krun-ai 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for krun_ai-0.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.