🧠 Интеллектуальный исследовательский агент с адаптивным планированием и автоматическим цитированием

SGR Research Agent - это интеллектуальный исследовательский агент, основанный на принципах Schema-Guided Reasoning (SGR) с возможностями адаптивного планирования. Система предназначена для проведения глубоких исследований с автоматическим управлением цитированием и многоязычной поддержкой.

📄 Посмотрите пример готового отчета →

flowchart TD
    A["👤 Пользователь вводит запрос"] --> B{🤔 Запрос неясен?}
    
    B -->|Да| C["❓ Clarification<br/>Запрос уточнений"]
    C --> D["💬 Ответ пользователя"]
    D --> E["📋 GeneratePlan<br/>Создание плана"]
    
    B -->|Нет| E
    
    E --> F["🔍 WebSearch<br/>Поиск информации"]
    F --> G{📊 Данные противоречат плану?}
    
    G -->|Да| H["🔄 AdaptPlan<br/>Адаптация плана"]
    H --> I{💾 Достаточно данных?}
    
    G -->|Нет| I
    I -->|Нет| F
    I -->|Да| J["📄 CreateReport<br/>Создание отчета с цитатами"]
    
    J --> K["✅ ReportCompletion<br/>Завершение"]
    K --> L["💾 Сохранение в MD файл"]
    
    style C fill:#ffeb3b
    style H fill:#ff9800
    style J fill:#4caf50
    style K fill:#2196f3

# 1. Клонируйте репозиторий
git clone https://github.com/vakovalskii/sgr-deep-research.git
cd sgr-deep-research

# 2. Установите зависимости
pip install -r requirements.txt

# 3. Настройте конфигурацию
cp config.yaml.example config.yaml
# Отредактируйте config.yaml, добавив ваши API ключи

# 4. Запустите агента
python3 sgr-deep-research.py

• 🤔 Clarification-First подход: Приоритет уточнений при любой неопределенности
• 🔄 Адаптивное планирование: Автоматическая корректировка плана при обнаружении противоречий
• 📎 Автоматическое цитирование: Управление источниками и нумерацией ссылок
• 🌍 Многоязычность: Поддержка русского и английского языков
• 🛡️ Анти-цикличность: Защита от бесконечных циклов уточнений
• 📊 Структурированные отчеты: Детальные отчеты с цитатами в формате Markdown

1. SGR Schemas - Структурированные схемы для каждого типа действий
2. NextStep Engine - Ядро адаптивного планирования
3. Dispatch System - Система выполнения команд
4. Context Management - Управление состоянием и контекстом
5. Multi-language Support - Поддержка множественных языков

class Clarification(BaseModel):
    tool: Literal["clarification"]
    reasoning: str                    # Обоснование необходимости уточнения
    unclear_terms: List[str]          # Неясные термины
    questions: List[str]              # 3-5 уточняющих вопросов
    assumptions: List[str]            # Возможные интерпретации

class GeneratePlan(BaseModel):
    tool: Literal["generate_plan"]
    reasoning: str                    # Обоснование подхода к исследованию
    research_goal: str                # Основная цель исследования
    planned_steps: List[str]          # 3-4 запланированных шага
    search_strategies: List[str]      # Стратегии поиска информации

class WebSearch(BaseModel):
    tool: Literal["web_search"]
    reasoning: str                    # Обоснование необходимости поиска
    query: str                        # Поисковый запрос (на языке пользователя)
    max_results: int = 10             # Максимальное количество результатов
    plan_adapted: bool = False        # Поиск после адаптации плана

class AdaptPlan(BaseModel):
    tool: Literal["adapt_plan"]
    reasoning: str                    # Обоснование необходимости адаптации
    original_goal: str                # Исходная цель исследования
    new_goal: str                     # Обновленная цель
    plan_changes: List[str]           # Конкретные изменения в плане
    next_steps: List[str]             # Обновленные оставшиеся шаги

class CreateReport(BaseModel):
    tool: Literal["create_report"]
    reasoning: str                    # Обоснование готовности к созданию отчета
    title: str                        # Заголовок отчета
    content: str                      # Детальное содержание (800+ слов) с цитатами
    confidence: Literal["high", "medium", "low"]  # Уровень уверенности

