# NL→SQL Assistant — архитектура v2 (lean baseline)

**Дата:** 2026-05-10
**Статус:** active baseline (после CX + KM review v1)
**Заменяет:** `01_architecture.md`
**Сопровождает:** `00_task.md`, `03_eval_methodology.md`

> «Lean» здесь = ровно столько компонентов, сколько даёт измеримый сигнал в портфолио
> Senior DE. Всё, что не даёт сигнала или дублирует RAG_Support_Assistant, удалено.
> Каждое решение — следствие конкретной правки CX/KM, см. раздел 13.

---

## 1. Главный сдвиг от v1

**v1 фокус:** «нагруженный pipeline + красивый UI».
**v2 фокус:** «измеримая точность + продуманный retrieval + lean stack».

Сигнал для рекрутёра / собеседующего создаётся:

1. **Ablation-таблицей в README** (см. `03_eval_methodology.md`) — публичные числа,
   которые нельзя получить «скопировав туториал».
2. **Schema retrieval recall как самостоятельной метрикой** — это инженерный
   subproblem, не «прикрутил RAG, посмотрел красивые проценты».
3. **Provider-bakeoff** на 30 вопросах между 3 моделями — превращает «почему Mistral»
   из вкусовщины в *измеримый trade-off*.
4. **Безопасным execution layer** на трёх уровнях, с явным error taxonomy.

Всё остальное (UI, observability, кэш, мульти-БД) — *поддержка*, не *суть*.

## 2. Системная диаграмма (lean)

```text
                        ┌─────────────────────────────────┐
                        │  Web UI (Streamlit или Next.js) │  ← решение в §8
                        │   ─ chat input                  │
                        │   ─ scalar/sentence/table/chart │
                        │   ─ show working                │
                        └────────────┬────────────────────┘
                                     │ HTTPS
                                     ▼
                  ┌──────────────────────────────────────┐
                  │  FastAPI gateway (rate-limit, CORS)  │
                  │  /ask, /databases, /eval/report      │
                  └────────────┬─────────────────────────┘
                               │
       ┌───────────────────────┼───────────────────────┐
       │                       │                       │
       ▼                       ▼                       ▼
 ┌──────────────┐      ┌────────────────┐     ┌───────────────────┐
 │ LangGraph    │      │ Eval harness   │     │ Schema indexer    │
 │ NL→SQL graph │      │ (BIRD Mini-Dev)│     │ (offline pipeline)│
 │ 6 nodes      │      │ + ablation     │     └────────┬──────────┘
 └──────┬───────┘      └────────┬───────┘              │
        │                       │                      │
        ▼                       ▼                      ▼
 ┌─────────────────────────────────────────────────────────────┐
 │              Shared services layer (lean)                    │
 ├──────────────┬──────────────┬─────────────┬────────────────┤
 │ Provider     │ Chroma       │ Postgres /  │ in-memory       │
 │ adapter:     │ schema_chunks│ SQLite      │ LRU cache       │
 │ Mistral /    │ fewshot_qsql │ target DBs  │ (cachetools)    │
 │ frontier /   │              │             │ slowapi rate-lim│
 │ local        │              │             │                 │
 └──────────────┴──────────────┴─────────────┴────────────────┘
                               │
                               ▼
                  ┌──────────────────────────┐
                  │  Langfuse traces only    │
                  └──────────────────────────┘
```

**Удалено vs v1:** Redis (отдельный сервис), Prometheus, OpenTelemetry,
backend history, multi-DB auto-switching как фича, Live `/eval` страница.

**Перенесено:** автогенерация Vega-spec из LLM → детерминированный chart picker.

## 3. LangGraph pipeline (6 узлов)

