# AGENTS.md — AIRUS Integration Rules

Инструкции для AI coding-агентов (Cursor, Cline, Claude Code, Codex CLI, n8n) по подключению AIRUS Gateway.

## Использование AIRUS API
- Base URL: `https://airus.world/v1`
- Аутентификация: `Authorization: Bearer $AIRUS_API_KEY` — ключ из переменной окружения `AIRUS_API_KEY`, НИКОГДА не хардкодь.
- API OpenAI-совместим: используйте официальный OpenAI SDK, меняя только base_url.
- Основной эндпоинт: `POST /v1/chat/completions`. Модель по умолчанию: `airus:auto` (роутинг подберёт под задачу).
- Передавайте `metadata` (feature, client_id, environment) — включает cost-атрибуцию и receipts.

## Production-правила
- Никогда не хардкодь ключ — читай из env AIRUS_API_KEY.
- Для backend/n8n/CI используй service account ключи (keyType: service), а не личные.
- Логируй request_id из ответа (заголовок x-request-id) для трассировки и сверки списаний.
- Ставь timeout >= 60s на production-вызовы (генерация бывает долгой).
- Обрабатывай коды: 401, 402, 403, 429, 451, 500, 502, 503, 504 — см. GET /v1/airus/errors (Error Doctor).
- Передавай metadata (feature, client_id, environment) — это включает cost-атрибуцию и receipts.
- Не полагайся на плавающие алиасы (airus:auto*) в проде без явного запроса пользователя — фиксируй модель, если нужна воспроизводимость.
- Задай дневной бюджет в политике проекта и подпишись на webhook budget.threshold_reached.
- Стриминг: stream:true, читай SSE до data: [DONE]; usage приходит в финальном чанке.

## Тестирование интеграции
- Добавь smoke-тест первого запроса (chat/completions с airus:auto).
- Добавь тест стриминга, если используешь stream:true.
- Добавь тест обработки ошибки (например insufficient_balance или model_not_found).

## Проверка совместимости
- Живая проверка ключом: `POST /v1/airus/migrations/check` { "api_key": "airus_sk_..." } — вернёт compatibility score и рекомендации.
- Каталог ошибок с диагнозом: `GET /v1/airus/errors` (Error Doctor).
- Полный машинный контекст: https://airus.world/llms-full.txt

## Model aliases
- `cheap-chat` — быстрая недорогая chat-модель
- `strong-chat` — сильная chat-модель для сложных задач
- `embeddings-small` — модель эмбеддингов
- `airus:auto` — авто-роутинг по task_type и политике
- `airus:auto-support` — короткие ответы поддержки
- `airus:auto-rag` — ответы по источникам (RAG)
- `airus:auto-code` — код-ревью
- `airus:auto-legal` — юридические/договорные тексты
- `airus:auto-classify` — классификация
- `airus:auto-cheap` — самый дешёвый проходной вариант