Quickstart

This guide takes you from an API key to your first decision. You need Python 3.10 or later and a Krun API key.

Install the SDK

pip install krun-ai

The package is krun-ai on PyPI. You import it as krun.

Set your API key

The SDK reads the key from the KRUN_API_KEY environment variable.

export KRUN_API_KEY=krun_live_...

$env:KRUN_API_KEY = "krun_live_..."

Keep your API key on the server. Never ship it in browser or mobile client code. See Authentication.

Make a decision

Create decide.py:

decide.py

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"]
print(answer.choice)         # returns
print(answer.confidence)     # 0.967536
print(answer.probabilities)  # {'shipping': 0.011351, 'returns': 0.978886, 'billing': 0.009763}
print(result.request_id)     # req_...

Run it:

python decide.py

Handle abstention

When the model is not confident enough, it abstains: answer.choice is None and answer.abstain is True. The probabilities are still there if you want a best guess.

if answer.choice is None:
    best_guess = max(answer.probabilities, key=answer.probabilities.get)
    send_to_human(best_guess)
else:
    route(answer.choice)

See Abstention for when to trust this signal.

The numbers above come from a real call. Your values can differ slightly between calls and model updates, so don’t hard-code them in tests.

Use the HTTP API directly

The same request with curl:

curl https://api.krun.ai/v1/decide \
  -H "Authorization: Bearer $KRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
        }
      }
    }
  }'

from krun import Krun

client = Krun()
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",
            },
        }
    },
)
print(result.answers["department"].choice)

The TypeScript SDK (@krun-ai/sdk) is not published on npm yet.
Use the HTTP API from Node.js until it is released.
See /sdks/typescript for its status.

Response:

{
  "model": "krun-one-v0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "returns",
      "confidence": 0.967536,
      "probabilities": {
        "shipping": 0.011351,
        "returns": 0.978886,
        "billing": 0.009763
      },
      "abstain": false,
      "abstention_status": "advisory"
    }
  },
  "usage": {
    "input_tokens": 49
  }
}

The request id is in the X-Request-ID response header (curl -i shows it). You need it to send feedback.

The first request after a period without traffic can take longer while the model starts. The SDK’s default 70-second timeout covers this. See Production best practices.

Next steps

Questions and answers

How requests and answers are structured.

Multiple questions

Ask several questions about the same text in one call.

Tool routing

Pick a tool for an agent step.

Python SDK

Async client, errors, timeouts and retries.

Overview

Concepts

Guides

SDKs

API Reference

Resources

Use the HTTP API directly

Next steps

Questions and answers

Multiple questions

Tool routing

Python SDK

​Use the HTTP API directly

​Next steps

Questions and answers

Multiple questions

Tool routing

Python SDK

Use the HTTP API directly

Next steps