alloc-context 0.1.0__py3-none-any.whl

alloccontext/rollup/portfolio.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+from typing import Any
+
+from alloccontext.rollup.band import check_allocation_band
+from alloccontext.rollup.breadth import build_market_breadth_context
+
+
+def _allocation_pct(allocation: dict[str, Any], key: str) -> float:
+    if key in allocation:
+        return float(allocation[key])
+    return 0.0
+
+
+def build_portfolio_context(conn: sqlite3.Connection, config) -> dict[str, Any]:
+    row = conn.execute(
+        """
+        SELECT ts, nav_usd, cash_usd, allocation_json
+        FROM portfolio_snapshots ORDER BY ts DESC LIMIT 1
+        """
+    ).fetchone()
+    if row is None:
+        return {"available": False, "reason": "no_portfolio_snapshot"}
+
+    allocation = json.loads(row["allocation_json"] or "{}")
+    target = dict(config.portfolio.target_allocations)
+    band_result = check_allocation_band(
+        {
+            "BTC": _allocation_pct(allocation, "BTC"),
+            "ETH": _allocation_pct(allocation, "ETH"),
+            "CASH": _allocation_pct(allocation, "CASH"),
+        },
+        target,
+        float(config.portfolio.rebalance_band),
+    )
+    btc_pct = band_result["allocation_pct"]["BTC"]
+    eth_pct = band_result["allocation_pct"]["ETH"]
+    cash_pct = band_result["allocation_pct"]["CASH"]
+    drift = band_result["drift"]
+    rebalance_hint = band_result["hint"]
+
+    prior = conn.execute(
+        """
+        SELECT nav_usd FROM portfolio_snapshots
+        WHERE ts < ?
+        ORDER BY ts DESC LIMIT 1
+        """,
+        (row["ts"],),
+    ).fetchone()
+
+    pnl_24h = None
+    if prior and prior["nav_usd"] is not None and row["nav_usd"] is not None:
+        pnl_24h = round(float(row["nav_usd"]) - float(prior["nav_usd"]), 2)
+
+    return {
+        "available": True,
+        "as_of": row["ts"],
+        "nav_usd": round(float(row["nav_usd"] or 0), 2),
+        "cash_usd": round(float(row["cash_usd"] or 0), 2),
+        "allocation_pct": {
+            "BTC": round(btc_pct, 4),
+            "ETH": round(eth_pct, 4),
+            "CASH": round(cash_pct, 4),
+        },
+        "target_allocation_pct": target,
+        "drift": drift,
+        "rebalance_hint": rebalance_hint,
+        "outside_band": band_result["outside_band"],
+        "max_drift": band_result["max_drift"],
+        "band": band_result["band"],
+        "pnl_usd": {"since_prior_snapshot": pnl_24h},
+        "prices": allocation.get("prices") or {},
+        "cash_breakdown": allocation.get("cash_breakdown") or {},
+    }
+
+
+def build_market_context(conn: sqlite3.Connection, config) -> dict[str, Any]:
+    spot = config.exchanges.primary_spot()
+    assets = build_spot_market_assets(conn, spot)
+    breadth = build_market_breadth_context(conn)
+
+    if not assets and not breadth.get("available"):
+        return {"available": False, "reason": "no_market_data"}
+
+    result: dict[str, Any] = {"available": True, "interval_minutes": spot.ohlc_interval_minutes}
+    if assets:
+        result["assets"] = assets
+    if breadth.get("available"):
+        result["breadth"] = breadth
+    if not assets:
+        result["reason"] = "no_market_bars"
+    return result
+
+
+def _spot_pair_to_symbol(pair: str) -> str:
+    if "-" in pair:
+        from alloccontext.ingest.coinbase_client import product_to_symbol
+
+        return product_to_symbol(pair)
+    from alloccontext.ingest.kraken_client import pair_to_symbol
+
+    return pair_to_symbol(pair)
+
+
+def build_spot_market_assets(conn: sqlite3.Connection, spot) -> dict[str, Any]:
+    assets: dict[str, Any] = {}
+    interval = spot.ohlc_interval_minutes
+    for pair in spot.pairs:
+        symbol = _spot_pair_to_symbol(pair)
+        rows = conn.execute(
+            """
+            SELECT bar_ts, close FROM market_bars
+            WHERE pair = ? AND interval_minutes = ?
+            ORDER BY bar_ts DESC LIMIT 2
+            """,
+            (pair, interval),
+        ).fetchall()
+        if not rows:
+            continue
+        latest = float(rows[0]["close"])
+        change_pct = None
+        if len(rows) >= 2 and float(rows[1]["close"]) > 0:
+            prior = float(rows[1]["close"])
+            change_pct = round((latest - prior) / prior * 100, 2)
+        assets[symbol.lower()] = {
+            "pair": pair,
+            "price_usd": round(latest, 2),
+            "change_pct": {"1_bar": change_pct},
+        }
+    return assets
+
+
+def build_kraken_market_assets(conn: sqlite3.Connection, config) -> dict[str, Any]:
+    """Compatibility alias — use build_spot_market_assets with primary exchange config."""
+    return build_spot_market_assets(conn, config.exchanges.primary_spot())

