TradeCouncil Options

A credit-aware, explainable multi-agent options trading project for the Alpaca AI Trading Agents Hackathon (Aug 28–Sep 4, 2026).

Core idea: do not pay an LLM to scan every tick. Python screens a small liquid universe first. Only the strongest candidates reach a Featherless Bull Analyst, Bear Analyst, and CIO Judge. The AI can choose direction, but it cannot invent contracts or bypass deterministic risk limits. A deterministic selector chooses a liquid call/put contract, and a risk sentinel decides whether an Alpaca paper order is allowed.

Judge quick path

1. Read the one-page submission brief for the problem, customer value, architecture, and evidence boundary. The submission form copy keeps every public field and still-unverified placeholder in one operator checklist.
2. Review the pitch deck and live demo script. The rendered 82-second final cut has passed local preview, full-decode, audio, and sampled-frame checks; its public MP4 link is pending upload.
3. Run the credential-free walkthrough with docker compose up --build, open http://127.0.0.1:8000, click Run deterministic cycle, select a candidate, and click Preview bounded decision. No key or broker account is required, and this profile cannot submit an order.

The public demo URL will be added here after the hardened image passes its container smoke test and is deployed. The competition paper-account ID is also intentionally absent until the dedicated $100,000 account is verified; no API key or secret belongs in this repository.

Supporting scenes: Bull/Bear/CIO debate · deterministic risk gate · non-mutating execution receipt · synthetic portfolio and journal

Customer and value

TradeCouncil is for options traders and small quantitative teams that want to prototype AI-assisted decisions in paper trading without giving an LLM direct control of contract selection, position size, or execution. Local code screens the full watchlist, so only the top one or two candidates consume Featherless inference; the default budget permits at most six calls per cycle. Every proposal carries the opposing case, the CIO rationale, the chosen contract, and a deterministic risk result in one audit trail.

The practical path is paper-first: a hosted research and decision-journal product with predictable inference limits, explainable reviews, and explicit operator-controlled execution. Potential paid tiers could add team policy templates, longer audit retention, and broker reconciliation. This project makes no return or passive-income claim; options remain risky, and the current workflow is deliberately restricted to paper trading.

What is included

• FastAPI backend + zero-build web dashboard (no Node/npm required)
• Local technical screening: SMA, RSI, momentum, volatility, regime score
• Featherless AI integration using the OpenAI-compatible /v1/chat/completions API
• Parallel Bull/Bear adversarial agents + CIO judge
• Credit guards for a $25 coupon: top-N candidate screening and short completion caps
• Alpaca stock bars, news and option-chain integration
• Free indicative option feed by default
• Long-call / long-put contract selection using DTE, delta, bid/ask spread and open interest
• Deterministic confidence, drawdown, max-loss, concurrency and liquidity gates
• Official Alpaca CLI for paper order submission (local paper profile)
• Stable decision-derived client order IDs and duplicate-submit short-circuiting
• Audit journal
• Credential-free deterministic demo mode
• Tests and PowerPoint-friendly demo scenes

Runtime authority profiles

TradeCouncil has two deliberately separate entrypoints:

Profile	Entrypoint	Data / AI	Order authority
Public hosted demo	app.hosted:app / Dockerfile	Date-relative synthetic fixtures and deterministic decision rules	None; submission is short-circuited before broker access
Local competition paper workflow	app.main:app	Optional Featherless and Alpaca paper APIs	Disabled by default; Alpaca CLI paper orders require an explicit local flag

Never attach Alpaca or Featherless secrets to the hosted service. The hosted entrypoint ignores all ambient application-policy values, forces demo mode, and the public image does not install the httpx or openai client packages. Full deployment, verification, and rollback instructions are in docs/HOSTED_DEMO_DEPLOYMENT.md.

Run the public-safe container locally

docker compose up --build

Open http://127.0.0.1:8000, then run the smoke test in another terminal:

python scripts/smoke_hosted_demo.py

The health response must report deployment_profile=hosted-demo, external_service_calls_enabled=false, and execution_enabled=false.

1) Run the local project with zero keys

Python 3.10+ is required.

# Run from the cloned repository root.
python -m venv .venv

Windows PowerShell:

.venv\Scripts\Activate.ps1
pip install -r backend\requirements.txt
Copy-Item .env.example .env
python -m uvicorn app.main:app --app-dir backend --reload --port 8000

macOS/Linux:

