Quickstart

Install the Krun Python SDK, set your API key and make your first decision.

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

1. Install the SDK

   pip install krun-ai
   

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

2. Set your API key

   The SDK reads the key from the KRUN_API_KEY environment variable.

   macOS / Linux

   export KRUN_API_KEY=krun_live_...
   

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

3. 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
   
4. 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

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"
        }
      }
    }
  }'

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.