# HW RAG + MCP Knowledge Base

Проект строит базу знаний, индексирует ее в Chroma и открывает поиск по базе через MCP-инструмент `search_docs`.

## 1. Установка зависимостей

```bash
cd hw_rag_mcp
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

## 2. Переменные окружения

Создайте `.env` из примера:

```bash
cp .env.example .env
```

Заполните `.env`:

```text
GIGACHAT_CREDENTIALS=...
GIGACHAT_SCOPE=GIGACHAT_API_PERS
GIGACHAT_MODEL=GigaChat-2-Max
GIGACHAT_EMBEDDINGS=EmbeddingsGigaR
SOURCE_FETCH_TIMEOUT=30
```

## 3. Подготовка корпуса

Корпус скачивается автоматически в `src/ingest.py` из открытых источников:

1. PDF Банка России: кодекс этики ИИ на финансовом рынке.
2. Web-страница Банка России: искусственный интеллект на финансовом рынке.
3. Wikipedia: статья "Искусственный интеллект".
4. Wikipedia: статья "Искусственный интеллект в проектах Викимедиа".

Дополнительно скачивать файлы вручную не нужно.

## 4. Разбиение и индексация

Запустите ingestion:

```bash
python src/ingest.py
```

Скрипт:

1. скачивает корпус;
2. очищает текст;
3. разбивает документы на фрагменты;
4. добавляет метаданные `document_id`, `chunk_id`, `source`;
5. считает embeddings через `EmbeddingsGigaR`;
6. сохраняет индекс в Chroma collection `course_rag`.

После успешного запуска появится папка:

```text
data/chroma_db/
```

## 5. Запуск MCP-сервера

MCP-сервер находится в `src/mcp_server.py`.

```bash
python src/mcp_server.py
```

Сервер использует stdio transport. В обычном сценарии его запускает MCP-клиент, например `src/agent_demo.py`.

Пример MCP-конфигурации:

```json
{
  "knowledge_base": {
    "transport": "stdio",
    "command": "python3",
    "args": ["src/mcp_server.py"]
  }
}
```

Публикуемые возможности:

- resource `kb://corpus/stats`;
- tool `search_docs(query, k)`;
- tool `search_by_source(source_id, query, k)`.

## 6. Демонстрационный запрос

Проверка поиска напрямую через Chroma:

```bash
python src/search_demo.py --k 3
```

Проверка поиска через агента и MCP:

```bash
python src/agent_demo.py
```

В выводе `agent_demo.py` должно быть видно:

1. MCP tools загружены;
2. агент вызвал `search_docs`;
3. результат содержит top-k фрагменты с `document_id`, `chunk_id`, `source` и `score`.

## 7. Проверка на 15 запросах

Список запросов:

```text
eval/eval_queries.csv
```

Запуск проверки:

```bash
python src/eval_search.py
```

Скрипт создает:

```text
eval/eval_results.jsonl
eval/eval_report.md
```

`eval_report.md` содержит top-k результаты, ожидаемый источник, признак попадания в top-3 и краткую ручную оценку.