```text
       ┌─────────────────┐
       │ context_builder │   объединённый retrieve_schema + retrieve_examples
       └────────┬────────┘   + dialect adapter; единый context budget
                │            и единый trace
                ▼
       ┌─────────────────┐
       │ generate_sql    │   codestral-latest, structured output:
       └────────┬────────┘   { "sql": "...", "rationale": "...",
                │              "tables_used": [...], "confidence": 0..1 }
                ▼
       ┌─────────────────┐
       │ validate /      │   sqlglot AST guard (SELECT-only, no DML, whitelist)
       │ repair_once     │   FAIL → ОДИН repair с error-context → fail-fast
       └────────┬────────┘
                │
                ▼
       ┌─────────────────┐
       │ execute         │   read-only role, statement_timeout, LIMIT-cap
       └────────┬────────┘   no EXPLAIN-gate (см. §5)
                │
                ▼
       ┌─────────────────┐
       │ deterministic_  │   100% Python: shape result → scalar/sentence/table/chart
       │ format          │   chart type по heuristics, НЕ LLM
       └────────┬────────┘
                │
                ▼
       ┌─────────────────┐
       │ explain_trace   │   mistral-large-latest: NL caption (≤2 предложения)
       └─────────────────┘   + Langfuse span; persistence — middleware, не node
```

### Изменения от v1 (11 узлов → 6)

| Удалён узел | Почему |
|---|---|
| `classify_intent` | Эвристика по ключевым словам справится; LLM-call расточителен |
| `select_database` | UI даёт explicit DB, auto-select — optional, не часть графа |
| `retrieve_schema` + `retrieve_examples` (отдельные) | Объединены в `context_builder` с единым budget — упрощает trace и instrumentation |
| `static_validate` отдельно | Слит с `repair_once` (один retry-узел) |
| `explain_plan` | Brittle между БД, ломает легитимные тяжёлые запросы; перенесён в optional health-check внутри `execute` |
| `verify_result` retry | Empty result часто *корректен* (e.g. «есть ли заказы у клиента X?»). Retry → wrong-but-executable SQL. Заменено на graceful-degradation (показать результат + diagnostic) |
| `choose_format` отдельно | Детерминированно от result shape, не нужен граф-узел |
| `render_answer` | Слит с `explain_trace`: только NL-caption, рендер — на фронте |
| `persist_trace` | Middleware/span (Langfuse), не node |

### Что добавлено

- **dialect adapter** в `context_builder`: подмешивает Postgres/SQLite-specific
  hints в prompt (DATE_TRUNC vs strftime, JSONB vs JSON1, и т.д.).
- **schema-linking confidence** в structured output `generate_sql` — если
  `confidence < 0.5` или `tables_used` пересекается с retrieved schema <50%,
  поднять флаг для report (не для retry).
- **error taxonomy**: `NoRetrieval`, `InvalidSQL`, `ExecutionTimeout`,
  `EmptyResult`, `LowConfidence`, `RepairFailed` — фиксированное множество для метрик.

### Retry policy

- `validate` → ровно **один** repair pass с error-context. Если второй раз FAIL → fail-fast с diagnostic.
- `execute` syntax/runtime error → тот же repair pass (если ещё не использован).
- **Никаких retry на verify_result.** Empty / sparse result — это валидный исход,
  репортится как `EmptyResult` в error taxonomy.

## 4. Schema-RAG: 2 коллекции (вместо 4)

**Удалено:** `schema_columns` (отдельная коллекция), `relations` (FK через dense search — бесполезно).

**Оставлено:**

| Коллекция | Что в чанке |
|---|---|
| `schema_chunks` | Один чанк = одна таблица: имя + описание + полный список колонок (имена, типы, описания, top-5 sample values, NULL%, nunique) + список FK от/к этой таблице + 1-2 ключевых business-term hints |
| `fewshot_qsql` | Q→SQL пара: вопрос + аннотация интента (SQL не эмбеддится). **Только из train split** — никогда из dev/test (см. `03_eval_methodology.md` §5). |

**FK** хранятся как **deterministic catalog graph** (Python dict в памяти, обновляется при индексации) — после retrieve top-N таблиц делается graph traversal на FK для добавления связных таблиц до budget.

### Почему 2, а не 4

CX обоснование: dense retrieval на FK-связях `from.col → to.col` бесполезен — семантика связи не раскрывается user-вопросом, FK — это структурные метаданные.
KM обоснование: separate `schema_columns` добавляет multi-hop retrieval (table → columns → join) без доказанного прироста; начни с baseline, оптимизируй после ablation.

**Если ablation покажет (см. §6 03_eval_methodology), что 2-коллекционный baseline даёт ≥+5% schema recall@5 при отдельных колонках** — добавим как опцию, но не до измерения.

## 5. Безопасность execution: 3 уровня (без EXPLAIN-gate)