class ReportCompletion(BaseModel):
    tool: Literal["report_completion"]
    reasoning: str                    # Обоснование завершения исследования
    completed_steps: List[str]        # Сводка выполненных шагов
    status: Literal["completed", "failed"]  # Статус завершения

Центральная схема, определяющая следующий шаг в процессе исследования:

class NextStep(BaseModel):
    # Анализ и оценка состояния
    current_situation: str            # Анализ текущей ситуации
    plan_status: str                  # Статус выполнения плана
    
    # Логика адаптивного планирования
    new_data_conflicts_plan: bool     # Конфликтуют ли новые данные с планом
    
    # Отслеживание прогресса
    searches_done: int                # Количество выполненных поисков
    enough_data: bool                 # Достаточно ли данных для отчета
    
    # Планирование следующих шагов
    remaining_steps: List[str]        # 1-3 оставшихся шага
    task_completed: bool              # Завершена ли исследовательская задача
    
    # Маршрутизация инструментов с приоритетом уточнений
    function: Union[
        Clarification,      # ПЕРВЫЙ ПРИОРИТЕТ: При неопределенности
        GeneratePlan,       # ВТОРОЙ: Когда запрос ясен
        WebSearch,          # Основной инструмент исследования
        AdaptPlan,          # При конфликте данных с планом
        CreateReport,       # При достаточном количестве данных
        ReportCompletion    # Завершение задачи
    ]

1. 🤔 Clarification (ВЫСШИЙ ПРИОРИТЕТ)

   • При любой неопределенности в запросе
   • Неизвестные термины, акронимы, аббревиатуры
   • Неоднозначные запросы с множественными интерпретациями
   • Отсутствие контекста для специализированных областей

2. 📋 GeneratePlan

   • Когда план не существует и запрос ясен
   • После получения уточнений от пользователя

3. 🔄 AdaptPlan

   • Когда новые данные противоречат текущему плану
   • При обнаружении неточностей в первоначальных предположениях

4. 🔍 WebSearch

   • Когда нужна дополнительная информация
   • Обычно 2-3 поиска на исследование

5. 📄 CreateReport

   • При достаточном количестве данных (2+ поиска)
   • Когда собрана информация для полного анализа

6. ✅ ReportCompletion

   • После создания отчета
   • Финализация исследования

• Максимум 1 запрос уточнения на сессию
• Флаг clarification_used предотвращает повторные уточнения
• Принудительное продолжение при попытке циклирования

• Активное изменение плана при обнаружении новых данных
• Отслеживание конфликтов между планом и фактами
• Гибкая корректировка целей исследования

CONTEXT = {
    "plan": None,                    # Текущий план исследования
    "searches": [],                  # История поисков
    "sources": {},                   # Источники: url -> citation_number
    "citation_counter": 0,           # Счетчик цитат
    "clarification_used": False      # Флаг использования уточнения
}

• Каждый источник получает уникальный номер
• Автоматическое форматирование ссылок в отчете
• Сохранение метаданных источников (заголовок, URL)

Система автоматически адаптируется к языку пользователя через системный промпт:

• Автоматическое определение языка: LLM сам определяет язык запроса пользователя
• Поисковые запросы: Выполняются на том же языке, что и запрос пользователя
• Отчеты: Создаются полностью на языке пользователя
• Уточнения: Задаются на языке исходного запроса

Никаких дополнительных настроек не требуется - просто пишите на удобном вам языке!

Полный пример сгенерированного отчета доступен в файле example_report.md. Этот отчет демонстрирует:

• Структурированный анализ с четкими разделами
• Автоматическое цитирование всех источников
• Многоязычность (отчет на русском языке)
• Техническую глубину с конкретными примерами
• Качественные выводы на основе найденной информации
• Правильную интеграцию цитат внутри предложений

Отчет был создан по запросу "SGR в LLM" и показывает, как система обрабатывает неоднозначные запросы, проводит исследование и формирует структурированные выводы.

openai:
  api_key: "your-openai-api-key"
  base_url: "https://api.openai.com/v1"  # Опционально
  model: "gpt-4o-mini"
  max_tokens: 8000
  temperature: 0.4

