Financial Options Analysis Agent

A sophisticated AI-powered agent for real-time stock options data analysis, visualization, and intelligent caching. Built with LangChain, LangGraph, and ChromaDB for enterprise-level financial data processing.

Author: Leo Ji
Version: 1.0.0
Last Updated: December 2025

---

📋 Table of Contents

• Overview
• Key Features
• Architecture
• Project Structure
• Installation
• Configuration
• Usage
• API Reference
• Development
• Evaluation & Testing
• Troubleshooting

---

🎯 Overview

The Financial Options Analysis Agent is an intelligent conversational AI system designed to:

• Search & Retrieve: Real-time options data from Polygon.io with smart caching
• Analyze: Professional-grade options analysis with sentiment detection and anomaly detection
• Export: Multiple export formats (CSV, Charts, Reports)
• Learn: Persistent memory across sessions with SQLite
• Scale: Microservice architecture with FastAPI integration
• Evaluate: Built-in A/B testing, skill ablation, and performance monitoring

The agent uses LangGraph for orchestration, maintains long-term conversation memory, and provides multiple tools for data analysis and visualization.

---

✨ Key Features

1. Intelligent Data Caching

• Automatic knowledge base lookup before API calls
• Smart hybrid storage (ChromaDB + SQLite)
• Manual refresh option with force_refresh=True
• Reduces API usage and improves response time

2. Persistent Memory

• SQLite-based conversation history
• Multi-session continuity
• Remembers previous searches and preferences
• Survives program restarts

3. Professional Analysis Tools

• Options chain analysis with Greeks
• Sentiment analysis on options positioning
• Anomaly detection using vector similarity
• Comparative analysis across multiple tickers

4. Flexible Export Options

• Standard CSV export
• Custom CSV generation with code execution
• PNG chart visualization
• Professional reports in multiple formats

5. RAG (Retrieval-Augmented Generation)

• Knowledge base integration
• Semantic search on historical data
• Date range collection
• Automatic watchlist updates

6. Performance Monitoring

• Token usage tracking
• Tool execution metrics
• Query performance statistics
• A/B testing evaluators

7. Microservice Integration

• FastAPI endpoints for all tools
• Docker support
• RESTful API interface
• Easy scalability

---

🏗️ Architecture

System Design

┌─────────────────────────────────────────────────────────────────┐
│                     User Interface                              │
│                 (CLI / API / Integration)                       │
└──────────────────────────┬──────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│                      LangGraph Agent                            │
│  ┌─────────────┐    ┌──────────┐    ┌──────────────────┐       │
│  │   Chatbot   │◄──►│  Tools   │◄──►│ LLM (GPT-4o)     │       │
│  │   Node      │    │  Node    │    │                  │       │
│  └─────────────┘    └──────────┘    └──────────────────┘       │
└──────────────────────────┬──────────────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┬───────────────┐
        │                  │                  │               │
┌───────▼────────┐  ┌──────▼──────┐  ┌──────▼─────┐  ┌──────▼──────┐
│  Tool Suite    │  │ Memory/State│  │   RAG KB   │  │ Monitoring  │
│  - Search      │  │  - SQLite   │  │ -ChromaDB  │  │  - Metrics  │
│  - Export      │  │  - Session  │  │ -SQLite    │  │  - Tracking │
│  - Analysis    │  │  - History  │  │ -Embeddings│  │  - A/B Test │
│  - Web Search  │  │             │  │            │  │             │
└────────────────┘  └─────────────┘  └────────────┘  └─────────────┘
        │                   │                │              │
        └───────────────────┴────────────────┴──────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
┌───────▼─────────┐  ┌─────▼──────┐  ┌──────▼────────┐
│ Polygon.io API  │  │File Storage │  │ Microservice  │
│  (Options Data) │  │(CSV/Charts) │  │  (FastAPI)    │
└─────────────────┘  └─────────────┘  └───────────────┘

Component Stack

| Layer | Technology | Purpose | |-------|-----------|---------| | LLM Orchestration | LangGraph | Multi-agent workflow management | | Language Model | GPT-4o (OpenAI) | Intelligent decision making | | Vector DB | ChromaDB | Semantic similarity search | | Relational DB | SQLite | Persistent storage | | API Framework | FastAPI | Microservice endpoints | | Embeddings | OpenAI Text Embedding 3-Small | Semantic encoding | | Data Source | Polygon.io | Real-time options data | | Search | Tavily Search | Web context retrieval |

---

📂 Project Structure

Overview