| Уровень | Что | Покрывает |
|---|---|---|
| **DB role** | Postgres user с `SELECT ONLY`, `default_transaction_read_only=on`, `temp_file_limit`, fixed `search_path` | DML, DDL, schema escalation |
| **AST guard (sqlglot)** | SELECT-only, no multi-statement, no DML in CTE, function allowlist (запрет `pg_sleep`, `pg_read_file`, `generate_series` свыше N, `ATTACH` для SQLite, extension load) | Function-level abuse, DoS via SELECT |
| **Runtime** | `statement_timeout=30s`, `idle_in_transaction_session_timeout=10s`, hard `LIMIT 10000` если в SQL нет агрегации, result payload cap 5MB | Long scans, huge payloads |

**Удалён EXPLAIN-gate** (cost > X). Brittle между БД, зависит от планировщика и stats, ломает легитимные тяжёлые аналитические запросы. Заменён на runtime `statement_timeout` (фактический предел) + result-payload cap.

### Acceptable-risk vectors (документированы, не закрыты)

Для read-only solo-demo:
- prompt injection через sample values (включаются в schema chunks из БД)
- `information_schema` / `pg_catalog` чтение (частично whitelist)
- recursive CTE с разумным timeout

Это не SaaS — для портфолио важно показать осознанные trade-off, не максимальную защиту.

## 6. LLM роутинг + provider abstraction

### Модели (переименованы из v1)

| Роль | Модель | Замечание |
|---|---|---|
| SQL generation + repair | `codestral-latest` (Codestral v25.08) | codestral-2501 был deprecated с ноября 2025 |
| NL caption / explain | `mistral-large-latest` | Только в `explain_trace`, не в pipeline |
| Embeddings | `mistral-embed` | Schema chunks + fewshot |
| Intent / format selection | **— (детерминировано Python)** | Ни одной LLM-call для этих задач |

### Provider abstraction (обязательно)

Слой `llm/providers/`:

```python
class LLMProvider(Protocol):
    def complete(self, prompt: str, schema: dict) -> SQLOutput: ...
    def embed(self, texts: list[str]) -> list[list[float]]: ...
    def explain(self, sql: str, result: pd.DataFrame) -> str: ...
```

Реализации: `MistralProvider` (default), `OpenAIProvider`, `OllamaProvider`.
Конфиг — env var `LLM_PROVIDER=mistral|openai|ollama`.

### Bakeoff (артефакт портфолио) — конкретные модели, $0 budget

`eval/bakeoff/` содержит 30 курированных вопросов с эталонными SQL,
прогон через **3 фиксированных провайдера** (зафиксировано 2026-05-10).
**Жёсткое ограничение проекта: $0 external cost.** Только бесплатные тиры.

| Слот | Модель | Где | Стоимость 30 вопросов | Примечание |
|---|---|---|---|---|
| Code-specialized API | `codestral-latest` (Mistral v25.08) | La Plateforme free tier + диск-кэш | $0 (rate-limit-aware + caching) | Default provider |
| Frontier API | `gpt-4o-mini` (или `gpt-4.1-mini`) **через GitHub Models** | `models.inference.ai.azure.com` через GitHub Personal Access Token | $0 (free tier для personal GitHub аккаунтов) | См. §6.6 |
| Local code-specialized | `qwen2.5-coder:7b-instruct` (Ollama, default Q4_K_M ≈ 4.7 GB) | Локально через Ollama | $0 (электричество) | Подходит к 16 GB RAM (комфортный fit с запущенным Postgres+Chroma) |

**Сравнительная таблица в README** — это и есть ответ на «почему не GPT-4». Не идеологический, а измерительный.

**Backup для frontier slot** (если GitHub Models упрётся в daily rate limit или сервис будет недоступен):
- **Google Gemini 2.0 Flash** через Google AI Studio free tier (~1500 req/day, 15 RPM). Truly free, фронтир-class. Ключ создаётся в `aistudio.google.com`.
- Включается через тот же provider adapter, env var `LLM_FRONTIER_PROVIDER=gemini`.

