horizon-code 0.1.2 → 0.3.0

package/src/strategy/prompts.ts

@@ -22,6 +22,52 @@ is_stale() returns True if no data in N seconds OR feed never connected.
 - Submitting identical orders rapidly — dedup risk check rejects them
 `;
 
+const RISK_CAPITAL_GUIDE = `
+## Risk & Capital Requirements (MANDATORY)
+
+Every strategy you generate MUST include:
+
+### 1. Explicit Risk Configuration
+NEVER use default values. Every hz.Risk() must specify ALL fields with values appropriate to the user's context:
+\`\`\`python
+risk=hz.Risk(
+    max_position=50,       # max contracts per market
+    max_notional=500,      # max $ total exposure across all markets
+    max_drawdown_pct=5,    # kill switch activates at this % loss
+    max_order_size=10,     # max contracts per single order
+)
+\`\`\`
+
+### 2. Capital Context in hz.run()
+Always include initial_capital context in params so the user knows the assumed capital:
+\`\`\`python
+params={
+    "initial_capital": 1000,   # assumed starting capital
+    "spread": 0.06,
+    "size": 10,
+}
+\`\`\`
+
+### 3. Money Explanation (after code)
+After EVERY code fence, add a brief **Capital & Risk** section explaining in plain English:
+- **Capital**: How much money the strategy assumes (e.g., "$1,000 paper mode")
+- **Max exposure**: Maximum $ at risk at any time (max_notional)
+- **Max loss**: Worst case before kill switch (max_drawdown_pct of max_notional)
+- **Position sizing**: How big each trade is (max_order_size contracts, ~$X at current prices)
+- **Risk level**: Conservative / Moderate / Aggressive — based on notional-to-capital ratio
+
+Example:
+> **Capital & Risk**: This strategy assumes $1,000 in paper mode. Max exposure is $500 across all markets. The kill switch triggers at 5% drawdown ($25 loss). Each order is at most 10 contracts (~$5-7 at typical prices). Risk level: **Conservative** (50% max exposure).
+
+### 4. Risk Scaling Rules
+- Conservative: max_notional ≤ 30% of capital, max_drawdown_pct ≤ 3%
+- Moderate: max_notional ≤ 60% of capital, max_drawdown_pct ≤ 5%
+- Aggressive: max_notional ≤ 90% of capital, max_drawdown_pct ≤ 10%
+
+If the user doesn't specify risk tolerance, default to **Conservative**.
+If the user doesn't specify capital, default to **$1,000 paper mode**.
+`;
+
 const SDK_PIPELINE_SOURCE = `
 import horizon as hz
 
@@ -44,7 +90,12 @@ hz.run(
     markets=["market-slug"],
     feeds={"mid": hz.PolymarketBook("market-slug")},
     pipeline=[fair_value, quoter],
-    risk=hz.Risk(max_position=100, max_notional=1000, max_drawdown_pct=5),
+    risk=hz.Risk(
+        max_position=100,       # max 100 contracts per market
+        max_notional=1000,      # max $1,000 total exposure
+        max_drawdown_pct=5,     # kill switch at 5% loss ($50)
+        max_order_size=50,      # max 50 contracts per order
+    ),
     mode="paper",
     params={"spread": 0.06, "size": 5}
 )
@@ -311,6 +362,82 @@ from horizon._horizon import calibration_curve, log_loss, edge_decay
 # edge_decay(edge_series, timestamps) -> half_life_seconds
 `;
 
