FinSight Copilot: финансовый исследовательский и аналитический RAG-агент

FinSight Copilot — это комплексный AI-ассистент для финансовых исследований, предназначенный для финансовых аналитиков. Построенный на основе Anthropic Claude Messages API, PostgreSQL с pgvector, инструментов реального времени для финансовых рынков и Model Context Protocol (MCP), FinSight Copilot предоставляет анализ отчётов о прибылях с цитированием, детерминированные метрики портфельного риска и возможности финансовых исследований с соблюдением ограничений.

Ключевые возможности и функции

• Движок аналитического копилота: Работает на Claude Messages API с XML-структурированными подсказками, рассуждениями Chain-of-Thought (CoT), разбором структурированных выходных данных и обработкой ответов в реальном времени.

• Векторный RAG с встроенными цитатами: Обоснованный анализ документов SEC (10-K, раскрытий о прибылях и стенограмм) с использованием pgvector. Каждое утверждение сопровождается строгими цитатами на документ и раздел.

• Инструменты реального времени для финансовых рынков: Поиск данных о финансовых рынках в реальном времени (котировки, коэффициенты P/E, объёмы торгов) через внешние API финансовых данных (Yahoo Finance / yfinance).

• Детерминированная математика портфеля: Расчёты Value at Risk (VaR) в сочетании с обязательными конституционными оговорками.

• Model Context Protocol (MCP): Предоставляет финансовые инструменты в виде стандартизированных MCP-эндпоинтов с использованием fastmcp.

• Оптимизация и кэширование: Использует активное кэширование подсказок Anthropic (cache_control={"type": "ephemeral"}) для снижения накладных расходов на входные токены до ~90% при повторяющихся RAG-запросах.

• Среда оценки и защиты: Включает автоматизированный набор тестов, проверяющих точность обоснования, защиту от инъекций в подсказки, соблюдение ограничений и отслеживание стоимости выполнения.

Related MCP server: FinImpulse MCP Server

Структура проекта

finsight-copilot/
│
├── data/
│   ├── 10k_reports/             # Seed Data: Raw PDF filings (e.g., Tesla, Nvidia, Amazon 10-Ks)
│   ├── research_notes/          # Supplementary RAG context (e.g., tech_sector_2024.txt)
│   └── transcripts/             # Adversarial testing data (e.g., malicious_hack.txt for prompt injection defenses)
│
├── src/
│   ├── agent.py                 # Autonomous State Machine loop (e.g., FETCH -> FLAG_RISK -> SUMMARIZE)
│   ├── copilot.py               # Main agent logic, tool routing, guardrails, and prompt caching
│   ├── eval.py                  # Automated evaluation suite testing accuracy, security, and token costs
│   ├── mcp_server.py            # Model Context Protocol (MCP) server exposing tools via fastmcp
│   ├── rag.py                   # Ingestion pipeline, PDF sliding-window chunker, and pgvector engine
│   ├── skills.py                # Modular AI skill definitions and instructions used by the agent/server
│   └── tools.py                 # Live yfinance integration and portfolio risk (VaR) math functions
│
├── .env                         # Local environment variables (Git ignored)
├── .env.example                 # Template for required environment variables
├── requirements.txt             # Python project dependencies
└── README.md                    # Project documentation

Предварительные требования

Убедитесь, что на вашем компьютере установлено следующее перед настройкой:

• Python: v3.10 или выше

• Docker Desktop: Требуется для запуска контейнера PostgreSQL + pgvector (или локальный PostgreSQL v15+ с pgvector)

• Anthropic API Key: Активный ключ из Anthropic Console

Руководство по установке и настройке

Шаг 1: Клонирование каталога проекта

git clone https://github.com/ayadav6/finsight-copilot.git
cd finsight-copilot

Шаг 2: Настройка виртуального окружения Python (venv)

Создайте и активируйте изолированное виртуальное окружение Python:

macOS / Linux:

python3 -m venv venv
source venv/bin/activate

Windows (командная строка):

python -m venv venv
venv\Scripts\activate.bat

Windows (PowerShell):

python -m venv venv
.\venv\Scripts\Activate.ps1

Шаг 3: Установка зависимостей проекта

pip install --upgrade pip
pip install -r requirements.txt

(Примечание: fastmcp включён в requirements.txt для функциональности MCP-сервера).

Шаг 4: Настройка переменных окружения

Создайте файл .env в корневом каталоге:

touch .env

Добавьте свои учётные данные API и параметры подключения к базе данных в .env:

# Anthropic API Configuration
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# PostgreSQL database connection string (Default for local Docker pgvector)
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres

Шаг 5: Запуск и настройка векторной базы данных PostgreSQL

Запустите контейнеризированный экземпляр PostgreSQL с включённым pgvector с помощью Docker:

docker run --name pgvector-finsight \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=postgres \
  -p 5432:5432 \
  -d pgvector/pgvector:pg16

Руководство по выполнению

Шаг 1: Загрузка данных и приём финансовых отчётов

Поместите все целевые PDF-файлы SEC Form 10-K (например, Tesla_2025_10K.pdf, Nvidia_2025_10K.pdf, Amazon_2025_10K.pdf) в каталог data/10k_reports/.

Запустите скрипт приёма документов RAG для разбора отчётов, разбиения текста на фрагменты с помощью скользящих контекстных окон, вычисления эмбеддингов и заполнения PostgreSQL:

python src/rag.py

(Примечание: Приём многостраничных PDF-файлов локально на CPU может занять от 5 до 15 минут. Скрипт содержит автоматическую проверку количества документов, чтобы пропустить повторный приём при последующих запусках).

Шаг 2: Запуск FinSight Copilot

После заполнения векторной базы данных финансовыми отчётами запустите основное интерактивное приложение копилота:

python src/copilot.py

Поддерживаемые операции в copilot.py:

• Поиск данных о рынке в реальном времени: Получает текущие цены акций, объёмы и коэффициенты P/E (например, «Какова текущая цена акций NVDA и коэффициент P/E?»).

• Расчёты портфельного риска: Вычисляет детерминированные метрики Value at Risk (VaR) для портфелей пользователей с добавлением обязательных оговорок.

• RAG на основе документов: Запросы о исторических финансовых данных (например, «Обобщите сделки Tesla со связанными сторонами с xAI в 2025 и 2026 годах») с цитированием документов.

Шаг 3: Запуск автоматизированной среды оценки

Для запуска тестов на соответствие требованиям, проверки обоснованных цитат, проверки ограничений и создания отчёта о микро-затратах на токены выполнения:

python src/eval.py

Шаг 4: Запуск MCP-сервера

Инструменты FinSight упакованы в MCP-сервер. Запустите инспектор MCP-сервера с помощью:

fastmcp dev inspector src/mcp_server.py

Эта команда запускает локальный веб-сервер (обычно http://localhost:5173), где вы можете визуально просматривать, подключаться и тестировать инструменты get_stock_quote и compute_portfolio_risk непосредственно через веб-интерфейс.

Инженерные и архитектурные особенности