feat(rag): add claw-rag-service

Adds claw-rag-service for repository indexing and semantic search.
2026-05-27 16:06:44 +00:00 · 2026-05-25 05:25:25 +03:00
parent 52572d5883
commit a4efdc43d7
12 changed files with 1510 additions and 0 deletions
--- a/docs/rag-web-ui.md
+++ b/docs/rag-web-ui.md
@@ -0,0 +1,78 @@
+# RAG и веб‑UI: архитектура и фазы
+
+Цель: **не** раздувать `claw-analog` и основной `claw` — вынести индексацию и (позже) UI в отдельные процессы с явными HTTP/MCP контрактами.
+
+## Принципы
+
+1. **RAG как сервис** — отдельный бинарь (сейчас `claw-rag-service`), свой жизненный цикл, свои секреты (embedding API), своё хранилище.
+2. **Агент только вызывает retrieval** — в **`claw-analog`** инструмент **`retrieve_context`** → HTTP `POST {RAG_BASE_URL}/v1/query` (база без суффикса `/v1`); лимиты **`rag_timeout_secs`**, **`rag_top_k_max`** в `.claw-analog.toml`; ответ для модели — фрагменты с `path` + `snippet` + `score`.
+3. **Веб‑UI** — минимальная страница **`GET /`** в `claw-rag-service` (stats + форма `POST /v1/query`); чат с моделью и «переиндексировать» из браузера — при необходимости позже.
+
+## Компоненты (целевая картина)
+
+```text
+┌─────────────────┐     POST /v1/query      ┌──────────────────────┐
+│  claw-analog    │ ──────────────────────►│  claw-rag-service    │
+│  (+ tool)       │◄──────────────────────│  (embed + vector DB) │
+└─────────────────┘     JSON hits          └──────────┬───────────┘
+                                                      │
+                                             ingest (watch / CLI)
+                                                      ▼
+                                             workspace files / git tree
+```
+
+- **Индексация**: отдельная команда или воркер (chunking, хеш файла, инкремент). Хранилище: на старте SQLite + `sqlite-vec` / файловый эмбеддинг-кэш; при росте — Qdrant/Chroma в Docker.
+- **Эмбеддинги**: HTTP к OpenAI/Anthropic-совместимому embedding endpoint или локальная модель (отдельное решение по лицензии и размеру).
+- **Веб‑UI**: авторизация (минимум: токен + reverse proxy), SSE или WebSocket для стрима ответа модели; UI **не** владеет секретами провайдера, если продукт так решит — прокси через бэкенд.
+
+## Текущая реализация
+
+Крейт **`rust/crates/claw-rag-service`** (из каталога `rust/`):
+
+### HTTP
+
+- `GET /` — одностраничный UI (встроенный `static/index.html`): счётчики из `/v1/stats`, поиск через `/v1/query`.
+- `GET /health` — `ok`.
+- `GET /v1/stats` — `{ "chunks": N, "phase": "1-sqlite" }` (если БД ещё нет: `chunks: 0`, `phase`: `1-sqlite-no-db`).
+- `POST /v1/query` — тело `{"query":"...", "top_k":8}`; ответ `{"hits":[{"path","snippet","score"}], "phase":"1-sqlite"|"1-sqlite-empty"|"1-sqlite-no-db"}`.
+
+Поиск: **линейный обход** всех векторов в SQLite (MVP; для больших репозиториев планировать Qdrant/sqlite-vec или батчевый ANN).
+
+### Индексация (фаза 1)
+
+```powershell
+cd D:\path\to\claw-code-main\rust
+$env:OPENAI_API_KEY = "sk-..."
+cargo run -p claw-rag-service -- ingest -w D:\path\to\repo --db D:\path\to\index.sqlite
+cargo run -p claw-analog -- ...   # при RAG_BASE_URL или rag_base_url в TOML — инструмент retrieve_context
+```
+
+Переменные окружения:
+
+- **`OPENAI_API_KEY`** или **`CLAW_RAG_OPENAI_API_KEY`** — для вызова `POST …/embeddings`.
+- **`CLAW_RAG_EMBEDDING_BASE_URL`** — по умолчанию `https://api.openai.com/v1`.
+- **`CLAW_RAG_EMBEDDING_MODEL`** — по умолчанию `text-embedding-3-small`.
+- **`CLAW_RAG_DB`** — путь к SQLite (у ingest/`serve`; у `serve` есть default `.claw-rag/index.sqlite`).
+- **`CLAW_RAG_PORT`** — порт HTTP (по умолчанию `8787`).
+- **`CLAW_RAG_MOCK_PROVIDERS=1`** — детерминированные вектора без сети (для тестов CI).
+
+Запуск сервера: `cargo run -p claw-rag-service` или `cargo run -p claw-rag-service -- serve --db path\to\index.sqlite`.
+
+### Дальше по фазам
+
+| Фаза | Содержание |
+|------|------------|
+| 1 | ~~Ingest + SQLite + embeddings~~ (базово сделано; улучшения: инкремент, ANN, Docker-векторка). |
+| 2 | ~~Инструмент `retrieve_context`~~: `RAG_BASE_URL` / `rag_base_url`, `rag_timeout_secs`, `rag_top_k_max` в `.claw-analog.toml`. |
+| 3 | ~~Минимальный UI~~: `GET /` + те же `/v1/*` (дальше: чат, кнопка re-index из UI). |
+
+## Риски и ограничения
+
+- Секреты и PII в индексе; размер индекса и стоимость эмбеддингов.
+- Согласованность с symlink/jail как в `claw-analog` — retrieval не должен «утекать» за пределы workspace.
+- Локаль на UI: i18n отдельно от `AnalogLanguage` в CLI.
+
+## Связанные документы
+
+- Локальный запуск контейнеров (если поднимете векторку): [`container.md`](container.md).
+- Обзор `claw-analog`: [`how_to_run.md`](../how_to_run.md).