---
title: stocks
app_file: gradio_stock_dashboard.py
sdk: gradio
sdk_version: 3.40.0
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

# 📈 Real-Time Stock Market Dashboard

A comprehensive stock market analysis dashboard built with Gradio that provides real-time stock data visualization, technical analysis, and SEC EDGAR integration for regulatory filings and financial metrics.

## ✨ Features

### 📊 Stock Analysis
- **Real-time stock data** from S&P 500 companies
- **Multiple chart types**: Candlestick, Line, OHLC, Renko, and Technical Analysis
- **Technical indicators**: SMA, EMA, MACD, Volume analysis
- **Correlation heatmaps** for portfolio analysis
- **Market summary** with current prices and changes

### 📄 SEC EDGAR Integration
- **Real-time SEC filings** with direct links to official documents
- **Financial metrics extraction** from XBRL data
- **Comprehensive filing analysis** including 10-K, 10-Q, 8-K, and more
- **Key financial data**: Revenue, Net Income, Total Assets, Cash & Equivalents
- **Rate-limited API calls** with automatic retry logic
- **Enhanced error handling** for robust data retrieval

## 🚀 Getting Started

### Prerequisites
- Python 3.8 or higher
- Internet connection for real-time data
- Modern web browser

### Installation

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd stocks
   ```

2. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

3. **Run the dashboard**
   ```bash
   python gradio_stock_dashboard.py
   ```

4. **Open your browser** and navigate to `http://localhost:7860`

## 📖 Usage Guide

### Basic Stock Analysis
1. **Select stocks** from the S&P 500 list
2. **Choose chart type** (candlestick, line, OHLC, technical)
3. **Set time period** (5-365 days)
4. **Click "Update Chart"** to generate visualizations

### SEC EDGAR Features

#### 📄 View Recent SEC Filings
1. Select one or more companies
2. Click **"Update Filings"** button
3. View comprehensive filing table with:
   - Company name and ticker
   - Filing type and description
   - Filing date (color-coded by recency)
   - Direct links to SEC documents
   - Form type explanations

#### 💰 Financial Metrics Analysis
1. Select companies for analysis
2. Click **"Update Metrics"** button
3. View key financial data:
   - Revenue and Net Income
   - Total Assets and Cash & Equivalents
   - Report dates and data sources
   - Currency formatting (B/M/K for billions/millions/thousands)

#### 📊 Comprehensive SEC Summary
1. Select multiple companies
2. Click **"Update Comprehensive Summary"** button
3. Get combined overview of:
   - Financial data availability
   - Filing type distribution
   - Usage instructions
   - Data freshness information

### Advanced Features
- **Auto-refresh** settings for real-time updates
- **Correlation analysis** for portfolio optimization
- **Technical indicators** for trading decisions
- **Volume analysis** for market sentiment

## 🔧 Technical Details

### SEC EDGAR API Integration
- **Rate limiting**: 100ms between requests (SEC requirement)
- **Retry logic**: Automatic retry with exponential backoff
- **Error handling**: Comprehensive HTTP status code handling
- **Data parsing**: XBRL and JSON response processing
- **CIK mapping**: Automatic ticker to CIK conversion

### Data Sources
- **Stock data**: Yahoo Finance (yfinance) with fallback data
- **SEC filings**: Official SEC EDGAR database
- **Company info**: SEC company tickers endpoint
- **Financial metrics**: XBRL data from company facts

### Performance Features
- **Caching**: Company info and ticker data caching
- **Async processing**: Concurrent data retrieval
- **Memory management**: Efficient data storage and cleanup
- **User feedback**: Progress indicators and status messages

## 🧪 Testing

Run the test script to verify SEC EDGAR integration:

```bash
python test_sec_integration.py
```

This will test:
- SEC API connectivity
- Company CIK lookup
- Filing retrieval
- Financial metrics extraction
- Multiple company processing

## 📁 File Structure

```
stocks/
├── gradio_stock_dashboard.py    # Main dashboard application
├── test_sec_integration.py      # SEC integration test script
├── requirements.txt             # Python dependencies
├── README.md                    # This documentation
└── sp500tickers.pickle         # Cached S&P 500 tickers (auto-generated)
```

## 🚨 Important Notes

### SEC API Usage
- **Rate limits**: Respect SEC's 100ms minimum interval between requests
- **User agent**: Proper identification required for API access
- **Data freshness**: Financial data may have reporting delays
- **API availability**: SEC services may experience occasional downtime

### Data Accuracy
- **Real-time data**: Stock prices update continuously during market hours
- **SEC filings**: Official regulatory documents with filing delays
- **Fallback data**: Generated sample data when external sources fail
- **Verification**: Always verify critical data from official sources

## 🐛 Troubleshooting

### Common Issues

1. **No stock data available**
   - Check internet connection
   - Verify yfinance installation
   - Try refreshing data

2. **SEC filings not loading**
   - Check SEC API status
   - Verify company ticker spelling
   - Wait for rate limit reset

3. **Chart display issues**
   - Update matplotlib and mplfinance
   - Check browser compatibility
   - Clear browser cache

### Error Messages
- **Rate limit exceeded**: Wait and retry
- **No CIK found**: Verify ticker symbol
- **API timeout**: Check network connection
- **Data parsing error**: Report issue with specific company

## 🤝 Contributing

Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🙏 Acknowledgments

- **SEC EDGAR**: For providing public financial data
- **Gradio**: For the excellent web interface framework
- **yfinance**: For stock market data access
- **Open source community**: For various supporting libraries

---

**Disclaimer**: This tool is for educational and research purposes. Always verify financial data from official sources before making investment decisions.