feat: solution for '8. Самописный поисковый агент на основе deep agents from scratch'

README.md

@@ -2,97 +2,94 @@
 
 ## Описание
 
-Это простая реализация поискового агента, использующего трансформерный энкодер для векторизации документов и запросов. Поиск осуществляется по косинусному сходству между векторами.
+Данный репозиторий содержит простую реализацию поискового агента, построенного с нуля с использованием глубоких нейронных сетей. Агент:
 
-## Структура проекта
+- **Преобразует** запросы и документы в TF‑IDF векторы.
+- **Обучается** на паре запрос‑документ с метками релевантности, используя логистическую регрессию (один линейный слой).
+- **Оценивает** точность и полноту на тестовом наборе.
+- **Возвращает** топ‑k наиболее релевантных документов для любого запроса.
 
-```
-src/
-├── index.py          # Основной код агента и API
-data/
-└── documents.txt     # Текстовый файл с документами (один документ на строку)
-README.md
-```
+### Технологии
 
-> **Важно**: файл `data/documents.txt` должен существовать и содержать хотя бы несколько строк текста. Если его нет, агент не запустится.
+- Python 3.8+
+- PyTorch
+- scikit‑learn
+- NumPy
 
 ## Установка
 
 ```bash
+# Клонируйте репозиторий
+git clone https://git.brojs.ru/kuzakhmetovartur/8.-samopisnyy-poiskovyy-agent-na-osnove.git
+cd 8.-samopisnyy-poiskovyy-agent-na-osnove
+
 # Создайте виртуальное окружение (рекомендуется)
 python -m venv venv
 source venv/bin/activate   # Windows: venv\Scripts\activate
 
 # Установите зависимости
-pip install -U pip
-pip install torch transformers fastapi uvicorn pydantic numpy
+pip install -r requirements.txt
 ```
 
-> Если у вас есть GPU, убедитесь, что установлена версия `torch` с поддержкой CUDA.
+`requirements.txt` содержит:
 
-## Запуск
+```
+torch>=1.7.0
+scikit-learn>=0.24
+numpy>=1.19
+```
+
+## Использование
+
+### Демонстрация
 
 ```bash
 python src/index.py
 ```
 
-Сервер будет доступен по адресу `http://0.0.0.0:8000`.
+Вы увидите вывод обучения, оценку точности/полноты и пример поиска.
 
-## API
-
-### POST `/search`
-
-**Запрос**
-
-```json
-{
-  "query": "пример запроса",
-  "top_k": 5
-}
-```
-
-- `query` – строка запроса.
-- `top_k` – количество возвращаемых документов (по умолчанию 5).
-
-**Ответ**
-
-```json
-{
-  "results": [
-    {
-      "document": "текст найденного документа",
-      "score": 0.8723
-    },
-    ...
-  ]
-}
-```
-
-## Пример использования
-
-```bash
-curl -X POST "http://0.0.0.0:8000/search" \
-     -H "Content-Type: application/json" \
-     -d '{"query":"машинное обучение", "top_k":3}'
-```
-
-## Как добавить документы
-
-1. Откройте файл `data/documents.txt`.
-2. Добавьте новые строки – каждая строка будет рассматриваться как отдельный документ.
-3. Перезапустите сервер, чтобы обновления вступили в силу.
-
-## Тесты
-
-Тестов в проекте нет, но вы можете быстро проверить работу:
+### Интеграция в свой проект
 
 ```python
 from src.index import SearchAgent
 
-agent = SearchAgent()
-print(agent.search("пример", top_k=3))
+documents = [
+    "Документ 1",
+    "Документ 2",
+    # ...
+]
+
+agent = SearchAgent(documents)
+
+# Обучаем
+queries = ["Какой вопрос?", "Что такое AI?"]
+relevance = [[0], [1]]  # индексы релевантных документов
+agent.train_agent(queries, relevance, epochs=10)
+
+# Оцениваем
+precision, recall = agent.evaluate(queries, relevance)
+
+# Поиск
+results = agent.search("Новый запрос", top_k=3)
+for doc, score in results:
+    print(f"{score:.4f} - {doc}")
 ```
 
+## Тесты
+
+Тесты находятся в `tests/` (если добавлены). Запуск:
+
+```bash
+pytest tests/
+```
+
+## Ограничения
+
+- Модель использует только один линейный слой, поэтому не может захватывать сложные взаимосвязи.
+- Размерность TF‑IDF может быть большой; для больших наборов данных стоит использовать более эффективные методы векторизации.
+- В примере используется синтетический набор данных; для реальных задач потребуется более крупный датасет и более сложная модель.
+
 ## Лицензия
 
 MIT License