Orchestrator

README.md

@@ -1,33 +1,56 @@
-# PyAgentX 🤖
+# 🤖 Autonomous Multi-Agent System for Software Development
 
-**PyAgentX** — это модульный и расширяемый AI-агент на Python, созданный для взаимодействия с вашей файловой системой. Он может читать, создавать, редактировать и удалять файлы, а также просматривать структуру директорий, что делает его мощным помощником для разработчиков и автоматизации рутинных задач.
+**Autonomous Multi-Agent System** — это продвинутая система на базе LLM, предназначенная для автоматизации полного цикла разработки программного обеспечения. Она использует команду специализированных ИИ-агентов, которые совместно работают над решением задач: от декомпозиции высокоуровневых целей до написания, проверки, тестирования и оценки кода.
 
-Агент использует современные LLM от OpenAI и легко расширяется новыми инструментами для выполнения практически любых задач.
+Ключевой особенностью системы является **интеграция с корпоративной базой знаний (RAG)**, что позволяет агентам генерировать код, соответствующий внутренним стандартам, архитектурным паттернам и лучшим практикам вашей команды.
 
 ## 🚀 Основные возможности
 
-- **Работа с файлами:** Чтение, запись, удаление и листинг файлов и директорий.
-- **Модульная архитектура:** Легко добавляйте новые инструменты (функции), расширяя возможности агента.
-- **Интерактивный чат:** Общайтесь с агентом в режиме реального времени через консоль.
-- **Интеграция с OpenAI:** Использует мощные модели (GPT-4o и другие) для принятия решений.
-- **Защита от зацикливания:** Встроенный механизм для предотвращения бесконечных вызовов инструментов.
-- **Простота настройки:** Использует `.env` для конфигурации и стандартный `requirements.txt` для зависимостей.
+- **Многоагентная архитектура:** Система включает в себя различных агентов и компоненты:
+  - **`TaskDecomposer`**: Планировщик, который анализирует высокоуровневую цель и разбивает ее на выполнимые подзадачи.
+  - **`CodingAgent`**: Пишет код для реализации конкретной функциональности.
+  - **`ReviewerAgent`**: Проверяет сгенерированный код на соответствие стандартам и наличие ошибок, **используя данные из базы знаний (RAG)**.
+  - **`TestingAgent`**: Запускает тесты для проверки кода (в будущем будет создавать их).
+  - **`EvaluatorAgent`**: Оценивает общее качество решения и его соответствие первоначальной цели.
+  - **`Orchestrator`**: Управляет потоком задач между агентами, обеспечивая их слаженную работу.
+- **Интеграция с Базой Знаний (RAG):** Агенты используют Retrieval-Augmented Generation для доступа к внутренней документации, гайдам по стилю и примерам кода, что обеспечивает консистентность и высокое качество результата.
+- **Надежное тестирование:** Встроенный набор модульных тестов с использованием моков позволяет проверять логику, не затрагивая реальные API.
+- **Работа с файловой системой:** Агенты могут читать, создавать и редактировать файлы прямо в вашем проекте.
+- **Модульность и расширяемость:** Легко добавляйте новых агентов и инструменты для расширения функциональности.
+- **Простота настройки:** Использует `.env` для конфигурации и `requirements.txt` для зависимостей.
+
+## 🧠 Архитектура с Базой Знаний (RAG)
+
+Система использует подход Retrieval-Augmented Generation (RAG) для "заземления" ответов и действий агентов на основе релевантного контекста из вашей собственной базы знаний.
+
+Это решает ключевую проблему LLM — отсутствие знаний о специфике вашего проекта.
+
+### Как это работает?
+
+1.  **Наполнение Базы Знаний:** Вы добавляете внутреннюю документацию (стандарты кодирования, архитектурные гайды, примеры кода в формате `.md`) в папку `knowledge/`.
+2.  **Индексация:** Вы запускаете скрипт `scripts/build_knowledge_base.py`. Он обрабатывает документы, разбивает их на смысловые фрагменты (чанки), векторизует с помощью OpenAI API и сохраняет в локальную векторную базу данных в папке `db/`.
+3.  **Извлечение контекста:** Когда агент (например, `ReviewerAgent`) получает задачу, он сначала делает семантический поиск по базе знаний, чтобы найти наиболее релевантную информацию.
+4.  **Обогащение промпта:** Найденные фрагменты документации добавляются в системный промпт агента.
+5.  **Генерация с контекстом:** Агент выполняет свою задачу (например, пишет ревью на код), основываясь не только на своих общих знаниях, но и на предоставленных ему внутренних правилах и стандартах.
+
+Этот механизм гарантирует, что генерируемый код и ревью будут соответствовать принятым в вашей команде практикам.
 
 ## 🛠️ Быстрый старт
 
 ### 1. Клонирование репозитория
 
 ```bash
 git clone <URL-вашего-репозитория>
-cd PyAgentX # или название вашей папки
+cd <название-папки-проекта>
 ```
 
 ### 2. Настройка окружения
 
 - Создайте и активируйте виртуальное окружение:
   ```bash
-  python3 -m venv .venv
+  python -m venv .venv
   source .venv/bin/activate
+  # Для Windows: .venv\Scripts\activate
   ```
 - Установите зависимости:
   ```bash
@@ -36,64 +59,77 @@ cd PyAgentX # или название вашей папки
 
 ### 3. Конфигурация
 
-- Скопируйте `.env.example` в `.env`:
-  ```bash
-  cp .env.example .env
-  ```
+- Создайте файл `.env` в корне проекта.
 - Откройте файл `.env` и вставьте ваш ключ OpenAI:
   ```
   OPENAI_API_KEY="sk-..."