**Опциональные расширения** (для опытов, не в default bakeoff):
- `qwen2.5-coder:14b-instruct` (9.0 GB) — лучше качество, но на 16 GB RAM **тесно**. Включается только при выключенных Postgres/Chroma во время локального прогона. Не годится для combined eval workflow на 16 GB.
- `qwen2.5-coder:32b-instruct` (20 GB) — **не помещается в 16 GB RAM**, не использовать.
- `sqlcoder-7b-2` (defog) — SQL-specialized альтернатива qwen2.5-coder; добавляется одной строкой в `config/providers.yml`. Полезно как secondary local point.

### 6.6 Frontier slot через GitHub Models (детали)

**GitHub Models** (`models.inference.ai.azure.com`) — Microsoft-managed бесплатный API-доступ к premium моделям для personal GitHub аккаунтов.

| Параметр | Значение |
|---|---|
| Endpoint | `https://models.inference.ai.azure.com/chat/completions` |
| Auth | GitHub Personal Access Token (без специальных scope, `read:user` достаточно) |
| Доступные модели (на 2026-05) | `gpt-4o-mini`, `gpt-4o`, `gpt-4.1-mini`, `o1-mini`, `claude-3-5-sonnet`, `meta-llama-3.1-405b-instruct`, и др. |
| SDK | OpenAI-compatible (`openai-python` с `base_url`), либо Azure AI Inference SDK |
| Rate limits | Daily quota per token + per-model RPM (точные числа меняются; на момент фиксации хватало для bakeoff с большим запасом) |

**Provider adapter implementation:**
```python
class GitHubModelsProvider(LLMProvider):
    def __init__(self):
        self.client = OpenAI(
            base_url="https://models.inference.ai.azure.com",
            api_key=os.getenv("GITHUB_TOKEN"),  # PAT
        )
        self.model = os.getenv("GH_MODELS_FRONTIER_MODEL", "gpt-4o-mini")
```

**Преимущество для портфолио:** anyone with a GitHub account может воспроизвести bakeoff бесплатно. Это сильнее «GPT-4 за $20» с точки зрения reproducibility.

**Когда переключаться на Gemini backup:** если GitHub Models показывает 429 или сервис недоступен — переключение через env var, без перезапуска кода. См. §11 risks.

## 6.5. Cost / quota strategy (no account rotation)

**Принципиальная позиция:** ротация Mistral free-tier аккаунтов **не делается**.

Причины:
1. Нарушение Mistral ToS; детекция по payment fingerprint + IP + browser fingerprint + email → бан всей цепочки и flagged email/card на будущее.
2. Negative signal в портфолио: на собеседовании honest-ответ «ротировал аккаунты» = disqualifier для Senior DE.
3. Premise неверный: с aggressive caching и rate-limit-aware throughput free tier покрывает весь dev-цикл.

### Стратегия экономии (вместо ротации)

| Слой | Механизм | Эффект |
|---|---|---|
| Generation cache | `diskcache` на ключ `(provider, model, prompt_hash)` → response | Каждый уникальный prompt идёт в API один раз; повтор тот же запрос → 0 latency, 0 quota. Покрывает повторные ablation-прогонки той же конфигурации. |
| Embedding cache | `diskcache` на `(model, text_hash)` → vector | Schema indexer и fewshot indexer переиндексируют без повторных API-вызовов. |
| CI smoke | `vcr.py` cassette в репо | 5-10 cached examples в CI, 0 live API calls, детерминированный CI. |
| Eval batch throttling | `tenacity` retry + `asyncio.Semaphore(N)` где N = 0.8 × free-tier RPS | Чтобы не упираться в rate-limit на массовом прогоне. |
| Daily quota check | Pre-flight `eval/check_quota.py` | Если приближаемся к daily limit — батч откладывается на следующий день. |

### Реальные цифры расхода

Расчёт для одного полного eval-прогона (BIRD Mini-Dev = 500 примеров, 5 ablation конфигураций):

```
Уникальных generation calls:
  - A (full_schema):  500 (схема одна на БД, prompt уникален per-вопрос)
  - B (BM25 cards):   500
  - C (Chroma cards): 500
  - D (+ fewshot):    500
  - E (+ repair):     500 + ~50-100 repair retries
Total uniq:          ~2600 generation calls

С diskcache при повторных прогонах:
  - Первый прогон конфигурации:  500 calls (full miss)
  - Повторный того же config:    0 calls (full hit)
  - Прогон новой конфигурации:   500 calls (промпт меняется → cache miss)

Embedding calls (one-time индексация):
  - Schema chunks для BIRD ~11 БД: ~200-400 chunks
  - Fewshot pool из BIRD train:    ~9k embeddings (one-time)
```

