Financial Agent

RAG-powered agent for querying SEC financial filings (10-K annual reports).

Ask questions about company finances, risks, business models, and more - with citations from official SEC documents.

Installation

pip install financial-agent

Quick Start

1. Get a Gemini API Key (free)

Get your free API key at: https://aistudio.google.com/app/apikey

2. Set Environment Variable

export GOOGLE_API_KEY=your-api-key-here

3. Download Vector Database

Download the pre-built vector database from GitHub Releases and extract it.

4. Use the Agent

from financial_agent import FinancialAgent

# Initialize with path to vector database
agent = FinancialAgent("path/to/vector_db")

# Ask a question
result = agent.query("What are Apple's main revenue sources?")

# Print the answer
print(result["answer"])

# Print citations
for citation in result["citations"]:
    print(f"[{citation['reference_number']}] {citation['user_friendly_format']}")

Features

• Natural Language Queries: Ask questions in plain English
• Multi-Company Support: Query data from AAPL, MSFT, GOOGL, AMZN, TSLA, META, NFLX, NVDA, WMT
• Citations: Every answer includes references to source documents
• Smart Retrieval: Hybrid search combining semantic similarity and keyword matching

Example Queries

# Single company questions
agent.query("What are Apple's main revenue sources?")
agent.query("What risks does Tesla face?")

# Comparison questions
agent.query("Compare Apple and Microsoft's business models")

# Specific topics
agent.query("What does Amazon say about competition?")

Response Format

result = agent.query("What are Apple's revenues?")

# result contains:
{
    "query": "What are Apple's revenues?",
    "answer": "According to Apple's 2023 annual report...",
    "citations": [...],
    "retrieved_chunks": 5,
    "model_used": "gemini-2.0-flash-exp",
    "timestamp": "2024-01-15T10:30:00"
}

Requirements

• Python 3.9+
• Google Gemini API key (free tier available)
• Pre-built vector database (download from releases)

Building Your Own Vector Database (Advanced)

If you want to build your own vector database with fresh data or different companies, follow these instructions.

Pipeline Setup

git clone https://github.com/YOUR_USERNAME/financial-agent.git
cd financial-agent
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[pipeline]"

# Download spaCy model
python -m spacy download en_core_web_sm

Environment Variables

Create a .env file:

# SEC API (from sec-api.io)
SEC_API_KEY=your_sec_api_key_here
CONTACT_EMAIL=your_email@example.com

# Google Cloud / Vertex AI (for embeddings)
GCP_PROJECT_ID=your-gcp-project-id
GOOGLE_CLOUD_LOCATION=us-central1

Run the Pipeline

# 1. Download SEC filings
python scripts/01_download_filings.py

# 2. Clean filing text
python scripts/02_clean_sec_data.py

# 3. Analyze document structure
python scripts/03_analyze_documents.py

# 4. Create chunks
python scripts/04_create_chunks.py

# 5. Generate embeddings (requires GCP)
python scripts/05_create_embeddings.py

# 6. Set up vector database
python scripts/06_setup_vector_db.py

Project Structure

financial-agent/
├── src/
│   └── financial_agent/        # The pip-installable library
│       ├── __init__.py
│       ├── agent.py            # FinancialAgent class
│       ├── vector_db.py        # Vector database search
│       └── chunk_utils.py      # Text chunking utilities
├── scripts/                    # Data pipeline scripts
│   ├── 01_download_filings.py
│   ├── 02_clean_sec_data.py
│   ├── 03_analyze_documents.py
│   ├── 04_create_chunks.py
│   ├── 05_create_embeddings.py
│   └── 06_setup_vector_db.py
├── vector_db/                  # Pre-built FAISS index
├── pyproject.toml
└── README.md

License

MIT