market-swarm-lab — System Architecture

External Sources

📈 Alpha Vantage

TIME_SERIES_DAILY_ADJUSTED
100 trading days
OHLCV + adjusted close

REST API

HTTP GET

🤖 Apify

trudax/reddit-scraper
r/wsb · r/stocks · r/options
Posts + comments

Actor API

HTTP POST

📰 NewsAPI

Everything endpoint
Last 3–5 days
Up to 20 articles

REST API

HTTP GET

🎲 Kalshi

Open prediction markets
YES/NO probabilities
No key required

REST API

HTTP GET

🏛 SEC / EDGAR

10-K · 10-Q · 8-K filings
Risk language NLP
Filing digest

REST API

raw OHLCV

posts + comments

articles[]

markets[]

filings[]

Collection Services

price-collector

alpha_vantage_client.py
price_service.py
RSI-14 · VWAP
Rolling vol 5d/10d
10d momentum
→ state/raw/ohlcv/
→ data/ohlcv/*.parquet

Parquet + JSON

reddit-collector

apify_reddit_fetcher.py
apify_normalizer.py
NLP sentiment scoring
bullish/bearish ratios
engagement_velocity
disagreement_index
→ state/raw/reddit/

JSON artifacts

news-collector

newsapi_client.py
news_service.py
Sentiment scoring
narrative_strength
breaking_news_flag
bullish/bearish themes
→ state/raw/news/

JSON artifacts

kalshi-collector

kalshi.py
polymarket.py
Keyword match
YES probability avg
Direction signal
Volume weighting

Live / fixture

sec-collector

sec.py
EDGAR filings fetch
Risk NLP scoring
sec_risk_score
Filing summaries

Live / fixture

all source data → normalize

Normalization

🔀 UnifiedNormalizerService → normalized_bundle

snapshot{} close_prices[] returns[] volatility rsi_14 momentum vwap feature_window[] reddit_features{} kalshi_contracts[] documents[] simulation_seed{} source_audit{} timesfm_inputs[]

Source Audit

source_audit

ohlcv: live · alphavantage · 100 records reddit: live · apify · 60 posts news: live · newsapi · 20 articles kalshi: live · kalshi · 3 markets sec: fallback · sec_api · 0 records

close_prices[]

normalized_bundle

Intelligence

⚡ TimesFM Forecasting

forecast_from_prices()
Input: 60–100 close prices
─────────────────
direction: bullish/bearish/neutral
predicted_return: float
confidence: float
trend_strength: float
forecast_deviation: float
quantiles: p10 · p50 · p90
─────────────────
Mode: TimesFM 2.5 200M
Fallback: local trend extrap

→ state/raw/ohlcv/timesfm_*

forecast{}

⚖️ Divergence Engine

compute_divergence()
─────────────────
Scores TimesFM/Reddit/Kalshi
each mapped to [-1, +1]
─────────────────
timesfm_vs_reddit: float
timesfm_vs_kalshi: float
reddit_vs_kalshi: float
divergence_score: 0–1
alignment_score: 0–1
signal: reversal_candidate
trend_confirmation
mixed

→ normalized_bundle[divergence]

divergence{}

🌱 Seed Builder

build_seed_pack()
─────────────────
price_summary: str
timesfm_summary: str
news_summary: str
reddit_summary: str
kalshi_summary: str
key_bullish_points: []
key_bearish_points: []
disagreement_level: float
sources_used: []
news_confidence: float
reddit_confidence: float

→ seed_pack{}

seed{} + forecast{} + divergence{} → per-archetype context injection

Agent Simulation

🛍 Retail ×40

Receives:
reddit_context{}
· bullish_ratio
· bearish_ratio
· engagement_velocity
· disagreement_index
news_context{}
· news_summary
· bullish_points[]
· sentiment_score

🏦 Institutional ×30

Receives:
timesfm_context{}
· direction
· confidence
· predicted_return
kalshi_context{}
· avg_yes_prob
· summary
sec: risk_score
filing summaries

📊 Momentum ×20

Receives:
price_context{}
· rsi_14
· rolling_vol_5d/10d
· momentum (10d)
· vwap
· price_trend
timesfm_context{}
· direction
· trend_strength

🔄 Contrarian ×10

Receives:
divergence_context{}
· divergence_score
· alignment_score
· signal
· timesfm_vs_reddit
· timesfm_vs_kalshi
· reddit_vs_kalshi
Prompt includes
reversal thesis

votes

🗳 Simulation Engine

run_simulation()
─────────────
Aggregates 100 votes
buy_sell_ratio
final_direction
outlook_score
sentiment_per_day
price_trajectory
agent_memory_summary
final_confidence

simulation_result{}

strategy_context{}

Decision Layer

🎯 Strategy Engine

generate_signal()
─────────────────
Rule 1: trend_confirmation_bullish
TF bullish + align≥0.65 → CALL
Rule 2: trend_confirmation_bearish
TF bearish + align≥0.65 → PUT
Rule 3: reversal_bullish
crowd bearish + TF bullish → CALL
Rule 4: reversal_bearish
crowd bullish + TF bearish → PUT
Rule 5: volatility_play
diverg>0.6 + vol>0.25 → HOLD
Rule 6: no_trade → HOLD
─────────────────
confidence = weighted avg:
TF×0.35 + align×0.25
+ sim×0.25 + freshness×0.15
─────────────────
option_plan by horizon:
1h: same-day · ATM
1d: 2 DTE · ATM
3d: 4 DTE · ATM±1%
5d: 7 DTE · delta-based

signal{}

🛡 Risk Engine

evaluate()
─────────────────
Gate 1: conf < 0.60 → HOLD
Gate 2: OHLCV fallback → HOLD
Gate 3: disagreement>0.7 → HOLD
Gate 4: HOLD signal → size=0
─────────────────
Position sizing:
conf ≥ 0.80 → 75%
conf ≥ 0.70 → 50%
conf ≥ 0.60 → 25%
─────────────────
Stop loss / take profit:
1h: 25% SL · 50% TP
1d: 30% SL · 60% TP
3d: 35% SL · 80% TP
5d: 40% SL · 100% TP

risk{}

📉 Backtester

run()
─────────────────
Rolling 60-bar window
Phase 1 approx:
3× leverage on ATM
Slippage: 0.02
─────────────────
Metrics:
win_rate
avg_return
max_drawdown
sharpe_ratio
by_strategy{}
─────────────────
Output files:
backtest.json
backtest.md
trades.csv
equity_curve.csv

approved signal → paper order

position record

Execution & Output

📋 Execution Engine

execute()
Mode: paper (default)
─────────────────
Generates order ticket:
BUY_TO_OPEN / NONE
instrument: CALL/PUT
expiry_days · strike
quantity · entry_style
stop_loss · take_profit
─────────────────
→ state/orders/*.json
─────────────────
⚠ Live requires:
EXECUTION_MODE=live
LIVE_TRADING_ENABLED=true

💼 Portfolio Engine

record_trade()
get_portfolio_state()
─────────────────
open_positions[]
closed_positions[]
realized_pnl: float
unrealized_pnl: float
win_rate: float
total_trades: int
─────────────────
→ state/portfolio/
trade_journal.json
daily_summary.md

📊 Unified Reporter

report()
─────────────────
Full structured report
seed_pack summary
agent vote breakdown
simulation trajectory
trade signal
source_audit (all 5)
─────────────────
→ state/reports/
{TICKER}_{DATE}.json
{TICKER}_{DATE}.md

🌐 API Endpoints

GET /run-demo
GET /signal
GET /trade-plan
POST /backtest
─────────────────
GET /debug/price
GET /debug/news
GET /debug/reddit
GET /debug/timesfm
─────────────────
GET /health
POST /v1/tickers/{t}/run

market-swarm-lab — Technical System Architecture