**Итог:** ~2600 generation + ~9.5k embedding **за весь dev-цикл**. На Mistral free tier с throttling = 1-2 ночные batch-сессии. После cache warm-up любой повторный ablation-прогон = 0 API calls.

### Bakeoff cost (one-time)

30 questions × 3 providers × ~3 000 tokens (prompt+completion, average) ≈ 270 K tokens total.
- Mistral: covered by free tier (La Plateforme).
- Frontier slot via **GitHub Models** (`gpt-4o-mini`): covered by free tier (personal GitHub PAT).
- Local Ollama: $0 (электричество).

Итого external cost проекта: **$0** за весь жизненный цикл portfolio-демо. Это hard constraint.

---

## 7. Целевые БД (реранжированы)

| База | Размер | Роль |
|---|---|---|
| **BIRD Mini-Dev** | 500 Q→SQL, ~11 БД | **Primary eval** — публичный leaderboard, ablation matrix |
| **StackExchange (curated mini)** | gaming.stackexchange.com OR SO 2023-2024 trimmed (~2-5 GB) | **Real-world demo** — 20-30 курированных gold questions с manual review |
| **Chinook** | <10MB | Только smoke / sanity check, не «портфолио-сигнал» |

### Изменения от v1

- BIRD: было «mini, ~1500 Q-SQL, 11 БД» → факт **500 Q-SQL** (см. `WebFetch` подтверждение от bird-bench.github.io).
- StackExchange: «full dump» → curated mini c явным набором gold-вопросов. Full dump = неделя ETL, не нужно.
- Chinook понижен до smoke-only.

### Optional альтернатива (если хочется «вау»)

DuckDB + Parquet с публичным датасетом (HN dump / GH Archive / NYC Taxi) — современный аналитический стек, сильнее сигнал «в тренде DE». Решение откладываем до недели 2; сейчас baseline = Postgres+SQLite.

## 8. UI (узкое решение)

**Решение:** Streamlit для v1 demo, Next.js — *opt-in* если останется неделя в roadmap.

Обоснование:
- Цель проекта = NL→SQL и eval, не frontend.
- Streamlit за 2-3 дня даёт chat + DB switcher + table/chart/scalar/sentence + show-working.
- Next.js — неделя, и сигнал об этом — *frontend skill*, не *DE*.
- Если хочешь именно fullstack-сигнал — Next.js включается на неделе 7+, после того как eval-цифра достигнута.

UI обязан показывать:
- сам ответ (один из 4 форматов),
- SQL с подсветкой и copy-кнопкой,
- блок «show working»: retrieved schema chunks, few-shot, rationale, time, model used,
- error taxonomy при failure: какой именно узел упал.

**Charts:** детерминированный picker на фронте (Plotly или ApexCharts), НИКАКИХ Vega-Lite спек от LLM.

```python
def pick_chart(df: pd.DataFrame, intent_hint: str) -> ChartSpec:
    if df.shape == (1, 1): return ScalarSpec(value=df.iat[0, 0])
    if len(df) > 50:        return TableSpec()
    if has_temporal(df):    return LineSpec(x=temporal_col, y=numeric_cols)
    if 2 <= len(df) <= 12 and is_categorical(df.iloc[:, 0]):
                            return BarSpec(...)
    return TableSpec()
```

LLM генерирует только `intent_hint` (одно слово из enum) + caption.

## 9. Eval — vendored из 03_eval_methodology.md

Полностью описан в `03_eval_methodology.md`. Краткая сводка:

- **Целевые метрики:** Execution Accuracy (primary), Schema Recall@k, SQL Validity Rate, Repair Success Rate, Latency P50/P95, Cost-per-query.
- **Ablation matrix** (5 точек): `full_schema → BM25 cards → Chroma cards → +fewshot → +repair`.
- **Slicing:** by difficulty (BIRD provides), by dialect, by join count, by aggregation type.
- **Train/dev hygiene:** few-shot pool ТОЛЬКО из train; dev запрещён к использованию в few-shot.
- **CI:** unit tests + 5-10 кэшированных smoke-примеров (vcr.py / diskcache). НЕ live API.
- **Nightly/manual:** полный 50/100/500-example прогон с отчётом.
- **Hard checkpoint неделя 3:** EA <35% → scope down (см. roadmap §11).

