fix bugs

.gitignore

@@ -68,3 +68,7 @@ htmlcov/
 # Outputs
 outputs/
 results/
+
+# Документы ВКР
+*.docx
+*.pptx

Dockerfile

@@ -1,24 +1,43 @@
+# Образ для HuggingFace Spaces (Docker SDK).
+# Запускает оба процесса Ru2SQL в одном контейнере:
+#   - FastAPI на 127.0.0.1:8000 (внутренний)
+#   - Streamlit на 0.0.0.0:7860 (внешний, HF Spaces читает с этого порта)
+# Оркестрирует их scripts/run_app.py.
+
 FROM python:3.12-slim
 
 WORKDIR /app
 
-RUN apt-get update && apt-get install -y \
-    build-essential \
-    curl \
-    git \
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential \
+        curl \
+        git \
     && rm -rf /var/lib/apt/lists/*
 
+# Сначала ставим torch с поддержкой CUDA 12.1 — это нужно для T4 Small на HF.
+# На CPU-окружении этот же torch автоматически работает через CPU-бэкенд.
+RUN pip3 install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cu121
+
 COPY requirements.txt ./
-RUN pip3 install -r requirements.txt
+RUN pip3 install --no-cache-dir -r requirements.txt
 
 COPY . .
 
-ENV LORA_ADAPTER_PATH=Tyycha/qwen-coder-pauq-lora
-ENV BASE_MODEL_NAME=Qwen/Qwen2.5-Coder-3B-Instruct
-ENV DEVICE=cpu
+# Дефолты для HF Spaces. Переписываются Variables/Secrets в настройках Space.
+ENV LORA_ADAPTER_PATH=Tyycha/qwen-coder-pauq-lora \
+    BASE_MODEL_NAME=Qwen/Qwen2.5-Coder-3B-Instruct \
+    DEVICE=cuda \
+    API_HOST=127.0.0.1 \
+    API_PORT=8000 \
+    STREAMLIT_HOST=0.0.0.0 \
+    STREAMLIT_PORT=7860 \
+    RU2SQL_API_URL=http://127.0.0.1:8000
 
 EXPOSE 7860
 
-HEALTHCHECK CMD curl --fail http://localhost:7860/_stcore/health
+# start-period=600s — у первого запуска есть до 10 минут на скачивание модели
+# с HuggingFace. Дальше healthcheck опрашивает Streamlit каждые 30 секунд.
+HEALTHCHECK --interval=30s --timeout=10s --start-period=600s --retries=3 \
+    CMD curl --fail http://localhost:7860/_stcore/health || exit 1
 
-ENTRYPOINT ["streamlit", "run", "streamlit_app.py", "--server.port=7860", "--server.address=0.0.0.0"]
+ENTRYPOINT ["python", "scripts/run_app.py"]

README.md

@@ -12,23 +12,43 @@ pinned: false
 Генеративная модель для преобразования вопросов на русском языке в SQL-запросы.
 Практическая часть ВКР, направление «Программная инженерия», 4 курс.
 
-**Стек:** Python 3.10+, PyTorch, transformers, PEFT (LoRA), FastAPI, sqlglot.
+**Стек:** Python 3.10+, PyTorch, transformers, PEFT (LoRA), FastAPI, Streamlit, sqlglot.
 **Основная модель:** Qwen2.5-Coder-3B-Instruct, дообученная методом QLoRA на датасете PAUQ.
 **Сравнение:** ruT5-base baseline + GigaChat API.
 
-См. `plan_VKR_text2sql_ru.md` для полного плана работ на месяц.
+См. `plan_VKR_text2sql_ru.md` для полного плана работ.
 
 ---
 
-## Быстрый старт (на десктопе)
+## Архитектура
+
+```
+┌─────────────────────┐    HTTP     ┌──────────────────────┐
+│  Streamlit-клиент   │ ─────────►  │   FastAPI REST API   │
+│  (порт 8501)        │             │   (порт 8000)        │
+└─────────────────────┘             └──────────┬───────────┘
+                                               │
+                            ┌──────────────────┼──────────────────┐
+                            ▼                  ▼                  ▼
+                  ┌──────────────────┐ ┌──────────────┐ ┌────────────────┐
+                  │ InferenceEngine  │ │ SchemaProvi- │ │ BusinessVocab- │
+                  │ Qwen + LoRA      │ │ der + Sql-   │ │ ulary (YAML)   │
+                  │                  │ │ Executor     │ │                │
+                  └──────────────────┘ └──────────────┘ └────────────────┘
+```
+
+Streamlit-интерфейс не вызывает модель напрямую — он обращается к REST API
+через `httpx`. Это позволяет запускать UI и инференс на разных машинах,
+а также подключать к API любых сторонних клиентов.
+
+---
+
+## Быстрый старт
 
 ### 1. Установка
 
 ```bash
-# Установи uv (https://docs.astral.sh/uv/) если ещё нет
 pip install uv
-
-# Клонируй репозиторий и установи зависимости
 git clone <твой-репо> ru2sql
 cd ru2sql
 uv venv
@@ -44,36 +64,97 @@ copy .env.example .env          # Windows
 # cp .env.example .env          # Linux/Mac
 ```
 
-Открой `.env` и заполни ключи (минимум `GIGACHAT_API_KEY` для baseline-сравнения, остальное опционально).
+Заполни в `.env`:
+- `BASE_MODEL_NAME` (по умолчанию Qwen/Qwen2.5-Coder-3B-Instruct),
+- `LORA_ADAPTER_PATH` (локальная папка или HF-repo),
+- опционально — API-ключ GigaChat для baseline-сравнения.
+
+Если HuggingFace недоступен из вашей сети, добавь:
+```
+HF_ENDPOINT=https://hf-mirror.com
+```
 
-### 3. Скачай PAUQ
+### 3. Тесты
 
 ```bash
-git clone https://github.com/ai-forever/pauq.git data/pauq_repo
-# Затем разложи train.json/dev.json/test.json в data/pauq/
-# и SQLite-файлы в data/databases/{db_id}/{db_id}.sqlite
+pytest -v
 ```
 
-### 4. Тесты
+Ожидаемо: 80+ зелёных тестов.
 
+### 4. Smoke-проверка
+
+Быстрая (5 сек, без модели):
 ```bash
-pytest -v
+python scripts/smoke_local.py
 ```
 
-Тесты для модулей `prompt`, `postprocess`, `metrics`, `schema` должны проходить
-без скачивания модели и датасета.
+Полная (с загрузкой Qwen, ~5 минут на CPU):
+```bash
+python scripts/smoke_local.py --with-model
+```
 
-### 5. Запуск API
+### 5. Запуск приложения
 
+Нужны **два процесса** — API и UI:
+
+**Окно 1** — REST API:
 ```bash
 uvicorn src.api.main:app --reload
 # Swagger UI: http://127.0.0.1:8000/docs
 ```
 
-При первом запуске модель Qwen2.5-Coder-3B (~6 GB) скачается из HuggingFace Hub.
-На CPU инференс занимает 15–30 секунд на запрос — это ожидаемо.
+**Окно 2** — Streamlit-интерфейс:
+```bash
+streamlit run streamlit_app.py
+# UI: http://127.0.0.1:8501
+```
+
+При первом запуске модель Qwen2.5-Coder-3B (~6 GB) скачивается из HuggingFace
+Hub. На CPU инференс одного запроса занимает 15–30 секунд — это ожидаемо.
+
+Адрес API можно переопределить переменной окружения:
+```bash
+set RU2SQL_API_URL=http://192.168.1.10:8000     # Windows
+# export RU2SQL_API_URL=http://192.168.1.10:8000  # Linux/Mac
+```
+
+---
+
+## REST API
+
+### Базовые эндпоинты
+
+| Метод | Путь | Назначение |
+|---|---|---|
+| GET  | `/health`        | статус сервиса и загруженной модели |
+| GET  | `/databases`     | список БД из data/databases (PAUQ-структура) |
+| POST | `/generate-sql`  | генерация SQL по db_id из PAUQ |
+| POST | `/schema`        | схема произвольной БД по connection string |
+| POST | `/query`         | полный pipeline для произвольной БД |
+
+### Пример: запрос к произвольной БД
+
+```bash
+curl -X POST http://127.0.0.1:8000/query \
+     -H "Content-Type: application/json" \
+     -d '{
+       "question": "Какая выручка за 2026 год?",
+       "connection_string": "sqlite:///data/demo/sales.sqlite",
+       "execute": true,
+       "vocabulary": {
+         "company": "Демо-магазин",
+         "terms": {"выручка": "SUM(orders.amount) WHERE status='paid'"}
+       }
+     }'
+```
+
+Ответ содержит `sql`, `raw_output`, `is_valid_sql`, `gen_time_seconds` и
+опционально `execution` с результатами выполнения. Перед исполнением
+SQL проходит AST-уровневую проверку (см. `is_select_only` в
+`src/models/postprocess.py`) — DDL и DML на БД через API невозможны.
 
-### 6. Запрос к API
+### Пример: PAUQ-режим (старый эндпоинт)
 
 ```bash
 curl -X POST http://127.0.0.1:8000/generate-sql \
@@ -90,7 +171,7 @@ curl -X POST http://127.0.0.1:8000/generate-sql \
 
 Шаги:
 1. Открой `notebooks/kaggle_train_qwen_qlora.ipynb` на kaggle.com.
-2. В Settings выбери Accelerator: GPU T4 x1 (или x2 для скорости).
+2. В Settings выбери Accelerator: GPU T4 x1.
 3. Add-ons → Secrets → добавь `HF_TOKEN` и `WANDB_API_KEY`.
 4. Запусти все ячейки. Тренировка ~4–6 часов.
 5. По завершении адаптер пушится на твой приватный HF-репо.
@@ -109,32 +190,47 @@ curl -X POST http://127.0.0.1:8000/generate-sql \
 
 ```
 ru2sql/
-├── pyproject.toml              # зависимости (uv)
+├── pyproject.toml              # зависимости
 ├── .env.example                # шаблон конфигурации
-├── plan_VKR_text2sql_ru.md     # план работ на месяц
+├── plan_VKR_text2sql_ru.md     # план работ
 ├── notebooks/
 │   └── kaggle_train_qwen_qlora.ipynb
+├── scripts/
+│   └── smoke_local.py          # локальная проверка работоспособности
+├── configs/
+│   ├── example_vocabulary.yaml
+│   └── sales_vocabulary.yaml
 ├── src/
 │   ├── config.py               # настройки через pydantic-settings
 │   ├── data/
 │   │   ├── loader.py           # чтение PAUQ JSON
-│   │   ├── schema.py           # SchemaRetriever (DDL из SQLite)
+│   │   ├── schema_provider.py  # SchemaProvider — единый интерфейс
+│   │   ├── schema.py           # SchemaRetriever (фасад для PAUQ)
 │   │   └── prompt.py           # PromptBuilder + chat-template
+│   ├── db/
+│   │   ├── connector.py        # DbConnector — чтение схем
+│   │   └── executor.py         # SqlExecutor с read-only
+│   ├── business/
+│   │   └── vocabulary.py       # BusinessVocabulary (YAML-конфиг)
 │   ├── models/
 │   │   ├── inference.py        # InferenceEngine (модель + LoRA)
-│   │   └── postprocess.py      # очистка SQL + sqlglot валидация
+│   │   └── postprocess.py      # очистка SQL + guardrail
 │   ├── evaluation/
-│   │   ├── metrics.py          # Exact Match + Execution Accuracy
-│   │   └── evaluate.py         # CLI для прогона на split'е
+│   │   ├── metrics.py          # EM + Execution Accuracy
+│   │   └── evaluate.py         # CLI для прогона на split
 │   └── api/
-│       ├── main.py             # FastAPI app
+│       ├── main.py             # FastAPI app (5 эндпоинтов)
 │       ├── schemas.py          # Pydantic-модели
 │       └── dependencies.py     # lifespan + DI
-└── tests/
+├─�� streamlit_app.py            # UI (HTTPX-клиент к API)
+└── tests/                      # 80+ тестов
     ├── test_prompt.py
     ├── test_postprocess.py
     ├── test_metrics.py
-    └── test_schema.py
+    ├── test_schema.py
+    ├── test_schema_provider.py
+    ├── test_vocabulary.py
+    └── test_db.py
 ```
 
 ---
@@ -153,13 +249,13 @@ python -m src.evaluation.evaluate --split dev --limit 50
 
 ---
 
-## Метрики (планируемые)
+## Метрики
 
 | Модель | EM | Execution Accuracy |
 |---|---|---|
-| ruT5-base (baseline) | 25–35% | 30–40% |
-| **Qwen2.5-Coder-3B + QLoRA** | **50–60%** | **55–70%** |
-| GigaChat API (zero-shot) | 55–70% | 65–80% |
+| ruT5-base (baseline) | 25–35 % | 30–40 % |
+| **Qwen2.5-Coder-3B + QLoRA** | **40,0 %** | **71,9 %** |
+| BRIDGE / RAT-SQL (PAUQ, mono) | 51 / 52 % | 48 / 49 % |
 
 ---
 

adapters/qwen-coder-pauq-lora/README.md

@@ -1,199 +1,136 @@
 ---
-library_name: transformers
-tags: []
+library_name: peft
+base_model: Qwen/Qwen2.5-Coder-3B-Instruct
+language:
+  - ru
+tags:
+  - text-to-sql
+  - qlora
+  - russian
+  - sql-generation
+license: apache-2.0
+datasets:
+  - ai-forever/PAUQ
 ---
 
-# Model Card for Model ID
-
-<!-- Provide a quick summary of what the model is/does. -->
-
-
-
-## Model Details
-
-### Model Description
-
-<!-- Provide a longer summary of what this model is. -->
-
-This is the model card of a 🤗 transformers model that has been pushed on the Hub. This model card has been automatically generated.
-
-- **Developed by:** [More Information Needed]
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
-
-### Model Sources [optional]
-
-<!-- Provide the basic links for the model. -->
-
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
-
-## Uses
-
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
-
-### Direct Use
-
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
-
-[More Information Needed]
-
-### Downstream Use [optional]
-
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
-
-[More Information Needed]
-
-### Out-of-Scope Use
-
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
-
-[More Information Needed]
-
-## Bias, Risks, and Limitations
-
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
-
-[More Information Needed]
-
-### Recommendations
-
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
-
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
-
-## How to Get Started with the Model
-
-Use the code below to get started with the model.
-
-[More Information Needed]
-
-## Training Details
-
-### Training Data
-
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
-
-[More Information Needed]
-
-### Training Procedure
-
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
-
-#### Preprocessing [optional]
-
-[More Information Needed]
-
-
-#### Training Hyperparameters
-
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
-
-#### Speeds, Sizes, Times [optional]
-
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
-
-[More Information Needed]
-
-## Evaluation
-
-<!-- This section describes the evaluation protocols and provides the results. -->
-
-### Testing Data, Factors & Metrics
-
-#### Testing Data
-
-<!-- This should link to a Dataset Card if possible. -->
-
-[More Information Needed]
-
-#### Factors
-
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
-
-[More Information Needed]
-
-#### Metrics
-
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
-
-[More Information Needed]
-
-### Results
-
-[More Information Needed]
-
-#### Summary
-
-
-
-## Model Examination [optional]
-
-<!-- Relevant interpretability work for the model goes here -->
-
-[More Information Needed]
-
-## Environmental Impact
-
-<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
-
-Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
-
-- **Hardware Type:** [More Information Needed]
-- **Hours used:** [More Information Needed]
-- **Cloud Provider:** [More Information Needed]
-- **Compute Region:** [More Information Needed]
-- **Carbon Emitted:** [More Information Needed]
-
-## Technical Specifications [optional]
-
-### Model Architecture and Objective
-
-[More Information Needed]
-
-### Compute Infrastructure
-
-[More Information Needed]
-
-#### Hardware
-
-[More Information Needed]
-
-#### Software
-
-[More Information Needed]
-
-## Citation [optional]
-
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
-
-**BibTeX:**
-
-[More Information Needed]
-
-**APA:**
-
-[More Information Needed]
-
-## Glossary [optional]
-
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
-
-[More Information Needed]
-
-## More Information [optional]
-
-[More Information Needed]
-
-## Model Card Authors [optional]
-
-[More Information Needed]
-
-## Model Card Contact
-
-[More Information Needed]
+# qwen-coder-pauq-lora
+
+LoRA-адаптер для модели **Qwen2.5-Coder-3B-Instruct**, обученный методом
+**QLoRA** на датасете **PAUQ** для задачи преобразования вопросов на
+русском языке в SQL-запросы. Часть выпускной квалификационной работы
+по направлению 09.03.04 «Программная инженерия», КНИТУ-КАИ.
+
+## Описание
+
+Адаптер обучает модель отвечать на русскоязычный аналитический вопрос
+синтаксически корректным SQL-запросом, учитывая схему конкретной базы
+данных, переданную в системном сообщении вместе с примерами строк.
+
+Базовая модель остаётся замороженной, обучаются только LoRA-матрицы
+рангом 16, наложенные на все проекционные слои attention и MLP. Это
+позволяет хранить и распространять адаптер размером несколько десятков
+мегабайт, а не полные веса модели в несколько гигабайт.
+
+## Использование
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+
+base = "Qwen/Qwen2.5-Coder-3B-Instruct"
+adapter = "Tyycha/qwen-coder-pauq-lora"
+
+tokenizer = AutoTokenizer.from_pretrained(base)
+model = AutoModelForCausalLM.from_pretrained(base, device_map="auto")
+model = PeftModel.from_pretrained(model, adapter)
+model.eval()
+
+messages = [
+    {"role": "system", "content": "Ты — ассистент, который преобразует вопросы на русском языке в SQL..."},
+    {"role": "user", "content": "### Schema:\nCREATE TABLE orders (id INT, amount REAL, status TEXT);\n\n### Question:\nКакая суммарная выручка по оплаченным заказам?\n\n### SQL:\n"},
+]
+prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
+output = model.generate(**inputs, max_new_tokens=256, do_sample=False)
+print(tokenizer.decode(output[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True))
+```
+
+Полный pipeline (формирование промпта, постобработка, исполнение SQL)
+реализован в проекте [Ru2SQL](https://github.com/Tyycha/Ru2SQL).
+
+## Данные
+
+- **Датасет:** PAUQ (Bakshandaeva et al., 2022) — первый крупный русскоязычный
+  корпус для задачи Text-to-SQL, построенный на основе Spider.
+- **Размер:** ~7 тыс. пар (вопрос, SQL) в train, 1076 в dev.
+- **Структура примера:** диалог в формате chat-template из трёх сообщений
+  (`system` с инструкцией и опциональным бизнес-словарём, `user` со
+  схемой и вопросом, `assistant` с эталонным SQL).
+
+## Гиперпараметры обучения
+
+| Параметр | Значение |
+|---|---|
+| Базовая модель | Qwen/Qwen2.5-Coder-3B-Instruct |
+| Метод | QLoRA (NF4, double quantization, compute dtype = bfloat16) |
+| LoRA rank `r` | 16 |
+| LoRA alpha | 32 |
+| LoRA dropout | 0.05 |
+| Target modules | q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj |
+| Эпохи | 2 |
+| Размер батча | 1 (на устройство) |
+| Накопление градиентов | 8 шагов (эффективный батч 8) |
+| Скорость обучения | 2e-4 (cosine, warmup 3 %) |
+| Max sequence length | 1024 |
+| Точность | bfloat16 |
+| Оборудование | NVIDIA Tesla T4 16 GB (Kaggle) |
+
+## Метрики
+
+Оценка на валидационной выборке PAUQ (1076 примеров, 166 баз данных):
+
+| Метрика | Значение |
+|---|---|
+| Exact Match (EM) | 40.0 % (430 / 1076) |
+| Execution Accuracy (EX) | 71.9 % (772 / 1074) |
+
+Для сравнения, опубликованные результаты на той же выборке:
+
+| Модель | EM | EX |
+|---|---|---|
+| RAT-SQL (PAUQ, mono) | 51 % | 49 % |
+| BRIDGE (PAUQ, mono) | 52 % | 48 % |
+| **Qwen2.5-Coder-3B + QLoRA (эта работа)** | **40 %** | **71.9 %** |
+
+Высокий разрыв между EM и EX отражает специфику задачи: модель
+генерирует семантически корректные запросы, но синтаксически
+отличающиеся от эталонных (другой порядок условий, альтернативные
+JOIN-стратегии, иные псевдонимы).
+
+## Ограничения
+
+- Модель обучена на схемах PAUQ/Spider. На существенно отличающихся
+  предметных областях качество может падать; для адаптации
+  предусмотрен механизм бизнес-словаря в основном проекте.
+- Наиболее сложные классы запросов — вложенные SELECT, конструкции
+  INTERSECT/EXCEPT/UNION, HAVING с несколькими условиями — остаются
+  слабым местом.
+- При работе на CPU без GPU инференс занимает 15–30 секунд на запрос.
+- Адаптер ориентирован на SQLite. Для PostgreSQL/MySQL рекомендуется
+  явно указать диалект в промпте.
+
+## Лицензия
+
+Apache 2.0. Базовая модель Qwen2.5-Coder также распространяется под
+лицензией Apache 2.0; датасет PAUQ — Apache 2.0.
+
+## Цитирование
+
+```bibtex
+@misc{ru2sql-qlora-2026,
+  title  = {Ru2SQL: Russian Text-to-SQL via QLoRA on Qwen2.5-Coder},
+  author = {Siryazeev, Danis},
+  year   = {2026},
+  note   = {Bachelor's thesis, Kazan National Research Technical University},
+}
+```

evaluate_pauq.py

@@ -0,0 +1,271 @@
+"""
+Скрипт прогона метрик Ru2SQL на валидационной выборке PAUQ.
+
+Считает Exact Match (EM) и Execution Accuracy (EX) для дообученной модели
+Qwen2.5-Coder-3B + QLoRA. Используется на Kaggle (T4 GPU), результат
+сохраняется в eval_results.csv и eval_summary.json.
+
+Источник цифр для раздела 4.3 пояснительной записки.
+
+Использование на Kaggle:
+  1. Загрузить проект целиком (через Kaggle Dataset или git clone).
+  2. Установить ADAPTER_ID на свой HF-репо.
+  3. python evaluate_pauq.py
+
+Постобработка и нормализация SQL импортируются из src/models/postprocess.py,
+чтобы метрики локально и на Kaggle оставались сопоставимыми.
+"""
+
+import sys
+from pathlib import Path
+
+# Делаем пакет src/ импортируемым, когда скрипт запускается из корня.
+_PROJECT_ROOT = Path(__file__).resolve().parent
+if str(_PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(_PROJECT_ROOT))
+
+import csv
+import json
+import sqlite3
+
+from tqdm import tqdm
+
+import torch
+from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
+from peft import PeftModel
+from datasets import load_dataset
+
+from src.models.postprocess import (
+    normalize_sql,
+    strip_model_artifacts as strip_artifacts,
+)
+
+# ─── CONFIG ───────────────────────────────────────────────────────────────────
+
+BASE_MODEL_ID  = "Qwen/Qwen2.5-Coder-3B-Instruct"
+ADAPTER_ID     = "Tyycha/qwen-coder-pauq-lora"
+PAUQ_SPLIT     = "validation"   # 1034 примера
+MAX_NEW_TOKENS = 256
+DEVICE         = "cuda" if torch.cuda.is_available() else "cpu"
+
+# Путь к папке с SQLite-базами PAUQ (Spider databases)
+# На Kaggle: скачай https://drive.google.com/uc?id=1iRDVHLr4mX2wQKSgA9VxUUFpj-3-Kj5B
+# Или используй датасет: kaggle datasets download -d wikisql/spider
+PAUQ_DB_DIR    = Path("./pauq_databases")   # папка, где лежат папки баз данных
+
+# ─── OUTPUT ───────────────────────────────────────────────────────────────────
+
+RESULTS_FILE   = "eval_results.csv"
+SUMMARY_FILE   = "eval_summary.json"
+
+# ─── LOAD MODEL ───────────────────────────────────────────────────────────────
+
+print("Loading model...")
+bnb_config = BitsAndBytesConfig(
+    load_in_4bit=True,
+    bnb_4bit_quant_type="nf4",
+    bnb_4bit_compute_dtype=torch.bfloat16,
+    bnb_4bit_use_double_quant=True,
+)
+
+tokenizer = AutoTokenizer.from_pretrained(BASE_MODEL_ID, trust_remote_code=True)
+base_model = AutoModelForCausalLM.from_pretrained(
+    BASE_MODEL_ID,
+    quantization_config=bnb_config,
+    device_map="auto",
+    trust_remote_code=True
+)
+model = PeftModel.from_pretrained(base_model, ADAPTER_ID)
+model.eval()
+print(f"Model loaded on {DEVICE}")
+
+# ─── SCHEMA RETRIEVER ─────────────────────────────────────────────────────────
+
+def get_schema(db_id: str) -> str:
+    """Extract CREATE TABLE statements from SQLite database."""
+    db_path = PAUQ_DB_DIR / db_id / f"{db_id}.sqlite"
+    if not db_path.exists():
+        return f"-- Database {db_id} not found"
+    
+    conn = sqlite3.connect(str(db_path))
+    cursor = conn.cursor()
+    
+    cursor.execute("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name")
+    tables = [row[0] for row in cursor.fetchall()]
+    
+    schema_parts = []
+    for table in tables:
+        cursor.execute(f"SELECT sql FROM sqlite_master WHERE type='table' AND name=?", (table,))
+        create_sql = cursor.fetchone()
+        if create_sql and create_sql[0]:
+            schema_parts.append(create_sql[0])
+            # Add sample rows
+            try:
+                cursor.execute(f"SELECT * FROM \"{table}\" LIMIT 3")
+                rows = cursor.fetchall()
+                cursor.execute(f"PRAGMA table_info(\"{table}\")")
+                cols = [col[1] for col in cursor.fetchall()]
+                if rows:
+                    schema_parts.append(f"-- Sample data for {table}:")
+                    schema_parts.append("-- " + " | ".join(cols))
+                    for row in rows[:3]:
+                        schema_parts.append("-- " + " | ".join(str(v) for v in row))
+            except Exception:
+                pass
+    
+    conn.close()
+    return "\n\n".join(schema_parts)
+
+# ─── PROMPT BUILDER ───────────────────────────────────────────────────────────
+
+SYSTEM_PROMPT = (
+    "Ты — ассистент, который преобразует вопросы на русском языке в SQL-запросы. "
+    "Отвечай ТОЛЬКО SQL-запросом без объяснений, комментариев и markdown-разметки."
+)
+
+def build_prompt(question: str, schema: str) -> str:
+    user_msg = f"Schema:\n{schema}\n\nQuestion: {question}\n\nSQL:"
+    messages = [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user",   "content": user_msg},
+    ]
+    return tokenizer.apply_chat_template(
+        messages, tokenize=False, add_generation_prompt=True
+    )
+
+# ─── SQL POSTPROCESSING ───────────────────────────────────────────────────────
+# strip_artifacts и normalize_sql импортируются из src/models/postprocess.py
+# для гарантии того, что метрики на Kaggle и в локальных тестах считаются
+# по одной и той же логике.
+
+# ─── EXECUTION ────────────────────────────────────────────────────────────────
+
+def execute_sql(sql: str, db_id: str):
+    """Execute SQL and return result set as frozenset of tuples."""
+    db_path = PAUQ_DB_DIR / db_id / f"{db_id}.sqlite"
+    if not db_path.exists():
+        return None
+    try:
+        uri = f"file:{db_path}?mode=ro"
+        conn = sqlite3.connect(uri, uri=True)
+        cursor = conn.cursor()
+        cursor.execute(sql)
+        rows = cursor.fetchall()
+        conn.close()
+        return frozenset(tuple(str(v) for v in row) for row in rows)
+    except Exception:
+        return None
+
+# ─── INFERENCE ────────────────────────────────────────────────────────────────
+
+def generate_sql(question: str, schema: str) -> str:
+    prompt = build_prompt(question, schema)
+    inputs = tokenizer(prompt, return_tensors="pt").to(DEVICE)
+    
+    with torch.no_grad():
+        outputs = model.generate(
+            **inputs,
+            max_new_tokens=MAX_NEW_TOKENS,
+            do_sample=False,
+            temperature=1.0,
+            pad_token_id=tokenizer.eos_token_id,
+        )
+    
+    generated = tokenizer.decode(outputs[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True)
+    return strip_artifacts(generated)
+
+# ─── MAIN EVALUATION LOOP ─────────────────────────────────────────────────────
+
+def main():
+    print(f"Loading PAUQ {PAUQ_SPLIT} split...")
+    dataset = load_dataset("ai-forever/PAUQ", split=PAUQ_SPLIT)
+    print(f"Loaded {len(dataset)} examples")
+    
+    results = []
+    em_correct = 0
+    ex_correct = 0
+    ex_total   = 0  # only count where execution was possible
+    
+    with open(RESULTS_FILE, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=[
+            "idx", "db_id", "question", "gold_sql", "pred_sql",
+            "em", "ex", "error"
+        ])
+        writer.writeheader()
+        
+        for idx, example in enumerate(tqdm(dataset, desc="Evaluating")):
+            question  = example.get("question_ru") or example.get("question", "")
+            gold_sql  = example.get("query", "")
+            db_id     = example.get("db_id", "")
+            
+            try:
+                schema   = get_schema(db_id)
+                pred_sql = generate_sql(question, schema)
+                
+                # Exact Match
+                norm_pred = normalize_sql(pred_sql)
+                norm_gold = normalize_sql(gold_sql)
+                em = int(norm_pred == norm_gold)
+                
+                # Execution Accuracy
+                pred_result = execute_sql(pred_sql, db_id)
+                gold_result = execute_sql(gold_sql, db_id)
+                
+                if gold_result is not None:
+                    ex = int(pred_result == gold_result)
+                    ex_correct += ex
+                    ex_total   += 1
+                else:
+                    ex = None
+                
+                em_correct += em
+                error = ""
+                
+            except Exception as e:
+                pred_sql = ""
+                em = 0
+                ex = None
+                error = str(e)[:200]
+            
+            row = {
+                "idx": idx, "db_id": db_id, "question": question,
+                "gold_sql": gold_sql, "pred_sql": pred_sql,
+                "em": em, "ex": ex, "error": error
+            }
+            writer.writerow(row)
+            results.append(row)
+            
+            # Progress every 100 examples
+            if (idx + 1) % 100 == 0:
+                cur_em = em_correct / (idx + 1)
+                cur_ex = ex_correct / max(ex_total, 1)
+                print(f"[{idx+1}/{len(dataset)}] EM={cur_em:.3f}  EX={cur_ex:.3f}")
+    
+    # Final summary
+    n = len(dataset)
+    final_em = em_correct / n
+    final_ex = ex_correct / max(ex_total, 1)
+    
+    summary = {
+        "model": ADAPTER_ID,
+        "split": PAUQ_SPLIT,
+        "n_examples": n,
+        "exact_match": round(final_em, 4),
+        "execution_accuracy": round(final_ex, 4),
+        "em_correct": em_correct,
+        "ex_correct": ex_correct,
+        "ex_total": ex_total
+    }
+    
+    with open(SUMMARY_FILE, "w", encoding="utf-8") as f:
+        json.dump(summary, f, ensure_ascii=False, indent=2)
+    
+    print("\n" + "="*50)
+    print(f"RESULTS on PAUQ {PAUQ_SPLIT} ({n} examples)")
+    print(f"  Exact Match (EM):          {final_em:.1%}  ({em_correct}/{n})")
+    print(f"  Execution Accuracy (EX):   {final_ex:.1%}  ({ex_correct}/{ex_total})")
+    print(f"\nDetailed results saved to: {RESULTS_FILE}")
+    print(f"Summary saved to:          {SUMMARY_FILE}")
+
+if __name__ == "__main__":
+    main()

scripts/run_app.py

@@ -0,0 +1,113 @@
+"""Лаунчер двух процессов Ru2SQL: FastAPI + Streamlit.
+
+Запуск:
+    python scripts/run_app.py
+
+Скрипт стартует uvicorn в фоне, ждёт пока /health начнёт отвечать
+(модель Qwen может качаться 5–10 минут при первом запуске), и
+поднимает Streamlit как основной процесс. По Ctrl+C корректно
+останавливает оба.
+
+Полезно при разработке и для демо на защите: один Ctrl+C — и оба
+процесса завершены, не нужно искать висящий uvicorn в taskmgr.
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import httpx
+
+ROOT = Path(__file__).resolve().parent.parent
+API_HOST = os.environ.get("API_HOST", "127.0.0.1")
+API_PORT = int(os.environ.get("API_PORT", "8000"))
+STREAMLIT_PORT = int(os.environ.get("STREAMLIT_PORT", "8501"))
+# Streamlit слушает 0.0.0.0 в контейнере (нужен внешний доступ),
+# а локально по умолчанию 127.0.0.1 — это управляется отдельной переменной.
+STREAMLIT_HOST = os.environ.get("STREAMLIT_HOST", "127.0.0.1")
+API_URL = f"http://{API_HOST}:{API_PORT}"
+WAIT_API_SECONDS = 600   # модель скачивается долго
+
+
+def wait_for_api(timeout: int) -> bool:
+    """Опрашиваем /health, пока не получим 200 или не выйдет timeout."""
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        try:
+            r = httpx.get(f"{API_URL}/health", timeout=2.0)
+            if r.status_code == 200:
+                return True
+        except Exception:
+            pass
+        time.sleep(1.5)
+    return False
+
+
+def main():
+    print(f"[run_app] корень проекта: {ROOT}")
+    print(f"[run_app] стартую uvicorn на {API_URL}")
+
+    creation_flags = 0
+    if sys.platform == "win32":
+        creation_flags = subprocess.CREATE_NEW_PROCESS_GROUP
+
+    uvicorn_proc = subprocess.Popen(
+        [
+            sys.executable, "-m", "uvicorn", "src.api.main:app",
+            "--host", API_HOST,
+            "--port", str(API_PORT),
+        ],
+        cwd=str(ROOT),
+        creationflags=creation_flags,
+    )
+
+    try:
+        print(f"[run_app] жду готовности API ({WAIT_API_SECONDS} сек макс) — "
+              "при первом запуске Qwen качается с HuggingFace")
+        if not wait_for_api(WAIT_API_SECONDS):
+            print("[run_app] API не поднялся за отведённое время. Проверь логи uvicorn.")
+            uvicorn_proc.terminate()
+            sys.exit(1)
+        print(f"[run_app] API готов, стартую Streamlit на http://{STREAMLIT_HOST}:{STREAMLIT_PORT}")
+
+        env = os.environ.copy()
+        env["RU2SQL_API_URL"] = API_URL
+        streamlit_cmd = [
+            sys.executable, "-m", "streamlit", "run", "streamlit_app.py",
+            "--server.port", str(STREAMLIT_PORT),
+            "--server.address", STREAMLIT_HOST,
+        ]
+        streamlit_proc = subprocess.Popen(streamlit_cmd, cwd=str(ROOT), env=env)
+
+        # Главный цикл — ждём, пока streamlit или uvicorn не упадёт
+        try:
+            while True:
+                if uvicorn_proc.poll() is not None:
+                    print("[run_app] uvicorn завершился, останавливаю streamlit")
+                    streamlit_proc.terminate()
+                    break
+                if streamlit_proc.poll() is not None:
+                    print("[run_app] streamlit завершился, останавливаю uvicorn")
+                    break
+                time.sleep(1.0)
+        except KeyboardInterrupt:
+            print("\n[run_app] Ctrl+C получен, завершаю процессы…")
+            streamlit_proc.terminate()
+    finally:
+        try:
+            uvicorn_proc.terminate()
+            uvicorn_proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            uvicorn_proc.kill()
+        except Exception:
+            pass
+        print("[run_app] оба процесса остановлены")
+
+
+if __name__ == "__main__":
+    main()

scripts/smoke_local.py

@@ -0,0 +1,272 @@
+"""Локальный smoke-тест работоспособности Ru2SQL.
+
+Прогоняет ключевые слои без поднятия Streamlit/FastAPI как отдельных
+процессов. Покрывает: импорты, demo-базу, vocabulary, prompt,
+постобработку, guardrail, новый API через FastAPI TestClient и
+опционально — короткий инференс реальной модели.
+
+Запуск:
+    python scripts/smoke_local.py
+    python scripts/smoke_local.py --with-model    # медленно, грузит Qwen
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT))
+
+GREEN = "\033[32m"
+RED = "\033[31m"
+YELLOW = "\033[33m"
+RESET = "\033[0m"
+
+results: list[tuple[str, str, str]] = []
+
+
+def check(name: str):
+    def decorator(fn):
+        try:
+            t0 = time.time()
+            fn()
+            dt = time.time() - t0
+            results.append(("OK", name, f"{dt*1000:.0f} мс"))
+        except Exception as e:
+            results.append(("FAIL", name, f"{type(e).__name__}: {e}"))
+        return fn
+    return decorator
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Слой 1 — импорты, конфиг
+# ──────────────────────────────────────────────────────────────────────
+@check("Импорты ядра")
+def _():
+    from src.config import settings
+    from src.api.schemas import GenerateRequest, QueryRequest, SchemaRequest
+    from src.business.vocabulary import BusinessVocabulary
+    from src.data.prompt import build_chat_messages, BASE_SYSTEM_PROMPT
+    from src.data.schema_provider import (
+        SpiderSchemaProvider, ConnectionSchemaProvider, TableSchema,
+    )
+    from src.db.connector import DbConnector
+    from src.db.executor import SqlExecutor
+    from src.models.postprocess import postprocess, is_select_only, is_valid_sql
+    assert settings.base_model_name.startswith("Qwen")
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Слой 2 — демо-база и read-only guardrail
+# ──────────────────────────────────────────────────────────────────────
+@check("Демо-база sales.sqlite: подключение и схема")
+def _():
+    from src.db.connector import DbConnector
+    db = ROOT / "data" / "demo" / "sales.sqlite"
+    assert db.exists(), f"Не найден файл {db} — запусти data/demo/create_demo_db.py"
+    conn = DbConnector(str(db))
+    tables = conn.list_tables()
+    assert set(tables) == {"customers", "managers", "products", "orders", "order_items"}
+
+
+@check("Демо-база: реальный SELECT выручки")
+def _():
+    from src.db.executor import SqlExecutor
+    ex = SqlExecutor(str(ROOT / "data" / "demo" / "sales.sqlite"))
+    res = ex.run("SELECT SUM(amount) FROM orders WHERE status='paid'")
+    assert res.success, res.error
+    assert res.rows[0][0] > 0
+
+
+@check("Read-only guardrail: DELETE отклоняется драйвером")
+def _():
+    from src.db.executor import SqlExecutor
+    ex = SqlExecutor(str(ROOT / "data" / "demo" / "sales.sqlite"))
+    res = ex.run("DELETE FROM orders")
+    assert not res.success
+    assert ex.run("SELECT COUNT(*) FROM orders").rows[0][0] == 120
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Слой 3 — BusinessVocabulary из YAML
+# ──────────────────────────────────────────────────────────────────────
+@check("BusinessVocabulary из configs/example_vocabulary.yaml")
+def _():
+    from src.business.vocabulary import BusinessVocabulary
+    vocab = BusinessVocabulary.from_yaml(ROOT / "configs" / "example_vocabulary.yaml")
+    assert bool(vocab)
+    assert "выручка" in vocab.terms
+    assert "SUM(orders.amount)" in vocab.render_system_context()
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Слой 4 — PromptBuilder с реальной схемой и словарём
+# ──────────────────────────────────────────────────────────────────────
+@check("PromptBuilder: vocabulary уходит в system, не в user")
+def _():
+    from src.business.vocabulary import BusinessVocabulary
+    from src.data.prompt import build_chat_messages
+    from src.db.connector import DbConnector
+    vocab = BusinessVocabulary.from_yaml(ROOT / "configs" / "example_vocabulary.yaml")
+    schema = DbConnector(str(ROOT / "data" / "demo" / "sales.sqlite")).render_schema()
+    msgs = build_chat_messages(schema, "Какая выручка за 2026 год?", vocabulary=vocab)
+    assert "SUM(orders.amount)" in msgs[0]["content"]
+    assert "SUM(orders.amount)" not in msgs[1]["content"]
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Слой 5 — постобработка и guardrail
+# ──────────────────────────────────────────────────────────────────────
+@check("Постобработка: markdown, префиксы, truncated, мусор")
+def _():
+    from src.models.postprocess import postprocess, is_select_only
+    cases = [
+        ("```sql\nSELECT 1;\n```", lambda s: s.upper().startswith("SELECT")),
+        ("Ответ: SELECT name FROM customers;", lambda s: s.startswith("SELECT name")),
+        ("SELECT * FROM orders WHERE", lambda s: s == ""),
+        ("просто текст без SQL", lambda s: s == ""),
+    ]
+    for raw, ok in cases:
+        assert ok(postprocess(raw)), f"Сбой на: {raw!r} → {postprocess(raw)!r}"
+    assert is_select_only("SELECT 1") is True
+    assert is_select_only("DROP TABLE x") is False
+    assert is_select_only("DELETE FROM x") is False
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Слой 6 — FastAPI через TestClient с замоканным InferenceEngine
+# ──────────────────────────────────────────────────────────────────────
+@check("FastAPI: /health, /schema, /query с подменённым engine")
+def _():
+    try:
+        from fastapi.testclient import TestClient
+    except ImportError:
+        raise AssertionError("Поставь fastapi[all] или httpx — TestClient недоступен")
+
+    from src.api import dependencies as deps
+    from src.api.main import app
+    from src.models.inference import GenerationResult
+
+    class FakeEngine:
+        loaded = True
+        base_model_name = "Qwen/Qwen2.5-Coder-3B-Instruct"
+        def generate(self, schema, question, vocabulary=None, **kw):
+            # Эмулируем валидный SQL — pipeline должен пропустить через guardrail.
+            sql = "SELECT SUM(amount) FROM orders WHERE status = 'paid'"
+            return GenerationResult(sql=sql, raw_output=sql)
+
+    app.dependency_overrides[deps.get_engine] = lambda: FakeEngine()
+    try:
+        with TestClient(app) as client:
+            # /health
+            r = client.get("/health")
+            assert r.status_code == 200
+            assert r.json()["model_loaded"] is True
+
+            # /schema на реальной demo-базе
+            db_path = ROOT / "data" / "demo" / "sales.sqlite"
+            r = client.post("/schema", json={
+                "connection_string": str(db_path),
+                "include_samples": True,
+            })
+            assert r.status_code == 200, r.text
+            tables = r.json()["tables"]
+            assert {t["name"] for t in tables} == {
+                "customers", "managers", "products", "orders", "order_items"
+            }
+
+            # /query на реальной demo-базе, FakeEngine отдаст валидный SELECT
+            r = client.post("/query", json={
+                "question": "Какая выручка за оплаченные заказы?",
+                "connection_string": str(db_path),
+                "execute": True,
+                "vocabulary": {
+                    "company": "Демо",
+                    "terms": {"выручка": "SUM(amount) WHERE status='paid'"},
+                },
+            })
+            assert r.status_code == 200, r.text
+            body = r.json()
+            assert body["is_valid_sql"] is True
+            assert body["execution"] is not None
+            assert body["execution"]["rows"][0][0] > 0
+
+            # /query с DELETE — должен быть отбит guardrail'ом
+            class DropEngine(FakeEngine):
+                def generate(self, *a, **kw):
+                    return GenerationResult(
+                        sql="DELETE FROM orders WHERE id=1",
+                        raw_output="DELETE FROM orders WHERE id=1",
+                    )
+            app.dependency_overrides[deps.get_engine] = lambda: DropEngine()
+            r = client.post("/query", json={
+                "question": "Удали заказ 1",
+                "connection_string": str(db_path),
+                "execute": True,
+            })
+            assert r.status_code == 200, r.text
+            body = r.json()
+            assert body["execution"] is None
+            assert body["error"] and "гвардейл" in body["error"].lower()
+    finally:
+        app.dependency_overrides.clear()
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Слой 7 — опциональный инференс реальной модели
+# ──────────────────────────────────────────────────────────────────────
+def run_model_smoke():
+    @check("InferenceEngine: загрузка модели и одна генерация")
+    def _():
+        from src.business.vocabulary import BusinessVocabulary
+        from src.db.connector import DbConnector
+        from src.models.inference import InferenceEngine
+
+        engine = InferenceEngine()
+        engine.load()
+        assert engine.loaded
+        schema = DbConnector(str(ROOT / "data" / "demo" / "sales.sqlite")).render_schema()
+        vocab = BusinessVocabulary.from_yaml(ROOT / "configs" / "example_vocabulary.yaml")
+        res = engine.generate(schema, "Какая суммарная выручка за 2026 год?", vocab)
+        assert res.sql and res.sql.upper().startswith("SELECT"), \
+            f"Модель вернула: {res.raw_output!r}"
+
+
+# ──────────────────────────────────────────────────────────────────────
+# main
+# ──────────────────────────────────────────────────────────────────────
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--with-model", action="store_true",
+        help="Дополнительно прогнать реальный инференс Qwen (медленно, ~30 сек на CPU)",
+    )
+    args = parser.parse_args()
+
+    if args.with_model:
+        run_model_smoke()
+
+    print()
+    print("=" * 64)
+    print("Smoke-проверка Ru2SQL")
+    print("=" * 64)
+    for status, name, info in results:
+        color = GREEN if status == "OK" else RED
+        mark = "✓" if status == "OK" else "✗"
+        print(f"  {color}{mark}{RESET} {name}  {YELLOW}[{info}]{RESET}")
+    ok = sum(1 for s, _, _ in results if s == "OK")
+    print("=" * 64)
+    summary_color = GREEN if ok == len(results) else RED
+    print(f"  {summary_color}{ok} / {len(results)} проверок пройдено{RESET}")
+    print("=" * 64)
+    if ok < len(results):
+        print()
+        print("Подсказка: запусти 'pytest -v' для подробных диагностик.")
+    sys.exit(0 if ok == len(results) else 1)
+
+
+if __name__ == "__main__":
+    main()

src/api/main.py

@@ -3,11 +3,21 @@
 Запуск:
     uvicorn src.api.main:app --reload
     # Swagger UI: http://127.0.0.1:8000/docs
+
+Эндпоинты:
+    GET  /health           — статус сервиса и загруженной модели
+    GET  /databases        — список БД из data/databases (PAUQ-структура)
+    POST /generate-sql     — генерация SQL по db_id из PAUQ
+    POST /schema           — схема произвольной БД по connection string
+    POST /query            — полный pipeline для произвольной БД
+                              (генерация + опциональное исполнение + guardrail)
 """
 
 from __future__ import annotations
 
+import logging
 import sqlite3
+import time
 
 from fastapi import Depends, FastAPI, HTTPException
 from fastapi.concurrency import run_in_threadpool
@@ -19,29 +29,59 @@ from src.api.schemas import (
     GenerateRequest,
     GenerateResponse,
     HealthResponse,
+    QueryRequest,
+    QueryResponse,
+    SchemaRequest,
+    SchemaResponse,
+    TablePayload,
+    ColumnPayload,
 )
+from src.business.vocabulary import BusinessVocabulary
 from src.config import settings
 from src.data.schema import SchemaRetriever
+from src.data.schema_provider import ConnectionSchemaProvider
+from src.db.executor import SqlExecutor
 from src.models.inference import InferenceEngine
-from src.models.postprocess import is_valid_sql
+from src.models.postprocess import is_select_only, is_valid_sql
+
+logger = logging.getLogger(__name__)
 
 app = FastAPI(
     title="ru2sql",
     description="Преобразование вопросов на русском в SQL-запросы",
-    version="0.1.0",
+    version="0.2.0",
     lifespan=lifespan,
 )
 
 
+# ──────────────────────────────────────────────────────────────────────
+# Базовые эндпоинты
+# ──────────────────────────────────────────────────────────────────────
+
 @app.get("/health", response_model=HealthResponse)
 def health(engine: InferenceEngine = Depends(get_engine)):
     return HealthResponse(
         status="ok",
-        model_loaded=engine._loaded,
+        model_loaded=engine.loaded,
         base_model=engine.base_model_name,
     )
 
 
+@app.post("/warmup")
+async def warmup(engine: InferenceEngine = Depends(get_engine)):
+    """Прогревает модель одной короткой генерацией.
+
+    Первый инференс холодной модели на CPU сильно дольше последующих:
+    подгружаются LoRA-слои, формируется граф вычислений, заполняется
+    KV-кеш. Вызов /warmup делает один маленький проход с минимальным
+    max_new_tokens, чтобы боевой /query шёл уже по прогретой модели.
+    """
+    t0 = time.time()
+    schema = "CREATE TABLE t (id INT);"
+    await run_in_threadpool(engine.generate, schema, "SELECT id", None, 16)
+    return {"warmup_seconds": round(time.time() - t0, 2)}
+
+
 @app.get("/databases", response_model=list[DatabaseInfo])
 def list_databases(retriever: SchemaRetriever = Depends(get_schema_retriever)):
     out: list[DatabaseInfo] = []
@@ -54,21 +94,33 @@ def list_databases(retriever: SchemaRetriever = Depends(get_schema_retriever)):
     return out
 
 
+# ──────────────────────────────────────────────────────────────────────
+# PAUQ-сценарий (старый эндпоинт, оставлен для совместимости)
+# ──────────────────────────────────────────────────────────────────────
+
 @app.post("/generate-sql", response_model=GenerateResponse)
 async def generate_sql(
     req: GenerateRequest,
     engine: InferenceEngine = Depends(get_engine),
     retriever: SchemaRetriever = Depends(get_schema_retriever),
 ):
+    """Генерация SQL для базы из PAUQ-структуры (data/databases/{db_id})."""
     try:
         schema_text = retriever.render_schema(req.db_id)
     except FileNotFoundError as e:
         raise HTTPException(status_code=404, detail=str(e)) from e
 
-    # Inference синхронный и тяжёлый — выносим в threadpool
-    result = await run_in_threadpool(engine.generate, schema_text, req.question)
+    vocab = (
+        BusinessVocabulary.from_dict(req.vocabulary.model_dump())
+        if req.vocabulary
+        else None
+    )
 
+    result = await run_in_threadpool(
+        engine.generate, schema_text, req.question, vocab
+    )
     valid = is_valid_sql(result.sql)
+
     response = GenerateResponse(
         sql=result.sql,
         raw_output=result.raw_output,
@@ -76,9 +128,15 @@ async def generate_sql(
     )
 
     if req.execute and valid:
+        if not is_select_only(result.sql):
+            response.error = (
+                "SQL отклонён гвардейлом: разрешены только запросы SELECT и WITH."
+            )
+            logger.warning("Guardrail отклонил SQL: %r", result.sql[:120])
+            return response
         try:
             response.execution = await run_in_threadpool(
-                _execute_sql, req.db_id, result.sql, retriever
+                _execute_sql_pauq, req.db_id, result.sql, retriever
             )
         except sqlite3.Error as e:
             response.error = f"SQL execution error: {e}"
@@ -86,7 +144,7 @@ async def generate_sql(
     return response
 
 
-def _execute_sql(db_id: str, sql: str, retriever: SchemaRetriever) -> ExecutionResult:
+def _execute_sql_pauq(db_id: str, sql: str, retriever: SchemaRetriever) -> ExecutionResult:
     db_path = retriever.db_path(db_id)
     conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True)
     try:
@@ -95,16 +153,102 @@ def _execute_sql(db_id: str, sql: str, retriever: SchemaRetriever) -> ExecutionR
         cur.execute(sql)
         rows = cur.fetchmany(100)
         cols = [d[0] for d in cur.description] if cur.description else []
-        return ExecutionResult(
-            columns=cols,
-            rows=[list(r) for r in rows],
-            row_count=len(rows),
-        )
+        return ExecutionResult(columns=cols, rows=[list(r) for r in rows], row_count=len(rows))
     finally:
         conn.close()
 
 
+# ──────────────────────────────────────────────────────────────────────
+# Произвольная БД по connection string — новый сценарий для Streamlit
+# ──────────────────────────────────────────────────────────────────────
+
+@app.post("/schema", response_model=SchemaResponse)
+async def get_schema(req: SchemaRequest):
+    """Возвращает схему произвольной БД для отображения в клиенте."""
+    try:
+        provider = ConnectionSchemaProvider(req.connection_string)
+        tables = await run_in_threadpool(provider.get_tables, 2 if req.include_samples else 0)
+    except Exception as e:  # noqa: BLE001
+        raise HTTPException(status_code=400, detail=f"Ошибка чтения схемы: {e}") from e
+
+    payload = [
+        TablePayload(
+            name=t.name,
+            columns=[
+                ColumnPayload(
+                    name=c.name, type=c.type,
+                    nullable=c.nullable, primary_key=c.primary_key,
+                )
+                for c in t.columns
+            ],
+            sample_rows=[list(r) for r in t.sample_rows],
+            ddl=t.to_ddl(),
+        )
+        for t in tables
+    ]
+    return SchemaResponse(tables=payload)
+
+
+@app.post("/query", response_model=QueryResponse)
+async def query(
+    req: QueryRequest,
+    engine: InferenceEngine = Depends(get_engine),
+):
+    """Полный pipeline: вопрос → SQL → опциональное исполнение на БД.
+
+    В отличие от /generate-sql, работает с произвольной БД по connection
+    string. Используется Streamlit-клиентом и сторонними интеграциями.
+    Перед выполнением SQL проходит проверку is_select_only (раздел 4.4).
+    """
+    # 1. Схема целевой БД
+    try:
+        provider = ConnectionSchemaProvider(req.connection_string)
+        schema_text = await run_in_threadpool(provider.render_schema, True)
+    except Exception as e:  # noqa: BLE001
+        raise HTTPException(status_code=400, detail=f"Ошибка подключения к БД: {e}") from e
+
+    vocab = (
+        BusinessVocabulary.from_dict(req.vocabulary.model_dump())
+        if req.vocabulary
+        else None
+    )
+
+    # 2. Инференс
+    t0 = time.time()
+    result = await run_in_threadpool(engine.generate, schema_text, req.question, vocab)
+    gen_time = time.time() - t0
+
+    valid = is_valid_sql(result.sql)
+    response = QueryResponse(
+        sql=result.sql,
+        raw_output=result.raw_output,
+        is_valid_sql=valid,
+        gen_time_seconds=round(gen_time, 2),
+    )
+
+    # 3. Опциональное исполнение
+    if req.execute and valid:
+        if not is_select_only(result.sql):
+            response.error = (
+                "SQL отклонён гвардейлом: разрешены ��олько запросы SELECT и WITH."
+            )
+            logger.warning("Guardrail отклонил SQL: %r", result.sql[:120])
+            return response
+        try:
+            executor = SqlExecutor(req.connection_string)
+            qr = await run_in_threadpool(executor.run, result.sql)
+            if qr.success:
+                response.execution = ExecutionResult(
+                    columns=qr.columns, rows=qr.rows, row_count=qr.row_count,
+                )
+            else:
+                response.error = f"SQL execution error: {qr.error}"
+        except Exception as e:  # noqa: BLE001
+            response.error = f"SQL execution error: {e}"
+
+    return response
+
+
 if __name__ == "__main__":
     import uvicorn
-
     uvicorn.run("src.api.main:app", host=settings.api_host, port=settings.api_port, reload=True)

src/api/schemas.py

@@ -5,10 +5,30 @@ from __future__ import annotations
 from pydantic import BaseModel, Field
 
 
+class VocabularyPayload(BaseModel):
+    """Бизнес-словарь в формате, согласованном с BusinessVocabulary.from_dict.
+
+    Передаётся клиентом опционально в запросе на генерацию SQL. Если поле
+    отсутствует — модель работает без специальных бизнес-определений.
+    """
+    company: str = ""
+    terms: dict[str, str] = Field(default_factory=dict)
+    filters: dict[str, str] = Field(default_factory=dict)
+    notes: list[str] = Field(default_factory=list)
+
+
+# ──────────────────────────────────────────────────────────────────────
+# /generate-sql — старый эндпоинт для PAUQ-структуры (databases_dir + db_id)
+# ──────────────────────────────────────────────────────────────────────
+
 class GenerateRequest(BaseModel):
     question: str = Field(..., min_length=1, max_length=2000, description="Вопрос на русском")
     db_id: str = Field(..., min_length=1, description="Идентификатор БД из PAUQ")
     execute: bool = Field(default=False, description="Прогнать сгенерированный SQL на БД")
+    vocabulary: VocabularyPayload | None = Field(
+        default=None,
+        description="Опциональный бизнес-словарь компании (см. раздел 3.6 ВКР)",
+    )
 
 
 class ExecutionResult(BaseModel):
@@ -25,6 +45,66 @@ class GenerateResponse(BaseModel):
     error: str | None = None
 
 
+# ──────────────────────────────────────────────────────────────────────
+# /query — новый эндпоинт для произвольной БД (connection string)
+# ──────────────────────────────────────────────────────────────────────
+
+class QueryRequest(BaseModel):
+    """Полный запрос «вопрос на русском → SQL → результат» для произвольной БД.
+
+    В отличие от GenerateRequest, не привязан к PAUQ-структуре: клиент сам
+    передаёт connection string (SQLite/PostgreSQL/MySQL). Используется
+    Streamlit-интерфейсом и любыми сторонними клиентами.
+    """
+    question: str = Field(..., min_length=1, max_length=2000)
+    connection_string: str = Field(
+        ..., min_length=1,
+        description="Строка подключения. Пример: sqlite:///data/demo/sales.sqlite",
+    )
+    execute: bool = Field(default=True)
+    vocabulary: VocabularyPayload | None = None
+
+
+class QueryResponse(BaseModel):
+    sql: str
+    raw_output: str
+    is_valid_sql: bool
+    gen_time_seconds: float
+    execution: ExecutionResult | None = None
+    error: str | None = None
+
+
+# ──────────────────────────────────────────────────────────────────────
+# /schema — отдать схему произвольной БД для подстановки в UI
+# ──────────────────────────────────────────────────────────────────────
+
+class SchemaRequest(BaseModel):
+    connection_string: str = Field(..., min_length=1)
+    include_samples: bool = Field(default=True)
+
+
+class ColumnPayload(BaseModel):
+    name: str
+    type: str
+    nullable: bool
+    primary_key: bool
+
+
+class TablePayload(BaseModel):
+    name: str
+    columns: list[ColumnPayload]
+    sample_rows: list[list]
+    ddl: str
+
+
+class SchemaResponse(BaseModel):
+    tables: list[TablePayload]
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Прочее
+# ──────────────────────────────────────────────────────────────────────
+
 class DatabaseInfo(BaseModel):
     db_id: str
     tables: list[str]

src/data/prompt.py

@@ -1,8 +1,26 @@
-"""PromptBuilder — формирует input для модели в формате chat-template."""
+"""PromptBuilder — формирование chat-template input для модели.
+
+Соответствует разделу 2.4 пояснительной записки. Один и тот же билдер
+используется при обучении (формирование SFT-примеров) и при инференсе
+(формирование запроса к загруженной модели), что гарантирует совпадение
+формата train- и inference-time промптов.
+
+Помимо схемы и вопроса, билдер опционально принимает BusinessVocabulary
+(раздел 3.6 ВКР). Бизнес-термины подмешиваются в системное сообщение,
+а не конкатенируются к пользовательскому вопросу — это согласуется с
+тем, как современные instruction-tuned модели интерпретируют роли
+сообщений в chat-template.
+"""
 
 from __future__ import annotations
 
-SYSTEM_PROMPT = (
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from src.business.vocabulary import BusinessVocabulary
+
+
+BASE_SYSTEM_PROMPT = (
     "Ты — ассистент, который преобразует вопросы на русском языке в корректные SQL-запросы. "
     "Тебе даётся схема базы данных в виде CREATE TABLE statements и пример нескольких строк. "
     "Сгенерируй один SQL-запрос, который отвечает на вопрос пользователя. "
@@ -11,19 +29,63 @@ SYSTEM_PROMPT = (
 
 
 def build_user_message(schema: str, question: str) -> str:
+    """Пользовательская часть промпта в формате ``### Schema / ### Question / ### SQL:``."""
     return f"### Schema:\n{schema}\n\n### Question:\n{question}\n\n### SQL:\n"
 
 
-def build_chat_messages(schema: str, question: str) -> list[dict]:
-    """Формат для tokenizer.apply_chat_template."""
+def build_system_message(vocabulary: "BusinessVocabulary | None" = None) -> str:
+    """Собирает системное сообщение.
+
+    Если передан непустой бизнес-словарь, к базовому промпту добавляется
+    блок с определениями терминов, фильтрами и правилами компании. Это
+    позволяет адаптировать систему к терминологии конкретной организации
+    без повторного дообучения модели.
+    """
+    if vocabulary is None or not vocabulary:
+        return BASE_SYSTEM_PROMPT
+    context = vocabulary.render_system_context()
+    if not context:
+        return BASE_SYSTEM_PROMPT
+    return BASE_SYSTEM_PROMPT + "\n\n" + context
+
+
+def build_chat_messages(
+    schema: str,
+    question: str,
+    vocabulary: "BusinessVocabulary | None" = None,
+) -> list[dict]:
+    """Сообщения для ``tokenizer.apply_chat_template``.
+
+    Параметры
+    ---------
+    schema : str
+        Текстовое представление схемы (CREATE TABLE + sample rows).
+    question : str
+        Вопрос пользователя на русском языке.
+    vocabulary : BusinessVocabulary, optional
+        Бизнес-словарь компании. Если передан — добавляется в системное
+        сообщение, не нарушая структуры пользовательской реплики.
+    """
     return [
-        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "system", "content": build_system_message(vocabulary)},
         {"role": "user", "content": build_user_message(schema, question)},
     ]
 
 
-def build_training_example(schema: str, question: str, sql: str) -> list[dict]:
-    """Полный диалог для SFT с ответом ассистента."""
-    msgs = build_chat_messages(schema, question)
+def build_training_example(
+    schema: str,
+    question: str,
+    sql: str,
+    vocabulary: "BusinessVocabulary | None" = None,
+) -> list[dict]:
+    """Полный диалог с эталонной репликой ассистента для Supervised
+    Fine-Tuning (раздел 2.4 ВКР).
+    """
+    msgs = build_chat_messages(schema, question, vocabulary)
     msgs.append({"role": "assistant", "content": sql.strip()})
     return msgs
+
+
+# Обратная совместимость. Имя SYSTEM_PROMPT использовалось в старом коде
+# и в тестах; сохраняем алиас, чтобы не ломать импорты.
+SYSTEM_PROMPT = BASE_SYSTEM_PROMPT

src/data/schema.py

@@ -1,76 +1,27 @@
-"""SchemaRetriever — извлекает DDL и примеры строк из SQLite-файлов PAUQ/Spider."""
+"""SchemaRetriever — фасад над :class:`SpiderSchemaProvider`.
+
+Исторически здесь жила полная реализация чтения PAUQ/Spider-схем. После
+рефакторинга (раздел 4.2 аудита) общая логика переехала в
+``schema_provider.py``, а ``SchemaRetriever`` оставлен как тонкая
+обёртка ради обратной совместимости импортов (``from src.data.schema
+import SchemaRetriever``), которые используются в API и тестах.
+
+Новый код стоит писать сразу через :class:`SpiderSchemaProvider`.
+"""
 
 from __future__ import annotations
 
-import sqlite3
-from dataclasses import dataclass
 from pathlib import Path
 
+from src.data.schema_provider import SpiderSchemaProvider, TableSchema
 
-@dataclass
-class TableInfo:
-    name: str
-    create_sql: str
-    sample_rows: list[tuple]
+# Алиас для совместимости со старыми импортами вида
+# ``from src.data.schema import TableInfo``.
+TableInfo = TableSchema
 
 
-class SchemaRetriever:
-    """Читает структуру SQLite-БД для подачи в prompt модели."""
+class SchemaRetriever(SpiderSchemaProvider):
+    """Совместимый алиас :class:`SpiderSchemaProvider`."""
 
     def __init__(self, databases_dir: Path | str):
-        self.databases_dir = Path(databases_dir)
-
-    def db_path(self, db_id: str) -> Path:
-        """В Spider/PAUQ каждая БД лежит в databases_dir/{db_id}/{db_id}.sqlite."""
-        path = self.databases_dir / db_id / f"{db_id}.sqlite"
-        if not path.exists():
-            raise FileNotFoundError(f"Database file not found: {path}")
-        return path
-
-    def get_tables(self, db_id: str, n_sample_rows: int = 3) -> list[TableInfo]:
-        """Возвращает список таблиц с CREATE-SQL и примером строк."""
-        path = self.db_path(db_id)
-        conn = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
-        try:
-            conn.text_factory = lambda b: b.decode("utf-8", errors="replace")
-            cur = conn.cursor()
-            cur.execute(
-                "SELECT name, sql FROM sqlite_master "
-                "WHERE type='table' AND name NOT LIKE 'sqlite_%'"
-            )
-            rows = cur.fetchall()
-
-            tables: list[TableInfo] = []
-            for table_name, create_sql in rows:
-                if not create_sql:
-                    continue
-                try:
-                    cur.execute(f'SELECT * FROM "{table_name}" LIMIT {n_sample_rows}')
-                    samples = cur.fetchall()
-                except sqlite3.Error:
-                    samples = []
-                tables.append(
-                    TableInfo(name=table_name, create_sql=create_sql.strip(), sample_rows=samples)
-                )
-            return tables
-        finally:
-            conn.close()
-
-    def render_schema(self, db_id: str, include_samples: bool = True) -> str:
-        """Текстовое представление схемы для prompt'а."""
-        tables = self.get_tables(db_id)
-        parts: list[str] = []
-        for t in tables:
-            parts.append(t.create_sql + ";")
-            if include_samples and t.sample_rows:
-                parts.append(f"-- Примеры строк из {t.name}:")
-                for row in t.sample_rows:
-                    parts.append(f"-- {row}")
-            parts.append("")
-        return "\n".join(parts).strip()
-
-    def list_databases(self) -> list[str]:
-        """Список доступных db_id."""
-        if not self.databases_dir.exists():
-            return []
-        return sorted(p.name for p in self.databases_dir.iterdir() if p.is_dir())
+        super().__init__(databases_dir)

src/data/schema_provider.py

@@ -0,0 +1,190 @@
+"""Единый интерфейс работы со схемами баз данных.
+
+До рефакторинга в проекте существовали две независимые иерархии:
+
+* ``SchemaRetriever`` (``src/data/schema.py``) — читал DDL из SQLite-файлов
+  в Spider/PAUQ-структуре ``{databases_dir}/{db_id}/{db_id}.sqlite``.
+* ``DbConnector`` (``src/db/connector.py``) — подключался к произвольной БД
+  по строке подключения, умел SQLite/PostgreSQL/MySQL.
+
+Они решали одну задачу, но по-разному оформляли результат
+(``TableInfo`` в каждом был свой) и не имели общего интерфейса. Этот
+модуль вводит единый протокол ``SchemaProvider`` и общий dataclass
+``TableSchema``. Старые классы становятся тонкими фасадами поверх
+новых реализаций.
+
+Соответствует разделам 3.4 и 4.1 пояснительной записки.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable, Protocol
+
+
+@dataclass
+class ColumnSchema:
+    """Описание колонки таблицы."""
+
+    name: str
+    type: str
+    nullable: bool = True
+    primary_key: bool = False
+
+
+@dataclass
+class TableSchema:
+    """Унифицированное описание таблицы независимо от источника схемы.
+
+    Поле ``create_sql`` хранит исходный CREATE TABLE statement, если он
+    доступен (актуально для SQLite — он его сам отдаёт из ``sqlite_master``).
+    Когда источник схемы — PostgreSQL/MySQL, DDL генерируется из
+    метаданных через :meth:`to_ddl`.
+    """
+
+    name: str
+    columns: list[ColumnSchema] = field(default_factory=list)
+    sample_rows: list[tuple] = field(default_factory=list)
+    create_sql: str | None = None
+
+    def to_ddl(self) -> str:
+        """CREATE TABLE для подстановки в промпт.
+
+        Если есть оригинальный ``create_sql`` — возвращаем его, чтобы
+        сохранить все нюансы (ограничения, FK, AUTOINCREMENT). Иначе
+        собираем из метаданных колонок.
+        """
+        if self.create_sql:
+            return self.create_sql.rstrip(";") + ";"
+        col_parts: list[str] = []
+        for col in self.columns:
+            line = f"    {col.name} {col.type}"
+            if col.primary_key:
+                line += " PRIMARY KEY"
+            if not col.nullable:
+                line += " NOT NULL"
+            col_parts.append(line)
+        return f"CREATE TABLE {self.name} (\n" + ",\n".join(col_parts) + "\n);"
+
+
+class SchemaProvider(Protocol):
+    """Протокол любого источника схемы базы данных.
+
+    Контракт минимальный: уметь перечислить таблицы и отрендерить схему
+    в текст для подстановки в промпт. Этого достаточно и для PAUQ-сценария
+    (``SpiderSchemaProvider``), и для подключения к боевой БД пользователя
+    (``ConnectionSchemaProvider``).
+    """
+
+    def list_tables(self) -> list[str]: ...
+    def get_tables(self, n_sample_rows: int = 3) -> list[TableSchema]: ...
+    def render_schema(self, include_samples: bool = True) -> str: ...
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Утилита рендеринга — общая для всех реализаций
+# ──────────────────────────────────────────────────────────────────────
+
+def render_tables(tables: Iterable[TableSchema], include_samples: bool = True) -> str:
+    """Собирает текстовое представление списка таблиц для промпта."""
+    parts: list[str] = []
+    for t in tables:
+        parts.append(t.to_ddl())
+        if include_samples and t.sample_rows:
+            parts.append(f"-- Примеры строк из {t.name}:")
+            for row in t.sample_rows:
+                parts.append(f"--   {row}")
+        parts.append("")
+    return "\n".join(parts).strip()
+
+
+# ────────────────────────────────────────────────────────────────────��─
+# Реализация 1 — Spider/PAUQ-структура
+# ──────────────────────────────────────────────────────────────────────
+
+class SpiderSchemaProvider:
+    """SchemaProvider для каталога ``data/databases/{db_id}/{db_id}.sqlite``.
+
+    Используется при работе с PAUQ/Spider: каждая БД лежит в одноимённой
+    папке. Один экземпляр SpiderSchemaProvider обслуживает всю коллекцию
+    баз — конкретная БД выбирается по ``db_id`` в методах.
+    """
+
+    def __init__(self, databases_dir: Path | str):
+        self.databases_dir = Path(databases_dir)
+
+    def list_databases(self) -> list[str]:
+        if not self.databases_dir.exists():
+            return []
+        return sorted(p.name for p in self.databases_dir.iterdir() if p.is_dir())
+
+    def db_path(self, db_id: str) -> Path:
+        path = self.databases_dir / db_id / f"{db_id}.sqlite"
+        if not path.exists():
+            raise FileNotFoundError(f"Database file not found: {path}")
+        return path
+
+    def for_database(self, db_id: str) -> "ConnectionSchemaProvider":
+        """Возвращает SchemaProvider, привязанный к конкретной БД."""
+        return ConnectionSchemaProvider(f"sqlite:///{self.db_path(db_id)}")
+
+    # ── Совместимость с предыдущим API SchemaRetriever ────────────────
+
+    def get_tables(self, db_id: str, n_sample_rows: int = 3) -> list[TableSchema]:
+        return self.for_database(db_id).get_tables(n_sample_rows=n_sample_rows)
+
+    def render_schema(self, db_id: str, include_samples: bool = True) -> str:
+        return self.for_database(db_id).render_schema(include_samples=include_samples)
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Реализация 2 — произвольная БД по connection string
+# ──────────────────────────────────────────────────────────────────────
+
+class ConnectionSchemaProvider:
+    """SchemaProvider для произвольной БД (SQLite/PostgreSQL/MySQL).
+
+    Делегирует чтение DbConnector'у, но возвращает объекты единого типа
+    ``TableSchema``. Это нужно, чтобы один и тот же код в API и Streamlit
+    мог работать как с PAUQ-структурой, так и с боевой БД пользователя.
+    """
+
+    def __init__(self, connection_string: str, n_sample_rows: int = 2):
+        # Импорт здесь, чтобы избежать кольцевой зависимости
+        # (db.connector → data.schema_provider в случае фасада).
+        from src.db.connector import DbConnector
+        self._connector = DbConnector(connection_string, n_sample_rows=n_sample_rows)
+        self.connection_string = self._connector.connection_string
+
+    # ── Базовые операции SchemaProvider ───────────────────────────────
+
+    def list_tables(self) -> list[str]:
+        return self._connector.list_tables()
+
+    def get_tables(self, n_sample_rows: int = 3) -> list[TableSchema]:
+        # DbConnector в текущей реализации использует свой n_sample_rows из ctor;
+        # для совместимости с протоколом — игнорируем параметр здесь, доверяя
+        # настройке коннектора. При желании можно завести setter.
+        raw = self._connector.get_schema(include_samples=n_sample_rows > 0)
+        return [
+            TableSchema(
+                name=t.name,
+                columns=[
+                    ColumnSchema(
+                        name=c.name, type=c.type,
+                        nullable=c.nullable, primary_key=c.primary_key,
+                    )
+                    for c in t.columns
+                ],
+                sample_rows=list(t.sample_rows),
+            )
+            for t in raw
+        ]
+
+    def render_schema(self, include_samples: bool = True) -> str:
+        return render_tables(self.get_tables(n_sample_rows=2 if include_samples else 0),
+                             include_samples=include_samples)
+
+    def test_connection(self) -> bool:
+        return self._connector.test_connection()

src/db/connector.py

@@ -1,11 +1,11 @@
-"""DbConnector -- podklyuchenie k proizvolnoy baze dannykh i chtenie skhemy.
+"""DbConnector — подключение к произвольной БД и чтение схемы.
 
-Podderzhivaemye tipy BD:
-    SQLite     -- put k faylu: "sqlite:///path/to/db.sqlite" ili prosto put
-    PostgreSQL -- "postgresql://user:pass@host:port/dbname"  (trebuet psycopg2)
-    MySQL      -- "mysql://user:pass@host:port/dbname"       (trebuet pymysql)
+Поддерживаемые типы БД:
+    SQLite     — путь к файлу: "sqlite:///path/to/db.sqlite" или просто путь
+    PostgreSQL — "postgresql://user:pass@host:port/dbname" (требует psycopg2)
+    MySQL      — "mysql://user:pass@host:port/dbname"      (требует pymysql)
 
-Primer:
+Пример:
     conn = DbConnector("sqlite:///data/demo/sales.sqlite")
     print(conn.render_schema())
     tables = conn.list_tables()
@@ -13,11 +13,14 @@ Primer:
 
 from __future__ import annotations
 
+import logging
 import sqlite3
 from dataclasses import dataclass, field
 from pathlib import Path
 from urllib.parse import urlparse
 
+logger = logging.getLogger(__name__)
+
 
 @dataclass
 class ColumnInfo:
@@ -34,7 +37,7 @@ class TableInfo:
     sample_rows: list[tuple] = field(default_factory=list)
 
     def to_ddl(self) -> str:
-        """Generiruet CREATE TABLE statement iz metadannykh."""
+        """Генерирует CREATE TABLE statement из метаданных."""
         col_parts = []
         for col in self.columns:
             line = f"    {col.name} {col.type}"
@@ -47,7 +50,7 @@ class TableInfo:
 
 
 class DbConnector:
-    """Universalnyy konektor k BD. Umeet chitat skhemu dlya podstanovki v prompt."""
+    """Универсальный коннектор к БД. Читает схему для подстановки в промпт."""
 
     def __init__(self, connection_string: str, n_sample_rows: int = 2):
         self.connection_string = self._normalize(connection_string)
@@ -66,7 +69,7 @@ class DbConnector:
         for t in tables:
             parts.append(t.to_ddl())
             if include_samples and t.sample_rows:
-                parts.append(f"-- Primery strok iz {t.name}:")
+                parts.append(f"-- Примеры строк из {t.name}:")
                 for row in t.sample_rows:
                     parts.append(f"--   {row}")
             parts.append("")
@@ -76,7 +79,8 @@ class DbConnector:
         try:
             self._get_tables(n_sample_rows=0)
             return True
-        except Exception:
+        except Exception as e:  # noqa: BLE001
+            logger.warning("Подключение к БД не удалось: %s", e)
             return False
 
     def _get_tables(self, n_sample_rows: int) -> list[TableInfo]:
@@ -87,11 +91,19 @@ class DbConnector:
         elif self._db_type == "mysql":
             return self._get_tables_mysql(n_sample_rows)
         else:
-            raise ValueError(f"Neizvestnyy tip BD: {self._db_type}")
+            raise ValueError(f"Неизвестный тип БД: {self._db_type}")
 
     def _get_tables_sqlite(self, n_sample_rows: int) -> list[TableInfo]:
-        path = self._safe_sqlite_path(self._sqlite_path())
-        conn = sqlite3.connect(str(path))
+        """SQLite-подключение в режиме read-only через URI.
+
+        immutable=1 говорит SQLite, что файл не изменяется во время сессии,
+        поэтому journal/WAL-файлы можно игнорировать. Это убирает прежнюю
+        логику с копированием БД во временную директорию и заодно даёт
+        guardrail-уровень безопасности: любая модифицирующая операция
+        на таком соединении завершится ошибкой.
+        """
+        path = self._sqlite_path()
+        conn = sqlite3.connect(self._sqlite_uri(path), uri=True)
         conn.text_factory = lambda b: b.decode("utf-8", errors="replace")
         try:
             cur = conn.cursor()
@@ -118,8 +130,9 @@ class DbConnector:
                     try:
                         cur.execute(f'SELECT * FROM "{name}" LIMIT {n_sample_rows}')
                         samples = cur.fetchall()
-                    except sqlite3.Error:
-                        pass
+                    except sqlite3.Error as e:
+                        logger.debug("Не удалось получить sample-строки для %s: %s",
+                                     name, e)
                 tables.append(TableInfo(name=name, columns=cols, sample_rows=samples))
             return tables
         finally:
@@ -129,7 +142,7 @@ class DbConnector:
         try:
             import psycopg2  # type: ignore
         except ImportError as e:
-            raise ImportError("Ustanovi psycopg2: pip install psycopg2-binary") from e
+            raise ImportError("Установи psycopg2: pip install psycopg2-binary") from e
 
         conn = psycopg2.connect(self.connection_string)
         try:
@@ -166,7 +179,7 @@ class DbConnector:
         try:
             import pymysql  # type: ignore
         except ImportError as e:
-            raise ImportError("Ustanovi pymysql: pip install pymysql") from e
+            raise ImportError("Установи pymysql: pip install pymysql") from e
 
         parsed = urlparse(self.connection_string)
         conn = pymysql.connect(
@@ -207,22 +220,22 @@ class DbConnector:
         return Path(cs)
 
     @staticmethod
-    def _safe_sqlite_path(path: Path) -> Path:
-        """Esli ryadom s BD est journal-fayl, kopируем fayl vo vremennuyu direktoriu."""
-        import shutil
-        import tempfile
-        journal = Path(str(path) + "-journal")
-        wal = Path(str(path) + "-wal")
-        if journal.exists() or wal.exists():
-            tmp = Path(tempfile.mktemp(suffix=".sqlite"))
-            shutil.copy2(path, tmp)
-            return tmp
-        return path
+    def _sqlite_uri(path: Path) -> str:
+        """Read-only URI для SQLite с игнорированием journal/WAL."""
+        return f"file:{path}?mode=ro&immutable=1"
 
     @staticmethod
     def _normalize(cs: str) -> str:
-        """Esli peredan prosto put k faylu -- prevraschaem v sqlite:// URI."""
+        """Если передан просто путь к файлу — превращаем в sqlite:// URI.
+
+        Если строка уже выглядит как URI (sqlite/postgres/mysql) —
+        возвращаем как есть. Без этой проверки сценарий «передали
+        корректный sqlite:///path» приводил к двойной нормализации
+        и подключению к несуществующему пути.
+        """
         cs = cs.strip()
+        if cs.startswith(("sqlite:", "postgres", "mysql")):
+            return cs
         if cs.endswith(".sqlite") or cs.endswith(".db"):
             return f"sqlite:///{cs}"
         return cs
@@ -235,4 +248,4 @@ class DbConnector:
             return "postgresql"
         if cs.startswith("mysql"):
             return "mysql"
-        raise ValueError(f"Ne udalos opredelit tip BD: {cs}")
+        raise ValueError(f"Не удалось определить тип БД: {cs}")

src/db/executor.py

@@ -1,23 +1,25 @@
-"""SqlExecutor -- vypolnyaet SQL-zapros na podklyuchennoy BD i vozvraschaet rezultat.
+"""SqlExecutor — выполняет SQL-запрос на подключённой БД.
 
-Primer:
-    executor = SqlExecutor("sqlite:///data/demo/sales.sqlite")
-    result = executor.run("SELECT SUM(amount) FROM orders WHERE status='paid'")
-    print(result.columns)
-    print(result.rows)
+Для SQLite соединение открывается через URI с ``mode=ro&immutable=1`` —
+это обеспечивает read-only без копирования файла и режет любые попытки
+выполнить DDL/DML на уровне драйвера. Для PostgreSQL/MySQL отдельный
+guardrail остаётся на стороне API (см. is_select_only в postprocess.py).
 """
 
 from __future__ import annotations
 
+import logging
 import sqlite3
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from pathlib import Path
 from urllib.parse import urlparse
 
+logger = logging.getLogger(__name__)
+
 
 @dataclass
 class QueryResult:
-    """Rezultat vypolneniya SQL-zaprosa."""
+    """Результат выполнения SQL-запроса."""
     columns: list[str]
     rows: list[list]
     row_count: int
@@ -39,9 +41,9 @@ class QueryResult:
 
     def to_markdown_table(self) -> str:
         if self.error:
-            return f"Oshibka: {self.error}"
+            return f"Ошибка: {self.error}"
         if not self.rows:
-            return "(pustoy rezultat)"
+            return "(пустой результат)"
         header = " | ".join(self.columns)
         sep = " | ".join(["---"] * len(self.columns))
         rows = "\n".join(" | ".join(str(v) for v in row) for row in self.rows)
@@ -49,7 +51,7 @@ class QueryResult:
 
 
 class SqlExecutor:
-    """Vypolnyaet SQL na podklyuchennoy BD."""
+    """Выполняет SQL на подключённой БД."""
 
     MAX_ROWS = 500
 
@@ -67,13 +69,14 @@ class SqlExecutor:
                 return self._run_mysql(sql)
             else:
                 return QueryResult(columns=[], rows=[], row_count=0, sql=sql,
-                                   error=f"Neizvestnyy tip BD: {self._db_type}")
-        except Exception as e:
+                                   error=f"Неизвестный тип БД: {self._db_type}")
+        except Exception as e:  # noqa: BLE001
+            logger.warning("Ошибка выполнения SQL: %s", e)
             return QueryResult(columns=[], rows=[], row_count=0, sql=sql, error=str(e))
 
     def _run_sqlite(self, sql: str) -> QueryResult:
-        path = self._safe_sqlite_path(self._sqlite_path())
-        conn = sqlite3.connect(str(path))
+        path = self._sqlite_path()
+        conn = sqlite3.connect(self._sqlite_uri(path), uri=True)
         conn.text_factory = lambda b: b.decode("utf-8", errors="replace")
         try:
             cur = conn.cursor()
@@ -88,10 +91,12 @@ class SqlExecutor:
         try:
             import psycopg2  # type: ignore
         except ImportError as e:
-            raise ImportError("Ustanovi psycopg2: pip install psycopg2-binary") from e
+            raise ImportError("Установи psycopg2: pip install psycopg2-binary") from e
 
         conn = psycopg2.connect(self.connection_string)
         try:
+            # Транзакция в режиме READ ONLY — guardrail драйверного уровня.
+            conn.set_session(readonly=True, autocommit=False)
             cur = conn.cursor()
             cur.execute(sql)
             cols = [d[0] for d in (cur.description or [])]
@@ -104,7 +109,7 @@ class SqlExecutor:
         try:
             import pymysql  # type: ignore
         except ImportError as e:
-            raise ImportError("Ustanovi pymysql: pip install pymysql") from e
+            raise ImportError("Установи pymysql: pip install pymysql") from e
 
         parsed = urlparse(self.connection_string)
         conn = pymysql.connect(
@@ -116,6 +121,9 @@ class SqlExecutor:
         )
         try:
             cur = conn.cursor()
+            # MySQL не имеет «глобального» read-only флага в драйвере,
+            # но мы можем стартовать read-only-транзакцию.
+            cur.execute("START TRANSACTION READ ONLY")
             cur.execute(sql)
             cols = [d[0] for d in (cur.description or [])]
             rows = [list(r) for r in cur.fetchmany(self.MAX_ROWS)]
@@ -130,16 +138,9 @@ class SqlExecutor:
         return Path(cs)
 
     @staticmethod
-    def _safe_sqlite_path(path: Path) -> Path:
-        import shutil
-        import tempfile
-        journal = Path(str(path) + "-journal")
-        wal = Path(str(path) + "-wal")
-        if journal.exists() or wal.exists():
-            tmp = Path(tempfile.mktemp(suffix=".sqlite"))
-            shutil.copy2(path, tmp)
-            return tmp
-        return path
+    def _sqlite_uri(path: Path) -> str:
+        """Read-only URI для SQLite с и��норированием journal/WAL."""
+        return f"file:{path}?mode=ro&immutable=1"
 
     @staticmethod
     def _detect_type(cs: str) -> str:
@@ -149,4 +150,4 @@ class SqlExecutor:
             return "postgresql"
         if cs.startswith("mysql"):
             return "mysql"
-        raise ValueError(f"Ne udalos opredelit tip BD: {cs}")
+        raise ValueError(f"Не удалось определить тип БД: {cs}")

src/models/inference.py

@@ -1,21 +1,25 @@
 """Загрузка модели + LoRA-адаптера и инференс.
 
-На десктопе/ноутбуке без GPU работает на CPU. Медленно, но достаточно для разработки и демо.
-На Kaggle/Colab — на GPU, быстрее.
+На десктопе/ноутбуке без GPU работает на CPU. Медленно, но достаточно для
+разработки и демо. На Kaggle/Colab — на GPU, быстрее.
 """
 
 from __future__ import annotations
 
+import logging
 from dataclasses import dataclass
 from pathlib import Path
 
 import torch
 from transformers import AutoModelForCausalLM, AutoTokenizer
 
+from src.business.vocabulary import BusinessVocabulary
 from src.config import settings
 from src.data.prompt import build_chat_messages
 from src.models.postprocess import postprocess
 
+logger = logging.getLogger(__name__)
+
 
 @dataclass
 class GenerationResult:
@@ -39,11 +43,18 @@ class InferenceEngine:
         self.model = None
         self._loaded = False
 
+    @property
+    def loaded(self) -> bool:
+        """Публичное свойство — статус загрузки модели."""
+        return self._loaded
+
     def load(self) -> None:
         """Лениво грузим модель. На CPU без квантизации."""
         if self._loaded:
             return
 
+        logger.info("Загрузка базовой модели %s на устройство %s",
+                    self.base_model_name, self.device)
         self.tokenizer = AutoTokenizer.from_pretrained(self.base_model_name)
         # bfloat16 вдвое меньше float32 (~6 ГБ vs ~12 ГБ) и поддерживается на CPU
         self.model = AutoModelForCausalLM.from_pretrained(
@@ -57,38 +68,53 @@ class InferenceEngine:
         adapter_id = str(adapter_path) if adapter_path.exists() else self.lora_adapter_path
         try:
             from peft import PeftModel
+            logger.info("Подключение LoRA-адаптера %s", adapter_id)
             self.model = PeftModel.from_pretrained(self.model, adapter_id)
         except ImportError:
-            pass  # peft не установлен — работаем на базовой модели
+            logger.warning("peft не установлен, используется базовая модель без LoRA")
+        except Exception as e:  # noqa: BLE001 — лог достаточен, без падения
+            logger.warning("Не удалось подгрузить LoRA-адаптер %s: %s",
+                           adapter_id, e)
 
         self.model.eval()
         self._loaded = True
+        logger.info("InferenceEngine готов к работе")
 
     def generate(
         self,
         schema: str,
         question: str,
+        vocabulary: BusinessVocabulary | None = None,
         max_new_tokens: int | None = None,
     ) -> GenerationResult:
-        """Принимает schema (текст DDL) и вопрос, возвращает SQL."""
+        """Принимает schema (текст DDL) и вопрос, возвращает SQL.
+
+        Если передан непустой ``vocabulary``, бизнес-термины компании
+        подмешиваются в системное сообщение через PromptBuilder.
+        Это соответствует разделу 3.6 пояснительной записки.
+        """
         if not self._loaded:
             self.load()
 
-        messages = build_chat_messages(schema, question)
+        messages = build_chat_messages(schema, question, vocabulary=vocabulary)
         prompt = self.tokenizer.apply_chat_template(
             messages, tokenize=False, add_generation_prompt=True
         )
         inputs = self.tokenizer(prompt, return_tensors="pt").to(self.model.device)
 
+        # Параметры сэмплинга. При do_sample=False temperature игнорируется,
+        # поэтому не передаём её — иначе transformers выводит warning.
+        gen_kwargs = {
+            "max_new_tokens": max_new_tokens or settings.max_new_tokens,
+            "do_sample": settings.do_sample,
+            "pad_token_id": self.tokenizer.eos_token_id,
+        }
+        if settings.do_sample:
+            gen_kwargs["temperature"] = settings.temperature
+
         with torch.no_grad():
-            output_ids = self.model.generate(
-                **inputs,
-                max_new_tokens=max_new_tokens or settings.max_new_tokens,
-                do_sample=settings.do_sample,
-                temperature=settings.temperature if settings.do_sample else 1.0,
-                pad_token_id=self.tokenizer.eos_token_id,
-            )
-
-        new_tokens = output_ids[0][inputs["input_ids"].shape[1] :]
+            output_ids = self.model.generate(**inputs, **gen_kwargs)
+
+        new_tokens = output_ids[0][inputs["input_ids"].shape[1]:]
         raw = self.tokenizer.decode(new_tokens, skip_special_tokens=True)
         return GenerationResult(sql=postprocess(raw), raw_output=raw)

src/models/postprocess.py

@@ -1,24 +1,69 @@
-"""Постобработка SQL: чистка вывода модели и базовая валидация через sqlglot."""
+"""Постобработка SQL: чистка вывода модели, валидация и нормализация.
+
+Соответствует разделу 2.5 пояснительной записки. Pipeline:
+    raw_output  ──► strip_model_artifacts  ──► is_valid_sql  ──► sql | ""
+
+Дополнительно модуль предоставляет:
+    is_select_only(sql)  — AST-уровневый гвардейл против DDL/DML
+                            перед выполнением сгенерированного запроса;
+    normalize_sql(sql)   — каноническая форма для расчёта Exact Match
+                            (совместима с evaluate_pauq.py).
+"""
 
 from __future__ import annotations
 
+import logging
 import re
 
 import sqlglot
+from sqlglot import exp
 from sqlglot.errors import ParseError
 
+logger = logging.getLogger(__name__)
+
+# Ключевые слова, с которых может начинаться корректный SQL-запрос.
+_SQL_START_KEYWORDS = ("SELECT", "WITH", "INSERT", "UPDATE", "DELETE")
+_SQL_START_REGEX = re.compile(
+    r"\b(" + "|".join(_SQL_START_KEYWORDS) + r")\b",
+    flags=re.IGNORECASE,
+)
+_FENCE_REGEX = re.compile(r"```(?:sql)?\s*(.*?)```", flags=re.DOTALL | re.IGNORECASE)
+_PREFIX_REGEX = re.compile(r"^\s*(?:SQL|Ответ|Answer)\s*:\s*", flags=re.IGNORECASE)
+
+# Типы AST-узлов, которые мы считаем «осмысленными» SQL-запросами.
+# sqlglot — лояльный парсер: 'garbage text' он распарсит как Column/Table.
+# Без проверки isinstance такие случаи будут проходить is_valid_sql.
+_VALID_ROOT_TYPES: tuple[type[exp.Expression], ...] = (
+    exp.Select,
+    exp.With,
+    exp.Insert,
+    exp.Update,
+    exp.Delete,
+    exp.Union,
+    exp.Intersect,
+    exp.Except,
+)
+
 
 def strip_model_artifacts(text: str) -> str:
-    """Убирает markdown-блоки, префиксы, лишний текст после SQL."""
-    # ```sql ... ```
-    m = re.search(r"```(?:sql)?\s*(.*?)```", text, re.DOTALL | re.IGNORECASE)
-    if m:
-        text = m.group(1)
+    """Очищает вывод модели от markdown и пояснений до начала SQL-запроса.
+
+    Шаги:
+        1. Если ответ обёрнут в ```sql ... ``` — извлекается содержимое.
+        2. Удаляются префиксы вида «SQL:», «Ответ:», «Answer:».
+        3. Ищется первое вхождение SQL-ключевого слова, всё до него отбрасывается.
+        4. Берётся первый statement до первой точки с запятой включительно.
+    """
+    fence = _FENCE_REGEX.search(text)
+    if fence:
+        text = fence.group(1)
 
-    # Убираем "SQL:", "Ответ:" и т.п. в начале
-    text = re.sub(r"^\s*(?:SQL|Ответ|Answer)\s*:\s*", "", text, flags=re.IGNORECASE)
+    text = _PREFIX_REGEX.sub("", text)
+
+    keyword_match = _SQL_START_REGEX.search(text)
+    if keyword_match:
+        text = text[keyword_match.start():]
 
-    # Если есть несколько SQL — берём первый до точки с запятой
     text = text.strip()
     if ";" in text:
         head, _, _ = text.partition(";")
@@ -28,23 +73,75 @@ def strip_model_artifacts(text: str) -> str:
 
 
 def is_valid_sql(sql: str, dialect: str = "sqlite") -> bool:
-    """Парсится ли SQL через sqlglot."""
+    """Проверяет, что строка — это валидный SQL-запрос.
+
+    Парсится через sqlglot и дополнительно проверяется, что корень AST —
+    это один из «осмысленных» типов запроса (SELECT/WITH/INSERT/UPDATE/
+    DELETE/UNION). Без проверки типа sqlglot принимает за SQL даже
+    случайные идентификаторы, потому что он лояльный парсер.
+    """
+    if not sql or not sql.strip():
+        return False
     try:
-        sqlglot.parse_one(sql, dialect=dialect)
-        return True
-    except ParseError:
+        parsed = sqlglot.parse_one(sql, dialect=dialect)
+    except (ParseError, ValueError, TypeError) as e:
+        logger.debug("sqlglot не смог разобрать SQL: %s", e)
+        return False
+    if parsed is None:
         return False
+    return isinstance(parsed, _VALID_ROOT_TYPES)
+
+
+def is_select_only(sql: str, dialect: str = "sqlite") -> bool:
+    """Возвращает True, если SQL — это SELECT (в т. ч. внутри WITH-CTE).
+
+    Используется как guardrail перед выполнением сгенерированного запроса
+    на реальной базе данных: модель не должна получить возможность вызвать
+    DROP/UPDATE/DELETE/INSERT, даже если такие конструкции синтаксически
+    корректны.
+    """
+    if not sql or not sql.strip():
+        return False
+    try:
+        parsed = sqlglot.parse_one(sql, dialect=dialect)
+    except (ParseError, ValueError, TypeError):
+        return False
+    if parsed is None:
+        return False
+    if isinstance(parsed, exp.Select):
+        return True
+    if isinstance(parsed, exp.With):
+        return isinstance(parsed.this, exp.Select)
+    if isinstance(parsed, exp.Subquery):
+        return isinstance(parsed.this, exp.Select)
+    return False
 
 
 def normalize_sql(sql: str, dialect: str = "sqlite") -> str:
-    """Нормализация для Exact Match: единый регистр ключевых слов, пробелы."""
+    """Каноническая форма для расчёта Exact Match.
+
+    Использует sqlglot с флагом ``normalize=True`` — это нормализует регистр
+    ключевых слов и идентификаторов. Результат приводится к верхнему регистру,
+    чтобы EM считался идентично эталонной реализации в ``evaluate_pauq.py``.
+    """
     try:
-        return sqlglot.parse_one(sql, dialect=dialect).sql(dialect=dialect, pretty=False).lower()
-    except ParseError:
-        # Если не парсится — просто нижний регистр и схлопывание пробелов
-        return re.sub(r"\s+", " ", sql.lower()).strip().rstrip(";")
+        parsed = sqlglot.parse_one(sql, dialect=dialect)
+        return parsed.sql(dialect=dialect, normalize=True).upper()
+    except (ParseError, ValueError, TypeError):
+        return re.sub(r"\s+", " ", sql.upper()).strip().rstrip(";")
 
 
 def postprocess(raw_output: str) -> str:
-    """Полный pipeline постобработки."""
-    return strip_model_artifacts(raw_output)
+    """Полный pipeline постобработки вывода модели.
+
+    1. Чистка артефактов через :func:`strip_model_artifacts`.
+    2. Валидация через :func:`is_valid_sql`.
+    3. Возврат пустой строки при провале валидации.
+
+    Соответствует разделу 2.5 пояснительной записки.
+    """
+    sql = strip_model_artifacts(raw_output)
+    if not is_valid_sql(sql):
+        logger.warning("postprocess отбросил невалидный SQL: %r", sql[:120])
+        return ""
+    return sql

src/streamlit_app.py

@@ -1,9 +1,12 @@
-import os
-import sys
+"""Устаревший модуль.
 
-# Запускаем основное приложение из корня проекта
-root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-os.chdir(root)
-sys.path.insert(0, root)
+Точка входа Streamlit-приложения — ``streamlit_app.py`` в корне проекта.
+Запуск:
 
-exec(open(os.path.join(root, "streamlit_app.py")).read())
+    streamlit run streamlit_app.py
+
+Этот файл оставлен пустым ради обратной совместимости import-путей.
+Ранее здесь была обёртка через ``exec(open(...).read())``, которая
+запускала UI как побочный эффект импорта пакета ``src`` — что ломало
+сбор тестов и статический анализ. Хак удалён.
+"""

streamlit_app.py

@@ -1,16 +1,44 @@
-"""Streamlit-интерфейс утилиты Ru2SQL."""
+"""Streamlit-интерфейс утилиты Ru2SQL.
+
+Архитектурно — клиент REST API на FastAPI. Соответствует разделу 3.5
+пояснительной записки: все обращения к модели и базе данных идут через
+HTTP к ``src.api.main:app``. Запуск двух процессов:
+
+    uvicorn src.api.main:app --reload      # на 127.0.0.1:8000
+    streamlit run streamlit_app.py          # на 127.0.0.1:8501
+"""
 
 from __future__ import annotations
 
+import logging
+import os
 import sys
-import time
+import warnings
 from pathlib import Path
 
+# ──────────────────────────────────────────────
+# Глушим шумные warning'и
+# ──────────────────────────────────────────────
+# Streamlit-watcher ходит по всему пакету transformers (image-processors)
+# и спамит ModuleNotFoundError про torchvision. На работу это не влияет —
+# Qwen2.5-Coder text-only, torchvision не нужен.
+warnings.filterwarnings("ignore", message=".*torchvision.*")
+logging.getLogger("transformers").setLevel(logging.ERROR)
+logging.getLogger("streamlit.watcher.local_sources_watcher").setLevel(logging.ERROR)
+
+import httpx
 import streamlit as st
 
 ROOT = Path(__file__).resolve().parent
 sys.path.insert(0, str(ROOT))
 
+# Бизнес-словарь парсим локально — он не требует обращения к серверу
+from src.business.vocabulary import BusinessVocabulary
+
+API_URL = os.environ.get("RU2SQL_API_URL", "http://127.0.0.1:8000")
+QUERY_TIMEOUT = 1800.0  # 30 минут — фактически безлимит
+SHORT_TIMEOUT = 10.0   # для /health, /schema
+
 # ──────────────────────────────────────────────
 # Конфигурация страницы
 # ──────────────────────────────────────────────
@@ -21,11 +49,10 @@ st.set_page_config(
 )
 
 # ──────────────────────────────────────────────
-# CSS
+# CSS — оформление в стиле тёмной темы GitHub
 # ──────────────────────────────────────────────
 st.markdown("""
 <style>
-    /* ── Глобальный шрифт и фон ── */
     html, body, [data-testid="stAppViewContainer"] {
         background-color: #0d1117;
         font-size: 16px;
@@ -36,7 +63,6 @@ st.markdown("""
     }
     [data-testid="stHeader"] { background: transparent; }
 
-    /* ── Шапка ── */
     .app-header {
         padding: 32px 0 24px 0;
         border-bottom: 1px solid #30363d;
@@ -57,8 +83,6 @@ st.markdown("""
         font-weight: 400;
         letter-spacing: 0.1px;
     }
-
-    /* ── Сайдбар: секции ── */
     .sb-label {
         font-size: 10px;
         font-weight: 700;
@@ -73,32 +97,13 @@ st.markdown("""
         border-top: 1px solid #30363d;
         margin: 4px 0 0 0;
     }
-
-    /* ── Статусы ── */
     .status-ok  { color: #3fb950; font-size: 13px; font-weight: 600; }
     .status-err { color: #f85149; font-size: 13px; font-weight: 600; }
-
-    /* ── DB-переключатель ── */
-    div[data-testid="stRadio"] > div {
-        gap: 4px;
-    }
-    div[data-testid="stRadio"] > div > label {
-        font-size: 14px;
-        padding: 4px 0;
-    }
-
-    /* ── Кнопка словаря ── */
-    .vocab-status {
-        font-size: 12px;
-        color: #7d8590;
-        margin-top: 6px;
-    }
-
-    /* ── SQL-блок ── */
+    .status-warn { color: #d29922; font-size: 13px; font-weight: 600; }
     .sql-box {
         background: #161b22;
         color: #e6edf3;
-        font-family: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'Courier New', monospace;
+        font-family: 'JetBrains Mono', 'Fira Code', monospace;
         font-size: 14px;
         line-height: 1.7;
         padding: 20px 24px;
@@ -108,11 +113,7 @@ st.markdown("""
         white-space: pre-wrap;
         margin: 14px 0;
     }
-
-    /* ── Вкладки ── */
     [data-testid="stTabs"] button { font-size: 15px; font-weight: 500; }
-
-    /* ── Примеры запросов ── */
     .examples-label {
         font-size: 11px;
         font-weight: 700;
@@ -121,47 +122,21 @@ st.markdown("""
         color: #7d8590;
         margin: 24px 0 10px 0;
     }
-
-    /* ── Поле ввода вопроса ── */
     [data-testid="stTextArea"] textarea {
         font-size: 16px !important;
         line-height: 1.6 !important;
     }
-
-    /* ── Кнопка «Выполнить» ── */
     [data-testid="stButton"] > button[kind="primary"] {
         font-size: 15px;
         padding: 10px 28px;
         border-radius: 8px;
         font-weight: 600;
     }
-
-    /* ── Метрики ── */
-    [data-testid="stMetric"] label {
-        font-size: 12px !important;
-        color: #7d8590 !important;
-    }
-    [data-testid="stMetricValue"] {
-        font-size: 22px !important;
-        color: #e6edf3 !important;
-    }
-
-    /* ── Предупреждение о неготовности ── */
-    [data-testid="stAlertContainer"] {
-        border-radius: 8px;
-        font-size: 14px;
-    }
-
-    /* ── Expander схемы ── */
-    [data-testid="stExpander"] summary {
-        font-size: 15px;
-        font-weight: 500;
-    }
-
-    /* ── Скрыть кнопку Stop ── */
+    [data-testid="stMetric"] label { font-size: 12px !important; color: #7d8590 !important; }
+    [data-testid="stMetricValue"] { font-size: 22px !important; color: #e6edf3 !important; }
+    [data-testid="stAlertContainer"] { border-radius: 8px; font-size: 14px; }
+    [data-testid="stExpander"] summary { font-size: 15px; font-weight: 500; }
     button[kind="stop"] { display: none !important; }
-
-    /* ── Модальный диалог словаря ── */
     [data-testid="stDialog"] textarea {
         font-family: 'JetBrains Mono', 'Fira Code', monospace !important;
         font-size: 13px !important;
@@ -178,27 +153,21 @@ def _default_vocab_yaml() -> str:
     example = ROOT / "configs" / "example_vocabulary.yaml"
     if example.exists():
         return example.read_text(encoding="utf-8")
-    return (
-        "company: Моя компания\n\n"
-        "terms:\n"
-        "  выручка: SUM(orders.amount) WHERE status = 'paid'\n\n"
-        "filters:\n"
-        "  только_оплаченные: orders.status = 'paid'\n\n"
-        "notes: []\n"
-    )
+    return "company: Моя компания\n\nterms: {}\nfilters: {}\nnotes: []\n"
 
 
 def _init_state():
     defaults = {
-        "history":              [],
-        "model_loaded":         False,
-        "engine":               None,
-        "db_connector":         None,
-        "db_executor":          None,
-        "vocabulary":           None,
-        "db_connection_string": "",
-        "vocab_yaml":           _default_vocab_yaml(),
-        "db_mode":              None,
+        "history":               [],
+        "api_health":            None,      # dict | None
+        "api_error":             None,      # str | None
+        "connection_string":     "",
+        "schema_tables":         None,      # list[TablePayload-like dict] | None
+        "schema_error":          None,
+        "vocabulary":            None,      # BusinessVocabulary | None
+        "vocab_yaml":            _default_vocab_yaml(),
+        "db_mode":               None,
+        "warmup_done":           False,
     }
     for k, v in defaults.items():
         if k not in st.session_state:
@@ -209,58 +178,90 @@ _init_state()
 
 
 # ──────────────────────────────────────────────
-# Вспомогательные функции
+# Обёртки над API
 # ──────────────────────────────────────────────
-@st.cache_resource(show_spinner="Инициализация модели…")
-def _load_engine():
-    from src.models.inference import InferenceEngine
-    engine = InferenceEngine()
-    engine.load()
-    return engine
+def _api_get_health() -> dict | None:
+    """GET /health. None если API недоступен."""
+    try:
+        r = httpx.get(f"{API_URL}/health", timeout=SHORT_TIMEOUT)
+        r.raise_for_status()
+        return r.json()
+    except Exception as e:
+        st.session_state.api_error = str(e)
+        return None
 
 
-def _connect_db(cs: str):
-    from src.db.connector import DbConnector
-    from src.db.executor import SqlExecutor
-    return DbConnector(cs), SqlExecutor(cs)
+def _api_get_schema(cs: str) -> tuple[list[dict] | None, str | None]:
+    """POST /schema. Возвращает (tables, error)."""
+    try:
+        r = httpx.post(
+            f"{API_URL}/schema",
+            json={"connection_string": cs, "include_samples": True},
+            timeout=SHORT_TIMEOUT,
+        )
+        if r.status_code != 200:
+            try:
+                return None, r.json().get("detail", r.text)
+            except Exception:
+                return None, r.text
+        return r.json().get("tables", []), None
+    except Exception as e:
+        return None, str(e)
+
+
+def _api_query(question: str, cs: str, vocab: BusinessVocabulary | None) -> dict:
+    """POST /query — генерация SQL + опциональное исполнение."""
+    payload = {
+        "question": question,
+        "connection_string": cs,
+        "execute": True,
+    }
+    if vocab is not None and bool(vocab):
+        payload["vocabulary"] = {
+            "company": vocab.company,
+            "terms": vocab.terms,
+            "filters": vocab.filters,
+            "notes": vocab.notes,
+        }
+    r = httpx.post(f"{API_URL}/query", json=payload, timeout=QUERY_TIMEOUT)
+    if r.status_code != 200:
+        try:
+            detail = r.json().get("detail", r.text)
+        except Exception:
+            detail = r.text
+        raise RuntimeError(f"API вернул {r.status_code}: {detail}")
+    return r.json()
 
 
-def _load_vocab_from_yaml(yaml_text: str):
+
+def _api_warmup() -> tuple[bool, str | None]:
+    """POST /warmup — короткий прогон для прогрева модели на CPU."""
+    try:
+        r = httpx.post(f"{API_URL}/warmup", timeout=QUERY_TIMEOUT)
+        if r.status_code == 200:
+            return True, None
+        return False, r.text
+    except Exception as e:
+        return False, str(e)
+
+
+def _load_vocab_from_yaml(yaml_text: str) -> BusinessVocabulary:
     import tempfile
-    from src.business.vocabulary import BusinessVocabulary
     tmp = Path(tempfile.mktemp(suffix=".yaml"))
     tmp.write_text(yaml_text, encoding="utf-8")
-    vocab = BusinessVocabulary.from_yaml(tmp)
-    tmp.unlink(missing_ok=True)
-    return vocab
-
-
-def _auto_connect_demo():
-    """Подключить демо-базу и словарь к ней."""
-    demo_path = ROOT / "data" / "demo" / "sales.sqlite"
-    cs = str(demo_path)
     try:
-        connector, executor = _connect_db(cs)
-        st.session_state.db_connector         = connector
-        st.session_state.db_executor          = executor
-        st.session_state.db_connection_string = cs
-        if st.session_state.vocabulary is None:
-            vocab_path = ROOT / "configs" / "example_vocabulary.yaml"
-            if vocab_path.exists():
-                st.session_state.vocabulary = _load_vocab_from_yaml(
-                    vocab_path.read_text(encoding="utf-8")
-                )
-    except Exception:
-        pass
+        return BusinessVocabulary.from_yaml(tmp)
+    finally:
+        tmp.unlink(missing_ok=True)
 
 
 # ──────────────────────────────────────────────
-# Модальный диалог бизнес-словаря
+# Диалог редактирования бизнес-словаря
 # ──────────────────────────────────────────────
 @st.dialog("Бизнес-словарь", width="large")
 def vocab_dialog():
     st.caption(
-        "Опишите термины, метрики и правила вашей компании в формате YAML. "
+        "Опишите термины и метрики компании в формате YAML. "
         "Модель будет учитывать их при генерации SQL."
     )
     yaml_text = st.text_area(
@@ -269,77 +270,72 @@ def vocab_dialog():
         height=480,
         label_visibility="collapsed",
     )
-    col1, col2 = st.columns([1, 1])
-    with col1:
-        if st.button("Применить", type="primary", use_container_width=True):
+    c1, c2 = st.columns(2)
+    with c1:
+        if st.button("Применить", type="primary", width='stretch'):
             try:
-                vocab = _load_vocab_from_yaml(yaml_text)
-                st.session_state.vocabulary = vocab
+                st.session_state.vocabulary = _load_vocab_from_yaml(yaml_text)
                 st.session_state.vocab_yaml = yaml_text
                 st.rerun()
             except Exception as e:
                 st.error(f"Ошибка синтаксиса YAML: {e}")
-    with col2:
-        if st.button("Отмена", use_container_width=True):
+    with c2:
+        if st.button("Отмена", width='stretch'):
             st.rerun()
 
 
 # ──────────────────────────────────────────────
-# Боковая панель
+# Sidebar
 # ──────────────────────────────────────────────
 with st.sidebar:
 
-    # ── Модель ──
-    st.markdown('<p class="sb-label">Модель</p>', unsafe_allow_html=True)
-    if not st.session_state.model_loaded:
-        with st.spinner("Инициализация…"):
-            try:
-                st.session_state.engine     = _load_engine()
-                st.session_state.model_loaded = True
-            except Exception as e:
-                st.error(f"Ошибка: {e}")
-
-    if st.session_state.model_loaded:
-        st.markdown(
-            '<span class="status-ok">✅ Qwen2.5-Coder-3B + QLoRA</span>',
-            unsafe_allow_html=True,
-        )
+    # ── API ──
+    st.markdown('<p class="sb-label">API</p>', unsafe_allow_html=True)
+    health = _api_get_health()
+    st.session_state.api_health = health
+    if health is None:
+        st.markdown('<span class="status-err">API недоступен</span>', unsafe_allow_html=True)
+        st.caption(f"Адрес: {API_URL}")
+        st.caption("Запусти в отдельной консоли: `uvicorn src.api.main:app --reload`")
+        if st.session_state.api_error:
+            st.caption(f"Причина: {st.session_state.api_error[:160]}")
     else:
-        st.markdown(
-            '<span class="status-err">Модель не загружена</span>',
-            unsafe_allow_html=True,
-        )
+        if health.get("model_loaded"):
+            st.markdown(
+                f'<span class="status-ok">✅ {health.get("base_model", "модель")}</span>',
+                unsafe_allow_html=True,
+            )
+        else:
+            st.markdown(
+                '<span class="status-warn">⏳ Модель ещё загружается</span>',
+                unsafe_allow_html=True,
+            )
+            st.caption("Подождите несколько минут — модель ещё инициализируется.")
 
     st.markdown('<hr class="sb-divider">', unsafe_allow_html=True)
 
     # ── База данных ──
     st.markdown('<p class="sb-label">База данных</p>', unsafe_allow_html=True)
 
-    _modes = ["Демо-база", "Загрузить файл", "Строка подключения"]
-    _prev  = st.session_state.db_mode
+    modes = ["Демо-база", "Загрузить файл", "Строка подключения"]
+    prev = st.session_state.db_mode
     db_mode = st.radio(
-        "Источник данных",
-        _modes,
-        index=_modes.index(_prev) if _prev in _modes else None,
+        "Источник данных", modes,
+        index=modes.index(prev) if prev in modes else None,
         label_visibility="collapsed",
     )
-    if db_mode != _prev:
-        # При смене режима сбрасываем подключение
-        st.session_state.db_connector  = None
-        st.session_state.db_executor   = None
+    if db_mode != prev:
+        st.session_state.schema_tables = None
+        st.session_state.connection_string = ""
     st.session_state.db_mode = db_mode
 
     cs = ""
-
     if db_mode == "Демо-база":
         st.caption("Встроенная база: интернет-магазин электроники, 120 заказов.")
-        demo_path = ROOT / "data" / "demo" / "sales.sqlite"
-        cs = str(demo_path)
-
+        cs = str(ROOT / "data" / "demo" / "sales.sqlite")
     elif db_mode == "Загрузить файл":
         uploaded = st.file_uploader(
-            "SQLite-файл базы данных",
-            type=["sqlite", "db"],
+            "SQLite-файл базы данных", type=["sqlite", "db"],
             label_visibility="collapsed",
         )
         if uploaded:
@@ -349,81 +345,77 @@ with st.sidebar:
             cs = str(tmp_db)
         else:
             st.caption("Перетащите .sqlite или .db файл сюда")
-
-    else:  # Строка подключения
+    else:
         cs = st.text_input(
             "Строка подключения",
             placeholder="postgresql://user:pass@host:5432/db",
-            value=st.session_state.db_connection_string,
+            value=st.session_state.connection_string,
             label_visibility="collapsed",
         )
-        st.caption("PostgreSQL · MySQL (mysql+pymysql://) · SQLite (sqlite:///path)")
-
-    if cs and st.button("Подключиться", use_container_width=True, type="primary"):
-        try:
-            connector, executor = _connect_db(cs)
-            tables = connector.list_tables()
-            st.session_state.db_connector         = connector
-            st.session_state.db_executor          = executor
-            st.session_state.db_connection_string = cs
+        st.caption("PostgreSQL · MySQL · SQLite (sqlite:///path)")
+
+    if cs and st.button("Подключиться", width='stretch', type="primary"):
+        with st.spinner("Чтение схемы…"):
+            tables, err = _api_get_schema(cs)
+        if err:
+            st.error(f"Ошибка подключения: {err}")
+            st.session_state.schema_tables = None
+        else:
+            st.session_state.schema_tables = tables
+            st.session_state.connection_string = cs
+            st.session_state.schema_error = None
+            if not st.session_state.get("warmup_done", False):
+                with st.spinner("Прогрев модели (запускается один раз за сессию)…"):
+                    ok, _err = _api_warmup()
+                if ok:
+                    st.session_state.warmup_done = True
+            # Автозагрузка словаря для демо-базы
             if "sales" in cs and st.session_state.vocabulary is None:
-                vocab_path = ROOT / "configs" / "example_vocabulary.yaml"
-                if vocab_path.exists():
-                    st.session_state.vocabulary = _load_vocab_from_yaml(
-                        vocab_path.read_text(encoding="utf-8")
-                    )
+                vp = ROOT / "configs" / "example_vocabulary.yaml"
+                if vp.exists():
+                    try:
+                        st.session_state.vocabulary = _load_vocab_from_yaml(
+                            vp.read_text(encoding="utf-8")
+                        )
+                    except Exception:
+                        pass
             st.success(f"Подключено. Таблиц: {len(tables)}")
-        except Exception as e:
-            st.error(f"Ошибка подключения: {e}")
 
-    if st.session_state.db_connector:
-        tables = st.session_state.db_connector.list_tables()
+    if st.session_state.schema_tables is not None:
+        n = len(st.session_state.schema_tables)
         st.markdown(
             '<span class="status-ok">✅ База данных подключена</span>',
             unsafe_allow_html=True,
         )
-        with st.expander(f"Таблицы ({len(tables)})"):
-            for t in tables:
-                st.code(t, language=None)
+        with st.expander(f"Таблицы ({n})"):
+            for t in st.session_state.schema_tables:
+                st.code(t.get("name", ""), language=None)
 
     st.markdown('<hr class="sb-divider">', unsafe_allow_html=True)
 
     # ── Бизнес-словарь ──
     st.markdown('<p class="sb-label">Бизнес-словарь</p>', unsafe_allow_html=True)
-
     if st.session_state.vocabulary:
         v = st.session_state.vocabulary
         label = v.company if v.company else "Загружен"
-        st.markdown(
-            f'<span class="status-ok">✅ {label}</span>',
-            unsafe_allow_html=True,
-        )
+        st.markdown(f'<span class="status-ok">✅ {label}</span>', unsafe_allow_html=True)
         if v.terms:
-            st.markdown(
-                f'<span class="vocab-status">Терминов: {len(v.terms)}</span>',
-                unsafe_allow_html=True,
-            )
+            st.caption(f"Терминов: {len(v.terms)}")
     else:
-        st.markdown(
-            '<span class="vocab-status">Словарь не применён</span>',
-            unsafe_allow_html=True,
-        )
-
-    if st.button("Редактировать словарь", use_container_width=True):
+        st.caption("Словарь не применён")
+    if st.button("Редактировать словарь", width='stretch'):
         vocab_dialog()
 
 
-
-
 # ──────────────────────────────────────────────
-# Основная область — шапка
+# Шапка
 # ──────────────────────────────────────────────
 st.markdown("""
 <div class="app-header">
     <p class="app-title">Ru2SQL — генеративная модель преобразования запросов<br>
     к базе данных на русском языке в запросы на языке SQL</p>
     <p class="app-subtitle">
-        Qwen2.5-Coder-3B-Instruct &nbsp;·&nbsp; QLoRA fine-tuning на датасете PAUQ
+        Qwen2.5-Coder-3B-Instruct &nbsp;·&nbsp; QLoRA на PAUQ
         &nbsp;·&nbsp; SQLite / PostgreSQL / MySQL
     </p>
 </div>
@@ -431,15 +423,21 @@ st.markdown("""
 
 tab_query, tab_schema, tab_history = st.tabs(["Запрос", "Схема базы данных", "История"])
 
-# ──────────── Вкладка: Запрос ────────────
+
+# ──────────── Tab: Запрос ────────────
 with tab_query:
-    ready = st.session_state.model_loaded and st.session_state.db_connector is not None
+    api_ready = (
+        st.session_state.api_health is not None
+        and st.session_state.api_health.get("model_loaded", False)
+    )
+    db_ready = st.session_state.schema_tables is not None
+    ready = api_ready and db_ready
 
     if not ready:
         missing = []
-        if not st.session_state.model_loaded:
-            missing.append("модель инициализируется")
-        if st.session_state.db_connector is None:
+        if not api_ready:
+            missing.append("API/модель не готовы")
+        if not db_ready:
             missing.append("база данных не подключена")
         st.warning("Система не готова: " + ", ".join(missing) + ". Используйте панель слева.")
 
@@ -450,19 +448,19 @@ with tab_query:
         disabled=not ready,
     )
 
-    col_btn, col_spacer = st.columns([1, 5])
+    col_btn, _ = st.columns([1, 5])
     with col_btn:
         run_btn = st.button(
             "Выполнить",
             type="primary",
             disabled=not ready or not question.strip(),
-            use_container_width=True,
+            width='stretch',
         )
 
     # Примеры для демо-базы
     if (
-        st.session_state.db_connection_string
-        and "sales" in st.session_state.db_connection_string
+        st.session_state.connection_string
+        and "sales" in st.session_state.connection_string
     ):
         st.markdown('<p class="examples-label">Примеры запросов</p>', unsafe_allow_html=True)
         ex_cols = st.columns(3)
@@ -473,78 +471,76 @@ with tab_query:
         ]
         for i, ex in enumerate(examples):
             with ex_cols[i]:
-                if st.button(ex, key=f"ex_{i}", use_container_width=True):
+                if st.button(ex, key=f"ex_{i}", width='stretch'):
                     question = ex
-                    run_btn  = True
+                    run_btn = True
 
     if run_btn and question.strip():
-        engine    = st.session_state.engine
-        connector = st.session_state.db_connector
-        executor  = st.session_state.db_executor
-        vocab     = st.session_state.vocabulary
-
-        enriched = vocab.enrich_prompt(question) if vocab else question
-        schema   = connector.render_schema(include_samples=True)
+        cs = st.session_state.connection_string
+        vocab = st.session_state.vocabulary
 
-        with st.spinner("Генерация SQL-запроса…"):
-            t0     = time.time()
-            result = engine.generate(schema, enriched)
-            gen_time = time.time() - t0
+        with st.spinner("Запрос к API. Это может занять несколько минут"):
+            try:
+                resp = _api_query(question, cs, vocab)
+            except Exception as e:
+                st.error(f"Ошибка: {e}")
+                st.stop()
 
         st.markdown("**Сгенерированный SQL**")
-        st.markdown(f'<div class="sql-box">{result.sql}</div>', unsafe_allow_html=True)
+        st.markdown(f'<div class="sql-box">{resp.get("sql", "")}</div>', unsafe_allow_html=True)
 
-        qr = None
-        if result.sql.strip():
-            with st.spinner("Выполнение запроса…"):
-                qr = executor.run(result.sql)
+        gen_time = resp.get("gen_time_seconds", 0.0)
+        execution = resp.get("execution")
+        err = resp.get("error")
 
         c1, c2, c3 = st.columns(3)
         c1.metric("Время генерации", f"{gen_time:.1f} с")
-        if qr:
-            c2.metric("Строк получено", qr.row_count if qr.success else "—")
-            c3.metric("Статус", "Успешно" if qr.success else "Ошибка")
-
-        if qr and qr.success:
-            if qr.rows:
-                import pandas as pd
-                st.markdown("**Результат**")
-                df = pd.DataFrame(qr.rows, columns=qr.columns)
-                st.dataframe(df, use_container_width=True)
-            else:
-                st.info("Запрос выполнен успешно. Результат пустой.")
-        elif qr and not qr.success:
-            st.error(f"Ошибка выполнения SQL: {qr.error}")
+        if execution:
+            c2.metric("Строк получено", execution.get("row_count", 0))
+            c3.metric("Статус", "Успешно")
+        elif err:
+            c2.metric("Строк получено", "—")
+            c3.metric("Статус", "Ошибка")
+
+        if execution and execution.get("rows"):
+            import pandas as pd
+            st.markdown("**Результат**")
+            df = pd.DataFrame(execution["rows"], columns=execution["columns"])
+            st.dataframe(df, width='stretch')
+        elif execution and not execution.get("rows"):
+            st.info("Запрос выполнен успешно. Результат пустой.")
+        elif err:
+            st.error(f"Ошибка выполнения SQL: {err}")
 
         st.session_state.history.append({
             "question": question,
-            "sql":      result.sql,
-            "success":  qr.success if qr else False,
-            "rows":     qr.row_count if qr and qr.success else 0,
+            "sql":      resp.get("sql", ""),
+            "success":  bool(execution),
+            "rows":     execution.get("row_count", 0) if execution else 0,
             "time":     gen_time,
         })
 
-# ──────────── Вкладка: Схема БД ────────────
+
+# ──────────── Tab: Схема БД ────────────
 with tab_schema:
-    if st.session_state.db_connector is None:
+    if st.session_state.schema_tables is None:
         st.info("Подключитесь к базе данных через панель слева.")
     else:
-        connector    = st.session_state.db_connector
         show_samples = st.toggle("Показывать примеры данных", value=True)
-
-        for table in connector.get_schema(include_samples=show_samples):
-            with st.expander(f"{table.name}  —  {len(table.columns)} колонок"):
-                st.code(table.to_ddl(), language="sql")
-                if show_samples and table.sample_rows:
+        for t in st.session_state.schema_tables:
+            with st.expander(f"{t['name']}  —  {len(t['columns'])} колонок"):
+                st.code(t.get("ddl", ""), language="sql")
+                if show_samples and t.get("sample_rows"):
                     import pandas as pd
-                    cols = [c.name for c in table.columns]
+                    cols = [c["name"] for c in t["columns"]]
                     st.caption("Примеры данных:")
                     st.dataframe(
-                        pd.DataFrame(table.sample_rows, columns=cols),
-                        use_container_width=True,
+                        pd.DataFrame(t["sample_rows"], columns=cols),
+                        width='stretch',
                     )
 
-# ──────────── Вкладка: История ────────────
+
+# ──────────── Tab: История ────────────
 with tab_history:
     history = st.session_state.history
     if not history:
@@ -554,7 +550,7 @@ with tab_history:
         with col_h:
             st.markdown(f"**Запросов в сессии: {len(history)}**")
         with col_clr:
-            if st.button("Очистить", use_container_width=True):
+            if st.button("Очистить", width='stretch'):
                 st.session_state.history = []
                 st.rerun()
 

tests/test_db.py

@@ -0,0 +1,132 @@
+"""Тесты на DbConnector и SqlExecutor.
+
+Покрывают чтение схемы SQLite-баз, генерацию DDL и проверку того, что
+SQLite-подключение действительно открывается в режиме read-only —
+модифицирующие операции должны падать с sqlite3.OperationalError.
+"""
+
+import sqlite3
+from pathlib import Path
+
+import pytest
+
+from src.db.connector import DbConnector, TableInfo
+from src.db.executor import QueryResult, SqlExecutor
+
+
+@pytest.fixture
+def tiny_sqlite(tmp_path: Path) -> Path:
+    db = tmp_path / "tiny.sqlite"
+    conn = sqlite3.connect(db)
+    conn.execute(
+        "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, city TEXT)"
+    )
+    conn.executemany(
+        "INSERT INTO users (id, name, city) VALUES (?, ?, ?)",
+        [(1, "Иван", "Казань"), (2, "Анна", "Москва"), (3, "Олег", "Казань")],
+    )
+    conn.commit()
+    conn.close()
+    return db
+
+
+# ──────────────────────────────────────────────────────────────────────
+# DbConnector
+# ──────────────────────────────────────────────────────────────────────
+
+def test_connector_lists_tables(tiny_sqlite: Path):
+    c = DbConnector(str(tiny_sqlite))
+    assert c.list_tables() == ["users"]
+
+
+def test_connector_reads_columns(tiny_sqlite: Path):
+    c = DbConnector(str(tiny_sqlite))
+    tables = c.get_schema(include_samples=False)
+    assert len(tables) == 1
+    table = tables[0]
+    assert isinstance(table, TableInfo)
+    names = [col.name for col in table.columns]
+    assert names == ["id", "name", "city"]
+    # id — primary key, name — NOT NULL
+    pk = next(col for col in table.columns if col.name == "id")
+    assert pk.primary_key is True
+    nn = next(col for col in table.columns if col.name == "name")
+    assert nn.nullable is False
+
+
+def test_connector_renders_ddl(tiny_sqlite: Path):
+    c = DbConnector(str(tiny_sqlite))
+    schema_text = c.render_schema(include_samples=True)
+    assert "CREATE TABLE users" in schema_text
+    assert "PRIMARY KEY" in schema_text
+    # sample-строки прокинуты комментариями
+    assert "Иван" in schema_text or "Олег" in schema_text
+
+
+def test_connector_accepts_sqlite_uri(tiny_sqlite: Path):
+    c = DbConnector(f"sqlite:///{tiny_sqlite}")
+    assert c.list_tables() == ["users"]
+
+
+# ──────────────────────────────────────────────────────────────────────
+# SqlExecutor
+# ──────────────────────────────────────────────────────────────────────
+
+def test_executor_runs_select(tiny_sqlite: Path):
+    ex = SqlExecutor(str(tiny_sqlite))
+    res = ex.run("SELECT id, name FROM users ORDER BY id")
+    assert isinstance(res, QueryResult)
+    assert res.success
+    assert res.columns == ["id", "name"]
+    assert res.row_count == 3
+    assert res.rows[0] == [1, "Иван"]
+
+
+def test_executor_aggregation(tiny_sqlite: Path):
+    ex = SqlExecutor(str(tiny_sqlite))
+    res = ex.run("SELECT city, COUNT(*) AS cnt FROM users GROUP BY city ORDER BY cnt DESC")
+    assert res.success
+    assert res.rows[0] == ["Казань", 2]
+
+
+def test_executor_returns_error_on_bad_sql(tiny_sqlite: Path):
+    ex = SqlExecutor(str(tiny_sqlite))
+    res = ex.run("SELEC nonsense FROM users")
+    assert not res.success
+    assert res.error is not None
+
+
+def test_executor_blocks_modifications(tiny_sqlite: Path):
+    """Ключевая проверка: SQLite-соединение открывается в read-only
+    режиме (URI mode=ro&immutable=1), модифицирующие операции должны
+    падать ошибкой, а не выполняться втихую."""
+    ex = SqlExecutor(str(tiny_sqlite))
+
+    res = ex.run("DELETE FROM users WHERE id = 1")
+    assert not res.success
+    assert res.error is not None
+    assert "read" in res.error.lower() or "readonly" in res.error.lower() \
+        or "только для чтения" in res.error.lower()
+
+    # Подтверждение, что данные не пострадали
+    check = ex.run("SELECT COUNT(*) FROM users")
+    assert check.success
+    assert check.rows == [[3]]
+
+
+def test_executor_blocks_drop_table(tiny_sqlite: Path):
+    ex = SqlExecutor(str(tiny_sqlite))
+    res = ex.run("DROP TABLE users")
+    assert not res.success
+
+    # Подтверждение, что таблица на месте
+    check = ex.run("SELECT COUNT(*) FROM users")
+    assert check.success
+
+
+def test_queryresult_to_markdown(tiny_sqlite: Path):
+    ex = SqlExecutor(str(tiny_sqlite))
+    res = ex.run("SELECT id, name FROM users WHERE id = 1")
+    md = res.to_markdown_table()
+    assert "id" in md and "name" in md
+    assert "Иван" in md

tests/test_postprocess.py

@@ -1,6 +1,12 @@
-"""Тесты на постобработку SQL."""
+"""Тесты на постобработку SQL и связанные функции.
+
+Покрывает раздел 2.5 пояснительной записки: чистку артефактов,
+валидацию через sqlglot, нормализацию для Exact Match и AST-уровневый
+гвардейл is_select_only.
+"""
 
 from src.models.postprocess import (
+    is_select_only,
     is_valid_sql,
     normalize_sql,
     postprocess,
@@ -8,39 +14,165 @@ from src.models.postprocess import (
 )
 
 
-def test_strip_markdown_block():
+# ──────────────────────────────────────────────────────────────────────
+# strip_model_artifacts
+# ──────────────────────────────────────────────────────────────────────
+
+def test_strip_markdown_block_with_lang():
     raw = "```sql\nSELECT * FROM users;\n```"
-    assert strip_model_artifacts(raw).startswith("SELECT")
+    assert strip_model_artifacts(raw).upper().startswith("SELECT")
+
+
+def test_strip_markdown_block_without_lang():
+    raw = "```\nSELECT id FROM t;\n```"
+    assert strip_model_artifacts(raw).upper().startswith("SELECT")
 
 
 def test_strip_sql_prefix():
     raw = "SQL: SELECT 1;"
-    assert strip_model_artifacts(raw).startswith("SELECT")
+    assert strip_model_artifacts(raw).upper().startswith("SELECT")
 
 
-def test_keeps_first_statement():
+def test_strip_russian_prefix():
+    raw = "Ответ: SELECT name FROM students;"
+    assert strip_model_artifacts(raw).upper().startswith("SELECT")
+
+
+def test_strip_natural_language_before_select():
+    raw = "Вот SQL, который отвечает на вопрос: SELECT * FROM t WHERE id = 1;"
+    out = strip_model_artifacts(raw)
+    assert out.upper().startswith("SELECT")
+    assert "Вот" not in out
+
+
+def test_keeps_first_statement_of_two():
     raw = "SELECT 1; SELECT 2;"
     out = strip_model_artifacts(raw)
     assert "SELECT 1" in out
     assert "SELECT 2" not in out
 
 
-def test_valid_sql():
+def test_with_cte_is_preserved():
+    raw = "WITH agg AS (SELECT id FROM t) SELECT * FROM agg"
+    out = strip_model_artifacts(raw)
+    assert out.upper().startswith("WITH")
+
+
+def test_strip_returns_empty_on_garbage():
+    # Нет ни одного SQL-ключевого слова — обрезать нечего, но и пустого
+    # ответа модель ещё не нагенерила: возвращаем как есть, валидация
+    # отсеет дальше по пайплайну.
+    raw = "просто текст без запроса"
+    assert strip_model_artifacts(raw) == "просто текст без запроса"
+
+
+# ──────────────────────────────────────────────────────────────────────
+# is_valid_sql
+# ──────────────────────────────────────────────────────────────────────
+
+def test_valid_select():
     assert is_valid_sql("SELECT * FROM students WHERE id = 1")
 
 
-def test_invalid_sql():
+def test_valid_with_cte():
+    assert is_valid_sql("WITH x AS (SELECT id FROM t) SELECT * FROM x")
+
+
+def test_invalid_garbage():
     assert not is_valid_sql("SELEC * FRM where")
 
 
-def test_normalize_em():
+def test_invalid_empty():
+    assert not is_valid_sql("")
+    assert not is_valid_sql("   ")
+
+
+# ──────────────────────────────────────────────────────────────────────
+# is_select_only — guardrail
+# ──────────────────────────────────────────────────────────────────────
+
+def test_select_passes_guardrail():
+    assert is_select_only("SELECT id FROM t")
+
+
+def test_with_cte_passes_guardrail():
+    assert is_select_only("WITH x AS (SELECT id FROM t) SELECT * FROM x")
+
+
+def test_drop_table_blocked():
+    assert not is_select_only("DROP TABLE users")
+
+
+def test_delete_blocked():
+    assert not is_select_only("DELETE FROM users WHERE id = 1")
+
+
+def test_update_blocked():
+    assert not is_select_only("UPDATE users SET name = 'a' WHERE id = 1")
+
+
+def test_insert_blocked():
+    assert not is_select_only("INSERT INTO users (id, name) VALUES (1, 'a')")
+
+
+def test_empty_blocked():
+    assert not is_select_only("")
+    assert not is_select_only("   ")
+
+
+def test_invalid_sql_blocked_by_guardrail():
+    # На невалидной строке is_select_only должен честно возвращать False,
+    # а не падать с исключением.
+    assert not is_select_only("not a sql at all")
+
+
+# ──────────────────────────────────────────────────────────────────────
+# normalize_sql
+# ──────────────────────────────────────────────────────────────────────
+
+def test_normalize_collapses_whitespace():
     a = "SELECT  *  FROM  Users"
     b = "select * from users"
     assert normalize_sql(a) == normalize_sql(b)
 
 
-def test_postprocess_full():
+def test_normalize_idempotent():
+    sql = "SELECT id FROM t WHERE x = 1"
+    assert normalize_sql(normalize_sql(sql)) == normalize_sql(sql)
+
+
+def test_normalize_fallback_on_invalid():
+    # На невалидном SQL функция не должна падать — должен сработать fallback.
+    out = normalize_sql("not really sql")
+    assert isinstance(out, str)
+    assert out.upper() == out  # верхний регистр сохранён
+
+
+# ──────────────────────────────────────────────────────────────────────
+# postprocess — полный pipeline
+# ──────────────────────────────────────────────────────────────────────
+
+def test_postprocess_extracts_from_markdown():
     raw = "```sql\nSELECT name FROM students WHERE group_id = 1;\nSELECT 2;\n```"
     out = postprocess(raw)
-    assert out.startswith("SELECT name")
+    assert out.upper().startswith("SELECT NAME") or out.startswith("SELECT name")
     assert "SELECT 2" not in out
+
+
+def test_postprocess_returns_empty_on_invalid():
+    # Текст не содержит валидного SQL — pipeline должен вернуть пустую строку,
+    # как описано в разделе 2.5 пояснительной записки.
+    raw = "Я не могу сгенерировать SQL для этого вопроса."
+    assert postprocess(raw) == ""
+
+
+def test_postprocess_returns_empty_on_truncated():
+    # Модель оборвала генерацию на середине запроса — невалидный синтаксис.
+    raw = "SELECT * FROM users WHERE"
+    assert postprocess(raw) == ""
+
+
+def test_postprocess_keeps_valid_with_cte():
+    raw = "WITH agg AS (SELECT id FROM t) SELECT * FROM agg"
+    out = postprocess(raw)
+    assert out.upper().startswith("WITH")

tests/test_prompt.py

@@ -1,8 +1,15 @@
-"""Тесты на PromptBuilder."""
+"""Тесты на PromptBuilder.
 
+Покрывают как базовое формирование chat-template, так и опциональную
+интеграцию BusinessVocabulary в системное сообщение (раздел 3.6 ВКР).
+"""
+
+from src.business.vocabulary import BusinessVocabulary
 from src.data.prompt import (
+    BASE_SYSTEM_PROMPT,
     SYSTEM_PROMPT,
     build_chat_messages,
+    build_system_message,
     build_training_example,
     build_user_message,
 )
@@ -21,7 +28,7 @@ def test_chat_messages_have_system_and_user():
     msgs = build_chat_messages("schema", "question")
     assert len(msgs) == 2
     assert msgs[0]["role"] == "system"
-    assert msgs[0]["content"] == SYSTEM_PROMPT
+    assert msgs[0]["content"] == BASE_SYSTEM_PROMPT
     assert msgs[1]["role"] == "user"
 
 
@@ -30,3 +37,51 @@ def test_training_example_has_assistant():
     assert len(msgs) == 3
     assert msgs[2]["role"] == "assistant"
     assert msgs[2]["content"] == "SELECT 1"
+
+
+def test_legacy_system_prompt_alias():
+    assert SYSTEM_PROMPT == BASE_SYSTEM_PROMPT
+
+
+def test_system_message_without_vocabulary():
+    assert build_system_message(None) == BASE_SYSTEM_PROMPT
+
+
+def test_system_message_with_empty_vocabulary():
+    vocab = BusinessVocabulary.empty()
+    assert build_system_message(vocab) == BASE_SYSTEM_PROMPT
+
+
+def test_system_message_with_terms():
+    vocab = BusinessVocabulary(
+        company="ООО Ромашка",
+        terms={"выручка": "SUM(orders.amount) WHERE orders.status = 'paid'"},
+    )
+    msg = build_system_message(vocab)
+    assert msg.startswith(BASE_SYSTEM_PROMPT)
+    assert "ООО Ромашка" in msg
+    assert "выручка" in msg
+    assert "SUM(orders.amount)" in msg
+
+
+def test_chat_messages_with_vocabulary_keeps_user_clean():
+    vocab = BusinessVocabulary(
+        terms={"выручка": "SUM(amount) WHERE status='paid'"},
+    )
+    msgs = build_chat_messages("schema", "Какая выручка?", vocabulary=vocab)
+    assert msgs[0]["role"] == "system"
+    assert "SUM(amount)" in msgs[0]["content"]
+    assert msgs[1]["role"] == "user"
+    assert "SUM(amount)" not in msgs[1]["content"]
+    assert "Какая выручка?" in msgs[1]["content"]
+
+
+def test_training_example_with_vocabulary():
+    vocab = BusinessVocabulary(terms={"топ": "ORDER BY x DESC LIMIT 10"})
+    msgs = build_training_example(
+        "schema", "Топ клиентов", "SELECT 1", vocabulary=vocab
+    )
+    assert len(msgs) == 3
+    assert msgs[0]["role"] == "system"
+    assert "ORDER BY x DESC" in msgs[0]["content"]
+    assert msgs[2]["role"] == "assistant"

tests/test_schema_provider.py

@@ -0,0 +1,182 @@
+"""Тесты на единый SchemaProvider (раздел 4.2 аудита).
+
+Покрывают обе реализации: SpiderSchemaProvider (структура PAUQ/Spider)
+и ConnectionSchemaProvider (произвольное подключение к SQLite-файлу).
+"""
+
+import sqlite3
+from pathlib import Path
+
+import pytest
+
+from src.data.schema_provider import (
+    ColumnSchema,
+    ConnectionSchemaProvider,
+    SpiderSchemaProvider,
+    TableSchema,
+    render_tables,
+)
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Фикстуры
+# ──────────────────────────────────────────────────────────────────────
+
+@pytest.fixture
+def spider_dir(tmp_path: Path) -> Path:
+    """data/databases/uni/uni.sqlite + data/databases/sales/sales.sqlite."""
+    for db_id in ("uni", "sales"):
+        (tmp_path / db_id).mkdir()
+        db = tmp_path / db_id / f"{db_id}.sqlite"
+        conn = sqlite3.connect(db)
+        conn.execute(f"CREATE TABLE {db_id}_t (id INTEGER PRIMARY KEY, name TEXT NOT NULL)")
+        conn.execute(f"INSERT INTO {db_id}_t VALUES (1, '{db_id}-row')")
+        conn.commit()
+        conn.close()
+    return tmp_path
+
+
+@pytest.fixture
+def tiny_db(tmp_path: Path) -> Path:
+    db = tmp_path / "tiny.sqlite"
+    conn = sqlite3.connect(db)
+    conn.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")
+    conn.executemany("INSERT INTO users VALUES (?, ?)", [(1, "Иван"), (2, "Анна")])
+    conn.commit()
+    conn.close()
+    return db
+
+
+# ──────────────────────────────────────────────────────────────────────
+# TableSchema.to_ddl
+# ──────────────────────────────────────────────────────────────────────
+
+def test_table_schema_to_ddl_from_create_sql():
+    t = TableSchema(
+        name="t",
+        create_sql="CREATE TABLE t (id INT PRIMARY KEY, name TEXT)",
+    )
+    assert t.to_ddl() == "CREATE TABLE t (id INT PRIMARY KEY, name TEXT);"
+
+
+def test_table_schema_to_ddl_from_columns():
+    t = TableSchema(
+        name="users",
+        columns=[
+            ColumnSchema(name="id", type="INTEGER", primary_key=True, nullable=False),
+            ColumnSchema(name="email", type="TEXT", nullable=False),
+        ],
+    )
+    ddl = t.to_ddl()
+    assert ddl.startswith("CREATE TABLE users")
+    assert "id INTEGER PRIMARY KEY NOT NULL" in ddl
+    assert "email TEXT NOT NULL" in ddl
+
+
+# ──────────────────────────────────────────────────────────────────────
+# SpiderSchemaProvider
+# ──────────────────────────────────────────────────────────────────────
+
+def test_spider_lists_databases(spider_dir: Path):
+    p = SpiderSchemaProvider(spider_dir)
+    assert p.list_databases() == ["sales", "uni"]
+
+
+def test_spider_db_path_resolves(spider_dir: Path):
+    p = SpiderSchemaProvider(spider_dir)
+    path = p.db_path("uni")
+    assert path.exists()
+    assert path.name == "uni.sqlite"
+
+
+def test_spider_db_path_raises_on_missing(spider_dir: Path):
+    p = SpiderSchemaProvider(spider_dir)
+    with pytest.raises(FileNotFoundError):
+        p.db_path("nonexistent")
+
+
+def test_spider_get_tables_returns_tableschema(spider_dir: Path):
+    p = SpiderSchemaProvider(spider_dir)
+    tables = p.get_tables("uni")
+    assert len(tables) == 1
+    assert isinstance(tables[0], TableSchema)
+    assert tables[0].name == "uni_t"
+
+
+def test_spider_render_schema_has_create(spider_dir: Path):
+    p = SpiderSchemaProvider(spider_dir)
+    text = p.render_schema("uni")
+    assert "CREATE TABLE" in text
+    assert "uni_t" in text
+
+
+# ──────────────────────────────────────────────────────────────────────
+# ConnectionSchemaProvider
+# ──────────────────────────────────────────────────────────────────────
+
+def test_connection_lists_tables(tiny_db: Path):
+    p = ConnectionSchemaProvider(str(tiny_db))
+    assert p.list_tables() == ["users"]
+
+
+def test_connection_get_tables_columns(tiny_db: Path):
+    p = ConnectionSchemaProvider(str(tiny_db))
+    tables = p.get_tables()
+    assert len(tables) == 1
+    cols = {c.name for c in tables[0].columns}
+    assert cols == {"id", "name"}
+
+
+def test_connection_render_schema_with_samples(tiny_db: Path):
+    p = ConnectionSchemaProvider(str(tiny_db))
+    text = p.render_schema(include_samples=True)
+    assert "CREATE TABLE users" in text
+    assert "Иван" in text or "Анна" in text
+
+
+def test_connection_test_connection(tiny_db: Path):
+    p = ConnectionSchemaProvider(str(tiny_db))
+    assert p.test_connection() is True
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Цепочка SpiderSchemaProvider.for_database → ConnectionSchemaProvider
+# ──────────────────────────────────────────────────────────────────────
+
+def test_spider_for_database_returns_connection_provider(spider_dir: Path):
+    p = SpiderSchemaProvider(spider_dir)
+    sub = p.for_database("sales")
+    assert isinstance(sub, ConnectionSchemaProvider)
+    text = sub.render_schema()
+    assert "sales_t" in text
+
+
+# ──────────────────────────────────────────────────────────────────────
+# render_tables — общая утилита
+# ──────────────────────────────────────────────────────────────────────
+
+def test_render_tables_groups_ddl_and_samples():
+    tables = [
+        TableSchema(
+            name="x",
+            columns=[ColumnSchema(name="id", type="INT")],
+            sample_rows=[(1,), (2,)],
+        ),
+    ]
+    text = render_tables(tables, include_samples=True)
+    assert "CREATE TABLE x" in text
+    assert "Примеры строк" in text
+    assert "(1," in text and "(2," in text
+
+
+def test_render_tables_no_samples():
+    tables = [
+        TableSchema(
+            name="x",
+            columns=[ColumnSchema(name="id", type="INT")],
+            sample_rows=[(1,)],
+        ),
+    ]
+    text = render_tables(tables, include_samples=False)
+    assert "CREATE TABLE x" in text
+    assert "Примеры строк" not in text

tests/test_vocabulary.py

@@ -0,0 +1,123 @@
+"""Тесты на BusinessVocabulary (раздел 3.6 пояснительной записки)."""
+
+from pathlib import Path
+
+import pytest
+
+from src.business.vocabulary import BusinessVocabulary
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Загрузка
+# ──────────────────────────────────────────────────────────────────────
+
+def test_empty_vocabulary_is_falsy():
+    vocab = BusinessVocabulary.empty()
+    assert not vocab
+    assert vocab.render_system_context() == ""
+
+
+def test_from_dict_basic():
+    vocab = BusinessVocabulary.from_dict(
+        {
+            "company": "ООО Тест",
+            "terms": {"выручка": "SUM(amount)"},
+            "filters": {"paid": "status='paid'"},
+            "notes": ["Период: 2025-01-01—2026-04-30"],
+        }
+    )
+    assert bool(vocab)
+    assert vocab.company == "ООО Тест"
+    assert vocab.terms == {"выручка": "SUM(amount)"}
+    assert vocab.filters == {"paid": "status='paid'"}
+    assert vocab.notes == ["Период: 2025-01-01—2026-04-30"]
+
+
+def test_from_yaml_roundtrip(tmp_path: Path):
+    original = BusinessVocabulary(
+        company="ООО Ромашка",
+        terms={"выручка": "SUM(orders.amount)"},
+        filters={"paid_only": "orders.status='paid'"},
+        notes=["amount только в orders"],
+    )
+    path = tmp_path / "vocab.yaml"
+    original.save_yaml(path)
+
+    loaded = BusinessVocabulary.from_yaml(path)
+    assert loaded.company == original.company
+    assert loaded.terms == original.terms
+    assert loaded.filters == original.filters
+    assert loaded.notes == original.notes
+
+
+def test_from_yaml_missing_file(tmp_path: Path):
+    with pytest.raises(FileNotFoundError):
+        BusinessVocabulary.from_yaml(tmp_path / "does_not_exist.yaml")
+
+
+# ──────────────────────────────────────────────────────────────────────
+# enrich_prompt — обратная совместимость со старым Streamlit-кодом
+# ──────────────────────────────────────────────────────────────────────
+
+def test_enrich_prompt_pass_through_when_empty():
+    vocab = BusinessVocabulary.empty()
+    assert vocab.enrich_prompt("Какая выручка?") == "Какая выручка?"
+
+
+def test_enrich_prompt_adds_term_definition():
+    vocab = BusinessVocabulary(
+        terms={"выручка": "SUM(amount) WHERE status='paid'"},
+    )
+    enriched = vocab.enrich_prompt("Какая выручка за январь?")
+    assert "выручка" in enriched
+    assert "SUM(amount)" in enriched
+    assert "Какая выручка за январь?" in enriched
+
+
+def test_enrich_prompt_case_insensitive_match():
+    vocab = BusinessVocabulary(terms={"выручка": "SUM(amount)"})
+    enriched = vocab.enrich_prompt("ВЫРУЧКА в этом месяце?")
+    assert "SUM(amount)" in enriched
+
+
+def test_enrich_prompt_ignores_unrelated_terms():
+    vocab = BusinessVocabulary(
+        terms={
+            "выручка": "SUM(amount)",
+            "топ клиентов": "ORDER BY SUM(amount) DESC",
+        },
+    )
+    enriched = vocab.enrich_prompt("Какая выручка?")
+    # Релевантный термин подмешан, посторонний — нет
+    assert "SUM(amount)" in enriched
+    assert "ORDER BY SUM(amount) DESC" not in enriched
+
+
+# ──────────────────────────────────────────────────────────────────────
+# render_system_context — то, что подмешивается в system-сообщение
+# ──────────────────────────────────────────────────────────────────────
+
+def test_render_system_context_empty():
+    assert BusinessVocabulary.empty().render_system_context() == ""
+
+
+def test_render_system_context_with_company():
+    vocab = BusinessVocabulary(
+        company="ООО Ромашка",
+        terms={"выручка": "SUM(amount)"},
+    )
+    ctx = vocab.render_system_context()
+    assert "ООО Ромашка" in ctx
+    assert "выручка" in ctx
+    assert "SUM(amount)" in ctx
+
+
+def test_render_system_context_with_filters_and_notes():
+    vocab = BusinessVocabulary(
+        filters={"только_оплаченные": "orders.status='paid'"},
+        notes=["amount только в orders"],
+    )
+    ctx = vocab.render_system_context()
+    assert "только_оплаченные" in ctx
+    assert "orders.status='paid'" in ctx
+    assert "amount только в orders" in ctx