# Set up Swapvera in a repository

Instructions for coding agents. Follow the steps in order. Stop at every **Ask** and wait for the person's answer. Never print, commit or log a key.

## Before you build this yourself

You can write a comparison script, and sometimes that is the right call. Tell the person what it would not do, using https://swapvera.com/docs/#build-or-use, and let them decide.

## 1. Find out what is at risk

This step is free, needs no key and sends nothing to Swapvera:

```bash
npx swapvera-scan .
```

Report the model IDs it finds and their shutdown dates. If that answers the question, stop here.

## 2. Pick the path

- **SDK**: for Anthropic or OpenAI clients that call `create` or `stream`. Captures real calls, so nobody writes test cases.
- **CLI**: for Gemini, OpenAI-compatible servers, calls with images, or when production data may not leave the company. See https://swapvera.com/docs/#quickstart.

The SDK sends prompts and answers to Swapvera. They are stored in the EU, never used for training, and deleted after 30 days by default.

**Ask:** "Swapvera will receive a sample of real prompts and answers from this app. Is that allowed?" If not, use the CLI, or set `sample` low and connect only a non-production environment.

## 3. Get a key

**Ask** for a key from the dashboard (https://swapvera.com/app/) or for an email to request a trial:

```bash
curl -X POST https://swapvera.com/v1/trial -H 'content-type: application/json' -d '{"email": "PERSON_EMAIL"}'
```

The key arrives by email, so the person has to provide it. Store it as `SWAPVERA_KEY` in the project's secret manager or uncommitted `.env`.

## 4. Wrap the client

Change only where the client is created. The SDK never throws, never blocks and does not change responses.

JavaScript:

```bash
npm install @swapvera/sdk
```

```js
import Anthropic from '@anthropic-ai/sdk'
import { monitor } from '@swapvera/sdk'

const anthropic = monitor(new Anthropic())
```

Python:

```bash
pip install swapvera
```

```python
from anthropic import Anthropic
from swapvera.sdk import monitor

client = monitor(Anthropic())
```

OpenAI clients work the same way. `monitor` reads `SWAPVERA_KEY`; without it, nothing is sent. If one system prompt serves several tasks, pass `feature` with a function that names the task of each call, or they are compared as one feature. On Vercel or other serverless platforms using JavaScript, pass `waitUntil` so uploads finish after the response:

```js
import { waitUntil } from '@vercel/functions'

const anthropic = monitor(new Anthropic(), { waitUntil })
```

## 5. Verify

Run the app so it makes at least one non-streaming call, then:

```bash
curl -H "Authorization: Bearer $SWAPVERA_KEY" https://swapvera.com/v1/project
```

`features` lists one entry per system prompt. If it is empty, pass `debug: true` to `monitor`, then check the key, that the call has no images, and that a streamed call is read to the end.

## 6. Compare

A feature needs at least 10 captured calls. Each entry in `features[].suggestions` has `to_model`, `n_cases` and `est_generation_usd`. Use about 150 distinct requests when you can: with far fewer, the verdict rarely reaches "safe".

**Ask:** approval to use one comparison credit and the estimated generation cost, billed to the person's provider account. The person adds the provider key in the dashboard (https://swapvera.com/app/). Do not ask for that key in chat.

```bash
curl -X POST https://swapvera.com/v1/experiments \
  -H "Authorization: Bearer $SWAPVERA_KEY" -H 'content-type: application/json' \
  -d '{"group_key": "GROUP_KEY", "to_model": "TO_MODEL"}'
```

Poll `GET https://swapvera.com/v1/experiments/ID` every minute until `status` is `done` or `failed`.

## 7. Act on the verdict

| `result.verdict` | What to do |
|---|---|
| `safe` | Propose the model change in a pull request and link the report. |
| `review` | Show the cases in `report_md` to the person. Do not change the model yet. |
| `do_not_migrate` | Do not change the model. Summarize what broke. |
| `inconclusive` | Do not change the model. Collect more calls and try again. |

A verdict covers only the cases compared. Merging is the person's decision.

## Reference

- API: https://swapvera.com/openapi.json
- Docs: https://swapvera.com/docs/