source .venv/bin/activate
pip install -r backend/requirements.txt
cp .env.example .env
python -m uvicorn app.main:app --app-dir backend --reload --port 8000

Open http://127.0.0.1:8000.

The default .env is safe:

DEMO_MODE=true
ALLOW_ORDER_EXECUTION=false

2) Turn on Featherless AI

Add your coupon/API key:

FEATHERLESS_API_KEY=YOUR_KEY
FEATHERLESS_ANALYST_MODEL=Qwen/Qwen2.5-7B-Instruct
FEATHERLESS_CIO_MODEL=Qwen/Qwen2.5-7B-Instruct

Restart the backend. The UI badge changes from deterministic-demo to featherless.

For your $25 credit balance, leave these guards in place until the demo is stable:

AI_MAX_CANDIDATES_PER_CYCLE=2
AI_MAX_CALLS_PER_CYCLE=6
FEATHERLESS_MAX_ANALYST_TOKENS=180
FEATHERLESS_MAX_CIO_TOKENS=180

A full candidate normally consumes 3 calls: Bull + Bear + CIO. The dashboard records actual token counts returned by Featherless. It intentionally does not guess USD spend because cost depends on the chosen model and input/output token pricing.

3) Connect the Alpaca competition paper account

Use a fresh competition paper account with $100,000 starting balance, per the hackathon requirements. Put its keys in .env:

DEMO_MODE=false
ALPACA_API_KEY=YOUR_PAPER_KEY
ALPACA_SECRET_KEY=YOUR_PAPER_SECRET
ALLOW_ORDER_EXECUTION=false

Keep execution disabled while testing. The app will use Alpaca data but only preview approved orders.

The Basic data plan supports the free indicative options feed, so the starter uses:

ALPACA_OPTIONS_FEED=indicative

4) Install the official Alpaca CLI

The hackathon requires Alpaca Trading API plus Alpaca MCP or CLI. This project uses the CLI for execution.

Official installation with Go:

go install github.com/alpacahq/cli/cmd/alpaca@latest
alpaca version
alpaca doctor

Paper API keys can be supplied through the same .env values. Paper is the CLI default.

When you are ready to submit paper orders:

ALLOW_ORDER_EXECUTION=true

The execution path is:

Risk approved
  -> Python builds bounded option order
  -> `alpaca api POST /v2/orders --quiet`
  -> Alpaca paper account

Architecture

Alpaca stock/news data
        |
        v
Local quantitative screen  -- no Featherless credits
        |
   top 1-2 symbols
        |
   +----+----+
   |         |
   v         v
Bull AI    Bear AI          <- Featherless, parallel
   \         /
    \       /
     v     v
     CIO Judge              <- Featherless
        |
  CALL / PUT / NO_TRADE
        |
        v
Deterministic option selector
DTE + delta + spread + OI
        |
        v
Deterministic Risk Sentinel
confidence + max loss + drawdown + position cap
        |
    APPROVE/VETO
        |
        v
Official Alpaca CLI
        |
        v
Alpaca paper option order

Important files to modify

• backend/app/agents/quant.py — change the local signal
• backend/app/agents/debate.py — Bull/Bear prompts
• backend/app/agents/cio.py — CIO prompt and decision policy
• backend/app/agents/options_selector.py — DTE/delta/liquidity scoring
• backend/app/agents/risk.py — hard safety rules
• backend/app/brokers/alpaca.py — Alpaca integration and CLI execution
• frontend/app.js / frontend/styles.css — dashboard
• .env — all thresholds/models without code edits

API

• GET /health
• GET /api/account
• GET /api/positions
• GET /api/usage
• GET /api/journal
• POST /api/run-cycle { "symbols": ["SPY","QQQ","NVDA"] }
• POST /api/analyze { "symbol": "NVDA" }
• POST /api/execute { "symbol": "NVDA" }

In the hosted profile, /api/execute is a non-mutating preview boundary and always returns submitted=false with reason HOSTED_DEMO_ONLY. It never calls a broker. The local paper profile retains the documented Alpaca CLI path for the event requirement.

Local-profile Swagger: http://127.0.0.1:8000/docs. API documentation is disabled in the public hosted profile.

Safety

This is paper-trading hackathon software, not investment advice. Options can expire worthless and can involve substantial risk. Do not point the project at a live account. The included code deliberately removes ALPACA_LIVE_TRADE before invoking the Alpaca CLI.

Public deployment is supported only through the hosted-demo entrypoint. Do not deploy app.main:app, mount a .env, attach a secret, or override the container command on a public service.