SEC Analyst - Robo SEC Filings Analyst

An AI-powered system that analyzes SEC filings, short seller reports, and market data to identify potential short-selling opportunities based on fraud detection and comprehensive financial analysis.

Features

• Automated SEC Filings Download: Download and parse all SEC filings for any ticker
• Short Seller Report Collection: Aggregate reports from major short sellers (Hindenburg, Muddy Waters, Citron, etc.)
• AI-Powered Fraud Detection: Multi-agent LLM system for analyzing accounting irregularities
• Comprehensive Market Data:
  • Prices: Historical OHLCV data with incremental updates
  • Fundamentals: Stock info, institutional holders, insider transactions, analyst recommendations, earnings dates, volatility
  • Financials: Income statements, balance sheets, cash flow statements (annual + quarterly)
  • Options: Options chains with Greeks and implied volatility
• Trading Strategy Recommendations: AI-driven strategy analysis with three risk profiles (conservative, moderate, aggressive) based on technical patterns, fundamental valuation, and catalyst timeline (NO hardcoded rules!)
• Probability Analysis: Compare market-implied vs. assessed fraud probabilities
• Comprehensive Reports: Generate detailed markdown, JSON, and PDF reports
• Interactive Dashboard: Dash-based UI for visual analysis
• Batch Data Updates: Efficiently update market data for entire watchlists

Quick Start

Prerequisites

• Python 3.10 or higher
• WSL (for Windows users)
• GitHub Copilot SDK token

Installation

1. Clone the repository:

cd /home/jude/sec_analyst

2. Create and activate virtual environment:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt
# Note: edgartools should be installed separately if available
# pip install -e ./edgartools

4. Configure environment:

cp .env.example .env
# Edit .env and add your API keys

5. Authenticate GitHub CLI (for Copilot):

gh auth login
gh extension install github/gh-copilot

Basic Usage

Analyze a ticker:

python -m src.main --ticker AAPL --model claude-sonnet-4.5

Download data only (no AI analysis):

python -m src.main --ticker TSLA --download-data

Check data status:

# See what data you have and what needs updating
python scripts/check_data_status.py

# Export status tables to CSV for detailed analysis
python scripts/check_data_status.py --export

Batch update market data for watchlist:

# Daily price updates (fastest)
python scripts/update_market_data.py

# Include fundamentals (stock info, holders, transactions, etc.)
python scripts/update_market_data.py --fundamentals

# Include financial statements (income statement, balance sheet, cash flow)
python scripts/update_market_data.py --financials

# Include options chains
python scripts/update_market_data.py --options

# Get everything
python scripts/update_market_data.py --all

# See DATA_LOADING_GUIDE.md for complete documentation

Download SEC filings only (standalone script):

python download_sec_filings.py TSLA --email [email protected]

Run with custom options:

python -m src.main \
    --ticker NVDA \
    --model claude-opus-4.5 \
    --capital 10000 \
    --output-dir ./my_analysis \
    --verbose

Project Structure

sec_analyst/
├── src/
│   ├── main.py                  # Main orchestrator script
│   ├── config.py                # Configuration management
│   ├── filings/                 # SEC filings download & parsing
│   ├── research/                # Short seller report collection
│   ├── analysis/                # Fraud detection & market analysis
│   ├── agents/                  # AI agent implementations
│   ├── reports/                 # Report generation
│   ├── utils/                   # Helper functions
│   └── ui/                      # Dash dashboard (Phase II)
├── tests/                       # Unit and integration tests
├── data/                        # Analysis output (gitignored)
├── download_sec_filings.py      # Standalone SEC downloader
├── requirements.txt             # Python dependencies
├── pyproject.toml               # Project configuration
└── README.md                    # This file

Workflow

1. Download SEC Filings: Fetches ALL available SEC filings (all types, no date limit)
2. Fetch Market Data: Downloads complete market data and saves to CSV/Parquet files:
   • Core Data: Price history (max available), options chains
   • Fundamentals (6 CSV files per ticker):
     • stock_info.csv - Market cap, PE ratios, beta, sector, industry
     • institutional_holders.csv - Top institutional ownership
     • insider_transactions.csv - Insider trading activity
     • analyst_recommendations.csv - Buy/Hold/Sell ratings
     • earnings_dates.csv - Historical and upcoming earnings
     • volatility.csv - Historical volatility metrics
   • Options: YYYYMMDD_options.csv - Options chains with dated filenames
   • See DATA_LOADING_GUIDE.md for complete details
