{"id":31681320,"url":"https://github.com/romanslack/gaprunner","last_synced_at":"2025-10-08T07:48:13.957Z","repository":{"id":307724023,"uuid":"1030466702","full_name":"RomanSlack/GapRunner","owner":"RomanSlack","description":"Intraday trading simulator that buys top U.S. gap-up stocks at open using real historical data. Includes backtesting, Streamlit UI, and Alpaca paper trading.","archived":false,"fork":false,"pushed_at":"2025-08-01T19:01:09.000Z","size":96,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-01T21:34:47.666Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RomanSlack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-01T17:31:04.000Z","updated_at":"2025-08-01T19:01:13.000Z","dependencies_parsed_at":"2025-08-01T21:34:53.663Z","dependency_job_id":"b1797ac0-ea95-4d32-be27-b18d477646fd","html_url":"https://github.com/RomanSlack/GapRunner","commit_stats":null,"previous_names":["romanslack/gaprunner"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/RomanSlack/GapRunner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomanSlack%2FGapRunner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomanSlack%2FGapRunner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomanSlack%2FGapRunner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomanSlack%2FGapRunner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RomanSlack","download_url":"https://codeload.github.com/RomanSlack/GapRunner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomanSlack%2FGapRunner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278909712,"owners_count":26066887,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-08T07:47:55.384Z","updated_at":"2025-10-08T07:48:13.948Z","avatar_url":"https://github.com/RomanSlack.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GapRunner - Production Gap Trading System\n\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Production Ready](https://img.shields.io/badge/status-production--ready-green.svg)]()\n[![Security Hardened](https://img.shields.io/badge/security-hardened-brightgreen.svg)]()\n[![Data Integrity](https://img.shields.io/badge/data-validated-blue.svg)]()\n[![Real-time](https://img.shields.io/badge/execution-real--time-orange.svg)]()\n\n![Backtest Results](/images/screenshot_2.png)\n\nA production-ready overnight gap trading system implementing momentum-gap strategy with real-time data collection, advanced portfolio simulation, and comprehensive risk management.\n\n## Overview\n\nGapRunner is a professional-grade two-tier trading system designed for production deployment. The system trades the top K gap-up stocks each session using a sophisticated momentum strategy with multiple exit conditions including profit targets, trailing stops, hard stops, and time-based exits.\n\n## Architecture\n\n### Two-Tier Design\n\n**Tier 1: Data Collection \u0026 Storage**\n- Robust data pipeline with progress tracking\n- Multi-source data providers (Yahoo Finance, Polygon, Tiingo)\n- Partitioned Parquet storage for efficient access\n- Data validation and integrity checking\n\n**Tier 2: Analysis \u0026 Trading**\n- Streamlit dashboard for strategy execution\n- Real-time gap detection and ranking\n- Advanced portfolio simulation engine\n- Comprehensive performance analytics\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    TIER 1: DATA LAYER                      │\n├─────────────────────────────────────────────────────────────┤\n│  Data Collection → Storage → Validation → Management       │\n│  • Multi-source APIs     • Parquet files    • CLI tools   │\n│  • Progress tracking     • Partitioning     • Monitoring   │\n└─────────────────────────────────────────────────────────────┘\n                               │\n                               ▼\n┌─────────────────────────────────────────────────────────────┐\n│                   TIER 2: ANALYSIS LAYER                   │\n├─────────────────────────────────────────────────────────────┤\n│  Gap Engine → Portfolio Sim → Dashboard → Strategy Exec    │\n│  • Real-time gaps    • P\u0026L tracking    • Web interface     │\n│  • Ranking system    • Risk metrics    • Configuration     │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## Core Features\n\n### Production-Ready Components\n- Multi-source data providers with failover\n- Robust error handling and comprehensive logging\n- CLI tools with rich progress bars\n- Partitioned Parquet storage for efficiency\n- Real-time gap detection with technical indicators\n- Advanced portfolio simulation engine\n- YAML configuration management with validation\n- Security best practices throughout\n\n### Gap Analysis Engine\n- Real-time gap calculation and ranking\n- Technical indicator integration\n- Historical pattern analysis\n- Sector diversification support\n- Risk management controls\n\n### Interactive Dashboard\n- Production Streamlit interface\n- Real-time data visualization\n- Configuration management UI\n- Portfolio performance tracking\n- Data validation tools\n\n## Quick Start\n\n### Prerequisites\n- Python 3.12+\n- 8GB+ RAM recommended\n- 10GB+ disk space for data storage\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/GapRunner.git\ncd GapRunner/gappers_trader\n\n# Install dependencies\npip install -r requirements.txt\n\n# Or with Poetry\npoetry install\n```\n\n### Environment Setup\n\nCreate a `.env` file for API keys (optional):\n\n```bash\n# Premium data sources (optional)\nPOLYGON_API_KEY=your_polygon_key\nTIINGO_API_KEY=your_tiingo_key\nALPACA_API_KEY=your_alpaca_key\nALPACA_SECRET_KEY=your_alpaca_secret\n```\n\n### Basic Usage\n\n#### 1. Data Collection (Tier 1)\n\n```bash\n# Collect last 30 days of data\npython cli_collect.py --days 30\n\n# Collect specific date range\npython cli_collect.py --start-end 2024-01-01 2024-01-31\n\n# Validate data integrity\npython cli_collect.py --days 7 --validate\n```\n\n#### 2. Gap Analysis (CLI)\n\n```bash\n# Analyze yesterday's gaps\npython cli_gaps.py --yesterday\n\n# Analyze specific date\npython cli_gaps.py --date 2024-01-15\n\n# Export to CSV\npython cli_gaps.py --date 2024-01-15 --export gaps.csv\n```\n\n#### 3. Dashboard (Tier 2)\n\n```bash\n# Launch Streamlit dashboard\nstreamlit run app_new.py\n```\n\nNavigate to `http://localhost:8501` to access the dashboard.\n\n## Strategy Implementation\n\n### Core Strategy Rules\n- **Entry**: Top K gap-up stocks at market open (09:30 ET)\n- **Profit Target**: +10% from entry (configurable)\n- **Trailing Stop**: 2% from session high (configurable)\n- **Hard Stop**: -4% from entry (configurable)\n- **Time Stop**: 15:55 ET exit (configurable)\n\n### Risk Management\n- Position sizing: $1,000 per position (configurable)\n- Maximum positions: 10 (configurable)\n- Sector diversification limits\n- Portfolio risk controls\n\n### Cost Model\n- Commission: $0.005 per share\n- Slippage: 10 basis points\n- All costs included in P\u0026L calculations\n\n## Configuration\n\nThe system uses YAML configuration files for all settings:\n\n```yaml\n# config.yaml\ndata_sources:\n  primary: \"yfinance\"\n  fallback: [\"yfinance\"]\n\ndata_collection:\n  universe_size: 3000\n  min_dollar_volume: 1000000\n  frequency_minutes: 30\n\nstrategy:\n  top_k: 10\n  min_gap_pct: 0.02\n  max_gap_pct: 0.30\n  profit_target_pct: 0.10\n  trailing_stop_pct: 0.02\n  hard_stop_pct: 0.04\n  time_stop_hour: 15\n```\n\n## Project Structure\n\n```\ngappers_trader/\n├── gappers/                    # Core system modules\n│   ├── config_new.py          # YAML configuration management\n│   ├── data_collector.py      # Production data collection\n│   ├── data_manager.py        # Data storage \u0026 retrieval\n│   ├── data_providers.py      # Multi-source data providers\n│   ├── gap_engine.py          # Gap calculation \u0026 ranking\n│   ├── portfolio_engine.py    # Portfolio simulation engine\n│   ├── universe.py            # Stock universe management\n│   └── ...\n├── app_new.py                 # Production Streamlit dashboard\n├── cli_collect.py             # CLI data collection tool\n├── cli_gaps.py                # CLI gap analysis tool\n├── config.yaml                # System configuration\n├── requirements.txt           # Python dependencies\n└── README_NEW.md              # Detailed documentation\n```\n\n## Dashboard Features\n\n### Dashboard\n- System overview and key metrics\n- Quick gap analysis\n- Real-time status monitoring\n\n### Data Collection\n- Interactive data collection interface\n- Progress tracking with rich progress bars\n- Data validation and integrity checks\n- Storage statistics and management\n\n### Gap Analysis\n- Real-time gap detection and ranking\n- Historical pattern analysis\n- Technical indicator integration\n- Interactive charts and visualizations\n\n### Portfolio Simulation\n- Advanced backtesting engine\n- P\u0026L tracking with costs\n- Risk metrics and drawdown analysis\n- Strategy parameter optimization with tooltips\n\n### Configuration\n- Web-based configuration management\n- Parameter validation\n- Multiple data source support\n- Security settings\n\n## Security \u0026 Production Features\n\n### Security\n- API key encryption and secure storage\n- Rate limiting and request throttling\n- Input validation and sanitization\n- Comprehensive audit logging\n- Error handling without data exposure\n\n### Production Readiness\n- Robust error handling and recovery\n- Comprehensive logging system\n- Data validation and integrity checks\n- Performance monitoring\n- Scalable architecture\n- Memory-efficient data processing\n- Concurrent data collection\n- Progress tracking and status reporting\n\n### Performance\n- Partitioned Parquet storage for fast queries\n- Caching system for API responses\n- Concurrent data processing\n- Memory-efficient operations\n- Optimized data structures\n\n## Testing \u0026 Validation\n\n```bash\n# Run tests\npytest tests/\n\n# Run with coverage\npytest --cov=gappers tests/\n\n# Lint code\nruff check gappers/\nblack --check gappers/\n\n# Type checking\nmypy gappers/\n```\n\n## API Reference\n\n### Core Classes\n\n#### `Config`\n```python\nfrom gappers.config_new import Config\n\nconfig = Config.load(\"config.yaml\")\nissues = config.validate()  # Returns validation issues\n```\n\n#### `DataCollector`\n```python\nfrom gappers.data_collector import DataCollector\n\ncollector = DataCollector(config)\nsuccess = collector.collect_full_dataset(start_date, end_date)\n```\n\n#### `GapEngine`\n```python\nfrom gappers.gap_engine import GapEngine\n\nengine = GapEngine(config)\ngaps_df = engine.calculate_daily_gaps(date)\ntop_gaps = engine.get_top_gaps(date, direction=\"up\", limit=10)\n```\n\n#### `PortfolioEngine`\n```python\nfrom gappers.portfolio_engine import PortfolioEngine\n\nengine = PortfolioEngine(config)\nresults = engine.run_backtest(start_date, end_date)\n```\n\n## Documentation\n\nFor detailed documentation, see [README_NEW.md](./gappers_trader/README_NEW.md) in the gappers_trader directory.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Disclaimer\n\nThis software is for educational and research purposes only. Past performance does not guarantee future results. Trading involves substantial risk of loss and is not suitable for all investors. Please consult with a qualified financial advisor before making any investment decisions.\n\n## Support\n\n- Issues: [GitHub Issues](https://github.com/yourusername/GapRunner/issues)\n- Documentation: [Full Documentation](./gappers_trader/README_NEW.md)\n\n---\n\n**Built for the trading community**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fromanslack%2Fgaprunner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fromanslack%2Fgaprunner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fromanslack%2Fgaprunner/lists"}