# ai-service — Claude context

AI provider intermediary, port 8010 (internal only — never proxied to the browser). Accepts chat requests from `doc-service` (and potentially other callers). Manages a priority queue and abstracts over multiple AI providers (Anthropic, Ollama/LM Studio). See root `CLAUDE.md` for architecture, Docker, and project-wide workflows.

---

## File & Folder Tree

```
features/ai-service/
├── app/
│   ├── main.py                    ← FastAPI, queue worker lifespan
│   ├── core/
│   │   └── config.py              ← Settings via pydantic-settings
│   ├── providers/
│   │   ├── base.py                ← AIProvider abstract class
│   │   ├── anthropic_provider.py  ← Anthropic API integration
│   │   └── openai_compat.py       ← Ollama / LM Studio compatibility
│   ├── routers/
│   │   ├── chat.py                ← POST /chat (sync, NORMAL priority queue)
│   │   ├── health.py              ← GET /health
│   │   ├── queue.py               ← GET /queue/status, /pause, /resume, /cancel/{id}
│   │   └── plugin.py              ← GET /plugin/manifest (access rules for ai-service-admin group)
│   └── services/
│       ├── queue.py               ← Priority queue (CRITICAL > HIGH > NORMAL)
│       └── config_reader.py       ← Reads ai_service_config.json from storage-service config bucket (30 s TTL cache)
├── Dockerfile                     ← python:3.12-slim, non-root user 1001
└── STATUS.md
```

---

## API Endpoints (internal only)

| Method | Path | Description |
|--------|------|-------------|
| POST | `/chat` | Chat request (queued at NORMAL priority) |
| GET | `/health` | Health check |
| GET | `/queue/status` | Queue state |
| POST | `/queue/pause` | Pause queue |
| POST | `/queue/resume` | Resume queue |
| POST | `/queue/cancel/{job_id}` | Cancel job |
| GET | `/plugin/manifest` | Plugin manifest (access rules for ai-service-admin group) |

These endpoints are only reachable on `backend-net`. The backend does not expose them to the browser.

---

## Note on timeout and retry configuration

Caller-side timeout and retry settings live in `features/doc-service/app/services/ai_client.py` — see `features/doc-service/CLAUDE.md` for the values.