{"id":31936625,"url":"https://github.com/bluepeter/alphagroove","last_synced_at":"2026-07-18T06:33:44.723Z","repository":{"id":318524497,"uuid":"979055621","full_name":"bluepeter/alphagroove","owner":"bluepeter","description":"Backtesting engine with LLM trade analysis and real-time market scouting","archived":false,"fork":false,"pushed_at":"2025-10-07T18:47:58.000Z","size":854,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2026-07-18T06:33:23.036Z","etag":null,"topics":["backtesting","daytrading","stock-analysis","stock-trading","technical-analysis"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bluepeter.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-06T23:42:58.000Z","updated_at":"2025-10-15T14:17:08.000Z","dependencies_parsed_at":"2025-10-07T18:42:20.099Z","dependency_job_id":null,"html_url":"https://github.com/bluepeter/alphagroove","commit_stats":null,"previous_names":["bluepeter/alphagroove"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bluepeter/alphagroove","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluepeter%2Falphagroove","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluepeter%2Falphagroove/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluepeter%2Falphagroove/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluepeter%2Falphagroove/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bluepeter","download_url":"https://codeload.github.com/bluepeter/alphagroove/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluepeter%2Falphagroove/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35609253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-18T02:00:07.223Z","response_time":61,"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":["backtesting","daytrading","stock-analysis","stock-trading","technical-analysis"],"created_at":"2025-10-14T07:46:51.375Z","updated_at":"2026-07-18T06:33:44.707Z","avatar_url":"https://github.com/bluepeter.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AlphaGroove\n\nA comprehensive trading strategy development and execution toolkit that bridges the gap between\nbacktesting and live trading. AlphaGroove consists of two complementary tools designed for hands-on\nquant researchers who prefer scripting over spreadsheets, precision over black boxes, and\nintelligent analysis over curve-fitting.\n\n## Tools Overview\n\n**Backtesting Engine (`pnpm dev:start`)**\n\n- Historical analysis of intraday trading patterns using high-resolution datasets\n- LLM-powered trade analysis with automated chart generation for pattern recognition\n- **Enhanced Market Context**: LLM receives comprehensive market metrics including gaps, VWAP, SMA,\n  and price relationships\n- Statistical analysis with comprehensive metrics (mean/median returns, win rates, distribution\n  analysis)\n- Modular pattern architecture for entry/exit strategies\n\n**Entry Scout (`pnpm scout`)**\n\n- Real-time market analysis using Polygon.io API\n- Same LLM configuration and analysis methods validated through backtesting\n- **Rich Market Context**: LLM receives detailed market metrics including previous close, gaps, VWAP\n  vs price, SMA vs price\n- Generates actionable trade signals with specific entry/exit levels for manual execution\n- On-demand analysis for any date/time, not just current market conditions\n- **Automated Monitoring**: Continuous execution with prominent alerts for trade signal changes\n\n## Installation \u0026 Setup\n\n### Prerequisites\n\n**Required: DuckDB Installation**\n\n```bash\n# Install DuckDB using Homebrew\nbrew install duckdb\n\n# Verify the installation\nduckdb --version\n```\n\nIf you don't have Homebrew installed, you can install it from [brew.sh](https://brew.sh).\n\n**Node.js Setup \u0026 Dependencies**\n\nThe project requires Node.js 18 or later. We recommend using `pnpm` as the package manager.\n\n```bash\n# Install dependencies\npnpm install\n```\n\nThis command will install all necessary Node.js packages, including `sharp` which is used for\ngenerating PNG chart images. `sharp` includes native C++ components; `pnpm` typically handles its\ncompilation and any system dependencies. However, if you encounter issues during `sharp`\ninstallation related to `libvips` or similar missing libraries, you may need to install `libvips`\nmanually using your system's package manager (e.g., `brew install vips` on macOS, or\n`sudo apt-get install libvips-dev` on Debian/Ubuntu) and then try `pnpm install` again.\n\n### Configuration\n\n**Required:** Create a configuration file named `alphagroove.config.yaml` in the project root\ndirectory:\n\n```yaml\n# === SHARED CONFIGURATION ===\n# Used by both backtest and scout tools\nshared:\n  ticker: 'SPY'\n  timeframe: '1min'\n  suppressSma: false # Set to true to disable SMA computation and display\n  suppressVwap: false # Set to true to disable VWAP computation and display\n  suppressMetricsInPrompts: false # Set to true to exclude text metrics from LLM prompts\n\n  # LLM configuration for intelligent trade analysis\n  llmConfirmationScreen:\n    # Choose your LLM provider - flagship models are automatically selected:\n    llmProvider: 'anthropic' # Uses claude-sonnet-4-20250514 automatically\n    # llmProvider: 'openai'   # Uses gpt-5-mini automatically\n\n    numCalls: 2\n    agreementThreshold: 2\n    temperatures: [0.2, 1.0] # Note: GPT-5-mini only supports default temperature (1)\n    prompts:\n      - 'Analyze this chart as a cautious trader. Action: long, short, or do_nothing? Rationale?'\n      - 'Analyze this chart as an aggressive trader. Action: long, short, or do_nothing? Rationale?'\n    commonPromptSuffixForJson: \u003e-\n      Respond in JSON: {\"action\": \"\u003caction\u003e\", \"rationalization\": \"\u003cone_sentence_rationale\u003e\",\n      \"proposedStopLoss\": \u003cprice_or_null\u003e, \"proposedProfitTarget\": \u003cprice_or_null\u003e}\n    systemPrompt: \u003e-\n      You are a seasoned day trader. You know when to save your powder and wait. Only when you're\n      sure will you go long or short.\n    maxOutputTokens: 2000\n    timeoutMs: 30000\n\n# === BACKTEST-SPECIFIC CONFIGURATION ===\nbacktest:\n  date:\n    from: '2023-01-01'\n    to: '2025-05-02'\n  parallelization:\n    maxConcurrentDays: 3\n\n  # Entry pattern configuration (backtest only)\n  entry:\n    enabled: [randomTimeEntry]\n    strategyOptions:\n      randomTimeEntry:\n        startTime: '10:00'\n        endTime: '15:00'\n      fixedTimeEntry:\n        entryTime: '13:00'\n      quickRise:\n        risePct: 0.3\n        withinMinutes: 5\n      quickFall:\n        fallPct: 0.3\n        withinMinutes: 5\n\n  # Exit strategies configuration (backtest only)\n  exit:\n    enabled: [profitTarget, trailingStop]\n    endOfDay:\n      time: '16:00'\n    strategyOptions:\n      profitTarget:\n        atrMultiplier: 3.0\n        useLlmProposedPrice: true\n      trailingStop:\n        activationAtrMultiplier: 0\n        trailAtrMultiplier: 2.5\n\n  # Execution configuration (backtest only)\n  execution:\n    slippage:\n      model: 'fixed'\n      value: 0.01\n\n# === SCOUT-SPECIFIC CONFIGURATION ===\nscout:\n  polygon:\n    apiKeyEnvVar: 'POLYGON_API_KEY'\n```\n\n**Configuration Structure**\n\nThe `alphagroove.config.yaml` file is organized into three sections:\n\n1. **`shared`**: Settings used by both tools (ticker, LLM configuration, SMA suppression)\n2. **`backtest`**: Backtest-specific settings (date ranges, entry patterns, exit strategies)\n3. **`scout`**: Scout-specific settings (API configuration)\n\n**Environment Variables**\n\nCreate a `.env.local` file in the project root with your API keys:\n\n```bash\n# LLM Provider API Keys (set the one you're using)\nANTHROPIC_API_KEY=your_anthropic_api_key_here  # For Anthropic Claude\nOPENAI_API_KEY=your_openai_api_key_here        # For OpenAI GPT models\n\n# Market Data API Key\nPOLYGON_API_KEY=your_polygon_api_key_here\n```\n\n**Note**: The system automatically selects the correct API key based on your `llmProvider` setting:\n\n- `llmProvider: 'anthropic'` → uses `ANTHROPIC_API_KEY`\n- `llmProvider: 'openai'` → uses `OPENAI_API_KEY`\n\n**Available Timeframes**\n\nFormat: `\u003cnumber\u003e\u003cunit\u003e` where unit is min, hour, or day\n\n- `1min`, `5min`, `15min`, `30min`, `1hour`, `1day`\n\n**Configuration Priority**\n\nConfiguration hierarchy (highest to lowest priority):\n\n1. Command line arguments\n2. Config file settings\n3. ⚠️ **No system defaults** - explicit configuration required\n\nAll configuration must be explicitly provided. The system will provide clear error messages for\nmissing settings rather than using hidden defaults.\n\n**SMA Suppression**\n\nThe `suppressSma` option in the shared configuration allows you to disable SMA (Simple Moving\nAverage) computation and display across both backtest and scout tools:\n\n- **Performance Benefits**: Eliminates the need to fetch additional historical data for SMA\n  calculation\n- **Faster Execution**: Reduces API calls to Polygon for scout and database queries for backtest\n- **Simplified Analysis**: Focuses analysis on price action, volume, and VWAP without SMA context\n- **Chart Clarity**: Removes SMA line and VWAP vs SMA comparison from charts\n- **LLM Prompts**: Excludes SMA context from market metrics sent to LLMs\n\nSet `suppressSma: true` when you want to focus purely on intraday price action and VWAP analysis\nwithout the overhead of 20-day SMA calculations.\n\n**VWAP Suppression**\n\nThe `suppressVwap` option in the shared configuration allows you to disable VWAP (Volume Weighted\nAverage Price) computation and display across both backtest and scout tools:\n\n- **Performance Benefits**: Eliminates VWAP calculations during chart generation\n- **Faster Execution**: Reduces computation overhead for volume-weighted price analysis\n- **Simplified Analysis**: Focuses analysis on price action and SMA without VWAP context\n- **Chart Clarity**: Removes VWAP line and VWAP vs SMA comparison from charts\n- **LLM Prompts**: Excludes VWAP context from market metrics sent to LLMs\n\nSet `suppressVwap: true` when you want to focus purely on price action and SMA analysis without VWAP\ncalculations. You can use both `suppressSma` and `suppressVwap` together to create the most\nstreamlined analysis focusing only on basic price action.\n\n**Market Metrics in Prompts Suppression**\n\nThe `suppressMetricsInPrompts` option in the shared configuration allows you to exclude all text\nmetrics from LLM prompts while keeping them visible in charts:\n\n- **Chart Preservation**: All metrics (VWAP, SMA, gap analysis) remain visible in generated charts\n- **Prompt Simplification**: LLM prompts contain no \"Market Context\" section with text metrics\n- **Performance Benefits**: Eliminates market metrics calculation overhead for LLM calls\n- **Focus on Visual Analysis**: Forces LLM to rely purely on visual chart analysis\n\nSet `suppressMetricsInPrompts: true` when you want the LLM to make decisions based solely on chart\npatterns without being influenced by numerical market context. This can be useful for testing\nwhether the LLM's visual pattern recognition performs better without text-based market data.\n\nYou can generate a default config file by running:\n\n```bash\npnpm dev:start init\n```\n\n## LLM-Powered Analysis\n\nBoth tools use Large Language Models to analyze chart patterns and make intelligent trading\ndecisions. Rather than relying solely on technical indicators, the system generates high-quality\ncharts for every potential trade and sends them to an LLM for analysis.\n\n**How it Works:**\n\n- **Automatic Chart Generation**: Every signal triggers creation of anonymized candlestick charts\n- **Multi-Model Analysis**: Configurable number of LLM calls with different temperature settings\n- **Consensus Decision Making**: Trades execute only when LLMs reach agreement threshold\n- **Dynamic Direction**: LLM can decide whether to go long, short, or skip the trade entirely\n- **Price Target Suggestions**: LLMs can propose stop loss and profit target levels\n\n**Key Benefits:**\n\n- **Pattern Recognition**: LLMs excel at identifying complex chart patterns humans might miss\n- **Context Awareness**: Considers volume, prior day action, and intraday dynamics\n- **Risk Management**: Conservative approach - only trades when confident\n- **Eliminates Bias**: Anonymized charts prevent historical knowledge from influencing decisions\n\n## LLM Provider Support\n\nAlphaGroove supports multiple LLM providers with automatic flagship model selection and optimized\nconfigurations:\n\n### Supported Providers\n\n**Anthropic Claude**\n\n- **Model**: `claude-sonnet-4-20250514` (automatically selected)\n- **API Key**: `ANTHROPIC_API_KEY` (automatically used)\n- **Temperature Support**: Full range (0.0 - 2.0)\n- **Cost**: ~$3/$15 per million input/output tokens\n\n**OpenAI GPT**\n\n- **Model**: `gpt-5-mini` (automatically selected)\n- **API Key**: `OPENAI_API_KEY` (automatically used)\n- **Temperature Support**: Default only (1.0) - model limitation\n- **Cost**: ~$5/$20 per million input/output tokens\n- **Special Features**: Reasoning effort, verbosity controls\n\n### Switching Providers\n\nSimply change the `llmProvider` setting in your config:\n\n```yaml\nshared:\n  llmConfirmationScreen:\n    # Switch between providers:\n    llmProvider: 'anthropic' # Uses claude-sonnet-4-20250514\n    # llmProvider: 'openai'   # Uses gpt-5-mini\n```\n\n**No other configuration changes needed** - the system automatically:\n\n- Selects the flagship model for your chosen provider\n- Uses the correct API key environment variable\n- Applies provider-specific parameter optimizations\n- Handles model-specific limitations (e.g., temperature restrictions)\n\n### Provider-Specific Behavior\n\n- **Temperature Handling**: OpenAI GPT-5-mini uses default temperature (1.0) regardless of your\n  `temperatures` config due to model limitations. Anthropic supports custom temperatures.\n- **API Parameters**: Each provider uses optimized parameters (e.g., `max_completion_tokens` for\n  GPT-5, `reasoning_effort` settings)\n- **Cost Tracking**: Accurate token-based cost calculation for each provider\n- **Error Handling**: Provider-specific error messages and graceful degradation\n\n---\n\n# Backtesting Engine\n\nHistorical analysis of trading patterns with comprehensive statistical reporting.\n\n## Usage\n\n```bash\n# Basic usage with config file\npnpm dev:start\n\n# Override specific settings\npnpm dev:start --from 2023-01-01 --to 2023-12-31\n\n# Use different entry pattern\npnpm dev:start --entry-pattern quickFall\n\n# Override pattern parameters\npnpm dev:start --quickRise.risePct=0.5 --fixedTimeEntry.entryTime=13:00\n\n# Process multiple days concurrently for faster execution\npnpm dev:start --maxConcurrentDays 5\n\n# Show debug information\npnpm dev:start --debug --verbose\n\n# Dry run (show query without executing)\npnpm dev:start --dry-run\n```\n\n## Entry Patterns\n\nEntry patterns detect specific market conditions for trade initiation:\n\n- **`quickRise`**: Detects a percentage rise in the first few minutes of trading\n- **`quickFall`**: Detects a percentage fall in the first few minutes of trading\n- **`fixedTimeEntry`**: Triggers entry at a specific time of day\n- **`randomTimeEntry`**: Triggers entry at a random time within a configured window (eliminates\n  time-based biases)\n\n## Exit Strategies\n\nDynamic exit strategies analyze price action bar-by-bar:\n\n### Stop Loss\n\nExits when price moves against your position by a specified amount.\n\n- `percentFromEntry`: Exit when price moves against position by this percentage\n- `atrMultiplier`: Alternative using Average True Range multiplier\n- `useLlmProposedPrice`: Use LLM-suggested stop loss price if available\n\n### Profit Target\n\nExits when price moves in your favor by a specified amount.\n\n- `percentFromEntry`: Exit when price moves in favor by this percentage\n- `atrMultiplier`: Alternative using ATR multiplier\n- `useLlmProposedPrice`: Use LLM-suggested profit target price if available\n\n### Trailing Stop\n\nFollows price movement with a dynamic stop loss.\n\n- `activationPercent`: Trailing stop activates after this favorable move\n- `trailPercent`: Stop trails best price by this percentage\n\n### Time-Based Exits\n\n- **Max Hold Time**: Exit after holding for specified minutes\n- **End of Day**: Exit at specific time to avoid overnight exposure\n\n### ATR-Based Dynamic Adjustment\n\nExit parameters can use Average True Range from the prior trading day for volatility-adaptive\nlevels:\n\n```yaml\nexit:\n  strategyOptions:\n    stopLoss:\n      atrMultiplier: 1.5 # Stop at 1.5x ATR below entry (longs)\n    profitTarget:\n      atrMultiplier: 3.0 # Target at 3.0x ATR above entry (longs)\n```\n\n### Slippage Modeling\n\nModels realistic trading costs:\n\n- `model`: 'percent' or 'fixed'\n- `value`: Percentage (e.g., 0.05 for 0.05%) or fixed amount\n\n## Performance Optimization\n\n**Parallel Processing**: Process multiple trading days concurrently for faster backtests:\n\n```bash\n# Process up to 5 days simultaneously\npnpm dev:start --maxConcurrentDays 5\n```\n\nConfiguration:\n\n```yaml\nbacktest:\n  parallelization:\n    maxConcurrentDays: 5\n```\n\n**LLM Analysis Output**: When LLM screening is enabled, the backtest generates chart overlays with\ncolor-coded decisions (LONG/SHORT/DO_NOTHING) and detailed analysis files for each trade, saved in\nthe entry pattern directory.\n\n## Command Line Options\n\n| Option                         | Description                                                      | Default     |\n| ------------------------------ | ---------------------------------------------------------------- | ----------- |\n| `--from \u003cYYYY-MM-DD\u003e`          | Start date (inclusive)                                           | From config |\n| `--to \u003cYYYY-MM-DD\u003e`            | End date (inclusive)                                             | From config |\n| `--entry-pattern \u003cpattern\u003e`    | Entry pattern to use                                             | From config |\n| `--ticker \u003csymbol\u003e`            | Ticker to analyze                                                | SPY         |\n| `--timeframe \u003cperiod\u003e`         | Data resolution                                                  | 1min        |\n| `--maxConcurrentDays \u003cnumber\u003e` | Max concurrent days (1-20)                                       | 3           |\n| `--debug`                      | Show debug information                                           | false       |\n| `--verbose`                    | Show detailed LLM responses and full prompts with market context | false       |\n| `--dry-run`                    | Show query without executing                                     | false       |\n\n### Pattern-Specific Options\n\n**Quick Rise/Fall:**\n\n- `--quickRise.risePct=0.5` - Minimum percentage rise to trigger\n- `--quickRise.withinMinutes=5` - Minutes to look for the rise\n- `--quickFall.fallPct=0.3` - Minimum percentage fall to trigger\n- `--quickFall.withinMinutes=5` - Minutes to look for the fall\n\n**Fixed Time Entry:**\n\n- `--fixedTimeEntry.entryTime=13:00` - Entry time in HH:MM format (required)\n\n**Random Time Entry:**\n\n- `--randomTimeEntry.startTime=09:30` - Start of random window\n- `--randomTimeEntry.endTime=16:00` - End of random window\n\n---\n\n# Entry Scout\n\nReal-time market analysis for live trading decisions.\n\n## Usage\n\n```bash\n# Scout current market conditions\npnpm scout\n\n# Scout with verbose LLM output\npnpm scout --verbose\n\n# Scout specific ticker\npnpm scout --ticker AAPL\n\n# Scout specific date and time\npnpm scout --date 2025-05-28 --time 12:30\n\n# Scout with custom ticker and time\npnpm scout --ticker SPY --date 2025-05-28 --time 14:30 --verbose\n```\n\n## Features\n\n- **Real-Time Data**: Uses Polygon.io API for current and historical market data\n- **Identical Analysis**: Same LLM configuration and chart generation as backtesting\n- **Enhanced Market Context**: LLM receives comprehensive market metrics (see below)\n- **Trade Recommendations**: Provides entry/exit levels, stop loss, and profit targets\n- **Risk/Reward Analysis**: Calculates risk-reward ratios and percentage moves\n- **Flexible Timing**: Analyze any date/time, not just current market conditions\n- **Result Charts**: Automatically generates charts with LLM decision overlays\n- **Output Files**: Saves complete analysis results to timestamped and latest files\n\n## Market Context for LLM Analysis\n\nBoth the backtesting engine and scout provide rich market context to the LLM for more informed\ndecision-making. When using the `--verbose` flag, you can see the full prompts including this market\ncontext.\n\n### Market Metrics Included\n\nThe LLM receives a **Market Context** section with each prompt containing:\n\n- **Previous Close \u0026 Today's Open**: Gap analysis with percentage and direction\n- **Today's High/Low Range**: Current trading range context\n- **Current Price \u0026 Time**: Real-time price action\n- **VWAP Analysis**: Current price relative to Volume Weighted Average Price (if not suppressed)\n- **SMA Analysis**: Current price relative to 20-day Simple Moving Average (if not suppressed)\n- **VWAP vs SMA**: Relationship between technical indicators (if neither VWAP nor SMA suppressed)\n\n### Example Market Context\n\n```\nMarket Context:\nPrev Close: $644.84 | Today Open: $637.50 | GAP DOWN: $-7.34 (-1.14%)\nToday H/L: $640.14/$634.92 | Current: $638.53 @ 03:10 PM\nCurrent price of $638.53 is $1.08 ABOVE VWAP of $637.45.\nCurrent price of $638.53 is $2.02 BELOW SMA of $640.55.\nVWAP of $637.45 is $3.10 BELOW SMA of $640.55.\n```\n\nThis context helps the LLM understand:\n\n- **Gap conditions** (up/down from previous close)\n- **Intraday momentum** (relative to VWAP)\n- **Trend context** (relative to 20-day SMA, when enabled)\n- **Technical alignment** (VWAP vs SMA positioning, when SMA enabled)\n\n**Note**: When `suppressSma: true` is set in configuration, SMA-related metrics are excluded from\nboth charts and LLM prompts, focusing analysis on price action and VWAP only.\n\n## Generated Files\n\nScout automatically generates multiple files for each analysis:\n\n### Chart Files\n\n- **`YYYY-MM-DDTHH-mm-ss_TICKER_YYYYMMDD_masked.png`** - Anonymized chart sent to LLM\n- **`YYYY-MM-DDTHH-mm-ss_TICKER_YYYYMMDD_complete.png`** - Full chart with all details\n- **`YYYY-MM-DDTHH-mm-ss_TICKER_YYYYMMDD_masked_result.png`** - Masked chart with LLM decision\n  overlay\n- **`latest_masked.png`** - Most recent anonymized chart\n- **`latest_complete.png`** - Most recent complete chart\n- **`latest_masked_result.png`** - Most recent chart with decision overlay\n\n### Output Files\n\n- **`YYYY-MM-DDTHH-mm-ss_TICKER_YYYYMMDD_action_[DECISION].txt`** - Timestamped analysis results\n- **`latest_action.txt`** - Most recent analysis results (overwritten each run)\n\n### Decision Overlays\n\nCharts with `_result.png` suffix include color-coded decision overlays:\n\n- **LONG** - Green text overlay\n- **SHORT** - Red text overlay\n- **DO NOTHING** - Orange text overlay\n\n## Command Line Options\n\n| Option                | Description                                                      | Default      |\n| --------------------- | ---------------------------------------------------------------- | ------------ |\n| `--ticker \u003csymbol\u003e`   | Ticker symbol (overrides config)                                 | From config  |\n| `--date \u003cYYYY-MM-DD\u003e` | Trade date                                                       | Today        |\n| `--time \u003cHH:MM\u003e`      | Entry time in Eastern Time                                       | Current time |\n| `-v, --verbose`       | Show detailed LLM responses and full prompts with market context | false        |\n\n## Requirements\n\n- Polygon.io API key set in environment variable\n- Market data availability for requested date/time\n\n## Integration with Backtesting\n\nThe scout uses identical methods as the backtesting engine:\n\n- Same LLM configuration and consensus logic\n- Identical exit strategy calculations (stop loss, profit target, trailing stop)\n- Same chart format and anonymization\n- ATR-based calculations using real-time data\n\n## Automated Live Trading Monitoring\n\nFor continuous monitoring during trading hours, use the two-terminal approach:\n\n### Terminal 1: Continuous Scout Execution\n\n```bash\n# Run scout every 60 seconds continuously\nwatch -n 60 'pnpm scout'\n\n# Alternative: Run every 30 seconds for faster updates\nwatch -n 30 'pnpm scout'\n```\n\n### Terminal 2: Decision Change Monitoring\n\n```bash\n# Monitor for trade signal changes with prominent alerts\n./monitor_scout.sh\n```\n\n### How It Works\n\n1. **Terminal 1** runs `pnpm scout` continuously at your chosen interval (30-60 seconds recommended)\n2. Each scout run updates `charts/scout/latest_action_simple.txt` with the current decision: `LONG`,\n   `SHORT`, or `DO NOTHING`\n3. **Terminal 2** monitors this file and provides **prominent alerts** when decisions change:\n   - **🚨 TRADE SIGNALS (LONG/SHORT)**: Multiple notifications with different sounds, visual\n     terminal alerts, and audio bells\n   - **💤 DO NOTHING**: Single quiet notification\n\n### Setup\n\n```bash\n# Make the monitoring script executable (one-time setup)\nchmod +x monitor_scout.sh\n\n# Start monitoring in one terminal\n./monitor_scout.sh\n\n# Start continuous scout execution in another terminal\nwatch -n 60 'pnpm scout'\n```\n\n### Files Generated\n\n- **`latest_action_simple.txt`** - Single word decision file for monitoring (`LONG`, `SHORT`,\n  `DO NOTHING`)\n- **`latest_action.txt`** - Full detailed analysis results\n- **`latest_masked_result.png`** - Chart with decision overlay\n- All timestamped versions are also created for historical reference\n\n## Typical Workflow\n\n1. **Backtest**: Validate strategy parameters and LLM configuration using historical data\n2. **Scout**: Use real-time analysis for current market conditions\n3. **Monitor**: Use automated monitoring for continuous trade signal detection\n4. **Execute**: Apply LLM recommendations and calculated levels in your brokerage platform\n\n## Directory Structure\n\n```\nalphagroove/\n├── src/                # Source code\n│   ├── index.ts        # Backtesting engine\n│   ├── scout.ts        # Entry scout\n│   ├── patterns/       # Entry and exit pattern implementations\n│   ├── services/       # External service integrations\n│   └── utils/          # Utility functions\n├── tickers/            # Market data (SPY, TEST, etc.)\n├── charts/             # Generated chart outputs\n├── results/            # Backtest results\n├── alphagroove.config.yaml # Configuration file (you create this)\n└── README.md           # This documentation\n```\n\n## Licensing\n\n- Community: AGPL‑3.0‑only. See [LICENSE](LICENSE).\n- Commercial: Need to use our software without AGPL obligations or for closed‑source use?\n  [COMMERCIAL.md](COMMERCIAL.md) has details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluepeter%2Falphagroove","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbluepeter%2Falphagroove","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluepeter%2Falphagroove/lists"}