## 10. Стек (lean)

| Слой | Технология | Замечание |
|---|---|---|
| LLM API | Mistral + OpenAI + Ollama (через provider adapter) | Bakeoff артефакт |
| Orchestration | LangGraph | Тот же что в RAG_SA |
| API | FastAPI + Pydantic v2 | Standard |
| Vector DB | Chroma | 2 коллекции |
| SQL parser | sqlglot | AST guard, dialect translation |
| Target DB | Postgres 16 + SQLite | StackExchange + BIRD/Chinook |
| Cache | `cachetools.LRUCache` (in-memory) + `slowapi` (rate-limit) + `diskcache` для LLM API replay | **БЕЗ Redis** |
| Charting | Plotly + heuristics picker | **БЕЗ Vega-Lite от LLM** |
| Frontend | Streamlit (v1) → Next.js (opt-in) | См. §8 |
| Observability | Langfuse only | **БЕЗ Prometheus + OTel** |
| Eval cache | vcr.py / diskcache | Для CI smoke |
| Tests | pytest + httpx + testcontainers (Postgres) | Без mock в integration tests |
| Lint/Type | ruff + mypy strict (api/, agent/, llm/) | Как в DE_project |
| CI | GitHub Actions | Unit + 5-10 cached smoke + lint |
| Deploy | docker-compose (dev) + single Dockerfile | StackExchange dump в named volume |

## 11. Roadmap (8-10 недель — реалистично)

| # | Этап | Длительность | DoD |
|---|---|---|---|
| 1 | Bootstrap + provider adapter | 0.5 нед | FastAPI hello, Mistral/OpenAI/Ollama providers, тесты на adapter с моком |
| 2 | Target DBs ready | 0.5 нед | Postgres+StackExchange-mini, SQLite+Chinook, BIRD Mini-Dev в `data/` |
| 3 | Schema indexer (2 collections) | 0.5-1 нед | Offline скрипт строит Chroma; smoke-test schema recall@5 |
| 4 | Pipeline v1 (6 узлов) | 1 нед | Граф работает на Chinook + BIRD subset, single-shot |
| 5 | Guards + repair_once | 0.5 нед | sqlglot AST + 3-уровневая защита + error taxonomy |
| 6 | Eval harness + first ablation | 1.5-2 нед | Runner, EA метрика, baseline ablation 5 точек, schema recall |
| 7 | **Hard checkpoint** | gate | EA ≥35% on BIRD Mini-Dev → continue; <35% → scope down (см. §12) |
| 8 | Tuning loop (retrieval + few-shot + prompts) | 2-3 нед | Итеративный — где будет основная боль |
| 9 | Multi-format render + chart picker | 0.5 нед | Heuristics-based, Plotly templates, 4 формата |
| 10 | UI (Streamlit) | 0.5 нед | chat + DB switcher + show-working + history (localStorage) |
| 11 | Bakeoff (3 providers × 30 questions) | 0.5 нед | Сравнительная таблица в README |
| 12 | Polish + deploy + README + demo video | 1 нед | docker-compose, README c ablation+bakeoff, видео 3 мин |

**Итого:** 8.5-11 недель в спокойном темпе или 5-6 в плотном (с риском burnout, см. §13).

## 12. Scope-down protocol (если EA <35% на неделе 3)

Если eval упирается:

1. **Drop BIRD as primary metric** — оставить только StackExchange-mini c 20-30 курированными вопросами + manual review accuracy.
2. **Cut bakeoff** — оставить только Mistral.
3. **Cut Next.js даже если был план** — Streamlit-only.
4. **Сместить фокус** в README с «BIRD execution accuracy» на «безопасное execution + schema retrieval» как core competency.

Это не «провал» — это honest scoping. Senior DE сигнал даёт *показ зрелости в принятии решений*, не «достиг 50% любой ценой».

## 13. Риски (расширенный список после CX/KM)