tavily:
  api_key: "your-tavily-api-key"

search:
  max_results: 10

execution:
  max_steps: 6
  reports_dir: "reports"

• OPENAI_API_KEY - Ключ API OpenAI
• OPENAI_BASE_URL - Базовый URL (опционально)
• OPENAI_MODEL - Модель для использования
• TAVILY_API_KEY - Ключ API Tavily
• MAX_TOKENS - Максимальное количество токенов
• TEMPERATURE - Температура генерации
• MAX_SEARCH_RESULTS - Максимальное количество результатов поиска
• MAX_EXECUTION_STEPS - Максимальное количество шагов выполнения
• REPORTS_DIRECTORY - Директория для сохранения отчетов

# Установка всех зависимостей из файла
pip install -r requirements.txt

# Или установка вручную
pip install openai tavily-python pydantic rich pyyaml

• sgr-deep-research.py - Основная версия SGR Research Agent (production-ready)
• config.yaml.example - Шаблон конфигурации
• requirements.txt - Список зависимостей Python
• example_report.md - Пример сгенерированного отчета
• README.md - Документация проекта
• .gitignore - Исключения для Git (включая config.yaml)
• reports/ - Директория для сохранения отчетов

1. Скопируйте config.yaml.example в config.yaml и заполните API ключи
2. Или установите переменные окружения
3. Убедитесь, что директория reports существует

python3 sgr-deep-research.py

🔍 Enter research task: SGR в LLM

🤔 CLARIFICATION NEEDED
💭 Reason: Аббревиатура "SGR" может иметь множественные интерпретации...

CLARIFYING QUESTIONS:
   1. Что означает аббревиатура "SGR" в контексте вашего запроса?
   2. Какой аспект применения SGR в LLM вас интересует больше всего?
   ...

💬 Your clarification response: Schema-Guided Reasoning - методология структурированного рассуждения в больших языковых моделях

🔍 Enter research task: Analyze the latest developments in transformer architecture optimization

📋 Research Plan Created:
🎯 Goal: Analyze recent developments in transformer architecture optimization
📝 Steps: 4
   1. Search for recent papers on transformer optimization
   2. Investigate new architectural improvements
   3. Analyze performance benchmarks
   4. Synthesize findings into comprehensive report

Отчеты сохраняются в формате Markdown с следующей структурой:

# Заголовок отчета

*Created: 2024-08-26 12:34:56*

## Executive Summary
Краткое изложение основных выводов...

## Technical Analysis
Детальный технический анализ с интегрированными цитатами. SGR помогает LLM создавать структурированные выводы [1], улучшая качество рассуждений [2]...

## Key Findings
Ключевые находки исследования...

## Conclusions
Выводы и рекомендации...

## Источники
[1] Название статьи - https://example.com/article1
[2] Другой источник - https://example.com/article2
[3] Третий источник - https://example.com/article3

• OpenAI: Взаимодействие с языковыми моделями
• Tavily: Веб-поиск с фокусом на достоверность
• Pydantic: Валидация схем и структурированные ответы
• Rich: Красивый консольный интерфейс
• PyYAML: Обработка конфигурационных файлов

• Schema-First: Все действия определяются через Pydantic схемы
• Functional Programming: Избегание классов, функциональный подход
• Immutable Context: Контекст изменяется только через определенные функции
• Error Resilience: Graceful обработка ошибок API и сети
• Logging: Подробное логирование всех операций

1. Структурированность: Каждое действие четко определено схемой
2. Предсказуемость: Ясная логика выбора следующего шага
3. Адаптивность: Способность изменять план на основе новых данных
4. Прозрачность: Все решения обоснованы и логируются
5. Масштабируемость: Легко добавлять новые типы действий
6. Надежность: Встроенные механизмы защиты от циклов

• Новые источники данных: Интеграция с базами данных, API
• Дополнительные языки: Расширение многоязычной поддержки
• Специализированные схемы: Схемы для конкретных доменов
• Веб-интерфейс: GUI для более удобного взаимодействия
• Коллаборативность: Поддержка совместной работы
• Экспорт: Различные форматы отчетов (PDF, DOCX, HTML)

Этот проект распространяется под лицензией MIT.