Add CI pipeline and update README

costajohnt · claude · costajohnt · commit ab975c054cf0 · 2026-02-24T15:04:53.000-08:00
CI workflow runs tests on push/PR to main. README updated to reflect
current architecture: strategy agent, OpenRouter integration, 654 tests,
GHA-based daily pipeline, quality filters, and safety rails.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install Python and dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run python -m pytest tests/ -v --tb=short
diff --git a/README.md b/README.md
@@ -1,11 +1,15 @@
 # alpaca-trader
 
+[![CI](https://github.com/costajohnt/alpaca-trader/actions/workflows/ci.yml/badge.svg)](https://github.com/costajohnt/alpaca-trader/actions/workflows/ci.yml)
+
 Automated equities trading system built on Alpaca's API. Combines mean-reversion technicals, AI sentiment analysis, insider trading signals, and momentum detection with conviction-based position sizing and sector exposure guards.
 
+An autonomous strategy agent (Claude Opus 4.6 via OpenRouter) reviews performance weekly, runs shadow experiments, and deploys validated improvements — all within hardcoded safety rails.
+
 ## Setup
 
 ```bash
-# Install dependencies
+# Install dependencies (requires Python 3.14+)
 uv sync
 
 # Copy and fill in your API keys
@@ -19,11 +23,11 @@ Required `.env` keys:
 
 Optional `.env` keys:
 
-- `FINNHUB_API_KEY` — enables insider trading + earnings signals
+- `ANTHROPIC_API_KEY` — enables Claude Haiku sentiment analysis via Alpaca News API
+- `OPENROUTER_API_KEY` — enables autonomous strategy agent (Claude Opus 4.6)
+- `FINNHUB_API_KEY` — enables insider trading + earnings signals (cached, rate-limited)
 - `TELEGRAM_BOT_TOKEN` / `TELEGRAM_CHAT_ID` — enables Telegram notifications
 
-> The Claude CLI must be installed and authenticated separately for sentiment analysis.
-
 ## Usage
 
 ```bash
@@ -46,7 +50,10 @@ uv run python scripts/scan_with_sentiment.py --execute
 uv run python scripts/screener.py --min-dip -8.0
 
 # Auto-trade top screener picks
-uv run python scripts/screener_trade.py --min-dip -10.0 --max-trades 5 --execute
+uv run python scripts/screener_trade.py --min-dip -7.0 --max-trades 8 --execute
+
+# Momentum auto-trade
+uv run python scripts/momentum_trade.py --min-momentum 10.0 --max-trades 5 --execute
 
 # Manage exits for open positions
 uv run python scripts/position_manager.py --execute --check-sentiment
@@ -55,51 +62,103 @@ uv run python scripts/position_manager.py --execute --check-sentiment
 uv run python scripts/dashboard.py
 
 # Run tests
-uv run pytest tests/
+uv run python -m pytest tests/
+
+# Strategy agent (dry run — no API key needed)
+uv run python scripts/strategy_agent.py --mode weekly --dry-run
 ```
 
 ## Daily Pipeline
 
-Automated via `scripts/daily_run.sh` (launchd at 6:45 AM and 12:45 PM PT):
+Automated via GitHub Actions (`.github/workflows/daily-trading.yml`), runs Mon-Fri at 6:45 AM and 12:45 PM PT:
 
-1. **Position manager** — manage exits for all open positions first
-2. **Screener auto-trade** — find biggest dips market-wide, trade top 5
-3. **Watchlist scan** — 3-layer analysis on core watchlist, execute trades
-4. **Momentum screener** — log surging stocks (research, no auto-trade)
+1. **Position manager** — manage exits for all open positions
+2. **Screener auto-trade** — find biggest dips market-wide, trade top picks
+3. **Watchlist scan** — 3-layer composite analysis on core watchlist
+4. **Momentum auto-trade** — trend-following entries on surging stocks
 5. **Portfolio + performance** — summary and signal accuracy report
+6. **Strategy agent** — lightweight event check for acute problems
+
+## Strategy Agent
+
+An autonomous agent (`scripts/strategy_agent.py`) that self-improves the trading system using Claude Opus 4.6 via OpenRouter.
+
+**Weekly review** (Saturdays via `.github/workflows/strategy-review.yml`):
+- Reads performance data, changelog, and experiment results
+- Diagnoses problems using structured reasoning (observe, compare, diagnose, validate, act)
+- Validates changes via walk-forward backtesting with holdout Sharpe validation
+- Deploys code changes or creates shadow experiments
+- Max 2 deploys/week, 14-day cooling period per file
+
+**Event check** (after each daily pipeline run):
+- Checks for acute problems (consecutive stop-losses, drawdown spikes, low win rates)
+- Evaluates active shadow experiments
+- Can pause strategies (auto-expires in 3 days) but saves bigger changes for weekly review
+
+**Safety rails** (hardcoded in `scripts/agent_tools.py` — agent cannot modify):
+- Minimum sample sizes enforced (50 trades for parameters, 30 for filters)
+- All tests must pass before any deploy
+- Position size capped at 5% of equity
+- Max-loss stop cannot be disabled
+- Automatic rollback on test failure
 
 ## Architecture
 
 ```
 client.py                          Alpaca client factory
 
 strategies/
-  mean_reversion.py                SMA-based mean reversion
-  sentiment.py                     Claude Haiku sentiment on news from Alpaca News API
-  insider.py                       Finnhub insider trading + earnings
+  mean_reversion.py                SMA-based mean reversion + weekly confirmation
+  sentiment.py                     Claude Haiku sentiment on news (Alpaca News API)
+  insider.py                       Finnhub insider trading + earnings (cached, rate-limited)
   momentum.py                      10d/50d momentum + volume surge
   config.py                        Watchlist + per-stock thresholds
   sizing.py                        Conviction-based position sizing
-  sector.py                        Sector exposure + correlation guard
+  volatility.py                    ATR-based volatility for threshold normalization
+  sector.py                        Sector exposure + correlation guard (126 tickers)
+  signal_scorer.py                 Empirical signal scoring (bucket win rates)
+  constants.py                     Tunable strategy parameters (agent-modifiable)
   enums.py                         Shared enums (Action, InsiderRecommendation)
 
 scripts/
   scan_with_sentiment.py           3-layer composite signal + sizing + sector guard
-  screener.py                      Market-wide screener (11K+ equities)
+  screener.py                      Market-wide screener (11K+ equities, quality filters)
   screener_trade.py                Auto-trade top screener picks
-  position_manager.py              Exit manager (trailing stop, take-profit, time, sentiment)
+  momentum_trade.py                Auto-trade momentum picks
+  position_manager.py              Exit manager (trailing stop, take-profit, breakeven, cooldown)
   portfolio.py                     CLI account dashboard
   dashboard.py                     Flask web dashboard (port 8050)
   performance.py                   Signal accuracy analysis
-  trade_logger.py                  CSV logging (data/signals.csv, data/trades.csv)
+  trade_logger.py                  CSV logging (auto-migrating headers)
   notify.py                        macOS + Telegram notifications
   backtest.py                      Single-ticker backtesting
   full_backtest.py                 Full system backtest (Sharpe, drawdown)
-  daily_run.sh                     Pipeline automation
-  account_status.py                Quick account connection + status check
-  run_strategy.py                  Single-ticker mean-reversion with optional execution
-  momentum_screener.py             Market-wide momentum screener (volume + 10d/50d)
+  pipeline_backtest.py             Pipeline backtest with all features
+  param_sweep.py                   Parameter grid search + sensitivity analysis
+  strategy_agent.py                Autonomous strategy agent (weekly review + event check)
+  agent_tools.py                   Agent tool definitions + safety-hardcoded dispatch
+  shadow_evaluator.py              Shadow experiment evaluation
+  daily_run.sh                     Local pipeline automation
+  account_status.py                Quick account connection check
+  run_strategy.py                  Single-ticker mean-reversion analysis
+  momentum_screener.py             Market-wide momentum screener
+
+data/                              Trading state (signals.csv, trades.csv, metrics.json)
+data/agent/                        Agent state (changelog, experiments, overrides)
+tests/                             654 tests across 30 test files
+```
+
+## Testing
 
-data/                              Local data (gitignored)
-tests/                             Test suite
+```bash
+# Run all tests
+uv run python -m pytest tests/
+
+# Run with verbose output
+uv run python -m pytest tests/ -v
+
+# Run a specific test file
+uv run python -m pytest tests/test_agent_tools.py -v
 ```
+
+CI runs automatically on push to `main` and on pull requests.