Algovant Internship/
├── 📖 README.md (this file)
├── 📋 requirements.txt
│
├── 🤖 AGENT CORE
│   ├── agent_main.py                 # Main entry point (latest modular version)
│   └── agent_with_rules.py           # Rules-based agent with external markdown rules
│
├── ⚙️ CONFIG
│   ├── config/__init__.py
│   └── config/settings.py            # Centralized configuration
│
├── 🔧 TOOLS
│   ├── tools/__init__.py
│   ├── tools/code_execution.py       # Code execution tool
│   ├── tools/web_search.py           # Web search integration
│   │
│   ├── search/                       # Options search tools
│   │   ├── __init__.py
│   │   ├── options_search.py         # Single ticker search
│   │   └── batch_search.py           # Batch search for multiple tickers
│   │
│   ├── export/                       # Data export tools
│   │   ├── __init__.py
│   │   ├── csv_export.py             # CSV export functionality
│   │   └── visualization.py          # Chart generation
│   │
│   └── analysis/                     # Analysis tools
│       ├── __init__.py
│       └── analysis_tools.py         # Professional options analysis
│
├── 📚 RAG (Knowledge Base)
│   ├── rag/__init__.py
│   ├── rag_config.py                 # RAG system configuration
│   ├── rag_knowledge_base.py        # ChromaDB + SQLite implementation
│   ├── rag_tools.py                  # Query tools
│   └── rag_collection_tools.py       # Data collection tools
│
├── 📊 MONITORING & EVALUATION
│   ├── monitoring/
│   │   ├── __init__.py
│   │   └── performance_monitor.py    # Performance tracking
│   │
│   └── evaluation/
│       ├── __init__.py
│       ├── ab_testing_evaluator.py   # A/B testing
│       ├── external_evaluator.py     # External evaluations
│       ├── llm_judge.py              # LLM-based judge
│       └── skills_ablation.py        # Skill ablation study
│
├── 🎯 ANALYSIS MODULES
│   ├── analysis/__init__.py
│   └── options_analyzer.py           # Options analysis logic
│
├── 📏 UTILITIES
│   ├── utils/__init__.py
│   └── utils/rules_loader.py         # Rule file loader
│
├── 🌐 MICROSERVICE
│   ├── microservice/
│   │   ├── app.py                    # FastAPI application
│   │   ├── docker-compose.yml        # Docker compose config
│   │   ├── Dockerfile                # Docker image definition
│   │   ├── env.template              # Environment template
│   │   ├── requirements.txt           # Microservice dependencies
│   │   ├── test_client.py            # Testing client
│   │   └── outputs/                  # API output directory
│
├── 📚 RULES
│   ├── rules/
│   │   ├── agent_rules.md            # Core agent behaviors and workflows
│   │   └── analysis_rules.md         # Professional analysis rules
│
├── 📝 LEARNING EXAMPLES (Week 1)
│   ├── Week1/
│   │   ├── README.md
│   │   ├── first_simple_openai_agent.py
│   │   ├── using_prebuilt.py
│   │   ├── add_tavily.py
│   │   ├── added_time_travel.py
│   │   └── add_customized_state.py
│   └── week2.py
│
├── 📁 DATA STORAGE
│   ├── data/
│   │   ├── chroma_db/                # Vector database (ChromaDB)
│   │   ├── conversation_memory.db    # SQLite memory
│   │   ├── options.db                # Options cache
│   │   ├── embeddings_cache/         # Embedding cache
│   │   └── evaluation_*.json         # Evaluation results
│
├── 📤 OUTPUT
│   ├── outputs/
│   │   ├── csv/                      # Exported CSV files
│   │   ├── charts/                   # Generated PNG charts
│   │   └── reports/                  # Analysis reports
│
├── 🧪 TESTS & EVALUATION
│   ├── run_evaluation.py             # Run evaluation suite
│   ├── run_ab_testing.py             # Run A/B testing
│   ├── run_skills_ablation.py        # Run skill ablation
│   └── langraph example/             # LangGraph example project
│
├── 🛠️ UTILITIES & SCRIPTS
│   ├── backup.py                     # Backup utility
│   ├── clear_memory.py               # Memory cleanup
│   └── code_examples/
│       └── csv_export_template.py    # CSV export example
│
└── 📊 DATA FILES
    └── NVDA_options_*.csv            # Sample data files

Key Directories Explained

config/

Centralized configuration management

• Environment variables
• API keys validation
• Model settings (GPT-4o selection)
• System limits (tokens, API calls)
• File paths organization
• Database connections

tools/

Complete tool suite for the agent

• search/: Options data retrieval (single and batch)
• export/: CSV export and chart visualization
• analysis/: Professional options analysis
• Additional tools: code execution, web search

rag/

Knowledge base and retrieval-augmented generation

• ChromaDB for vector similarity search
• SQLite for structured data persistence
• Collection tools for a