FinSight Copilot: 금융 리서치 및 분석 RAG 에이전트

FinSight Copilot은 금융 분석가를 위한 엔드투엔드 AI 기반 금융 리서치 어시스턴트입니다. Anthropic Claude Messages API, pgvector를 사용하는 PostgreSQL, 실시간 금융 시장 도구 및 Model Context Protocol (MCP)을 기반으로 구축된 FinSight Copilot은 인용된 실적 보고서 분석, 결정론적 포트폴리오 위험 지표, 그리고 가드레일이 적용된 금융 리서치 기능을 제공합니다.

주요 기능 및 특징

• 애널리스트 코파일럿 엔진: Claude Messages API 기반으로 XML 구조화 프롬프트, Chain-of-Thought (CoT) 추론, 구조화된 출력 파싱, 실시간 응답 처리를 지원합니다.

• 인라인 인용이 포함된 벡터 RAG: pgvector를 사용하여 SEC 서류(10-K, 실적 공시, 회의록)에 대한 근거 기반 분석을 제공합니다. 모든 주장에는 엄격한 문서 및 섹션 인용이 포함됩니다.

• 실시간 금융 도구: 외부 금융 데이터 API(Yahoo Finance / yfinance)를 통해 통합된 실시간 금융 시장 조회(주가, P/E 비율, 거래량)를 제공합니다.

• 결정론적 포트폴리오 수학: Value at Risk (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 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는 MCP 서버 기능을 위해 requirements.txt에 포함되어 있습니다).

4단계: 환경 변수 구성

루트 디렉터리에 .env 파일을 생성합니다:

touch .env

.env에 API 자격 증명과 데이터베이스 연결 정보를 추가합니다:

# 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 Form 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 비율은 얼마인가요?").

• 포트폴리오 위험 계산: 필수 고지 사항을 추가하면서 사용자 포트폴리오에 대한 결정론적 Value at Risk (VaR) 지표를 계산합니다.

• 문서 근거 RAG: 문서 인용과 함께 과거 금융 데이터에 대해 질의합니다 (예: "2025년과 2026년 Tesla의 xAI와의 특수관계자 거래를 요약해 주세요.").

3단계: 자동화된 평가 하네스 실행

적대적 컴플라이언스 테스트를 실행하고, 근거 인용을 검증하고, 가드레일을 확인하고, 실행 토큰 마이크로 비용 보고서를 생성하려면:

python src/eval.py

4단계: MCP 서버 실행

FinSight의 도구는 MCP 서버로 패키징되어 있습니다. 다음을 사용하여 MCP 서버 인스펙터를 실행합니다:

fastmcp dev inspector src/mcp_server.py

이 명령은 로컬 웹 서버(일반적으로 http://localhost:5173)를 시작하며, 웹 UI를 통해 get_stock_quote 및 compute_portfolio_risk 도구를 시각적으로 검사하고 연결하고 테스트할 수 있습니다.

엔지니어링 및 아키텍처 하이라이트