trade-lab

A research-oriented paper trading lab for US equities that combines deterministic market-data features, LLM-based trade analysis, rule-based intent gating, Alpaca paper execution, and post-trade journaling in PostgreSQL.

What this repo does

trade-lab is not just a backtest script and not just an execution bot. It is a trading research framework that:

• ingests and stores OHLCV candle data in PostgreSQL
• builds deterministic feature packets from local market data
• enriches each packet with account context, optional news, and symbol memory
• asks one or more LLMs for a structured trade thesis and plan
• applies deterministic gating and sizing rules before accepting a trade intent
• optionally sends accepted intents to Alpaca paper trading
• syncs orders and fills back into PostgreSQL
• records and evaluates decisions over time for learning and review

High-level architecture

Core flow:

1. Pull account state, positions, and open orders from Alpaca paper
2. Ingest latest candles and backfill stale windows into PostgreSQL
3. Build a feature packet for each symbol from local candle data
4. Add account context, optional news, and historical symbol memory
5. Run structured LLM analysis (single model or ensemble)
6. Convert the result into a trade intent
7. Apply deterministic rules, freshness checks, and sizing constraints
8. Optionally execute accepted intents on Alpaca paper
9. Sync orders/fills and evaluate pending journal entries

Main features

1) Market data ingestion and storage

• Unified candles table for multiple timeframes (1m, 5m, 15m, 1h, etc.)
• Latest-bar ingestion and stale-window backfill
• Local PostgreSQL store used as the source of truth for features and evaluation

2) Deterministic feature packet generation

Feature packets are built from local OHLCV data and currently include:

• latest candle snapshot
• 1d / 5d / 20d returns
• approximate daily volatility
• SMA20 / SMA50 trend summary
• liquidity proxy (average daily volume)
• basic data-quality metadata
• notable recent hourly moves

This keeps the LLM prompt compact, auditable, and reproducible.

3) LLM-assisted trade analysis

The LLM layer produces structured JSON only, including:

• bull / base / bear thesis
• risk flags
• a conditional trade plan
• suggested side (buy, sell, hold, none)
• setup / entry / exit / invalidation
• confidence score

Supported providers in the current code:

• OpenAI
• Anthropic
• Google Gemini

It also supports:

• retries and backoff
• provider/model fallback chains
• partial ensemble execution when one model fails
• ensemble selection policies across model outputs

4) Rule-based intent gating and sizing

LLM output is not executed directly.

Accepted intents pass through deterministic checks such as:

• packet/data existence
• market-data freshness
• minimum candle count sanity
• LLM side / confidence validation
• max open positions
• minimum cash buffer
• open-buy-order dedupe
• symbol exposure cap
• position-aware sell limits

Sizing is derived from a deterministic notional budget with confidence-based scaling and account constraints.

5) Alpaca paper execution

Accepted intents can be submitted to Alpaca paper trading.

Execution behavior includes:

• idempotent client_order_id based on intent_id
• paper order submission
• local order persistence in PostgreSQL
• later synchronization of orders and fills from Alpaca

6) Post-trade journaling and learning

The repo includes a learning/journal loop that records and later evaluates decisions.

Current journal features include:

• decision timestamp and entry price
• side / timeframe / horizon
• MFE / MAE
• end-of-horizon return
• outcome labels such as hit_profit, stopped_out, small_win, small_loss, chop
• per-symbol recent trade memory and 90-day summary statistics

This memory is reinjected into later LLM prompts to provide symbol context.

Tech stack

Language and runtime

• Python 3

Core libraries

• SQLAlchemy
• psycopg2-binary
• requests
• python-dotenv
• PyYAML
• OpenAI SDK
• Anthropic SDK
• Google GenAI SDK
• moomoo-api
• pandas / numpy / scipy / scikit-learn (installed dependencies)

External services / APIs

• PostgreSQL
• Alpaca paper trading API
• Alpaca market data API
• Optional Yahoo Finance RSS headlines
• Optional Moomoo OpenD connection (see test/test_connection.py)

Repository structure

Important files and directories currently identified:

• src/paper_loop.py — main orchestration loop
• src/features_packet.py — deterministic feature packet builder
• src/llm_analyze.py — provider wrappers, retries, ensemble logic, output normalization
• src/paper_intents.py — deterministic rules gate, sizing, and intent persistence
• src/learning.py — decision journaling, evaluation, and symbol memory
• src/risk.py — basic standalone intent checks
• src/alpaca_paper_exec.py — execution adapter for Alpaca paper
• src/config.py — YAML config loader and typed config models
• src/db.py — database connection and query helpers
• postgres/init.sql — base schema
• postgres/migration.sql — migration into the unified candles/trading schema
• postgres/migration_learning.sql — journal/learning schema additions
• test/test_connection.py — Moomoo/OpenD connectivity smoke test
• trade_lab.dump — database dump artifact included in repo