+const ADVANCED_SDK_REFERENCE = `
+# ── Advanced SDK Capabilities ──
+
+## Volatility Suite
+Six Rust-native estimators for adaptive spread sizing:
+hz.volatility(lookback=20, method="yang_zhang")  # Pipeline function
+# Methods: "close_to_close", "parkinson", "garman_klass", "yang_zhang", "ewma", "rolling"
+# Injects VolatilitySnapshot into ctx with .best property (best estimator auto-selected)
+# Use: widen spreads in high-vol regimes, tighten in low-vol
+
+## Example — volatility-adaptive market maker:
+def adaptive_quoter(ctx, fair):
+    if fair is None:
+        return []
+    vol = getattr(ctx, 'volatility', None)
+    base_spread = ctx.params.get("spread", 0.06)
+    if vol and vol.best > 0:
+        spread = base_spread * (1 + vol.best * 2)  # widen on high vol
+    else:
+        spread = base_spread
+    return hz.quotes(fair, spread=spread, size=ctx.params.get("size", 5))
+
+## Execution Algorithms
+For large orders that need careful execution:
+from horizon import TWAP, VWAP, Iceberg
+
+TWAP(engine, side, size, duration_secs=300, num_slices=10)   # Equal time slices
+VWAP(engine, side, size, duration_secs=300, volume_profile=[0.1, 0.15, ...])  # Volume-weighted
+Iceberg(engine, side, total_size, show_size=5)               # Hidden size
+
+# All have: .start(), .on_tick(), .is_complete, .total_filled
+# Use TWAP for uniform execution, VWAP for volume-aware, Iceberg for hiding size
+
+## Market Discovery
+Find real markets programmatically instead of hardcoding slugs:
+hz.discover_markets(exchange="polymarket", query="bitcoin", min_volume=10000, sort_by="volume")
+hz.top_markets(exchange="polymarket", limit=20)  # Highest-volume active markets
+hz.discover_events(exchange="polymarket")         # Multi-outcome events
+
+## Portfolio Management
+For multi-strategy coordination and risk budgeting:
+port = hz.Portfolio(name="my_fund", capital=10000)
+port.add_position(market_id, side, size, entry_price)
+port.update_price(market_id, current_price)
+# Optimization: port.optimize("kelly") | "equal_weight" | "risk_parity" | "min_variance"
+# Risk: port.var_95(), port.cvar_95(), port.correlation_matrix()
+# Rebalance: port.needs_rebalance(threshold=0.05), port.rebalance_orders()
+
+## Kelly Criterion (built-in)
+hz.edge(fair_prob=0.55, market_price=0.50)          # Expected value
+hz.kelly(prob=0.55, price=0.50)                     # Full Kelly fraction
+hz.fractional_kelly(prob=0.55, price=0.50, fraction=0.25)  # Conservative (recommended)
+hz.kelly_size(prob=0.55, price=0.50, bankroll=1000, max_size=50)  # Contract units
+hz.kelly_sizer(fraction=0.25, bankroll=1000)        # Pipeline factory
+hz.kelly_sizer_with_liquidity(fraction=0.25, bankroll=1000)  # Dampens for illiquid markets
+
+## Sentinel — Continuous Risk Monitor
+hz.sentinel(portfolio, config={
+    "drawdown_levels": [-5, -10, -20, -30],  # alert, reduce, pause, exit
+    "regime_lookback": 50,
+    "var_confidence": 0.95,
+})
+# Auto-reduces position size in high-drawdown regimes
+# Detects: drawdown escalation, regime change, correlation spikes
+# Actions: alert, reduce_positions, pause_trading, emergency_exit
+hz.suggest_hedges(portfolio, budget=500)  # Hedge recommendations
+
+## Promotion Gates (paper → live)
+Before deploying live, strategies should pass:
+- Sharpe ratio >= 1.0
+- At least 30 trades
+- Walk-forward p-value < 0.05
+- Probability of Backtest Overfitting (PBO) < 50%
+- Max drawdown < 10% of capital
+`;
+
 const EXAMPLE_MOMENTUM = `
 import horizon as hz
 from collections import deque
@@ -354,9 +481,14 @@ hz.run(
     markets=["market-slug"],
     feeds={"mid": hz.PolymarketBook("market-slug")},
     pipeline=[track_prices, quoter],
-    risk=hz.Risk(max_position=100, max_notional=1000, max_drawdown_pct=5),
+    risk=hz.Risk(
+        max_position=100,       # max 100 contracts per market
+        max_notional=1000,      # max $1,000 total exposure
+        max_drawdown_pct=5,     # kill switch at 5% loss ($50)
+        max_order_size=25,      # max 25 contracts per order
+    ),
     mode="paper",
-    params={"lookback": 15, "threshold": 0.03, "spread": 0.04, "size": 25}
+    params={"initial_capital": 1000, "lookback": 15, "threshold": 0.03, "spread": 0.04, "size": 25}
 )
 `;
 