| Риск | Вероятность | Митигация |
|---|---|---|
| Schema retrieval recall <60% | **высокая** (главный риск accuracy) | Ablation matrix покажет рано; компенсация — расширенные table cards, schema linking узел |
| LLM context overflow на широких БД | средняя | Hard limit retrieved tables + table card compression |
| Benchmark leakage (dev → few-shot) | высокая если не следить | Hard split в indexer: few-shot pool строится **только** из train, тесты на pollution |
| Business semantics gap («active user», «top», «growth») | высокая | Mini-glossary в schema_chunks (1-2 business-term hints на таблицу), документировано в `03_eval_methodology` §7 |
| codestral-latest версия меняется (alias drift) | средняя | Pin конкретный snapshot в bakeoff отчёте, alias — для prod-default |
| Repair-loop делает wrong-but-executable SQL | средняя | Один repair max + confidence flag; metrics: repair success rate vs first-pass accuracy |
| StackExchange ETL — неделя | высокая | Curated mini вместо full dump; gaming.stackexchange как fallback |
| Vega-spec ломается | **N/A в v2** | Удалено |
| Mistral API rate limits на eval | средняя | diskcache на (prompt_hash → response); throttle до 0.8×free-tier RPS; nightly батчем. **Ротация аккаунтов запрещена** (см. §6.5) |
| Local model RAM exhaustion (16 GB OS) | средняя | qwen2.5-coder:7b (4.7 GB) как default; 14b опциально только при выключенных Postgres/Chroma; 32b исключён |
| GitHub Models rate-limit hit на bakeoff | низкая | 30 вопросов под daily limit с большим запасом; backup — Gemini 2.0 Flash через `LLM_FRONTIER_PROVIDER=gemini` (см. §6.6) |
| GitHub Models меняет model availability | низкая-средняя | provider adapter изолирует; смена модели — env var; bakeoff фиксирует snapshot в отчёте |
| Burnout / scope creep | **средняя-высокая** | Hard checkpoint неделя 3; scope-down protocol §12 |

## 14. Что в этой архитектуре «нагруженного» (vs «фейковая нагрузка»)

«Нагруженно, но не фейк» (даёт сигнал):
- LangGraph 6 узлов с error taxonomy + repair loop
- Schema-RAG 2 коллекции с FK graph + dialect adapter
- 3-уровневая защита SQL execution
- Eval harness c ablation matrix + slicing + leakage prevention
- Provider adapter + 30-question bakeoff
- Schema recall@k как самостоятельная метрика

«Фейковая нагрузка для solo-demo» (вырезано в v2):
- Prometheus + OpenTelemetry (Langfuse достаточно)
- Redis (cachetools хватает)
- 4 коллекции Chroma вместо 2
- Vega-Lite spec generation от LLM
- 11-узловой граф с тремя retry-точками
- EXPLAIN-gate
- Backend history + bookmarks
- Multi-DB auto-switching как фича
- Live `/eval` page
- testcontainers everywhere

## 15. Карта решений: какая правка откуда

| v2 решение | Источник | Confidence |
|---|---|---|
| Pipeline 11 → 6 узлов | CX + KM convergent | high |
| Schema-RAG 4 → 2 коллекции | CX + KM convergent | high |
| Drop EXPLAIN-gate | CX + KM convergent | high |
| Drop Prom + OTel + Redis | CX + KM convergent | high |
| Vega-Lite от LLM → детерминированный picker | CX + KM convergent | high |
| Mistral-only → provider adapter + bakeoff | CX + KM convergent | high |
| BIRD Mini-Dev = 500 (factual fix) | CX (verified WebFetch) | factual |
| codestral-2501 → codestral-latest | CX (verified WebFetch) | factual |
| Eval target 50% → 35-40% baseline / 50% stretch | CX (BIRD Mini-Dev leaderboard numbers: GPT-4 = 47.8/40.8/35.8% EX) | high |
| Ablation matrix как central artifact | CX | high |
| Hard checkpoint неделя 3 + scope-down protocol | KM | medium-high |
| Streamlit вместо Next.js (default) | CX + KM | medium |
| Business semantics mini-glossary | CX | medium |
| Benchmark leakage prevention | CX | high |
| Roadmap 5-6 → 8-10 недель | CX + KM convergent | high |
| DuckDB + Parquet альтернатива | KM (optional) | low (на будущее) |