improve codebase

README.md

@@ -1,128 +1,92 @@
-# 🤖 PyAgentX: Autonomous Multi-Agent System for Software Development
+# PyAgentX: Продвинутая многоагентная AI-система
 
-**PyAgentX** — это продвинутая система на базе LLM, предназначенная для автоматизации полного цикла разработки программного обеспечения. Она использует команду специализированных ИИ-агентов, которые совместно работают над решением задач: от декомпозиции высокоуровневых целей до написания, проверки, тестирования и оценки кода.
+**PyAgentX** — это фреймворк для создания автономных AI-агентов, способных решать сложные, многошаговые задачи. Система использует архитектуру многоагентной команды, где центральный Оркестратор управляет командой узкоспециализированных агентов для достижения глобальной цели.
 
-Ключевой особенностью системы является **гибридная RAG-система**, которая совмещает семантический и ключевой поиск по базе знаний. Это позволяет агентам генерировать код, соответствующий внутренним стандартам, архитектурным паттернам и лучшим практикам вашей команды.
+Проект основан на самых современных концепциях в области Agentic AI, включая иерархическое планирование, самокоррекцию, продвинутый RAG с переранжированием и долгосрочную память.
 
-## 🚀 Ключевые возможности
+---
 
-- **Динамическая команда агентов**: Система гибко настраивается через YAML-конфиги. Вы можете легко добавлять, удалять или изменять роли агентов.
-- **Продвинутый RAG с гибридным поиском**: Использует комбинацию векторного поиска (семантика) и BM25 (ключевые слова) с Reciprocal Rank Fusion для максимально релевантных результатов из базы знаний.
-- **Динамическая конфигурация**: Все параметры системы, от моделей LLM до настроек RAG для каждого агента, задаются в YAML-файлах в директории `configs/`.
-- **Интерфейс командной строки (CLI)**: Удобный запуск и управление через `main.py` с использованием `typer`.
-- **Самостоятельная регистрация инструментов**: Агенты сами определяют и регистрируют свой инструментарий, что делает систему более модульной и инкапсулированной.
-- **Работа с файловой системой**: Агенты могут читать, создавать и редактировать файлы прямо в вашем проекте.
-- **Надежное тестирование**: Встроенный набор модульных тестов (`pytest`) с использованием моков позволяет проверять логику, не затрагивая реальные API.
+## 🏛️ Ключевые концепции
 
-## 🏛️ Архитектура
+Мы разделили документацию на несколько разделов для удобства:
 
-Система построена на модульных принципах, где каждый компонент имеет четкую зону ответственности.
+1.  [**Архитектура многоагентной системы**](./docs/01_multi_agent_architecture.md): Обзор Оркестратора, Планировщика, Исполнителей и принципов их взаимодействия.
+2.  [**Ядро агента: Цикл ReAct и Рефлексия**](./docs/02_agent_core_loop.md): Описание внутреннего цикла работы каждого агента и механизма самокоррекции при ошибках.
+3.  [**Продвинутый RAG-пайплайн**](./docs/03_advanced_rag.md): Детальное описание нашего двухэтапного RAG с семантическим чанкированием и переранжированием.
+4.  [**Долгосрочная память**](./docs/04_long_term_memory.md): Как агенты запоминают информацию между сессиями для повышения эффективности.
+5.  [**Оценка и Безопасность**](./docs/04_evaluation_and_safety.md): Описание наших собственных легковесных систем для оценки качества и модерации ответов.
 
-```
-PyAgentX/
-├── app/
-│   ├── agents/             # Логика и роли специализированных агентов
-│   │   ├── roles/          # Классы для конкретных ролей (Coding, Testing, etc.)
-│   │   ├── agent.py        # Базовый класс Agent с основной логикой
-│   │   └── tools.py        # Определения инструментов (read_file, edit_file)
-│   ├── factory/            # Фабрика для создания агентов
-│   │   └── agent_factory.py
-│   └── rag/                # Логика для Retrieval-Augmented Generation
-│       └── retriever.py    # Гибридный ретривер (Vector + BM25)
-├── configs/                # Конфигурационные файлы YAML
-│   ├── agents/             # Конфиги для каждого агента
-│   └── config.yaml         # Главный конфигурационный файл
-├── db/                     # Локальная база данных (создается автоматически)
-│   ├── chunks.json         # Текстовые чанки
-│   ├── embeddings.npy      # Векторные эмбеддинги
-│   └── bm25_index.pkl      # Индекс BM25 для ключевого поиска
-├── knowledge/              # Исходники для базы знаний (документация в .md)
-├── scripts/                # Вспомогательные скрипты
-│   └── build_knowledge_base.py
-├── tests/                  # Модульные тесты pytest
-├── .env                    # Файл для секретных ключей
-├── main.py                 # Точка входа в приложение (CLI на Typer)
-├── poetry.lock             # Файл зависимостей Poetry
-├── pyproject.toml          # Конфигурация проекта и зависимостей
-└── README.md
-```
+---
 
-**Логика работы:**
-1.  Пользователь запускает `main.py`, передавая задачу через CLI.
-2.  `agent_factory` читает `configs/config.yaml` и конфигурации агентов, создавая команду.
-3.  `TaskDecomposer` получает задачу и разбивает ее на последовательность шагов.
-4.  `Orchestrator` (в `main.py`) последовательно передает каждый шаг соответствующему агенту.
-5.  Каждый агент перед выполнением задачи может обратиться к `KnowledgeRetriever` для получения релевантного контекста из базы знаний.
-6.  Агент выполняет шаг, используя свои инструменты (`tools.py`).
-7.  Цикл повторяется, пока все шаги не будут выполнены.
+## 🛠️ Технологический стек
 