@@ -392,9 +524,14 @@ hz.run(
     markets=["market-slug"],
     feeds={"mid": hz.PolymarketBook("market-slug")},
     pipeline=[compute_inventory_skew, generate_quotes],
-    risk=hz.Risk(max_position=100, max_notional=1000, max_drawdown_pct=5),
+    risk=hz.Risk(
+        max_position=100,       # max 100 contracts per market
+        max_notional=1000,      # max $1,000 total exposure
+        max_drawdown_pct=5,     # kill switch at 5% loss ($50)
+        max_order_size=25,      # max 25 contracts per order
+    ),
     mode="paper",
-    params={"spread": 0.06, "size": 10, "max_position": 100}
+    params={"initial_capital": 1000, "spread": 0.06, "size": 10, "max_position": 100}
 )
 `;
 
@@ -455,6 +592,279 @@ print(hz.dashboard(bundle))
 print("---END_ASCII_DASHBOARD---")
 `;
 
+const STRATEGY_TEMPLATES = `
+# ── Strategy Templates ──
+# Reference these when the user asks for a specific strategy type.
+# Adapt parameters to the user's market, capital, and risk tolerance.
+
+## Template 1: Conservative Market Maker
+# Style: Wide spreads, small size, low risk. Good for beginners.
+# Capital: $500-2000 | Risk: Conservative | Expected Sharpe: 0.5-1.5
+# Best for: High-volume markets with tight spreads
+
+import horizon as hz
+
+def fair_value(ctx):
+    feed = ctx.feeds.get("mid")
+    if not feed or feed.is_stale(30):
+        return None
+    return feed.price
+
+def conservative_quoter(ctx, fair):
+    if fair is None:
+        return []
+    inv = ctx.inventory.net
+    max_pos = ctx.params.get("max_position", 50)
+    skew = inv / max_pos if max_pos > 0 else 0
+    spread = ctx.params.get("spread", 0.10) * (1 + abs(skew) * 0.5)
+    size = ctx.params.get("size", 5)
+    if abs(inv) > max_pos * 0.8:
+        size = max(1, size // 2)
+    return hz.quotes(fair, spread=spread, size=size)
+
+hz.run(
+    name="ConservativeMarketMaker",
+    exchange=hz.Polymarket(),
+    markets=["your-market-slug"],
+    feeds={"mid": hz.PolymarketBook("your-market-slug")},
+    pipeline=[fair_value, conservative_quoter],
+    risk=hz.Risk(
+        max_position=50,
+        max_notional=500,
+        max_drawdown_pct=3,
+        max_order_size=5,
+    ),
+    mode="paper",
+    params={"initial_capital": 1000, "spread": 0.10, "size": 5, "max_position": 50}
+)
+# Capital & Risk: $1,000 paper. Max $500 exposure. Kill switch at 3% ($15). Conservative.
+
+## Template 2: Momentum Follower with Kelly Sizing
+# Style: Directional, follows price trends. Uses Kelly for position sizing.
+# Capital: $1000-5000 | Risk: Moderate | Expected Sharpe: 1.0-2.0
+# Best for: Trending markets (elections, crypto events)
+
+import horizon as hz
+from collections import deque
+
+_prices: dict[str, deque] = {}
+
+def momentum_signal(ctx):
+    feed = ctx.feeds.get("mid")
+    if not feed or feed.is_stale(30):
+        return None
+    slug = ctx.market.slug
+    lookback = int(ctx.params.get("lookback", 20))
+    if slug not in _prices:
+        _prices[slug] = deque(maxlen=lookback)
+    _prices[slug].append(feed.price)
+    if len(_prices[slug]) < lookback:
+        return None
+    oldest = _prices[slug][0]
+    if oldest == 0:
+        return None
+    momentum = (feed.price - oldest) / oldest
+    return {"mid": feed.price, "momentum": momentum}
+
+def kelly_quoter(ctx, signal):
+    if signal is None:
+        return []
+    momentum = signal["momentum"]
+    threshold = ctx.params.get("threshold", 0.02)
+    if abs(momentum) < threshold:
+        return []
+    fair = signal["mid"]
+    prob = 0.5 + min(0.2, abs(momentum) * 2)
+    fraction = ctx.params.get("kelly_fraction", 0.25)
+    kelly_f = max(0, (prob - (1 - prob)) * fraction)
+    size = max(1, int(kelly_f * ctx.params.get("bankroll", 1000) / fair))
+    size = min(size, ctx.params.get("max_size", 20))
+    spread = ctx.params.get("spread", 0.04)
+    return hz.quotes(fair, spread=spread, size=size)
+
+hz.run(
+    name="MomentumFollower",
+    exchange=hz.Polymarket(),
+    markets=["your-market-slug"],
+    feeds={"mid": hz.PolymarketBook("your-market-slug")},
+    pipeline=[momentum_signal, kelly_quoter],
+    risk=hz.Risk(
+        max_position=100,
+        max_notional=1000,
+        max_drawdown_pct=5,
+        max_order_size=20,
+    ),
+    mode="paper",
+    params={"initial_capital": 2000, "lookback": 20, "threshold": 0.02, "spread": 0.04, "kelly_fraction": 0.25, "bankroll": 2000, "max_size": 20}
+)
+# Capital & Risk: $2,000 paper. Max $1,000 exposure. Kill switch at 5% ($50). Moderate.
+
+## Template 3: Mean Reversion
+# Style: Fades extreme prices toward fair value using z-score.
+# Capital: $500-2000 | Risk: Conservative-Moderate | Expected Sharpe: 0.8-1.5
+# Best for: Range-bound markets, markets with known fair value
+
+import horizon as hz
+from collections import deque
+import math
+
+_history: dict[str, deque] = {}
+
+def mean_reversion_signal(ctx):
+    feed = ctx.feeds.get("mid")
+    if not feed or feed.is_stale(30):
+        return None
+    slug = ctx.market.slug
+    window = int(ctx.params.get("window", 30))
+    if slug not in _history:
+        _history[slug] = deque(maxlen=window)
+    _history[slug].append(feed.price)
+    if len(_history[slug]) < window:
+        return None
+    prices = list(_history[slug])
+    mean = sum(prices) / len(prices)
+    std = math.sqrt(sum((p - mean) ** 2 for p in prices) / len(prices))
+    if std < 0.001:
+        return None
+    zscore = (feed.price - mean) / std
+    return {"mid": feed.price, "mean": mean, "zscore": zscore}
+
+def reversion_quoter(ctx, signal):
+    if signal is None:
+        return []
+    z = signal["zscore"]
+    entry_z = ctx.params.get("entry_z", 1.5)
+    if abs(z) < entry_z:
+        return []
+    fair = signal["mean"]
+    spread = ctx.params.get("spread", 0.06)
+    size = ctx.params.get("size", 10)
+    return hz.quotes(fair, spread=spread, size=size)
+
+hz.run(
+    name="MeanReversion",
+    exchange=hz.Polymarket(),
+    markets=["your-market-slug"],
+    feeds={"mid": hz.PolymarketBook("your-market-slug")},
+    pipeline=[mean_reversion_signal, reversion_quoter],
+    risk=hz.Risk(
+        max_position=80,
+        max_notional=800,
+        max_drawdown_pct=5,
+        max_order_size=10,
+    ),
+    mode="paper",
+    params={"initial_capital": 1000, "window": 30, "entry_z": 1.5, "spread": 0.06, "size": 10}
+)
+# Capital & Risk: $1,000 paper. Max $800 exposure. Kill switch at 5% ($40). Moderate.
+
+## Template 4: Cross-Market Arb (Polymarket vs Kalshi)
+# Style: Captures price discrepancies between exchanges.
+# Capital: $2000-10000 | Risk: Low (market-neutral) | Expected Sharpe: 1.5-3.0
+# Best for: Markets listed on both Polymarket and Kalshi
+
+import horizon as hz
+
+def arb_detector(ctx):
+    poly = ctx.feeds.get("poly")
+    kalshi = ctx.feeds.get("kalshi")
+    if not poly or poly.is_stale(30) or not kalshi or kalshi.is_stale(30):
+        return None
+    edge = abs(poly.price - kalshi.price)
+    min_edge = ctx.params.get("min_edge", 0.03)
+    if edge < min_edge:
+        return None
+    if poly.price < kalshi.price:
+        return {"buy_exchange": "poly", "fair": poly.price, "edge": edge}
+    else:
+        return {"buy_exchange": "kalshi", "fair": kalshi.price, "edge": edge}
+
+def arb_quoter(ctx, signal):
+    if signal is None:
+        return []
+    size = ctx.params.get("size", 10)
+    spread = ctx.params.get("spread", 0.02)
+    return hz.quotes(signal["fair"], spread=spread, size=size)
+
+hz.run(
+    name="CrossMarketArb",
+    exchanges=[hz.Polymarket(), hz.Kalshi()],
+    markets=["your-market-slug"],
+    feeds={
+        "poly": hz.PolymarketBook("your-market-slug"),
+        "kalshi": hz.KalshiBook("your-kalshi-ticker"),
+    },
+    pipeline=[arb_detector, arb_quoter],
+    risk=hz.Risk(
+        max_position=100,
+        max_notional=2000,
+        max_drawdown_pct=3,
+        max_order_size=10,
+    ),
+    mode="paper",
+    params={"initial_capital": 5000, "min_edge": 0.03, "spread": 0.02, "size": 10}
+)
+# Capital & Risk: $5,000 paper. Max $2,000 exposure. Kill switch at 3% ($60). Low risk (market-neutral).
+
+## Template 5: Multi-Signal Ensemble
+# Style: Combines price, spread, momentum, and flow signals.
+# Capital: $1000-5000 | Risk: Moderate | Expected Sharpe: 1.0-2.5
+# Best for: Liquid markets with diverse data
+
+import horizon as hz
+from collections import deque
+
+_momentum_history: dict[str, deque] = {}
+
+def multi_signal(ctx):
+    feed = ctx.feeds.get("mid")
+    if not feed or feed.is_stale(30):
+        return None
+    slug = ctx.market.slug
+    lookback = int(ctx.params.get("lookback", 15))
+    if slug not in _momentum_history:
+        _momentum_history[slug] = deque(maxlen=lookback)
+    _momentum_history[slug].append(feed.price)
+    price_signal = feed.price
+    spread_signal = (feed.ask - feed.bid) if feed.ask > 0 and feed.bid > 0 else 0.05
+    history = _momentum_history[slug]
+    momentum_signal = (feed.price - history[0]) / history[0] if len(history) >= lookback and history[0] > 0 else 0
+    inventory_signal = -ctx.inventory.net * 0.001
+    weights = ctx.params.get("weights", [0.4, 0.2, 0.2, 0.2])
+    combined = (
+        weights[0] * price_signal +
+        weights[1] * (1 - spread_signal * 10) * price_signal +
+        weights[2] * momentum_signal * price_signal +
+        weights[3] * inventory_signal
+    )
+    fair = max(0.01, min(0.99, combined))
+    return fair
+
+def ensemble_quoter(ctx, fair):
+    if fair is None:
+        return []
+    spread = ctx.params.get("spread", 0.05)
+    size = ctx.params.get("size", 8)
+    return hz.quotes(fair, spread=spread, size=size)
+
+hz.run(
+    name="MultiSignalEnsemble",
+    exchange=hz.Polymarket(),
+    markets=["your-market-slug"],
+    feeds={"mid": hz.PolymarketBook("your-market-slug")},
+    pipeline=[multi_signal, ensemble_quoter],
+    risk=hz.Risk(
+        max_position=80,
+        max_notional=1000,
+        max_drawdown_pct=5,
+        max_order_size=15,
+    ),
+    mode="paper",
+    params={"initial_capital": 2000, "lookback": 15, "spread": 0.05, "size": 8, "weights": [0.4, 0.2, 0.2, 0.2]}
+)
+# Capital & Risk: $2,000 paper. Max $1,000 exposure. Kill switch at 5% ($50). Moderate.
+`;
+
 /**
  * Build the system prompt for strategy mode.
  * Code streams via ```python fences — no tool calls for code generation.
@@ -577,6 +987,8 @@ The code you generate is the EXACT code that runs on Horizon. It must:
 7. \`hz.quotes(fair, spread, size)\` returns \`list[Quote]\`
 8. \`ctx.inventory\` is InventorySnapshot (NOT dict). Use \`.positions\`, \`.net\`, \`.net_for_market(id)\`
 
+${RISK_CAPITAL_GUIDE}
+
 ## SDK Reference
 
 ### Pipeline Structure
@@ -588,13 +1000,21 @@ ${STATIC_MODELS_SOURCE}
 ### Backtesting & Analytics
 ${BACKTEST_REFERENCE}
 
+### Advanced Capabilities
+${ADVANCED_SDK_REFERENCE}
+
 ${STRATEGY_GUIDE}
 
 ### Example: MomentumScalper
 ${EXAMPLE_MOMENTUM}
 
 ### Example: InventoryAwareMarketMaker
-${EXAMPLE_INVENTORY_MM}`;
+${EXAMPLE_INVENTORY_MM}
+
+### Strategy Templates
+When a user asks for a specific strategy type (market maker, momentum, arb, etc.), reference the corresponding template below. Adapt the parameters to their market, capital, and risk tolerance.
+
+${STRATEGY_TEMPLATES}`;
 }
 
 /**