FinSight Copilot: Agente RAG de Investigación y Análisis Financiero

FinSight Copilot es un asistente de investigación financiera de extremo a extremo, impulsado por IA, para analistas financieros. Construido sobre la API de Mensajes de Anthropic Claude, PostgreSQL con pgvector, herramientas de mercado financiero en tiempo real y el Model Context Protocol (MCP), FinSight Copilot proporciona análisis de informes de ganancias con citas, métricas deterministas de riesgo de cartera y capacidades de investigación financiera con salvaguardas.

Capacidades y Características Clave

• Motor de Copilot para Analistas: Impulsado por la API de Mensajes de Claude con prompts estructurados en XML, razonamiento Chain-of-Thought (CoT), análisis de salida estructurada y manejo de respuestas en tiempo real.

• RAG Vectorial con Citas en Línea: Análisis fundamentado sobre presentaciones de la SEC (10-K, divulgaciones de ganancias y transcripciones) usando pgvector. Cada afirmación incluye citas estrictas de documento y sección.

• Herramientas Financieras en Vivo: Consultas de mercado financiero en tiempo real (cotizaciones, ratios P/E, volúmenes de negociación) integradas a través de APIs externas de datos financieros (Yahoo Finance / yfinance).

• Matemáticas de Cartera Deterministas: Cálculos de Valor en Riesgo (VaR) combinados con descargos de responsabilidad constitucionales obligatorios.

• Model Context Protocol (MCP): Expone herramientas financieras como endpoints MCP estandarizados usando fastmcp.

• Optimización y Caché: Aprovecha el caché de prompts activo de Anthropic (cache_control={"type": "ephemeral"}) para reducir la sobrecarga de tokens de entrada hasta en ~90% en consultas RAG repetidas.

• Arnés de Evaluación y Defensa: Incluye un conjunto de pruebas automatizadas que verifican la precisión de la fundamentación, la defensa contra inyección de prompts, el cumplimiento de salvaguardas y el seguimiento de costos de ejecución.

Related MCP server: FinImpulse MCP Server

Estructura del Proyecto

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

Requisitos Previos

Asegúrate de tener lo siguiente instalado en tu máquina antes de la configuración:

• Python: v3.10 o superior

• Docker Desktop: Requerido para ejecutar el contenedor de PostgreSQL + pgvector (o PostgreSQL local v15+ con pgvector)

• Clave de API de Anthropic: Clave activa de la consola de Anthropic

Guía de Instalación y Configuración

Paso 1: Clonar el Directorio del Proyecto

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

Paso 2: Configurar el Entorno Virtual de Python (venv)

Crea y activa un entorno virtual de Python aislado:

macOS / Linux:

python3 -m venv venv
source venv/bin/activate

Windows (Símbolo del sistema):

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

Windows (PowerShell):

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

Paso 3: Instalar las Dependencias del Proyecto

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

(Nota: fastmcp está incluido en requirements.txt para la funcionalidad del servidor MCP).

Paso 4: Configurar las Variables de Entorno

Crea un archivo .env en el directorio raíz:

touch .env

Añade tus credenciales de API y los detalles de conexión a la base de datos en .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

Paso 5: Iniciar y Configurar la Base de Datos Vectorial PostgreSQL

Inicia una instancia de PostgreSQL contenerizada con pgvector habilitado usando 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

Guía de Ejecución

Paso 1: Sembrar Datos e Ingerir Divulgaciones Financieras

Coloca todos los PDFs del Formulario 10-K de la SEC (por ejemplo, Tesla_2025_10K.pdf, Nvidia_2025_10K.pdf, Amazon_2025_10K.pdf) en el directorio data/10k_reports/.

Ejecuta el script de ingesta de documentos RAG para analizar las divulgaciones, dividir el texto en fragmentos usando ventanas de contexto deslizantes, calcular embeddings y poblar PostgreSQL:

python src/rag.py

(Nota: La ingesta de presentaciones PDF de varias páginas localmente en CPU puede tardar entre 5 y 15 minutos. El script contiene una verificación automática del recuento de documentos para omitir la re-ingesta redundante en ejecuciones posteriores).

Paso 2: Ejecutar FinSight Copilot

Una vez que la base de datos vectorial esté poblada con las divulgaciones financieras, ejecuta la aplicación principal interactiva del copilot:

python src/copilot.py

Operaciones Soportadas en copilot.py:

• Consultas de Mercado en Vivo: Obtiene precios de acciones actuales, volumen y ratios P/E (por ejemplo, "¿Cuál es el precio actual de la acción de NVDA y su ratio P/E?").

• Cálculos de Riesgo de Cartera: Calcula métricas deterministas de Valor en Riesgo (VaR) para carteras de usuarios, añadiendo descargos de responsabilidad obligatorios.

• RAG Fundamentado en Documentos: Consulta datos financieros históricos (por ejemplo, "Resume las transacciones de partes relacionadas de Tesla con xAI en 2025 y 2026.") con citas de documentos.

Paso 3: Ejecutar el Arnés de Evaluación Automatizado

Para ejecutar pruebas de cumplimiento adversarial, verificar citas fundamentadas, comprobar salvaguardas y generar un informe de micro-costos de tokens de ejecución:

python src/eval.py

Paso 4: Ejecutar el Servidor MCP

Las herramientas de FinSight están empaquetadas en un servidor MCP. Ejecuta el inspector del servidor MCP usando:

fastmcp dev inspector src/mcp_server.py

Este comando lanza un servidor web local (generalmente http://localhost:5173) donde puedes inspeccionar visualmente, conectar y probar las herramientas get_stock_quote y compute_portfolio_risk directamente a través de una interfaz web.

Aspectos Destacados de Ingeniería y Arquitectura