# Quickstart

Source: https://docs.temprl.org/guide/quickstart

> Create an API key, install the simoai Python SDK and send your first request to Simo in a few minutes.

This takes about five minutes: create a key, install the SDK, ask a question.

## 1. Create an API key

[Create an account](https://app.temprl.org/signup) with Google or your email. It's open to everyone, and every new account gets **$2 of free credit** once the email is confirmed. Then open **API keys** and create one. Keys look like `simo_sk_...` and are shown once, so copy it somewhere safe.

Keep the key out of your source code. Put it in an environment variable:

**macOS / Linux**

```bash
export SIMO_API_KEY=simo_sk_...
```

**Windows**

```powershell
$env:SIMO_API_KEY = "simo_sk_..."
```

> **Tip** $2 covers about 66 million input tokens, enough to build and test a whole integration. See [Pricing](https://docs.temprl.org/models/pricing).

## 2. Install the SDK

```bash
pip install simoai
```

Python 3.10 or newer. The SDK uses only the standard library. For images and video, install an extra:

```bash
pip install "simoai[image]"   # image() and video(): adds Pillow
pip install "simoai[video]"   # video_file(): adds Pillow and OpenCV
```

Not using Python? Every feature is one HTTP endpoint. Skip to the [HTTP API](https://docs.temprl.org/api).

## 3. Check the key works

```python
from simoai import Client, Noul

with Client() as c:   # reads $SIMO_API_KEY; closes the connection on exit
    r = c.ask("The parcel arrived broken.", {"damaged": Noul("The goods are damaged")})
    print(r["damaged"].noul, r.cost_usd, r.balance_usd)
```

A wrong or revoked key raises `AuthError`. An empty balance raises `InsufficientBalance`.

## 4. Ask several questions at once

One request reads the situation once and answers every question about it.

**Python**

```python
from simoai import Client, Choice, Noul, Score, Fill

c = Client()
r = c.ask(
    "Hi, I was charged twice for order A-1042 ($89). This is the third time I'm writing. Fix it today.",
    {
        "refund": Noul("The customer asks for money back"),
        "team":   Choice("Which team should handle this ticket?",
                         {"billing": "refunds and payments", "shipping": "delivery and tracking",
                          "tech": "website and app problems"}),
        "mood":   Score("How upset is the customer?", ["calm", "annoyed", "angry", "furious"]),
        "amount": Fill("the amount charged, in dollars", kind="number"),
    },
)

r.values      # {"refund": True, "team": "billing", "mood": 2.3, "amount": 89.0}
r.certainty   # {"refund": 0.98, "team": 0.96, "mood": 0.71, "amount": 0.99}
```

**cURL**

```bash
curl https://api.temprl.org/v1/ask \
  -H "Authorization: Bearer $SIMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "simo-1-pro",
    "state": "Hi, I was charged twice for order A-1042 ($89). This is the third time I am writing. Fix it today.",
    "questions": {
      "refund": {"type": "noul", "instructions": "The customer asks for money back"},
      "team": {"type": "choice", "instructions": "Which team should handle this ticket?",
               "criteria": {"billing": "refunds and payments", "shipping": "delivery and tracking",
                            "tech": "website and app problems"}},
      "mood": {"type": "score", "instructions": "How upset is the customer?",
               "criteria": ["calm", "annoyed", "angry", "furious"]},
      "amount": {"type": "fill", "instructions": "the amount charged, in dollars", "kind": "number"}
    }
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.temprl.org/v1/ask", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SIMO_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "simo-1-pro",
    state: "Hi, I was charged twice for order A-1042 ($89). This is the third time I'm writing. Fix it today.",
    questions: {
      refund: { type: "noul", instructions: "The customer asks for money back" },
      team: {
        type: "choice",
        instructions: "Which team should handle this ticket?",
        criteria: { billing: "refunds and payments", shipping: "delivery and tracking", tech: "website and app problems" },
      },
      mood: { type: "score", instructions: "How upset is the customer?", criteria: ["calm", "annoyed", "angry", "furious"] },
      amount: { type: "fill", instructions: "the amount charged, in dollars", kind: "number" },
    },
  }),
});
const { answers, usage } = await res.json();
console.log(answers.team.choice, answers.team.probabilities, usage.cost);
```

## Client settings

| Argument | Default | Meaning |
|---|---|---|
| `api_key` | `$SIMO_API_KEY` | Sent as `Authorization: Bearer …` |
| `base_url` | `$SIMO_BASE_URL`, else `https://api.temprl.org` | The API. Always use `https://` |
| `model` | `"simo-1-pro"` | Default model for every call |
| `timeout` | `120` | Seconds to wait for an answer |
| `retries` | `3` | Extra attempts on 429, 502, 503, 504 and connection errors, honoring `Retry-After`. Those failures are not charged |

One `Client` keeps a connection per thread and is thread-safe. In a long-running service, create it once, reuse it and call `c.close()` on shutdown. `simoai.__version__` is the installed SDK version.

## Next steps

- [Core concepts](https://docs.temprl.org/guide/concepts): state, questions and calibration.
- [Question types](https://docs.temprl.org/guide/question-types): everything you can ask.
- [Examples](https://docs.temprl.org/examples): complete programs for common jobs.