🏦 AI for Finance: RAG Agentic Framework

🌟 Обзор

Это репозиторий продвинутого RAG-агента, разработанного в рамках хакатона AI for Finance Hack 2025. Наше решение — это не просто чат-бот, а полноценный фреймворк для построения надежных и точных ассистентов, способных решать сложные, многоэтапные ("multi-hop") вопросы.

Система показала высокую производительность, обрабатывая 500 вопросов в среднем за ~15 минут и укладываясь в ~10% от выделенного API-бюджета, при этом генерируя ответы экспертного качества.

Ключевые особенности:

• Агентская Архитектура (FAIR-RAG): Система работает в итеративном цикле, анализируя полноту информации и уточняя поиск.
• Гибридный Поиск (Ensemble Retriever): Использует 4-головый поисковый движок для максимальной полноты и точности.
• Управляемые Стратегии: Поддерживает несколько режимов работы (ITERATIVE, DECOMPOSE, SIMPLE) для гибкого баланса между скоростью и качеством.
• Встроенная Телеметрия: Включает ResourceManager для детального мониторинга производительности и затрат.

---

🚀 Архитектура

В основе системы лежит агентский цикл, управляемый "главным рубильником" в config.py, который позволяет выбрать одну из двух основных стратегий: ITERATIVE (итеративное уточнение) или DECOMPOSE (декомпозиция-и-поиск).

Обе стратегии используют наш кастомный 4-головый EnsembleRetriever:

• Голова A: Семантический поиск (FAISS) с MMR для разнообразия.
• Голова B: Поиск по ключевым словам (TF-IDF).
• Голова C: Поиск по метаданным (FAISS) с MMR.
• Голова D: Иерархический Граф Концептов (NetworkX + KMeans).

Научный Фундамент

Наша архитектура не случайна — она построена на идеях из нескольких state-of-the-art исследовательских работ в области RAG:

• FAIR-RAG: Faithful Adaptive Iterative Refinement for RAG

  • Идея: Превратить RAG в итеративный, агентский цикл, который анализирует "пробелы" в знаниях и уточняет поиск.
  • Наш Вклад: Это основа нашей ITERATIVE стратегии. SeaAgent (аудит доказательств) и RefinementAgent (уточнение запросов) являются прямой реализацией этих идей.

• GlobalRAG: Enhancing Global Reasoning in Multi-hop QA

  • Идея: Для сложных вопросов модель должна сначала составить "глобальный план" (декомпозировать вопрос).
  • Наш Вклад: Это основа нашей DECOMPOSE стратегии. DecompositionAgent создает такой "план" в самом начале, что резко повышает качество поиска.

• Graph-Guided Concept Selection (G2ConS)

  • Идея: Построить дешевый, но эффективный граф из "концептов" (ключевых слов) для поиска скрытых связей.
  • Наш Вклад: Это прямая основа для нашей "Головы D", которая использует TF-IDF для извлечения концептов и networkx для построения графа.

• LLM-GUIDED HIERARCHICAL RETRIEVAL (LATTICE)

  • Идея: Организовать корпус в семантическое дерево и использовать LLM для навигации.
  • Наш Вклад: Мы адаптировали эту идею, реализовав Иерархический Граф Концептов — сначала мы находим релевантные "темы" (кластеры), а потом ищем связи внутри них.

• Chain-of-Conceptual-Thought (CoCT)

  • Идея: Заставить LLM думать "концепциями" (<ТЕЗИС>, <ДЕТАЛИ>), а не просто "шагами".
  • Наш Вклад: Это стало нашим главным инструментом для улучшения промптов. Все наши агенты и финальный генератор используют CoCT для более структурированных и надежных рассуждений.

---

🛠️ Быстрый Старт

1. Требования

• Python 3.12+
• Зависимости из requirements.txt
• Данные train_data.csv и questions.csv в корне проекта.

2. Настройка

1. Клонируйте репозиторий и установите зависимости:

   git clone [URL-репозитория]
   cd [название-папки]
   python -m venv venv
   source venv/bin/activate  # Для Linux/macOS
   .\venv\Scripts\activate   # Для Windows
   pip install -r requirements.txt

2. Настройте API-ключи:

   • Создайте файл .env в корне проекта.
   • Пропишите в него ключи:

   LLM_API_KEY="sk-..."
   EMBEDDER_API_KEY="sk-..."

3. Запуск

• Для отладки на одном вопросе (рекомендуется):

  python debug_single_question.py

  Первый запуск будет долгим, так как он создает все поисковые индексы в папке storage/.

• Для полного прогона (генерация submission.csv):

  python main.py

  Скрипт поддерживает возобновление работы. Если его прервать, при следующем запуске он продолжит с того же места.

---

⚙️ Управление Конфигурацией