-## 🛠️ Быстрый старт
+-   **Язык**: Python 3.10+
+-   **LLM API**: OpenAI
+-   **Оркестрация и ядро агентов**: Кастомная реализация
+-   **Семантическое чанкирование**: `semchunk`
+-   **RAG**:
+    -   `unstructured` для парсинга документов
+    -   `rank-bm25` для sparse-поиска
+    -   `numpy` для векторных операций
+    -   `sentence-transformers` для Cross-Encoder Re-ranking
+-   **Долгосрочная память**: `sqlite3`
+-   **Безопасность**: `guardrails-ai`
+-   **Оценка**: `deepeval`, `pytest`
+-   **Зависимости**: `python-dotenv`, `tiktoken`
 
-### 1. Клонирование репозитория
+---
 
+## 🚀 Как запустить
+
+### 1. Установка зависимостей
 ```bash
-git clone https://github.com/your-username/PyAgentX.git
-cd PyAgentX
+pip install -r requirements.txt
 ```
 
 ### 2. Настройка окружения
-
-Проект использует [Poetry](https://python-poetry.org/) для управления зависимостями.
-
-- Установите Poetry (если не установлен):
-  ```bash
-  pip install poetry
-  ```
-- Создайте виртуальное окружение и установите зависимости:
-  ```bash
-  poetry install
-  ```
-
-### 3. Конфигурация
-
-- Создайте файл `.env` в корне проекта, скопировав `.env.example` (если он есть) или создав новый.
-- Добавьте ваш ключ OpenAI:
-  ```
-  OPENAI_API_KEY="sk-..."
-  ```
-
-### 4. Создание базы знаний
-
-Перед первым запуском необходимо проиндексировать вашу документацию из папки `knowledge/`.
-
+Скопируйте `.env.example` в `.env` и укажите ваш `OPENAI_API_KEY`.
 ```bash
-poetry run python -m scripts.build_knowledge_base
+cp .env.example .env
 ```
-Этот шаг нужно повторять только при изменении файлов в папке `knowledge/`.
-
-### 5. Запуск
-
-Запустите главный скрипт, передав ему задачу.
 
+### 3. Создание базы знаний
+Для работы RAG-пайплайна необходимо один раз создать векторную базу знаний из документов в директории `knowledge_base/`.
 ```bash
-poetry run python -m main --briefing "Создай новую функцию в 'app/utils.py' для сложения двух чисел и напиши на нее тест в 'tests/test_utils.py'."
+python -m scripts.build_knowledge_base
 ```
 
-Система начнет выполнение, и вы увидите логи работы агентов в консоли.
-
-## 🧩 Расширение системы
-
-### Добавление нового агента
-
-1.  Создайте новый класс агента в `app/agents/roles/`, унаследовав его от `Agent`.
-2.  В `__init__` нового агента зарегистрируйте необходимые ему инструменты с помощью `self.add_tool()`.
-3.  Создайте для него YAML-конфиг в `configs/agents/`.
-4.  Добавьте нового агента в главный `configs/config.yaml`.
-
-### Добавление нового инструмента
-
-1.  Определите функцию-инструмент и ее JSON-схему в `app/agents/tools.py`.
-2.  Добавьте вызов `self.add_tool()` в `__init__` того агента, который должен использовать этот инструмент.
-
-### Добавление знаний
+### 4. Запуск тестов (Опционально)
+Чтобы убедиться, что все работает корректно:
+```bash
+pytest
+```
 
-Просто добавьте новый `.md` файл в папку `knowledge/` и перезапустите скрипт `scripts/build_knowledge_base.py`.
+### 5. Запуск веб-сервера
+```bash
+uvicorn app.main:app --reload
+```
+После запуска API будет доступно по адресу `http://127.0.0.1:8000/docs`.
 
-## 💡 Следующий шаг: `PROJECT_CONTEXT.md`
+---
 
-Для дальнейшего улучшения согласованности действий агентов планируется внедрение файла `PROJECT_CONTEXT.md`. Это будет "конституция" проекта, содержащая глобальные правила и стандарты, которая будет автоматически добавляться в системный промпт каждого агента.
+## 🏗️ Структура проекта
+```
+PyAgentX/
+├── app/
+│   ├── agents/             # Логика агентов, их роли и инструменты
+│   │   ├── roles/
+│   │   └── prompts/
+│   ├── evaluation/         # Собственный фреймворк оценки
+│   ├── memory/             # Менеджер долгосрочной памяти (SQLite)
+│   ├── rag/                # RAG-пайплайн (ретривер)
+│   ├── safety/             # Собственные "ограждения" (Guardrails)
+│   ├── main.py             # FastAPI приложение
+│   └── orchestrator.py     # Оркестратор
+├── docs/                   # Детальная документация
+├── knowledge_base/         # Исходные документы для базы знаний
+├── scripts/                # Скрипты (например, для создания RAG-базы)
+├── tests/                  # Тесты
+├── .env.example
+├── README.md
+└── requirements.txt
+```