Database schema

Core tables

• candles

  • symbol, timeframe, ts, OHLCV, source

• trade_intents

  • normalized model outputs and rule-engine acceptance/rejection

• orders

  • broker orders persisted locally

• fills

  • fill/activity records linked to orders

Learning table

• trade_journal
  • decision records, evaluation timestamps, end price, return, MAE, MFE, and outcome labels

Configuration

1) Environment variables

This repo expects a .env file at the repo root.

At minimum, the current codebase may need values for:

• DATABASE_URL
• ALPACA_API_KEY / ALPACA_API_SECRET
• or Alpaca equivalents used by specific modules
• ALPACA_BASE_URL (optional; defaults to paper API)
• ALPACA_DATA_BASE (optional)
• ALPACA_DATA_FEED (optional)
• OPENAI_API_KEY (if using OpenAI)
• ANTHROPIC_API_KEY (if using Anthropic)
• GEMINI_API_KEY / Google GenAI key (if using Gemini)
• LLM_MODELS / provider-specific model settings
• GOOGLE_GENAI_FALLBACK_MODELS (optional)
• LLM_ALLOW_PARTIAL (optional)
• TRADING_UNLOCK_FILE (optional)

2) YAML config

The app also reads a config.yaml file (or CONFIG_PATH) with settings for:

• symbol universe
• bar interval
• horizon
• trading mode
• risk controls
• moomoo host/port
• loop timing

Expected config areas from the current code:

• symbols
• bar_interval
• horizon_min
• trading
• risk
• moomoo
• loop

Setup

1) Create and activate a Python environment

Example:

python -m venv .venv
source .venv/bin/activate

2) Install dependencies

If requirements.txt is present, install from it:

pip install -r requirements.txt

3) Prepare PostgreSQL

Create a PostgreSQL database and set DATABASE_URL in .env.

Then apply schema scripts as needed:

psql "$DATABASE_URL" -f postgres/init.sql
psql "$DATABASE_URL" -f postgres/migration.sql
psql "$DATABASE_URL" -f postgres/migration_learning.sql

If you want to inspect or restore the included dump, use PostgreSQL tooling such as pg_restore depending on the dump format.

4) Configure .env

Add the API credentials and runtime settings needed for your chosen providers and broker/data paths.

5) Configure config.yaml

Set your symbol universe, horizon, bar interval, trading mode, and risk constraints.

Running the paper loop

Example single-cycle run:

python -m src.paper_loop --run-once

Useful flags currently visible in the code:

• --cycle-min
• --stale-min
• --backfill-days
• --features-days
• --sync-hours
• --news
• --news-items
• --alpaca-feed
• --execute
• --stop-when-closed
• --allow-when-closed
• --run-once

Typical safe workflow:

1. Start with --run-once
2. Verify database writes and generated intents
3. Review trade_intents, orders, fills, and trade_journal
4. Only then consider repeated loop execution in paper mode

Safety notes

• This repo is designed around paper trading first.
• Model outputs are advisory and pass through deterministic gates before execution.
• The repo includes explicit live-trading safety latch conventions in environment comments.
• Do not enable live trading without reviewing every execution and risk path.

Current strengths

• Clear separation between features, LLM analysis, intents, execution, and learning
• PostgreSQL-backed auditability
• Deterministic pre/post-processing around LLM usage
• Journal and memory loop for trade review
• Ensemble and fallback support for model availability

Current limitations

Based on current code review, important limitations remain:

• feature packets are still fairly generic and not yet strongly setup-specific
• LLMs still occupy a high-level directional decision role
• risk logic is practical but not yet portfolio-grade
• learning currently functions more like evaluation + memory injection than a full adaptive optimizer
• repo appears better suited as a trading research lab than a production trading engine

Development status

This repository currently looks best understood as:

• a serious paper-trading research framework
• an experimentation platform for LLM-assisted trade analysis
• a foundation that can be refactored into a stronger strategy engine, risk engine, and skill-oriented architecture

Disclaimer

This project is for research and experimentation. It is not financial advice, and it should not be treated as a production-ready live trading system without substantial additional validation, controls, and review.