AI Trader

A local research tool that suggests options-oriented direction (put/call) and confidence for a watchlist, using historic price data. You run it; you execute any trades in your own brokerage.

Goal (for contributors and agents): Improve the quality of those suggestions over time. The system is designed to (1) monitor every prediction vs outcome and store accuracy historically, (2) use that history as a feature for the model so it can self-improve, and (3) later scan the options chain and surface the most promising ideas—and eventually rank by opportunity size so suggestions stay relevant to your portfolio. All of this is local and non-custodial; no order execution.

The app has two tabs: Predictions (sort by Ticker/Days left/Timeframe/Confidence, filters by Result/Source/Direction, manual add below cards, ticker autocomplete, prediction cards with Entry, Initial/Updated, Advanced/Archive/Remove, Refresh, View Archived, Analytics) and Best Trade (watchlist, Get Best → 3 per timeframe, Track, performance dashboard). Strike price is in place (entry, predicted strike, strike-aware resolution). Phase D and D+ done: accuracy as model input, point-in-time, resolved rows as training data. Next focus: hybrid model (Option A), Best Trade full log. See docs/PLAN.md and docs/TABS-BEST-TRADE-PLAN.md.

• Scope, roadmap, doc guide: docs/PLAN.md — §6 lists which doc to use when
• Docs index (one-line per doc): docs/README.md
• Architecture (big picture): docs/ARCHITECTURE.md — layers, request flow, directory map
• Agent onboarding: docs/AGENTS.md — first stop for AI agents
• Glossary: docs/GLOSSARY.md — put, call, strike, confidence, etc.
• Tabs + Best Trade: docs/TABS-BEST-TRADE-PLAN.md — Predictions | Best Trade, watchlist, top 3
• UI: docs/HANDOFF-UI.md — layout, cards/table, key files
• Codebase maintenance: docs/CODEBASE-MAINTENANCE.md — centralized patterns (API, horizons, error handling, toast)
• Style guide: docs/STYLE-GUIDE.md — design tokens (typography, color, spacing), CSS conventions
• ML / prediction: docs/HANDOFF-ML.md — model, features, tuning
• Strike price: docs/HANDOFF-STRIKE.md — strike decisions, display, backfill, model (confidence = P(hit strike))
• Self-improving: docs/HANDOFF-SELF-IMPROVING.md — archive/log, resolve, accuracy-as-feature. Next: Phase D (accuracy as model input) and Phase D+ (point-in-time, learn from each outcome).

For agents: See docs/ARCHITECTURE.md for the big picture, then docs/AGENTS.md for onboarding. Before changing UI, model, or self-improving behavior, open the matching handoff and docs/PLAN.md for scope and remaining work. For centralized patterns and styling, see CODEBASE-MAINTENANCE.md and STYLE-GUIDE.md.

---

How to run

1. Install dependencies (use your system Python; a venv is recommended so work projects stay untouched):

   python3 -m venv .venv
   source .venv/bin/activate   # Windows: .venv\Scripts\activate
   pip install -r requirements.txt

   If pip uses a private index (e.g. Artifactory) and fails to find fastapi or returns 401, install from public PyPI for this project only:

   pip install --index-url https://pypi.org/simple/ -r requirements.txt

2. Start the app

   • React front-end + API (one command):

     source .venv/bin/activate   # or: .venv\Scripts\activate on Windows
     pip install -r requirements.txt   # if not already done
     npm install
     npm install --prefix frontend
     npm run dev

     Important: Run npm run dev from a terminal where your Python venv is activated. The API starts first; the frontend waits for it (up to 60s) then opens. You should see [api] output (e.g. "Starting AI Trader API...") then [wait] then [frontend]. If you see "Connection refused" or the frontend never starts, the API didn't come up — run npm run dev:api in a separate terminal (with venv activated) to see the Python error.

     Opens the API at http://127.0.0.1:8000 and the React app at http://localhost:5173. Open the React URL in your browser. See docs/REACT-MIGRATION-PLAN.md.

   • Streamlit UI (legacy / debugging):

     streamlit run app.py

     Open the URL shown (e.g. http://localhost:8501). For page layout and flows see docs/HANDOFF-UI.md.

---

Project layout

Path	Purpose
app.py	Streamlit UI — run with streamlit run app.py (legacy/debugging)
api/main.py	REST API — FastAPI; run with uvicorn api.main:app --reload --port 8000 or npm run dev:api
frontend/	React app — Vite + TypeScript; run with npm run dev --prefix frontend or npm run dev from root
ai_trader/	Main package (data, model, db, app logic, UI helpers)
ai_trader/data/	Fetch (yfinance) and store (SQLite cache)
ai_trader/model/	Per-symbol prediction (features, labels, train, predict). See docs/HANDOFF-ML.md.
ai_trader/db.py	Local SQLite (price_cache, tracked_predictions, prediction_snapshots); add/list/delete predictions, snapshots; strike in snapshots; start_close/end_close at resolution
ai_trader/app_logic.py	Business logic: refresh_watchlist_cache, create_prediction, resolve, backfill, Best Trade preview/track
ai_trader/ui/	Display helpers: formatting (date range, bubble CSS), build_prediction_display_rows for table
ai_trader/symbols.py	Ticker autocomplete (suggestions after 1 character in Create Prediction)
scripts/	backup_and_clear_db.py, test_self_improving_backend.py, run_api.py. See scripts/README.md.
docs/	PLAN.md (§6 doc guide), ARCHITECTURE.md (big picture), AGENTS.md, GLOSSARY.md, HANDOFF-*.md, TABS-BEST-TRADE-PLAN.md, CODEBASE-MAINTENANCE.md, STYLE-GUIDE.md, REACT-MIGRATION-PLAN.md, PHASE-C-PLAN.md (reference)
tests/	Unit tests (data, DB, model). See tests/README.md.

Local DB: ai_trader_local.db is created next to the project when you first fetch data. It’s gitignored so you can keep it locally without committing.

---

Tests

pip install -r requirements.txt
pytest tests/ -v

Tests use a temporary DB (they don’t touch your real ai_trader_local.db). Model tests use a temp model cache. The fetch test may skip if the network or Yahoo is unavailable.