A sophisticated LangGraph-based agent that automates financial options analysis with real-time data from Polygon.io, smart caching, persistent memory, and professional-grade analysis. Built for traders, analysts, and developers who need intelligent options data processing
Based on repository activity, growth velocity and community engagement.
31
Growth6/30
Activity3/25
Popularity12/25
Trust11/20
631
Stars
High
Sentiment
Votes
631
README.md
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
# Example: Change default model
class ModelConfig:
MODEL_NAME = "gpt-4" # Instead of "gpt-4o-mini"
# Example: Increase context history
class Limits:
MAX_MESSAGES = 50 # Instead of 20
# Example: Adjust RAG sensitivity
class RAGConfig:
MIN_SIMILARITY_THRESHOLD = 0.5 # More lenient matching
🚀 Usage
Option 1: Interactive CLI Agent
Start the main agent:
python agent_main.py
Or use the rules-based version:
python agent_with_rules.py
Typical interaction flow:
User: Get options for AAPL on 2025-12-19
Agent: I'll search for Apple options expiring on December 19, 2025.
How many contracts would you like? (default: 100, max: 1000)
User: 200
Agent: Found 200 options contracts. What would you like to do?
- 📊 Export to CSV
- 📈 Generate chart
- 💬 Show summary
- 📋 Both CSV and chart
User: Both CSV and chart
Agent: Creating exports...
✅ CSV saved: outputs/csv/AAPL_options_2025-12_20251215_143022.csv
✅ Chart saved: outputs/charts/AAPL_options_2025-12.png
Option 2: Microservice API
Start the FastAPI server:
cd microservice
python app.py
# Or using uvicorn directly
uvicorn app:app --reload --host 0.0.0.0 --port 8000
from agent_main import graph, config, stream_graph_updates
# Use in your Python code
stream_graph_updates("Get options for AAPL on 2025-12-19")
Option 4: Learning with Examples
# Week 1 examples (basic to advanced)
cd Week1
python first_simple_openai_agent.py # Most basic
python using_prebuilt.py # With prebuilt components
python add_tavily.py # With web search
python added_time_travel.py # With memory
python add_customized_state.py # Advanced state
🛠️ API Reference
Core Tools
search_options()
Search for options data with smart caching
@tool
def search_options(
ticker: str, # Stock symbol (e.g., "AAPL")
date: str, # YYYY-MM-DD or YYYY-MM format
limit: int = 300, # Number of contracts (1-1000)
force_refresh: bool = False # Skip cache if True
) -> str: # Returns JSON with options data
Example:
result = search_options("AAPL", "2025-12-19", limit=200)
batch_search_options()
Search multiple tickers efficiently
@tool
def batch_search_options(
tickers: list, # ["AAPL", "TSLA", "MSFT"]
date: str, # Same date for all tickers
limit: int = 100
) -> str: # Returns dict with results for each ticker
make_option_table()
Export options data to CSV
@tool
def make_option_table(
data: str, # JSON data from search_options
ticker: str # Stock symbol
) -> str: # Returns success message with filename
plot_options_chain()
Generate PNG chart visualization
@tool
def plot_options_chain(
data: str, # JSON data from search_options
ticker: str # Stock symbol
) -> str: # Returns success message with filename
analyze_options_chain()
Professional options analysis
@tool
def analyze_options_chain(
ticker: str, # Stock symbol (must be first!)
options_data: str # JSON data
) -> str: # Returns detailed analysis report
collect_and_store_options()
Collect and immediately store in knowledge base
@tool
def collect_and_store_options(
ticker: str, # Stock symbol
date: str, # YYYY-MM-DD or YYYY-MM
limit: int # Number of contracts
) -> str: # Returns storage confirmation
search_knowledge_base()
Query the knowledge base
@tool
def search_knowledge_base(
query: str, # Natural language query
limit: int = 5 # Max results
) -> str: # Returns matching historical data
detect_anomaly()
Find unusual changes in options data
@tool
def detect_anomaly(
ticker: str, # Stock symbol
current_data: str # Current options data
) -> str: # Returns anomaly report
@tool
def human_assistance(question: str) -> str:
"""Ask for human intervention when needed"""
👨💻 Development
Project Architecture Principles
Modularity: Each tool and component is independent
Configurability: Settings centralized in config/settings.py
Extensibility: Easy to add new tools and rules
Maintainability: Clear separation of concerns
Observability: Built-in monitoring and logging
Adding a New Tool
Step 1: Create a new file in tools/:
# tools/my_new_tool.py
from langchain_core.tools import tool
@tool
def my_new_tool(parameter: str) -> str:
"""
Tool description for the LLM.
Args:
parameter: What this parameter does
Returns:
What the tool returns
"""
# Implementation
return "Result"
Step 2: Import and register in agent_main.py:
from tools.my_new_tool import my_new_tool
tools = [
# ... existing tools ...
my_new_tool, # Add here
]
Adding New Rules
Step 1: Edit rules/agent_rules.md or create new markdown file:
## 🎯 New Capability: My New Skill
### Description
What this skill does...
### Workflow
1. First step
2. Second step
3. Third step
### Tools Used
- tool_name_1
- tool_name_2
Step 2: Load rules in agent:
# In agent_with_rules.py
agent_rules = load_agent_rules("agent_rules.md")
# New rules automatically included
Extending Configuration
Add new configuration class in config/settings.py:
class MyNewConfig:
"""Configuration for my new feature"""
SETTING_1 = "value"
SETTING_2 = 100
# Add to Settings class
class Settings:
my_feature = MyNewConfig
# Export
MY_FEATURE_CONFIG = settings.my_feature