AlpacaStock

Paper-ready medium-frequency equities trading engine for US large/mid-cap stocks and sector ETFs.

What is included

• Python-first project scaffold with strict typing, test tooling, and CLI entrypoints
• Data adapters for PIT macro ingestion and Alpaca-backed broker/market data
• Four-sleeve signal engine, constraint-aware portfolio constructor, and independent risk veto
• Dedicated Momentum_Breakout_Regime_V1 strategy with fixed liquid universe, regime overlay, and intraday exit monitor
• Execution planner, broker reconciliation, backtest simulator, and daily reporting
• Paper trading daemon with fill-confirmed state transitions, job idempotence, and spread sampling
• Symphony + Linear harness files for unattended ticket orchestration

Quick start

uv sync --extra dev
cp .env.example .env
docker compose up -d
uv run pytest
uv run alpacastock demo-report
uv run alpacastock run-entry-scan
uv run alpacastock run-exit-monitor
uv run alpacastock run-reconcile
uv run alpacastock run-paper-daemon --once

Layout

src/alpacastock/
  adapters/     External data and broker interfaces
  backtest/     PIT simulator and validation helpers
  cli/          Operator entrypoints
  core/         Domain models, feature, signal, portfolio, risk, execution logic
  services/     Runtime services and orchestration
  storage/      SQLAlchemy state models

Symphony

Use the wrapper script so this repo can run against the local Symphony checkout even when symphony is not in PATH:

./bin/symphony-local

Before running it, build the reference implementation once:

cd ../symphony/elixir
mise trust
mise install
mise exec -- mix setup
mise exec -- mix build

Alpaca

Current default runtime assumes Alpaca for both brokerage and market data. Set credentials in .env.example using either ALPACASTOCK_ALPACA_* or Alpaca's standard APCA_API_KEY_ID / APCA_API_SECRET_KEY env vars, then verify with:

uv run alpacastock doctor

Momentum Breakout V1

The first production strategy is defined in config/momentum_breakout_v1.yaml. It trades a fixed liquid universe from config/universe_liquid.json with:

• EOD entry scan during 15:30-15:55 ET
• 5-minute exit monitor during regular trading hours
• SPY SMA200 bull/bear exposure overlay
• broker-truth recovery via persisted strategy position state

Primary operator commands:

uv run alpacastock run-entry-scan
uv run alpacastock run-entry-scan --submit
uv run alpacastock run-exit-monitor
uv run alpacastock run-exit-monitor --submit
uv run alpacastock run-reconcile
uv run alpacastock sync-broker-state
uv run alpacastock run-paper-cycle
uv run alpacastock run-paper-daemon --once
uv run alpacastock run-paper-daemon
uv run alpacastock run-dashboard --host 0.0.0.0 --port 8787
./bin/install-launchd-paper-daemon
./bin/install-launchd-dashboard

Paper runtime behavior:

• run-paper-daemon polls every 30s
• entry scan is idempotent once per session in 15:30-15:55 ET
• exit monitor is idempotent on aligned 5-minute buckets
• reconcile runs every minute while open and every 5 minutes while closed
• strategy state moves from pending_entry/pending_exit to open_position/cooldown only after Alpaca order-status confirmation

Launchd installs a repo-generated plist from ops/launchd/com.alpacastock.paper-daemon.plist.template into ~/Library/LaunchAgents/ and logs under ./logs/launchd.

Phone Dashboard

Read-only dashboard:

• local/LAN: http://<mac-ip>:8787
• Tailscale: http://<tailscale-ip>:8787

The dashboard shows broker snapshot, strategy lifecycle state, recent order intents, trigger rules, and runtime job/spread activity. Start it with:

uv run alpacastock run-dashboard --host 0.0.0.0 --port 8787

or install it as a background service:

./bin/install-launchd-dashboard