FinSight Copilot: 金融調査・分析RAGエージェント

FinSight Copilot は、金融アナリスト向けのエンドツーエンドのAI駆動型金融調査アシスタントです。Anthropic Claude Messages API、pgvector を備えたPostgreSQL、リアルタイム金融市場ツール、Model Context Protocol (MCP) を基盤として、引用付きの決算報告分析、決定的なポートフォリオリスク指標、ガードレールで保護された金融調査機能を提供します。

主な機能と特徴

• アナリストコパイロットエンジン: Claude Messages API を利用し、XML構造化プロンプト、Chain-of-Thought (CoT) 推論、構造化出力解析、リアルタイム応答処理を備えています。

• インライン引用付きベクターRAG: pgvector を使用してSEC提出書類（10-K、決算開示、トランスクリプト）に対する根拠に基づく分析を提供します。すべての主張には厳密な文書およびセクション引用が含まれます。

• ライブ金融ツール: 外部金融データAPI（Yahoo Finance / yfinance）を介して統合されたリアルタイムの金融市場ルックアップ（株価、P/Eレシオ、取引量）を提供します。

• 決定的ポートフォリオ計算: バリュー・アット・リスク（VaR）計算と、強制される憲法上の免責事項を組み合わせます。

• Model Context Protocol (MCP): fastmcp を使用して金融ツールを標準化されたMCPエンドポイントとして公開します。

• 最適化とキャッシング: アクティブなAnthropic Prompt Caching（cache_control={"type": "ephemeral"}）を活用し、繰り返しのRAGクエリで入力トークンのオーバーヘッドを最大約90%削減します。

• 評価と防御ハーネス: 根拠の正確性、プロンプトインジェクション防御、ガードレール順守、実行コスト追跡を検証する自動テストスイートが含まれています。

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 コンテナを実行するために必要（または pgvector を備えたローカル PostgreSQL v15+）

• Anthropic APIキー: 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 はMCPサーバー機能のために requirements.txt に含まれています）。

ステップ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ベクターデータベースの起動と設定

Dockerを使用してpgvectorを有効にしたコンテナ化されたPostgreSQLインスタンスを起動します：

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: データのシードと金融開示の取り込み

対象となるすべてのSECフォーム10-K PDF（例：Tesla_2025_10K.pdf、Nvidia_2025_10K.pdf、Amazon_2025_10K.pdf）を data/10k_reports/ ディレクトリに配置します。

RAG文書取り込みスクリプトを実行して、開示情報を解析し、スライディングコンテキストウィンドウを使用してテキストをチャンク化し、埋め込みを計算し、PostgreSQLにデータを投入します：

python src/rag.py

（注：CPU上でローカルに複数ページのPDF提出書類を取り込むには5〜15分かかる場合があります。スクリプトには自動文書数チェックが含まれており、後続の実行で冗長な再取り込みを回避します）。

ステップ2: FinSight Copilot の実行

ベクターデータベースに金融開示情報が投入されたら、メインの対話型コパイロットアプリケーションを実行します：

python src/copilot.py

copilot.py でサポートされている操作：

• ライブ市場ルックアップ: 現在の株価、取引量、P/Eレシオを取得します（例：「NVDAの現在の株価とP/Eレシオは？」）。

• ポートフォリオリスク計算: 必須の免責事項を追加しながら、ユーザーポートフォリオの決定的なバリュー・アット・リスク（VaR）指標を計算します。

• 文書根拠RAG: 文書引用付きで過去の財務データについて問い合わせます（例：「2025年と2026年のTeslaとxAIとの関連当事者取引を要約してください。」）。

ステップ3: 自動評価ハーネスの実行

敵対的コンプライアンステストを実行し、根拠のある引用を検証し、ガードレールを確認し、実行トークンのマイクロコストレポートを生成するには：

python src/eval.py

ステップ4: MCPサーバーの実行

FinSightのツールはMCPサーバーにパッケージ化されています。以下を使用してMCPサーバーインスペクターを実行します：

fastmcp dev inspector src/mcp_server.py

このコマンドはローカルWebサーバー（通常 http://localhost:5173）を起動し、Web UIを介して get_stock_quote および compute_portfolio_risk ツールを視覚的に検査、接続、テストできます。

エンジニアリングとアーキテクチャのハイライト