FinSight Copilot: Financial Research & Analysis RAG Agent

FinSight Copilot ist ein End-to-End-KI-gestützter Finanzrecherche-Assistent für Finanzanalysten. Aufbauend auf der Anthropic Claude Messages API, PostgreSQL mit pgvector, Echtzeit-Finanzmarkttools und dem Model Context Protocol (MCP) bietet FinSight Copilot zitierte Gewinnberichtsanalysen, deterministische Portfolio-Risikokennzahlen und durch Guardrails abgesicherte Finanzrecherchefunktionen.

Hauptfunktionen & Merkmale

• Analyst Copilot Engine: Angetrieben von der Claude Messages API mit XML-strukturierten Prompts, Chain-of-Thought (CoT)-Reasoning, strukturiertem Output-Parsing und Echtzeit-Antwortverarbeitung.

• Vector-RAG mit Inline-Zitaten: Fundierte Analyse von SEC-Einreichungen (10-Ks, Gewinnmitteilungen und Transkripten) unter Verwendung von pgvector. Jede Behauptung enthält strikte Dokument- und Abschnittszitate.

• Live-Finanzwerkzeuge: Echtzeit-Finanzmarktabfragen (Kurse, KGV, Handelsvolumina) integriert über externe Finanzdaten-APIs (Yahoo Finance / yfinance).

• Deterministische Portfolio-Mathematik: Value-at-Risk (VaR)-Berechnungen kombiniert mit durchgesetzten konstitutionellen Haftungsausschlüssen.

• Model Context Protocol (MCP): Stellt Finanzwerkzeuge als standardisierte MCP-Endpunkte über fastmcp bereit.

• Optimierung & Caching: Nutzt aktives Anthropic Prompt Caching (cache_control={"type": "ephemeral"}), um den Eingabe-Token-Overhead bei wiederholten RAG-Abfragen um bis zu ~90% zu reduzieren.

• Evaluierungs- & Verteidigungs-Harness: Enthält eine automatisierte Testsuite, die Grounding-Genauigkeit, Prompt-Injection-Abwehr, Einhaltung von Guardrails und Verfolgung der Ausführungskosten überprüft.

Related MCP server: FinImpulse MCP Server

Projektstruktur

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

Voraussetzungen

Stellen Sie sicher, dass die folgenden Komponenten auf Ihrem Rechner installiert sind, bevor Sie mit der Einrichtung beginnen:

• Python: v3.10 oder höher

• Docker Desktop: Erforderlich für den Betrieb des PostgreSQL + pgvector Containers (oder lokales PostgreSQL v15+ mit pgvector)

• Anthropic API Key: Aktiver Schlüssel aus der Anthropic Console

Installations- & Einrichtungsanleitung

Schritt 1: Projektverzeichnis klonen

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

Schritt 2: Python-Virtual-Environment (venv) einrichten

Erstellen und aktivieren Sie eine isolierte Python-Virtual-Environment:

macOS / Linux:

python3 -m venv venv
source venv/bin/activate

Windows (Eingabeaufforderung):

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

Windows (PowerShell):

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

Schritt 3: Projektabhängigkeiten installieren

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

(Hinweis: fastmcp ist in requirements.txt für die MCP-Serverfunktionalität enthalten).

Schritt 4: Umgebungsvariablen konfigurieren

Erstellen Sie eine .env-Datei im Stammverzeichnis:

touch .env

Fügen Sie Ihre API-Anmeldedaten und Datenbankverbindungsdetails zur .env-Datei hinzu:

# 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

Schritt 5: PostgreSQL-Vektordatenbank starten & konfigurieren

Starten Sie eine containerisierte PostgreSQL-Instanz mit aktiviertem pgvector über 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

Ausführungsanleitung

Schritt 1: Daten seeden & Finanzmitteilungen erfassen

Legen Sie alle Ziel-SEC-Formular-10-K-PDFs (z. B. Tesla_2025_10K.pdf, Nvidia_2025_10K.pdf, Amazon_2025_10K.pdf) in das Verzeichnis data/10k_reports/.

Führen Sie das RAG-Dokumenterfassungsskript aus, um Mitteilungen zu parsen, Text mithilfe gleitender Kontextfenster in Chunks zu unterteilen, Embeddings zu berechnen und PostgreSQL zu befüllen:

python src/rag.py

(Hinweis: Das Erfassen mehrseitiger PDF-Einreichungen lokal auf der CPU kann zwischen 5 und 15 Minuten dauern. Das Skript enthält eine automatisierte Dokumentanzahlprüfung, um eine redundante erneute Erfassung bei späteren Ausführungen zu überspringen).

Schritt 2: FinSight Copilot ausführen

Sobald die Vektordatenbank mit Finanzmitteilungen befüllt ist, führen Sie die interaktive Haupt-Copilot-Anwendung aus:

python src/copilot.py

Unterstützte Operationen in copilot.py:

• Live-Marktabfragen: Ruft aktuelle Aktienkurse, Volumen und KGV ab (z. B. „Wie hoch ist der aktuelle Aktienkurs und das KGV von NVDA?").

• Portfolio-Risikoberechnungen: Berechnet deterministische Value-at-Risk (VaR)-Kennzahlen für Benutzerportfolios und fügt obligatorische Haftungsausschlüsse hinzu.

• Dokumentbasiertes RAG: Fragt historische Finanzdaten ab (z. B. „Fassen Sie Teslas Transaktionen mit verbundenen Parteien mit xAI in den Jahren 2025 und 2026 zusammen.") mit Dokumentzitaten.

Schritt 3: Automatisierten Evaluierungs-Harness ausführen

Um adversariale Compliance-Tests auszuführen, fundierte Zitate zu überprüfen, Guardrails zu prüfen und einen Mikrokostenbericht für Ausführungstoken zu generieren:

python src/eval.py

Schritt 4: MCP-Server ausführen

Die Werkzeuge von FinSight sind in einem MCP-Server gebündelt. Führen Sie den MCP-Server-Inspektor mit folgendem Befehl aus:

fastmcp dev inspector src/mcp_server.py

Dieser Befehl startet einen lokalen Webserver (normalerweise http://localhost:5173), auf dem Sie die Werkzeuge get_stock_quote und compute_portfolio_risk direkt über eine Weboberfläche visuell inspizieren, verbinden und testen können.

Technische & Architektonische Highlights