# Setting the AI API key

The optional **AI enhancement** uses a low‑cost Claude model (Haiku 4.5) to
produce richer summaries, a reasoned Fit %, and more accurate certifications and
technical requirements.

The key is **not** entered in the web app — it's a secret, so it lives in an
environment variable that the backend reads at startup. Follow these steps.

---

## 1. Get an API key

1. Sign in to the Anthropic Console: <https://console.anthropic.com>
2. Go to **API keys** → **Create key**.
3. Copy the key — it starts with `sk-ant-`. (You won't be able to see it again.)

## 2. Add the key to the `.env` file

The `.env` file sits in the project root, next to `docker-compose.yml`.

1. If you don't have one yet, create it from the template:
   ```bash
   cp .env.example .env
   ```
2. Open `.env` in a text editor and set the key (no quotes, no spaces around `=`):
   ```
   ANTHROPIC_API_KEY=sk-ant-your-key-here
   AI_MODEL=claude-haiku-4-5
   ```
   `AI_MODEL` is optional — it already defaults to Haiku 4.5.

## 3. Restart the containers

Environment variables are only read when a container starts, so recreate them:

```bash
docker compose up -d --build
```

> No database wipe is needed — your data is preserved.

## 4. Confirm the backend can see the key

```bash
curl http://localhost:8080/api/config/ai
```

- `{"enabled":false,"available":true,"model":"claude-haiku-4-5"}` → **key detected.** ✅
- `"available":false` → the key isn't being picked up (see Troubleshooting).

You can also check inside the container:
```bash
docker compose exec backend printenv ANTHROPIC_API_KEY
```

## 5. Turn AI on in the app

1. Open the dashboard and go to **Settings → AI enhancement** (admins only).
2. The toggle is now enabled — switch it **On**.
3. Click **Recompute fit & certs** to apply AI to the opportunities already in the
   table. New opportunities are analysed automatically from then on.

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| Toggle is greyed out / `"available":false` | The backend isn't seeing the key. |
| | • Make sure `.env` is in the **same folder** as `docker-compose.yml`. |
| | • Check the line is exactly `ANTHROPIC_API_KEY=sk-ant-...` (no quotes/spaces). |
| | • Run `docker compose up -d --build` again (a plain restart of the old container won't reload env). |
| AI is on but rows have no AI summary | The model fell back to the deterministic engine for those rows (e.g. a transient API error or rate limit). Click **Recompute** to retry. |
| Want to turn AI off | Toggle it **Off** in Settings, or remove `ANTHROPIC_API_KEY` from `.env` and restart. The app then runs fully offline/deterministic. |

---

## Notes

- **Cost:** roughly half a cent per opportunity with Haiku 4.5 (one model call
  each). A full recompute over a few hundred rows is a few dollars at most. All
  spend is gated behind the toggle.
- **Security:** keep `.env` out of version control (it is already listed in
  `.gitignore`). Never paste the key into the web UI or commit it.
- **Privacy:** with AI **off**, nothing leaves your server. With it on, each
  opportunity's text is sent to the Anthropic API for analysis.