alloccontext/rollup/rebalance.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from typing import Any
+
+_ASSETS = ("BTC", "ETH", "CASH")
+
+_DEFAULT_PAIRS = {
+    "kraken": {"BTC": "XBTUSD", "ETH": "ETHUSD"},
+    "coinbase": {"BTC": "BTC-USD", "ETH": "ETH-USD"},
+}
+
+
+def _round_usd(value: float) -> float:
+    return round(value)
+
+
+def _product_for_asset(exchange: str, asset: str, pairs: dict[str, str] | None) -> str:
+    if pairs and asset in pairs:
+        return pairs[asset]
+    return _DEFAULT_PAIRS.get(exchange, _DEFAULT_PAIRS["kraken"])[asset]
+
+
+def _buy_move(exchange: str, asset: str, usd: float, pairs: dict[str, str] | None) -> str:
+    amount = _round_usd(usd)
+    if exchange == "coinbase":
+        product = _product_for_asset(exchange, asset, pairs)
+        return f"Buy ~${amount:,.0f} {asset} on {product}"
+    pair = _product_for_asset(exchange, asset, pairs)
+    symbol = "XBT" if asset == "BTC" else asset
+    return f"Buy ~${amount:,.0f} {symbol} ({pair})"
+
+
+def _trim_move(exchange: str, asset: str, usd: float, pairs: dict[str, str] | None) -> str:
+    amount = _round_usd(usd)
+    if exchange == "coinbase":
+        product = _product_for_asset(exchange, asset, pairs)
+        return f"Sell ~${amount:,.0f} {asset} on {product}"
+    pair = _product_for_asset(exchange, asset, pairs)
+    symbol = "XBT" if asset == "BTC" else asset
+    return f"Sell ~${amount:,.0f} {symbol} ({pair})"
+
+
+def _deploy_move(exchange: str, asset: str, usd: float, pairs: dict[str, str] | None) -> str:
+    amount = _round_usd(usd)
+    if exchange == "coinbase":
+        product = _product_for_asset(exchange, asset, pairs)
+        return f"Deploy ~${amount:,.0f} from USD → {asset} on {product}"
+    symbol = "XBT" if asset == "BTC" else asset
+    return f"Deploy ~${amount:,.0f} from cash → {symbol}"
+
+
+def compute_rebalance_plan(
+    nav_usd: float,
+    current_pct: dict[str, float],
+    target_pct: dict[str, float],
+    *,
+    min_usd: float = 1.0,
+    exchange: str = "kraken",
+    pairs: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """USD deltas and exchange-style moves from current to target allocation."""
+    if nav_usd <= 0:
+        return {"available": False, "reason": "no_nav"}
+
+    exchange_key = exchange.strip().lower() if exchange else "kraken"
+    current_usd = {a: nav_usd * float(current_pct.get(a) or 0) for a in _ASSETS}
+    target_usd = {a: nav_usd * float(target_pct.get(a) or 0) for a in _ASSETS}
+    delta_usd = {a: target_usd[a] - current_usd[a] for a in _ASSETS}
+
+    moves: list[str] = []
+    cash_surplus = max(0.0, -delta_usd["CASH"])
+    crypto_need = {
+        "BTC": max(0.0, delta_usd["BTC"]),
+        "ETH": max(0.0, delta_usd["ETH"]),
+    }
+    total_crypto_need = crypto_need["BTC"] + crypto_need["ETH"]
+
+    deployed: dict[str, float] = {"BTC": 0.0, "ETH": 0.0}
+    if cash_surplus >= min_usd and total_crypto_need >= min_usd:
+        deploy_total = min(cash_surplus, total_crypto_need)
+        for asset in ("BTC", "ETH"):
+            share = deploy_total * crypto_need[asset] / total_crypto_need
+            if share >= min_usd:
+                deployed[asset] = share
+                moves.append(_deploy_move(exchange_key, asset, share, pairs))
+
+    for asset in ("BTC", "ETH"):
+        remaining = delta_usd[asset] - deployed[asset]
+        if remaining >= min_usd:
+            moves.append(_buy_move(exchange_key, asset, remaining, pairs))
+        elif remaining <= -min_usd:
+            moves.append(_trim_move(exchange_key, asset, -remaining, pairs))
+
+    if not moves and all(abs(delta_usd[a]) < min_usd for a in _ASSETS):
+        moves.append("Already at target within ~$1 rounding.")
+
+    return {
+        "available": True,
+        "exchange": exchange_key,
+        "nav_usd": round(nav_usd, 2),
+        "current_usd": {a: round(current_usd[a], 2) for a in _ASSETS},
+        "target_usd": {a: round(target_usd[a], 2) for a in _ASSETS},
+        "delta_usd": {a: round(delta_usd[a], 2) for a in _ASSETS},
+        "moves": moves,
+    }
+
+
+def format_rebalance_plan(
+    plan: dict[str, Any],
+    *,
+    target_pct: dict[str, float],
+) -> str:
+    if not plan.get("available"):
+        return ""
+
+    btc = round(float(target_pct.get("BTC") or 0) * 100)
+    eth = round(float(target_pct.get("ETH") or 0) * 100)
+    cash = round(float(target_pct.get("CASH") or 0) * 100)
+    nav = plan.get("nav_usd", 0)
+    header = (
+        f"**Moves to reach BTC {btc}%, ETH {eth}%, Cash {cash}% "
+        f"(~${nav:,.0f} NAV):**"
+    )
+    bullets = "\n".join(f"- {line}" for line in plan.get("moves") or [])
+    return f"{header}\n{bullets}"

alloccontext/rollup/regime.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def _kalshi_block(sentiment: dict[str, Any]) -> dict[str, Any]:
+    kalshi = sentiment.get("kalshi")
+    return kalshi if isinstance(kalshi, dict) else {}
+
+
+def _fear_greed_block(sentiment: dict[str, Any]) -> dict[str, Any] | None:
+    fg = sentiment.get("fear_greed")
+    return fg if isinstance(fg, dict) else None
+
+
+def build_regime_context(
+    *,
+    portfolio: dict[str, Any],
+    sentiment: dict[str, Any],
+    delta: dict[str, Any],
+    prior_as_of: str | None,
+    max_cash_risk_off: float = 0.50,
+) -> dict[str, Any]:
+    hints: list[dict[str, str]] = []
+    allocation: dict[str, Any] = {"available": False}
+    volatility: dict[str, Any] = {"available": False}
+    sentiment_block: dict[str, Any] = {"available": False}
+
+    if portfolio.get("available"):
+        allocation = {
+            "available": True,
+            "hint": portfolio.get("rebalance_hint"),
+            "outside_band": portfolio.get("outside_band"),
+            "max_drift": portfolio.get("max_drift"),
+            "band": portfolio.get("band"),
+            "target_allocation_pct": portfolio.get("target_allocation_pct"),
+        }
+        hint = portfolio.get("rebalance_hint")
+        if hint:
+            hints.append(
+                {
+                    "kind": "allocation",
+                    "code": str(hint),
+                    "text": _allocation_hint_text(str(hint)),
+                }
+            )
+
+    kalshi = _kalshi_block(sentiment)
+    if kalshi.get("available"):
+        vol_regime = kalshi.get("volatility_regime")
+        vol_by_asset = kalshi.get("volatility_by_asset")
+        if vol_regime or vol_by_asset:
+            volatility = {
+                "available": True,
+                "regime": vol_regime,
+                "by_asset": vol_by_asset,
+            }
+            if vol_regime:
+                hints.append(
+                    {
+                        "kind": "volatility",
+                        "code": str(vol_regime),
+                        "text": f"Short-horizon volatility regime: {vol_regime}.",
+                    }
+                )
+        tape_summary = kalshi.get("tape_summary")
+        leaders_agree = kalshi.get("leaders_agree")
+        sentiment_up_frac = kalshi.get("sentiment_up_frac")
+        sentiment_block = {
+            "available": True,
+            "tape_summary": tape_summary,
+            "leaders_agree": leaders_agree,
+            "sentiment_up_frac": sentiment_up_frac,
+        }
+        if leaders_agree is False:
+            hints.append(
+                {
+                    "kind": "spot_prediction",
+                    "code": "leaders_diverge",
+                    "text": "BTC and ETH short-term Kalshi drift disagree.",
+                }
+            )
+
+    fg = _fear_greed_block(sentiment) if sentiment.get("available") else None
+    if fg and fg.get("value") is not None:
+        sentiment_block.setdefault("available", True)
+        sentiment_block["fear_greed_value"] = fg.get("value")
+        sentiment_block["fear_greed_classification"] = fg.get("classification")
+        classification = fg.get("classification")
+        if classification:
+            hints.append(
+                {
+                    "kind": "sentiment",
+                    "code": str(classification).lower().replace(" ", "_"),
+                    "text": f"Fear & Greed index: {fg['value']} ({classification}).",
+                }
+            )
+
+    comparison: dict[str, Any] = {
+        "prior_as_of": prior_as_of,
+        "has_prior_snapshot": bool(prior_as_of),
+    }
+    if delta.get("available"):
+        comparison["notable_shifts"] = list(delta.get("notable_shifts") or [])
+        for line in comparison["notable_shifts"]:
+            hints.append({"kind": "delta", "code": "notable_shift", "text": str(line)})
+
+    available = (
+        allocation.get("available")
+        or volatility.get("available")
+        or sentiment_block.get("available")
+        or comparison["has_prior_snapshot"]
+    )
+    summary_parts = [hint["text"] for hint in hints[:3]]
+    summary = " ".join(summary_parts) if summary_parts else None
+    risk_off = _build_risk_off(
+        portfolio=portfolio,
+        sentiment=sentiment,
+        max_cash_risk_off=max_cash_risk_off,
+    )
+
+    return {
+        "available": available,
+        "allocation": allocation,
+        "volatility": volatility,
+        "sentiment": sentiment_block,
+        "comparison": comparison,
+        "hints": hints,
+        "summary": summary,
+        "risk_off": risk_off,
+    }
+
+
+def _allocation_hint_text(code: str) -> str:
+    mapping = {
+        "within_band": "Portfolio allocation is within the configured drift band.",
+        "consider_deploy_cash": "Cash weight is above target — consider deploying idle cash.",
+        "consider_trim_to_cash": "Cash weight is below target — consider trimming to raise cash.",
+        "consider_rebalance": "Allocation drift exceeds the band — consider rebalancing.",
+    }
+    return mapping.get(code, f"Allocation hint: {code}.")
+
+
+def _build_risk_off(
+    *,
+    portfolio: dict[str, Any],
+    sentiment: dict[str, Any],
+    max_cash_risk_off: float,
+) -> dict[str, Any]:
+    signals: list[str] = []
+    score = 0
+
+    if portfolio.get("available"):
+        cash = float((portfolio.get("allocation_pct") or {}).get("CASH") or 0)
+        if cash >= max_cash_risk_off:
+            score += 40
+            signals.append(f"cash {cash * 100:.1f}% at/above risk-off ceiling")
+        elif cash >= max_cash_risk_off * 0.75:
+            score += 20
+            signals.append(f"cash {cash * 100:.1f}% elevated vs risk-off ceiling")
+        hint = str(portfolio.get("rebalance_hint") or "")
+        if hint == "consider_deploy_cash":
+            score += 15
+            signals.append("rebalance hint favors deploying cash")
+
+    fg = _fear_greed_block(sentiment) if sentiment.get("available") else None
+    if fg and fg.get("value") is not None:
+        value = int(fg["value"])
+        if value <= 25:
+            score += 35
+            signals.append(f"Fear & Greed {value} (extreme fear)")
+        elif value <= 40:
+            score += 20
+            signals.append(f"Fear & Greed {value} (fear)")
+
+    score = min(100, score)
+    level = "low"
+    if score >= 70:
+        level = "high"
+    elif score >= 40:
+        level = "moderate"
+
+    return {
+        "available": bool(signals),
+        "score": score,
+        "level": level,
+        "signals": signals,
+    }

alloccontext/rollup/sentiment.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+from datetime import datetime, timezone
+from typing import Any
+
+from alloccontext.rollup.cluster import MarketQuote
+from alloccontext.rollup.cluster_config import RollupConfig
+from alloccontext.rollup.tape import build_live_tape_context
+from alloccontext.store.meta import get_meta
+
+
+def _latest_snapshot(conn: sqlite3.Connection) -> sqlite3.Row | None:
+    return conn.execute(
+        """
+        SELECT ts, tape_summary, cluster_json, raw_json
+        FROM kalshi_snapshots ORDER BY id DESC LIMIT 1
+        """
+    ).fetchone()
+
+
+def _markets_from_meta(conn: sqlite3.Connection) -> list[MarketQuote]:
+    raw = get_meta(conn, "kalshi_markets") or get_meta(conn, "kalshi_markets_15m")
+    if not raw:
+        return []
+    try:
+        rows = json.loads(raw)
+    except json.JSONDecodeError:
+        return []
+    markets: list[MarketQuote] = []
+    for row in rows:
+        if not isinstance(row, dict):
+            continue
+        markets.append(
+            MarketQuote(
+                ticker=str(row.get("ticker") or ""),
+                yes_ask_cents=row.get("yes_ask_cents"),
+                no_ask_cents=row.get("no_ask_cents"),
+            )
+        )
+    return markets
+
+
+def _cf_history_from_meta(conn: sqlite3.Connection) -> dict[str, Any] | None:
+    raw = get_meta(conn, "cf_price_history")
+    if not raw:
+        return None
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def build_kalshi_sentiment_context(
+    conn: sqlite3.Connection,
+    rollup: RollupConfig,
+    *,
+    now: datetime | None = None,
+) -> dict[str, Any]:
+    now = now or datetime.now(timezone.utc)
+    row = _latest_snapshot(conn)
+    if row is None:
+        return {"available": False, "reason": "no_kalshi_snapshot"}
+
+    cluster = json.loads(row["cluster_json"] or "{}")
+    tape_summary = row["tape_summary"]
+    source = "kalshi_snapshot"
+
+    if not cluster:
+        cf_history = _cf_history_from_meta(conn)
+        markets = _markets_from_meta(conn)
+        computed = build_live_tape_context(
+            rollup,
+            cf_history=cf_history,
+            markets=markets,
+            now=now,
+        )
+        if computed:
+            tape_ctx, cluster_ctx, _computed_at = computed
+            cluster = cluster_ctx
+            tape_summary = tape_ctx.get("summary") or tape_summary
+            source = "computed_cf_meta"
+
+    if not cluster and not tape_summary:
+        return {"available": False, "reason": "empty_kalshi_telemetry"}
+
+    return {
+        "available": True,
+        "source": source,
+        "as_of": row["ts"],
+        "tape_summary": tape_summary,
+        **cluster,
+    }
+
+
+def build_sentiment_context(
+    conn: sqlite3.Connection,
+    config,
+    rollup: RollupConfig,
+    *,
+    now: datetime | None = None,
+) -> dict[str, Any]:
+    from alloccontext.rollup.fear_greed import build_fear_greed_context
+
+    now = now or datetime.now(timezone.utc)
+    fg = build_fear_greed_context(conn, now=now)
+    kalshi = build_kalshi_sentiment_context(conn, rollup, now=now)
+    available = fg is not None or kalshi.get("available")
+    body: dict[str, Any] = {
+        "available": available,
+        "fear_greed": fg,
+        "kalshi": kalshi,
+    }
+    if not available:
+        body["reason"] = "no_sentiment_sources"
+    return body

alloccontext/rollup/snapshots.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+from typing import Any, Literal
+
+Scope = Literal["daily", "weekly"]
+
+
+class SnapshotNotFoundError(LookupError):
+    pass
+
+
+def load_context_bundle_snapshot(
+    conn: sqlite3.Connection,
+    *,
+    scope: Scope,
+    as_of: str,
+) -> dict[str, Any]:
+    row = conn.execute(
+        """
+        SELECT context_json FROM context_snapshots
+        WHERE scope = ? AND as_of = ?
+        """,
+        (scope, as_of),
+    ).fetchone()
+    if row is None:
+        raise SnapshotNotFoundError(f"no {scope} snapshot at {as_of}")
+    try:
+        return json.loads(row["context_json"])
+    except (TypeError, json.JSONDecodeError) as exc:
+        raise SnapshotNotFoundError(f"invalid snapshot JSON at {as_of}") from exc
+
+
+def resolve_context_snapshot_as_of(
+    conn: sqlite3.Connection,
+    *,
+    scope: Scope,
+    as_of: str,
+    mode: Literal["exact", "at_or_before"] = "exact",
+) -> str:
+    if mode == "exact":
+        row = conn.execute(
+            """
+            SELECT as_of FROM context_snapshots
+            WHERE scope = ? AND as_of = ?
+            """,
+            (scope, as_of),
+        ).fetchone()
+        if row is None:
+            raise SnapshotNotFoundError(f"no {scope} snapshot at {as_of}")
+        return str(row["as_of"])
+
+    row = conn.execute(
+        """
+        SELECT as_of FROM context_snapshots
+        WHERE scope = ? AND as_of <= ?
+        ORDER BY as_of DESC LIMIT 1
+        """,
+        (scope, as_of),
+    ).fetchone()
+    if row is None:
+        raise SnapshotNotFoundError(f"no {scope} snapshot at or before {as_of}")
+    return str(row["as_of"])