docs: README with architecture, data inputs, decision engine, infrastructure map

2026-08-02 19:13:18 -07:00
parent c14bb98f7f
commit a4def4f72e
1 changed files with 114 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,114 @@
+# K4LSH1_OPS
+
+Multi-coin LLM-driven 15-minute binary options trading bot on Kalshi. Three independent bots trade DOGE, SOL, and ETH simultaneously using a two-tier LLM decision engine.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        K4LSH1_OPS FLEET                         │
+├──────────┬──────────┬───────────────────────────────────────────┤
+│  DOGE 🐶 │  SOL 🔮  │  ETH 💎  ← 3 independent processes        │
+│  .154    │  .71     │  .189    ← proxy-backed Binance intel     │
+│  doge.db │  sol.db  │  eth.db  ← isolated tick/decision DBs     │
+└──────────┴──────────┴───────────────────────────────────────────┘
+        │                              │
+        ▼                              ▼
+┌──────────────┐            ┌──────────────────┐
+│  qwen3.5:4b  │  borderline│  ornith:latest   │
+│  MacBook     │──────────▶ │  GamingPC .186   │
+│  (0.4s gate) │  escalate  │  RTX 3070 (0.86s)│
+└──────────────┘            └──────────────────┘
+        │
+        ▼
+┌──────────────────────────────────────────────┐
+│  Kalshi V2 API (api.elections.kalshi.com)    │
+│  /portfolio/events/orders — bid/ask format   │
+└──────────────────────────────────────────────┘
+```
+
+## Data Inputs Per Decision
+
+Every 5-minute decision cycle feeds the LLM a full market snapshot:
+
+| Source | Data | Frequency |
+|--------|------|-----------|
+| Kraken | Spot price (per coin) | 20s tick |
+| Binance (via proxy) | 24h change, 24h range, 24h volume | 5min cached |
+| Kraken OHLC | 1m/5m/15m/1h/2h multi-timeframe trend | per cycle |
+| SQLite ticks | RSI(14) on 1m and 5m timeframes | per cycle |
+| Kalshi orderbook | YES/NO ask, spread, depth imbalance | per cycle |
+| Fear&Greed Index | Market sentiment (0-100) | 5min cached |
+| Mempool.space | BTC fast fee (sat/vB) | 5min cached |
+| Orders DB | Per-coin 24h win rate, recent performance | per cycle |
+| Volatility calc | Market regime (choppy/trending/normal) | per cycle |
+
+## Decision Engine
+
+### Two-Tier LLM Voting
+
+1. **Fast gate** — `qwen3.5:4b` on MacBook (0.4s). Handles clear signals. If confident (≥0.70) → trade immediately.
+2. **Deep verify** — `ornith:latest` on GamingPC RTX 3070 (0.86s). Called when gate is borderline (<0.70 or unclear). Final verdict.
+
+### Safety Gates (checked before any order)
+
+- **RSI contrarian** — RSI > 85 → auto-fade DOWN, RSI < 15 → auto-fade UP (no LLM needed)
+- **BTC macro correlation** — Won't short alts when BTC 24h > +0.5% unless conf > 0.78
+- **Adaptive confidence** — Win rate adjusts minimum confidence (loses → tighter, wins → relaxed)
+- **Self-adapting overrides** — qwen analyzes last 20 resolved bets every 10 min, tunes thresholds
+- **Daily loss cap** — Hard stop at configurable daily loss limit
+- **Market expiration guard** — Verifies market open before placing order
+
+### Position Sizing
+
+- Max $1.00 per trade (configurable via `max_spend_cents`)
+- Confidence-scaled contracts: <0.70 = x1, 0.70-0.80 = x2, 0.80-0.90 = x3, >0.90 = x4
+- Auto-capped so `contracts × price ≤ max_spend`
+- Taker at ask when ≤ 55¢, maker at 50¢ when book is thin
+
+### Hedge Engine
+
+Scans every cycle for open positions where buying the opposite side locks ≥8¢ profit. Auto-executes counter-orders.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `bot.py` | Main bot — decision engine, Kalshi client, order placement |
+| `dashboard.py` | Flask dashboard — fleet view at `/fleet`, single-coin at `/` |
+| `test_bot.py` | Unit tests — momentum, RSI, hedge, decision logic, LLM parsing |
+| `config.json` | Base config (shared defaults) |
+| `doge.json` / `sol.json` / `eth.json` | Per-coin configs with proxies, LLM URLs, DB paths |
+
+## Quick Start
+
+```bash
+# Launch all 3 bots
+cd ~/kalshi-bot
+.venv/bin/python bot.py --config doge.json --lock doge &
+.venv/bin/python bot.py --config sol.json --lock sol &
+.venv/bin/python bot.py --config eth.json --lock eth &
+
+# Launch dashboard
+.venv/bin/python dashboard.py
+
+# Run tests
+.venv/bin/python test_bot.py
+```
+
+## Dashboard
+
+- **Fleet view**: `http://localhost:5053/fleet` — all 3 coins, color-coded, PNL, decision trace
+- **Single coin**: `http://localhost:5053` — controls, orderbook, momentum chart
+- **API**: `GET /api/fleet` — all coins JSON, `GET /api/state` — single coin state
+
+## Infrastructure
+
+| Component | Host | Purpose |
+|-----------|------|---------|
+| MacBook | localhost:11434 | qwen3.5:4b fast gate |
+| GamingPC | 10.30.20.186:11434 | ornith:latest deep verify (RTX 3070) |
+| proxy1 | 10.30.20.154:3128 | DOGE Binance intel (Brazil exit) |
+| proxy2 | 10.30.20.71:3128 | SOL Binance intel (EU exit) |
+| proxy3 | 10.30.20.189:3128 | ETH Binance intel (Brazil exit) |
+| Gitea | 10.30.20.149:3000 | Code repo |