# meraGPT: getting started (for you, or for your AI agent)

Give this file to a coding agent and it has everything needed to call meraGPT's models:
https://meragpt.com/llms-full.txt

meraGPT is an API for small models that each do one job. Three are live:

| model | what it does | endpoint |
|---|---|---|
| `decider-1` (Decider 1.1) | Answers typed questions about a piece of state (text, JSON or images): yes/no, a choice between labels, or a score on a rubric, each as a probability distribution. | `POST /v1/systemone` |
| `restyler-1` (Restyler 1.1) | Rewrites machine-written text so it reads like a person wrote it, keeping numbers, names and links. `"mode": "strict"` only removes AI tells. | `POST /v1/restyle` |
| `fanout-1` (Fanout 1.1) | Takes a question someone would ask an AI assistant and returns the web searches that assistant is likely to run first. | `POST /v1/fanout` |

## 1. Get a key

Sign in at https://meragpt.com/login (new accounts get $1 of free credit), then create a key at
https://meragpt.com/dashboard/keys. Keys look like `mg-live-…`. Send it on every request:

```
Authorization: Bearer $MERAGPT_API_KEY
Content-Type: application/json
```

Base URL: `https://meragpt.com/v1`. `GET /v1/models` lists the models without a key.

## 2. Decider: typed decisions

```bash
curl https://meragpt.com/v1/systemone \
  -H "Authorization: Bearer $MERAGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decider-1",
    "state": {
      "channel": "email",
      "messages": [{ "from": "customer", "text": "I was charged twice for September. Refund the duplicate, today please." }]
    },
    "questions": {
      "refund_requested": { "type": "noul", "instructions": "Is the customer asking for money back?" },
      "team": {
        "type": "choice",
        "instructions": "Which team should handle this?",
        "criteria": {
          "billing": "Charges, invoices, payments and refunds.",
          "technical": "The product is not working as expected.",
          "account": "Login, plan changes and access."
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this?",
        "criteria": ["Can wait a week", "Within a few days", "Today", "Immediately"]
      }
    }
  }'
```

Response:

```json
{
  "object": "systemone",
  "model": "decider-1",
  "answers": {
    "refund_requested": { "type": "noul", "noul": 0.9989 },
    "team": { "type": "choice", "choice": "billing", "confidence": 0.9967,
              "probabilities": { "billing": 0.9967, "technical": 0.0005, "account": 0.0028 } },
    "urgency": { "type": "score", "score": 2.0464, "confidence": 0.4405,
                 "probabilities": { "0": 0.0448, "1": 0.1895, "2": 0.4405, "3": 0.3253 } }
  },
  "usage": { "input_tokens": 188, "output_tokens": 0, "cost_usd": "$0.0000075" }
}
```

- Question types: `noul` (yes/no; `noul` is the probability of yes), `choice` (up to 255 labels, an object
  of label → description), `score` (an ordered list of up to 32 levels, lowest first).
- Each question is read on its own, so adding one never changes the others. Ask as many as you need in one
  call; the state is read once.
- `state` can hold images: `{ "type": "image_url", "image_url": { "url": "data:image/png;base64,…" } }`,
  up to 8 per request, 8 MB each.
- Up to 32,768 tokens of state plus question.
- It speaks TypeSafe's System One schema: the typesafe-sdk works unchanged with
  `TYPESAFE_BASE_URL=https://meragpt.com` and `TYPESAFE_API_KEY=$MERAGPT_API_KEY`.
- Decider has no chat-completions form: it returns probabilities, not text.

## 3. Restyler: rewrite text

```bash
curl https://meragpt.com/v1/restyle \
  -H "Authorization: Bearer $MERAGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "restyler-1", "text": "Your document.\n\nParagraphs separated by blank lines." }'
```

Response: `text` (the rewritten document, your formatting intact), `blocks` (one entry per paragraph:
`status` `rewritten` or `unchanged`, with a `reason` when unchanged), `rewritten`, `total`, `usage`.

- Up to 60,000 characters (about 10,000 words) per request. Longer documents: send sections.
- `"mode": "strict"`: keeps every word and only removes AI tells (em dashes, "!", sentence-opening filler).
  No model call, free, instant.
- Headings, tables, list markers and code come back exactly as sent.

## 4. Fanout: likely AI searches for a question

```bash
curl https://meragpt.com/v1/fanout \
  -H "Authorization: Bearer $MERAGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "fanout-1", "question": "What are the best project management tools available right now?" }'
```

Response: `queries`, an array of up to 6 searches (typically 3–5). Optional request fields: `category`
(a short category name, used on its own or with brands) and `brands` (up to 12 names in the category,
written back exactly as you send them). The current date is added for you, so searches carry this
year. The question is up to 2,000 characters: send a question, not a document. About 0.2 s per request.

## 5. OpenAI-compatible clients (Restyler and Fanout)

```python
from openai import OpenAI
client = OpenAI(api_key=os.environ["MERAGPT_API_KEY"], base_url="https://meragpt.com/v1")
resp = client.chat.completions.create(model="restyler-1", messages=[{"role": "user", "content": draft}])
print(resp.choices[0].message.content)
```

The last user message is the input. `temperature` and `top_p` are accepted and ignored. Fanout's searches
arrive newline-joined in the message and as an array under `meragpt.queries`.

## 6. Errors and retries

Errors use the OpenAI envelope: `{ "error": { "message", "type", "code", "param" } }`.

- `429 capacity_saturated`: retry after the `Retry-After` header (10 to 30 seconds). Nothing is charged.
  The first call after a quiet period can get this while capacity starts.
- `502` / `503`: retry with backoff.
- Any other `4xx`: fix the request; retrying the same body will not help. `400 input_too_large` names the
  size you sent. `402` means the balance is empty: top up at https://meragpt.com/dashboard/credits.

## 7. Pricing

Prepaid USD credit, billed per token, no subscription. All three models: $0.04 per million input tokens;
Restyler and Fanout $0.16 per million output tokens; Decider has no output charge. Failed requests are not
charged.

## More

Docs: https://meragpt.com/docs · Errors and limits: https://meragpt.com/docs/errors ·
Models: https://meragpt.com/docs/models · Playground (no account): https://meragpt.com/playground ·
Contact: hello@meragpt.com