Все основные настройки и "тумблеры" для управления архитектурой находятся в файле config.py. Вы можете изменять его для проведения экспериментов:

• STRATEGY: 'ITERATIVE' или 'DECOMPOSE'. Выбор основной стратегии работы.
• MAX_ITERATIONS: Количество итераций для ITERATIVE режима.
• ENABLE_..._HEAD: Включение/выключение "голов" ретривера.
• ANALYST_MODEL / GENERATOR_MODEL: Выбор LLM для разных ролей.

---

🗂️ Структура Проекта

• main.py: Точка входа для финального прогона.
• debug_single_question.py: Наш главный инструмент для отладки.
• prepare_logic.py: Логика создания всех поисковых индексов.
• build.py: Скрипт для сборки проекта в один файл для сдачи.
• config.py: Центральный конфигурационный файл.
• rag_components/: Ядро нашего решения (пайплайн, агенты, ретриверы).
• utils/: Вспомогательные модули (мониторинг, промпты).

---

🤝 Git Workflow

• Не работаем в develop или main.
• Для каждой задачи создаем новую ветку: feature/название-задачи.
• Коммиты делаем атомарные, по правилам Conventional Commits.
• Изменения вливаем в develop через Pull Request с обязательным ревью.

---

💡 Будущие Улучшения (Roadmap)

Этот проект — прочный, высокопроизводительный фундамент. Мы видим несколько ключевых направлений для его дальнейшего развития, превращающих его в полноценную SOTA-платформу для агентского RAG.

Уровень 1: Повышение "Интеллекта" Агентов

1. 🧠 Гибридный Агентский Пайплайн (Decompose + Iterative):

   • Идея: Создать "супер-стратегию", которая сначала декомпозирует сложный вопрос на под-запросы (Decomposition), а затем для каждого под-запроса запускает наш итеративный FAIR-RAG цикл (Iterative Refinement).
   • Влияние: Потенциально самый высокий уровень качества и полноты ответов за счет комбинации двух мощных подходов. Основной вызов — оптимизация производительности для укладывания в производственные лимиты.

2. 🤖 Адаптивный Маршрутизатор Стратегий:

   • Идея: Вместо ручного переключения STRATEGY в конфиге, создать "Агента-Маршрутизатора". Этот LLM-агент будет на первом шаге анализировать вопрос и автоматически выбирать, какую из наших стратегий (SIMPLE, DECOMPOSE или ITERATIVE) использовать.
   • Влияние: Превратит фреймворк в полностью автономную, адаптивную систему, которая сама выбирает оптимальный баланс "скорость/качество" для каждого вопроса.

3. 📊 Динамический Выбор Контекста (Агент-Селектор):

   • Идея: Заменить фиксированный MAX_CONTEXT_DOCS на "Агента-Селектора". Этот LLM будет анализировать топ-50 найденных документов и генерировать список номеров тех, которые являются минимально необходимыми для ответа (идея из статьи DPS).
   • Влияние: Сделает размер контекста адаптивным и еще более "чистым".

Уровень 2: Улучшение "Оптики" и "Движка"

4. 🔎 Внедрение Нейросетевого Реранкера:

   • Идея: Добавить дополнительный шаг "тонкой очистки" после EnsembleRetriever. Использовать либо разрешенные API-реранкеры, либо реализовать свой легковесный реранкер на torch (вдохновляясь статьей EBCAR).
   • Влияние: Значительно повысит точность (precision) поиска и качество финального контекста, подаваемого в агенты.

5. 🕸️ Обучаемый Граф Концептов:

   • Идея: Вместо TF-IDF использовать более продвинутые методы для построения графа, например, эмбеддинги графов (Graph Embeddings) или обучать веса ребер на основе обратной связи от SeaAgent.
   • Влияние: Сделает "Голову D" еще более мощным инструментом для multi-hop рассуждений.

Уровень 3: Инженерное Совершенство

6. ⚡️ Полный Переход на asyncio:

   • Идея: Переписать весь I/O-bound код (API-вызовы, файловые операции) с ThreadPoolExecutor на нативный async/await.
   • Влияние: Потенциальное ускорение параллельной обработки, особенно при масштабировании до десятков и сотен одновременных запросов. Снижение потребления ресурсов по сравнению с потоками.

7. 🧪 Расширение Системы Тестирования:

   • Идея: Реализовать полноценный фреймворк для юнит-тестирования с unittest.mock. Создать "золотой" датасет для регрессионного тестирования качества ответов. Настроить CI/CD для автоматического прогона тестов.
   • Влияние: Повысит стабильность и надежность проекта при дальнейших доработках.

---

👥 Контрибьюторы

• [Роман/Runoi] - Архитектор, ML Engineer
• [Никита] - AI Quality & Prompt Lead

Этот проект был создан с любовью и большим количеством API-вызовов в рамках AI for Finance Hack 2025.