# Getting started in five minutes

You need a running Jers gateway (port 8797 on the machine that runs it) and a key. Everything below was run for real; your numbers will differ a little.

## Minute 1: a key

Whoever runs the gateway makes one:

```bash
python3 decision_api_server.py keys add --tenant my-team --credit 5.00
```

It prints a key once, like `jj_live_4f9c...`. Put it in your shell:

```bash
export JERS_API_KEY=jj_live_...
export JERS_BASE_URL=http://127.0.0.1:8797     # the default; change it if the gateway is elsewhere
```

Check that it works:

```bash
curl -s $JERS_BASE_URL/v1/models -H "Authorization: Bearer $JERS_API_KEY"
```

You get the list of models and `"available": true` for each one that can answer now.

## Minute 2: your first decision

Ask one yes/no question about a message:

```bash
curl -s $JERS_BASE_URL/v1/systemone -H "Authorization: Bearer $JERS_API_KEY" -H "Content-Type: application/json" -d '{
  "state": "Hi, you charged me twice for September. Please send the second payment back.",
  "questions": {"refund": {"type": "noul", "instructions": "Is the customer asking for money back?"}}
}'
```

The answer carries the probability of yes and a confidence: `"refund": {"type": "noul", "noul": 0.9..., "confidence": 0.9...}`. Near 1 means yes, near 0 means no, near 0.5 means the engine cannot tell. The `usage` block says what it cost, `warnings` lists known traps in the request (none here), and `decision_id` is what you send back with `POST /v1/feedback` once you know the right answer.

## Minute 3: three questions at once

Add a choice and a score. They are answered in the same engine pass, so the request is billed three answers:

```bash
curl -s $JERS_BASE_URL/v1/systemone -H "Authorization: Bearer $JERS_API_KEY" -H "Content-Type: application/json" -d '{
  "state": "Hi, you charged me twice for September. Please send the second payment back.",
  "questions": {
    "route":   {"type": "choice", "instructions": "Which team should handle this?",
                "criteria": {"billing": "Charges and refunds", "support": "Product problems", "sales": "New licences", "other": "None of these"}},
    "refund":  {"type": "noul",   "instructions": "Is the customer asking for money back?"},
    "urgency": {"type": "score",  "instructions": "How urgent is this?",
                "criteria": ["Can wait a week", "Should be handled today", "Blocking the customer now"]}
  }
}'
```

Read the answer like this:

- `route.choice` is the option with the highest probability; `route.probabilities` shows the others; `route.confidence` says how concentrated they are.
- `refund.noul` is the probability of yes.
- `urgency.score` is a position between the levels, 0 to 2 here; `urgency.legend` maps the numbers back to your words.

## Minute 4: give it a memory

Write what you know about a subject once. A subject is whatever you decide about: a customer, a user, a player, a device, a case.

```bash
curl -s $JERS_BASE_URL/v1/memory/remember -H "Authorization: Bearer $JERS_API_KEY" -H "Content-Type: application/json" -d '{
  "subject": "acme",
  "text": "ACME Logistics holds an enterprise contract; refunds for ACME go to the billing team within one business day.\nACME Logistics is handled by the enterprise desk."
}'
```

Now name the subject in a decision and ask for the comparison:

```bash
curl -s $JERS_BASE_URL/v1/systemone -H "Authorization: Bearer $JERS_API_KEY" -H "Content-Type: application/json" -d '{
  "state": {"message": "We were charged twice for September again.", "account": "ACME Logistics"},
  "subject": "acme", "memory": {"compare": true},
  "questions": {"route": {"type": "choice", "instructions": "Which team should handle this?",
                          "criteria": {"billing": "Charges and refunds", "support": "Product problems", "enterprise_desk": "The enterprise account desk"}}}
}'
```

The answer now has a `memory` block: which lines were used (`hits`), how many the engine read (`lines_seen`), the answer without them, and `changes` per question. The `compare` pass is not billed. Forgetting is one call, and it tells you whether the line is really gone:

```bash
curl -s $JERS_BASE_URL/v1/memory/forget -H "Authorization: Bearer $JERS_API_KEY" -H "Content-Type: application/json" -d '{"subject": "acme", "concept": "enterprise desk"}'
```

## Minute 5: the same from Python

```bash
pip install -e sdk/python          # from the checkout; no dependencies (Pydantic is optional)
```

```python
from jers import JersClient, Choice, Noul, Score

with JersClient() as client:                       # reads JERS_API_KEY and JERS_BASE_URL
    r = client.system_one(
        state={"message": "We were charged twice for September again.", "account": "ACME Logistics"},
        questions={
            "route": Choice("Which team should handle this?", {"billing": "Charges and refunds", "support": "Product problems", "other": "None of these"}),
            "refund": Noul("Is the customer asking for money back?"),
            "urgency": Score("How urgent is this?", ["Can wait a week", "Should be handled today", "Blocking the customer now"]),
        },
        subject="acme", memory={"compare": True})

print(r.answers["route"].choice, r.answers["route"].confidence)
print(r.answers["refund"].noul, r.answers["urgency"].score)
print(r.memory.lines_used, r.memory.changes)
print(r.usage.cost, r.usage.currency, r.usage.balance)
```

## Where to go next

- Examples: twenty-five real requests and answers across support, e-commerce, moderation, games, machines and case files.
- Primitives, State and Confidence: how to write questions that work.
- Memory and Rules in memory: what to write for a subject, and what to check in code instead (numbers, dates, forbidden options).
- Warnings, Quality and Batches: known traps flagged per request, accuracy measured on your own labels, many requests at once.
- JavaScript and TypeScript, and Claude and MCP: the other two clients.
- Cookbooks: complete scripts with measured results.
- Troubleshooting and FAQ when something does not do what you expected.