3. Agent Exploration: Copilot agent independently researches downloaded files using built-in tools
4. AI Analysis Pipeline:
   • Filings Analyst: Analyzes financial statements from SEC filings
   • Fraud Analyst: Validates allegations and assesses fraud probability
   • Trading Strategy Agent: AI-driven analysis of technical patterns, IV conditions, and generates three distinct strategy profiles (conservative, moderate, aggressive)
5. Generate Report: Creates comprehensive analysis document
6. Output: Markdown and JSON reports with trading recommendations

Agent Architecture

The system uses specialized AI agents powered by LLMs:

• Fraud Analyst: Identifies accounting red flags and fraud probability in SEC documents
• Fundamental Analyst: DCF valuation analysis from SEC filings
• Technical Analyst: Multi-horizon price analysis and chart patterns
• Trading Strategy Agent: Generates three strategies (conservative, moderate, aggressive) tailored to different investor risk profiles

Configuration

Edit .env file to configure:

# API Keys
GITHUB_TOKEN=your_token_here

# SEC Identity (required)
[email protected]

# Default Settings
DEFAULT_MODEL=claude-sonnet-4.5
LOG_LEVEL=INFO
OUTPUT_DIR=./data

Development

Install development dependencies:

pip install -e ".[dev]"

Run tests:

pytest
pytest --cov=src --cov-report=html

Format code:

black src/ tests/
flake8 src/ tests/
mypy src/

Test Individual Agents

For debugging and tuning agents independently without running the full pipeline:

# Test fraud analyst
python scripts/test_individual_agent.py --agent fraud --ticker APP

# Test fundamental analyst (DCF valuation)
python scripts/test_individual_agent.py --agent fundamental --ticker APP

# Test technical analyst
python scripts/test_individual_agent.py --agent technical --ticker APP

# Test options strategy analyst
python scripts/test_individual_agent.py --agent options --ticker APP

# Test all agents sequentially
python scripts/test_individual_agent.py --agent all --ticker APP

# Use different model for testing
python scripts/test_individual_agent.py --agent fundamental --ticker APP --model claude-haiku-4.5

Benefits:

• ⚡ Faster iteration - Test one agent at a time instead of full pipeline
• 💰 Lower costs - Only pay for the agent you're testing
• 🐛 Easier debugging - Isolate issues to specific agents
• 🎯 Targeted tuning - Modify prompts and immediately see results

See docs/AGENT_TESTING_GUIDE.md for detailed documentation.

Phases

Phase 0: Setup ✅

• Environment configuration
• Dependencies installation
• Project structure

Phase I: Core Analysis (In Progress)

• SEC filings integration
• Short report collection
• AI agent framework
• Market data analysis
• Report generation

Phase II: Dashboard UI (Planned)

• Interactive Dash application
• Real-time progress tracking
• Visual analytics
• Strategy recommendations

Phase III: Advanced Features (Future)

• Database integration
• Backtesting engine
• Real-time monitoring
• Multi-ticker analysis

Key Dependencies

• copilot-sdk-python: AI agent framework
• edgartools: SEC filing downloads
• rich: Terminal UI
• yfinance: Market data
• pandas/numpy: Data analysis
• beautifulsoup4: Web scraping
• dash: Interactive UI (Phase II)

Documentation

• DATA_LOADING_GUIDE.md - Comprehensive guide to data loading, fundamentals, and batch updates
• DEPLOYMENT_GUIDE.md - Production deployment with systemd, Redis, and automation
• PHASE_7_SUMMARY.md - Production integration implementation details
• docs/AGENT_TESTING_GUIDE.md - Individual agent testing and debugging
• ui_project.md - Dashboard UI project status and features

License

MIT License - See LICENSE file for details

Disclaimer

This tool is for educational and research purposes only. It does not constitute financial advice. Always conduct your own due diligence before making investment decisions. Short selling carries significant risk of loss.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Support

For issues and questions:

• GitHub Issues: Report a bug
• Email: [email protected]

Acknowledgments

• SEC.gov for public company filings
• Short seller research firms for transparency
• Open source community for excellent tools