-  # Вы можете указать любую модель, поддерживающую function calling
-  OPENAI_MODEL="gpt-4o" 
   ```
 
-### 4. Запуск агента
+### 4. Создание базы знаний
 
+Перед первым запуском необходимо проиндексировать вашу документацию.
 ```bash
-python -m app.main
+python scripts/build_knowledge_base.py
 ```
+Этот шаг нужно повторять только при изменении файлов в папке `knowledge/`.
 
-Теперь вы можете общаться с агентом прямо в терминале!
-
-## 💡 Примеры использования
+### 5. Запуск
 
-Вот несколько сценариев, которые вы можете попробовать:
-
-- **Посмотреть структуру проекта:**
-  > *покажи мне все файлы в проекте*
+Запустите главный скрипт:
+```bash
+python main.py
+```
 
-- **Прочитать содержимое файла:**
-  > *что находится в файле app/main.py?*
+После запуска система попросит вас ввести высокоуровневую цель.
 
-- **Создать новый файл:**
-  > *создай файл `notes.txt` с текстом "Это моя первая заметка."*
+## ✅ Тестирование
 
-- **Решить загадку из файла:**
-  > *прочитай файл `secret-file.txt` и скажи мне ответ на загадку*
+Проект содержит набор модульных тестов для проверки ключевой логики без реальных вызовов к API OpenAI. Это достигается за счет использования **мок-объектов**.
 
-- **Удалить файл:**
-  > *удали `notes.txt`*
+Для запуска тестов выполните команду:
+```bash
+pytest -v
+```
+Все тесты должны пройти успешно, что гарантирует работоспособность `ReviewerAgent` и `KnowledgeRetriever`.
 
 ## 🏛️ Архитектура проекта
 
 ```
-PyAgentX/
+agent-ai/
 ├── app/
+│   ├── agents/             # Логика и роли специализированных агентов
+│   │   ├── roles/
+│   │   │   ├── reviewer_agent.py
+│   │   │   └── ...
+│   │   ├── agent.py          # Базовый класс агента
+│   │   └── tools.py          # Инструменты, доступные агентам
+│   ├── orchestration/      # Управление взаимодействием агентов
+│   │   └── orchestrator.py
+│   └── rag/                # Логика для Retrieval-Augmented Generation
+│       └── retriever.py
+├── db/                     # Локальная векторная база данных (создается автоматически)
+│   ├── chunks.json
+│   └── embeddings.npy
+├── knowledge/              # Папка для внутренней документации (источник для RAG)
+│   └── ...
+├── scripts/                # Вспомогательные скрипты
+│   └── build_knowledge_base.py
+├── tests/                  # Модульные тесты
 │   ├── agents/
-│   │   ├── agent.py      # Основная логика агента, цикл общения
-│   │   └── tools.py      # Определения всех инструментов (read, list, edit)
-│   └── main.py         # Точка входа в приложение
-├── .env                # Конфигурация (ключи, модель)
-├── .gitignore
-├── requirements.txt
+│   │   └── test_reviewer_agent.py
+│   └── rag/
+│       └── test_retriever.py
+├── .env                    # Файл для секретных ключей (необходим для запуска)
+├── main.py                 # Главная точка входа в приложение
+├── requirements.txt        # Список зависимостей Python
 └── README.md
 ```
 
 ## 🧩 Как добавить новый инструмент
 
 1.  **Определите функцию:** Откройте `app/agents/tools.py` и создайте новую Python-функцию, которая будет выполнять нужное действие (например, `run_command_tool`).
-2.  **Создайте `ToolDefinition`:** В том же файле создайте экземпляр класса `ToolDefinition`, описав ваш инструмент (имя, описание, схема аргументов) и связав его с функцией.
-3.  **Зарегистрируйте инструмент:** Откройте `app/main.py`, импортируйте ваше новое определение инструмента и добавьте его в список `tools` при создании агента.
+2.  **Создайте определение инструмента (`Tool`):** В том же файле создайте словарь (`tool definition`), описывающий ваш инструмент (имя, описание, схема аргументов).
+3.  **Зарегистрируйте инструмент:** Откройте `main.py`, импортируйте вашу функцию и ее определение, а затем добавьте их к нужному агенту с помощью метода `add_tool()`.
 
 Готово! Агент автоматически сможет использовать ваш новый инструмент.
 

app/__init__.py

@@ -0,0 +1,2 @@
+# Этот файл может быть пустым.
+# Он нужен, чтобы Python рассматривал директорию 'app' как пакет.