# Домашній файловий агент (Home File Agent)

Повністю самостійно написаний MCP-сервер — з нуля, без стартер-кітів і готових
шаблонів. Навчальний курсовий проєкт: агент, який працює з файлами в одній
заданій локальній папці — шукає за змістом (RAG), читає кілька форматів,
звітує про власний стан. Клієнт — Claude Desktop (MCP-конектор) або власний
`agent_loop.py` (окремо написаний call cycle — доказ розуміння механіки
tool-use циклу, а не готова агентна бібліотека).

## Відео-демонстрація

[Демонстрація функціоналу на YouTube](https://youtu.be/PCZk-YuYZIE)

## Архітектура одним абзацом

Claude (LLM) ↔ MCP-сервер (`server.py`, FastMCP) ↔ локальна папка (файли) +
Voyage AI (ембединги) + Chroma (векторна БД, локальна). Усі операції з
файлами проходять через sandbox-перевірку кореневої папки. Повна архітектурна
схема — окремо, у Draw.io (додається до захисту).

## Джерела даних

| Джерело | Роль | Де живе |
|---|---|---|
| Локальна папка (`AGENT_ROOT_DIR`) | Основні дані користувача (txt, md, pdf, docx, xml, xlsx, xls) | На диску користувача |
| Voyage AI (`voyage-4-lite`) | Ембединги для семантичного пошуку | Зовнішній API |
| Chroma | Векторна БД для RAG-пошуку | Локально, `.chroma_index/` |

## Встановлення

```powershell
cd C:\Home_agen_LLM
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

## Налаштування оточення

Створи `.env`:

ANTHROPIC_API_KEY=<потрібен лише для agent_loop.py, не для Claude Desktop>
VOYAGE_API_KEY=<з voyageai.com>
AGENT_ROOT_DIR=C:\Home_agen_LLM\test_data

## Локальний запуск через Claude Desktop (основний спосіб)

1. Settings → Developer → Edit Config у Claude Desktop.
2. Додай у `claude_desktop_config.json`:
```json
   {
     "mcpServers": {
       "home-file-agent": {
         "command": "C:\\Home_agen_LLM\\venv\\Scripts\\python.exe",
         "args": ["C:\\Home_agen_LLM\\server.py"],
         "env": {
           "AGENT_ROOT_DIR": "C:\\Home_agen_LLM\\test_data",
           "VOYAGE_API_KEY": "<ключ>"
         }
       }
     }
   }
```
3. Повний вихід із Claude Desktop і повторний запуск.
4. У чаті: "Проіндексуй мою папку", потім будь-яке питання по вмісту.

## Локальний запуск через власний цикл (`agent_loop.py`, ДЗ1-доказ)

```powershell
python agent_loop.py
```
Потребує `ANTHROPIC_API_KEY` в `.env`.

## Доступні tools

- `list_folder(path="")` — список файлів/підпапок
- `read_file(path)` — вміст файлу (txt, md, pdf, docx, xml, xlsx, xls)
- `reindex()` — перебудова RAG-індексу (запускати після зміни файлів)
- `search_files(query, top_k=5)` — семантичний пошук
- `status()` — стан індексу (для моніторингу)

## Тести

```powershell
pip install pytest pytest-asyncio ruff
pytest tests/ -v
ruff check .
```

## Docker / хмарний варіант

```powershell
docker build -t home-file-agent .
docker run -i -p 8080:8080 `
  -e VOYAGE_API_KEY=<ключ> `
  -e AGENT_ROOT_DIR=/data `
  -v C:\Home_agen_LLM\test_data:/data `
  home-file-agent
```

## Моніторинг

- `agent.log` — структуровані логи (без вмісту файлів)
- `python check_health.py` — перевірка свіжості індексу й аномалій у логах (exit code 0/1)
- tool `status()` — те саме, але прямо з чату

## Безпека

Детально — у `PROMPT_BOOK.md`. Коротко: read-only, sandbox на кореневу папку,
allowlist розширень, ліміт розміру файлу, rate limiting, приховані файли
недоступні, логи без вмісту.