alloc-context 0.1.0__py3-none-any.whl

alloccontext/mcp/x402_stables.py

@@ -0,0 +1,179 @@
+"""Base stablecoin options for x402 exact payments."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from decimal import Decimal, ROUND_HALF_UP
+
+from alloccontext.mcp.x402_pricing import (
+    build_mcp_dynamic_price,
+    mcp_call_is_heavy,
+    read_mcp_request_json,
+)
+
+BASE_MAINNET = "eip155:8453"
+BASE_SEPOLIA = "eip155:84532"
+DEFAULT_ACCEPTED_STABLES = "USDC,EURC"
+# When env parses to no symbols (e.g. X402_ACCEPTED_STABLES=""), discovery and
+# payment routes both use this list — not dynamic $ pricing.
+FALLBACK_ACCEPTED_STABLES = ("USDC",)
+
+
+@dataclass(frozen=True)
+class StableCoin:
+    """ERC-20 stable accepted for x402 exact settlement on Base."""
+
+    symbol: str
+    address: str
+    decimals: int
+    eip712_name: str
+    eip712_version: str
+
+
+# Circle USDC on Base mainnet matches x402 NETWORK_CONFIGS default_asset.
+_BASE_MAINNET_STABLES: dict[str, StableCoin] = {
+    "USDC": StableCoin(
+        symbol="USDC",
+        address="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        decimals=6,
+        eip712_name="USD Coin",
+        eip712_version="2",
+    ),
+    "EURC": StableCoin(
+        symbol="EURC",
+        address="0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42",
+        decimals=6,
+        eip712_name="EURC",
+        eip712_version="2",
+    ),
+}
+
+_BASE_SEPOLIA_STABLES: dict[str, StableCoin] = {
+    "USDC": StableCoin(
+        symbol="USDC",
+        address="0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+        decimals=6,
+        eip712_name="USDC",
+        eip712_version="2",
+    ),
+}
+
+_STABLES_BY_NETWORK: dict[str, dict[str, StableCoin]] = {
+    BASE_MAINNET: _BASE_MAINNET_STABLES,
+    BASE_SEPOLIA: _BASE_SEPOLIA_STABLES,
+}
+
+
+def parse_accepted_stable_symbols(raw: str | None) -> tuple[str, ...]:
+    """Parse comma-separated stable symbols (e.g. USDC,EURC)."""
+    value = (raw if raw is not None else DEFAULT_ACCEPTED_STABLES).strip()
+    if not value:
+        return ()
+    return tuple(part.strip().upper() for part in value.split(",") if part.strip())
+
+
+def effective_accepted_stable_symbols(symbols: tuple[str, ...]) -> tuple[str, ...]:
+    """Non-empty symbol list for routes and discovery; USDC when parse yields none."""
+    return symbols if symbols else FALLBACK_ACCEPTED_STABLES
+
+
+def load_accepted_stable_symbols() -> tuple[str, ...]:
+    raw = os.environ.get("X402_ACCEPTED_STABLES")
+    return effective_accepted_stable_symbols(parse_accepted_stable_symbols(raw))
+
+
+def stables_for_network(
+    network: str,
+    symbols: tuple[str, ...] | None = None,
+) -> tuple[StableCoin, ...]:
+    """Return configured stablecoins for a CAIP-2 network."""
+    catalog = _STABLES_BY_NETWORK.get(network)
+    if catalog is None:
+        return ()
+
+    chosen = symbols if symbols is not None else load_accepted_stable_symbols()
+    if not chosen:
+        return ()
+
+    resolved: list[StableCoin] = []
+    for symbol in chosen:
+        stable = catalog.get(symbol)
+        if stable is not None:
+            resolved.append(stable)
+    if chosen and not resolved:
+        raise ValueError(
+            f"no accepted stables from {chosen!r} are listed on network {network}"
+        )
+    return tuple(resolved)
+
+
+def dollar_to_atomic(amount: str, decimals: int) -> str:
+    """Convert a $ price string to ERC-20 atomic units (USD-pegged stables)."""
+    dollars = Decimal(amount.strip().lstrip("$"))
+    scale = Decimal(10) ** decimals
+    atomic = (dollars * scale).to_integral_value(rounding=ROUND_HALF_UP)
+    return str(int(atomic))
+
+
+def build_stable_dynamic_price(
+    *,
+    stable: StableCoin,
+    light_price: str,
+    heavy_price: str,
+):
+    """Build async DynamicPrice returning AssetAmount for one stable."""
+
+    async def resolve_price(context):
+        body = await read_mcp_request_json(context)
+        price_str = heavy_price if mcp_call_is_heavy(body) else light_price
+        return {
+            "amount": dollar_to_atomic(price_str, stable.decimals),
+            "asset": stable.address,
+            "extra": {
+                "name": stable.eip712_name,
+                "version": stable.eip712_version,
+            },
+        }
+
+    return resolve_price
+
+
+def build_payment_options_for_stables(
+    *,
+    pay_to: str,
+    network: str,
+    light_price: str,
+    heavy_price: str,
+    symbols: tuple[str, ...] | None = None,
+):
+    """PaymentOption list: one per accepted stable; fallback to $ price on unknown nets."""
+    from x402.http.types import PaymentOption
+
+    stables = stables_for_network(network, symbols)
+    if not stables:
+        return [
+            PaymentOption(
+                scheme="exact",
+                pay_to=pay_to,
+                price=build_mcp_dynamic_price(
+                    light_price=light_price,
+                    heavy_price=heavy_price,
+                ),
+                network=network,
+            )
+        ]
+
+    return [
+        PaymentOption(
+            scheme="exact",
+            pay_to=pay_to,
+            price=build_stable_dynamic_price(
+                stable=stable,
+                light_price=light_price,
+                heavy_price=heavy_price,
+            ),
+            network=network,
+        )
+        for stable in stables
+    ]

alloccontext/rollup/__init__.py

@@ -0,0 +1 @@
+"""Deterministic ContextBundle builders."""

alloccontext/rollup/band.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import Any
+
+_ASSETS = ("BTC", "ETH", "CASH")
+
+
+def _pct(allocation: dict[str, float], key: str) -> float:
+    return float(allocation.get(key) or 0)
+
+
+def check_allocation_band(
+    allocation_pct: dict[str, float],
+    target_pct: dict[str, float],
+    band: float,
+) -> dict[str, Any]:
+    """Drift vs target and rebalance hint for BTC/ETH/CASH."""
+    btc_pct = _pct(allocation_pct, "BTC")
+    eth_pct = _pct(allocation_pct, "ETH")
+    cash_pct = _pct(allocation_pct, "CASH")
+    drift = {
+        "BTC": round(btc_pct - _pct(target_pct, "BTC"), 4),
+        "ETH": round(eth_pct - _pct(target_pct, "ETH"), 4),
+        "CASH": round(cash_pct - _pct(target_pct, "CASH"), 4),
+    }
+    max_drift = max(abs(v) for v in drift.values()) if drift else 0.0
+    outside_band = max_drift > band
+    if not outside_band:
+        hint = "within_band"
+    elif cash_pct > _pct(target_pct, "CASH") + band:
+        hint = "consider_deploy_cash"
+    elif cash_pct < _pct(target_pct, "CASH") - band:
+        hint = "consider_trim_to_cash"
+    else:
+        hint = "consider_rebalance"
+
+    return {
+        "available": True,
+        "allocation_pct": {
+            "BTC": round(btc_pct, 4),
+            "ETH": round(eth_pct, 4),
+            "CASH": round(cash_pct, 4),
+        },
+        "target_pct": {a: _pct(target_pct, a) for a in _ASSETS},
+        "drift": drift,
+        "max_drift": round(max_drift, 4),
+        "band": band,
+        "outside_band": outside_band,
+        "hint": hint,
+    }

alloccontext/rollup/breadth.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import sqlite3
+from typing import Any
+
+from alloccontext.ingest.market_snapshots import (
+    dominance_delta,
+    latest_snapshot,
+    prior_snapshot,
+    row_to_dict,
+)
+
+_SOURCES = ("coingecko", "coinmarketcap")
+
+
+def build_market_breadth_context(conn: sqlite3.Connection) -> dict[str, Any]:
+    feeds: dict[str, Any] = {}
+    for source in _SOURCES:
+        row = latest_snapshot(conn, source)
+        if row is None:
+            feeds[source] = {"available": False, "reason": "no_snapshot"}
+            continue
+        current = row_to_dict(row)
+        prior = row_to_dict(prior_snapshot(conn, source, current["snapshot_ts"]))
+        block: dict[str, Any] = {
+            "available": True,
+            "as_of": current["snapshot_ts"],
+            **{k: v for k, v in current.items() if k not in {"snapshot_ts", "source"}},
+        }
+        if prior:
+            block["delta_since_prior"] = dominance_delta(current, prior)
+            if prior.get("btc_rank") is not None and current.get("btc_rank") is not None:
+                block["delta_since_prior"]["btc_rank_change"] = int(current["btc_rank"]) - int(
+                    prior["btc_rank"]
+                )
+            if prior.get("eth_rank") is not None and current.get("eth_rank") is not None:
+                block["delta_since_prior"]["eth_rank_change"] = int(current["eth_rank"]) - int(
+                    prior["eth_rank"]
+                )
+        feeds[source] = block
+
+    if not any(feed.get("available") for feed in feeds.values()):
+        return {"available": False, "reason": "no_market_breadth_data"}
+
+    return {"available": True, "feeds": feeds}

alloccontext/rollup/cf_math.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import datetime as dt
+from typing import Any
+
+
+def parse_ts(raw: str | None) -> dt.datetime | None:
+    if not raw:
+        return None
+    try:
+        parsed = dt.datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=dt.timezone.utc)
+    return parsed.astimezone(dt.timezone.utc)
+
+
+def pct_change_over_minutes(
+    history: dict[str, list[dict[str, Any]]] | None,
+    index: str,
+    now: dt.datetime,
+    *,
+    lookback_minutes: float,
+    min_samples: int,
+) -> float | None:
+    rows = history.get(index) if history else None
+    if not rows:
+        return None
+    now = now.astimezone(dt.timezone.utc)
+    cutoff = now - dt.timedelta(minutes=lookback_minutes)
+    samples: list[tuple[dt.datetime, float]] = []
+    for row in rows:
+        ts = parse_ts(row.get("at"))
+        price = row.get("price")
+        if ts is None or price is None or ts < cutoff:
+            continue
+        samples.append((ts, float(price)))
+    if len(samples) < min_samples:
+        return None
+    samples.sort(key=lambda item: item[0])
+    oldest = samples[0][1]
+    newest = samples[-1][1]
+    if oldest <= 0:
+        return None
+    return (newest - oldest) / oldest
+
+
+def range_pct_over_minutes(
+    history: dict[str, list[dict[str, Any]]] | None,
+    index: str,
+    now: dt.datetime,
+    *,
+    lookback_minutes: float,
+    min_samples: int,
+) -> float | None:
+    rows = history.get(index) if history else None
+    if not rows:
+        return None
+    now = now.astimezone(dt.timezone.utc)
+    cutoff = now - dt.timedelta(minutes=lookback_minutes)
+    prices: list[float] = []
+    for row in rows:
+        ts = parse_ts(row.get("at"))
+        price = row.get("price")
+        if ts is None or price is None or ts < cutoff:
+            continue
+        prices.append(float(price))
+    if len(prices) < min_samples:
+        return None
+    low = min(prices)
+    high = max(prices)
+    mid = (low + high) / 2.0
+    if mid <= 0:
+        return None
+    return (high - low) / mid
+
+
+def trend_pct_for_index(
+    history: dict[str, list[dict[str, Any]]] | None,
+    index: str,
+    now: dt.datetime,
+    *,
+    lookback_minutes: float,
+    min_samples: int,
+    enabled: bool = True,
+) -> float | None:
+    if not enabled:
+        return None
+    return pct_change_over_minutes(
+        history,
+        index,
+        now,
+        lookback_minutes=lookback_minutes,
+        min_samples=min_samples,
+    )
+
+
+def scale_pct_map(values: dict[str, float | None]) -> dict[str, float | None]:
+    return {
+        asset: None if pct is None else round(pct * 100, 4)
+        for asset, pct in values.items()
+    }

alloccontext/rollup/cluster.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass
+from typing import Any
+
+from alloccontext.rollup.cf_math import pct_change_over_minutes
+from alloccontext.rollup.cluster_config import ClusterLogConfig, CryptoAssetConfig
+
+
+@dataclass(frozen=True)
+class MarketQuote:
+    ticker: str
+    yes_ask_cents: int | None
+    no_ask_cents: int | None
+
+
+@dataclass(frozen=True)
+class ClusterSnapshot:
+    assets_with_drift: int
+    drift_5m_by_asset: dict[str, float]
+    weighted_drift_5m: float | None
+    btc_drift_5m: float | None
+    eth_drift_5m: float | None
+    sentiment_up_frac: float | None
+    sentiment_sample_size: int
+
+
+def _alt_weight(cfg: ClusterLogConfig, alt_count: int) -> float:
+    if alt_count <= 0:
+        return 0.0
+    remainder = max(0.0, 1.0 - cfg.btc_weight - cfg.eth_weight)
+    return remainder / alt_count
+
+
+def sentiment_up_fraction(markets: list[MarketQuote]) -> tuple[float | None, int]:
+    samples = 0
+    up_votes = 0
+    for market in markets:
+        yes_ask = market.yes_ask_cents
+        no_ask = market.no_ask_cents
+        if yes_ask is None or no_ask is None:
+            continue
+        samples += 1
+        if yes_ask >= no_ask:
+            up_votes += 1
+    if samples == 0:
+        return None, 0
+    return up_votes / samples, samples
+
+
+def build_cluster_snapshot(
+    cfg: ClusterLogConfig,
+    *,
+    crypto_assets: tuple[CryptoAssetConfig, ...],
+    cf_history: dict[str, list[dict[str, Any]]] | None,
+    markets: list[MarketQuote],
+    now: dt.datetime,
+    min_samples_short: int,
+) -> ClusterSnapshot | None:
+    if not cfg.enabled or not cf_history:
+        return None
+
+    drift_5m_by_asset: dict[str, float] = {}
+    for asset_row in crypto_assets:
+        index = asset_row.cf_index
+        if not index:
+            continue
+        drift = pct_change_over_minutes(
+            cf_history,
+            index,
+            now,
+            lookback_minutes=cfg.drift_lookback_minutes,
+            min_samples=min_samples_short,
+        )
+        if drift is not None:
+            drift_5m_by_asset[asset_row.asset] = drift
+
+    if not drift_5m_by_asset:
+        return None
+
+    alt_assets = [
+        asset
+        for asset in crypto_assets
+        if asset.asset not in cfg.leader_assets and asset.asset in drift_5m_by_asset
+    ]
+    alt_weight = _alt_weight(cfg, len(alt_assets))
+    weighted = 0.0
+    weight_used = 0.0
+    for asset_row in crypto_assets:
+        drift = drift_5m_by_asset.get(asset_row.asset)
+        if drift is None:
+            continue
+        if asset_row.asset == "BTC":
+            weight = cfg.btc_weight
+        elif asset_row.asset == "ETH":
+            weight = cfg.eth_weight
+        else:
+            weight = alt_weight
+        weighted += drift * weight
+        weight_used += weight
+    weighted_drift = weighted / weight_used if weight_used > 0 else None
+
+    sentiment_up_frac, sentiment_n = sentiment_up_fraction(markets)
+
+    return ClusterSnapshot(
+        assets_with_drift=len(drift_5m_by_asset),
+        drift_5m_by_asset=drift_5m_by_asset,
+        weighted_drift_5m=weighted_drift,
+        btc_drift_5m=drift_5m_by_asset.get("BTC"),
+        eth_drift_5m=drift_5m_by_asset.get("ETH"),
+        sentiment_up_frac=sentiment_up_frac,
+        sentiment_sample_size=sentiment_n,
+    )
+
+
+def cluster_advisory_fields(cluster: ClusterSnapshot | None) -> dict[str, Any]:
+    if cluster is None:
+        return {}
+
+    drifts = list(cluster.drift_5m_by_asset.values())
+    breadth = sum(1 for drift in drifts if drift > 0) / len(drifts) if drifts else None
+    leaders_agree = None
+    if cluster.btc_drift_5m is not None and cluster.eth_drift_5m is not None:
+        leaders_agree = (cluster.btc_drift_5m > 0) == (cluster.eth_drift_5m > 0)
+
+    fields: dict[str, Any] = {
+        "assets_with_drift": cluster.assets_with_drift,
+        "sentiment_sample": cluster.sentiment_sample_size,
+    }
+    if cluster.sentiment_up_frac is not None:
+        fields["sentiment_up_frac"] = round(cluster.sentiment_up_frac, 4)
+    if cluster.weighted_drift_5m is not None:
+        fields["weighted_drift_5m_pct"] = round(cluster.weighted_drift_5m * 100, 4)
+    if cluster.btc_drift_5m is not None:
+        fields["btc_drift_5m_pct"] = round(cluster.btc_drift_5m * 100, 4)
+    if cluster.eth_drift_5m is not None:
+        fields["eth_drift_5m_pct"] = round(cluster.eth_drift_5m * 100, 4)
+    drift_scaled = {
+        asset: round(value * 100, 4)
+        for asset, value in cluster.drift_5m_by_asset.items()
+    }
+    if drift_scaled:
+        fields["drift_5m_by_asset"] = drift_scaled
+    if breadth is not None:
+        fields["breadth_up_frac"] = round(breadth, 4)
+    if leaders_agree is not None:
+        fields["leaders_agree"] = leaders_agree
+    return fields

alloccontext/rollup/cluster_config.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class CryptoAssetConfig:
+    asset: str
+    cf_index: str
+
+
+@dataclass(frozen=True)
+class TrendFilterConfig:
+    enabled: bool
+    lookback_minutes: float
+    min_samples: int
+
+
+@dataclass(frozen=True)
+class ContextFilterConfig:
+    min_samples_short: int
+    short_drift_5m_minutes: float
+    short_drift_15m_minutes: float
+    volatility_lookback_minutes: float
+    medium_volatility_pct: float
+    high_volatility_pct: float
+
+
+@dataclass(frozen=True)
+class ClusterLogConfig:
+    enabled: bool
+    drift_lookback_minutes: float
+    btc_weight: float
+    eth_weight: float
+    leader_assets: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class RollupConfig:
+    crypto: tuple[CryptoAssetConfig, ...]
+    trend_filter: TrendFilterConfig
+    context_filter: ContextFilterConfig
+    cluster_log: ClusterLogConfig
+
+
+def load_rollup_config(raw: dict[str, Any]) -> RollupConfig:
+    rollup = raw.get("rollup") or {}
+    trend = rollup.get("trend_filter") or {}
+    ctx = rollup.get("context_filter") or {}
+    cluster = rollup.get("cluster") or {}
+    crypto_rows = rollup.get("crypto") or [
+        {"asset": "BTC", "cf_index": "BRTI"},
+        {"asset": "ETH", "cf_index": "ETHUSD_RTI"},
+    ]
+
+    return RollupConfig(
+        crypto=tuple(
+            CryptoAssetConfig(asset=str(row["asset"]), cf_index=str(row["cf_index"]))
+            for row in crypto_rows
+        ),
+        trend_filter=TrendFilterConfig(
+            enabled=bool(trend.get("enabled", True)),
+            lookback_minutes=float(trend.get("lookback_minutes", 60)),
+            min_samples=int(trend.get("min_samples", 4)),
+        ),
+        context_filter=ContextFilterConfig(
+            min_samples_short=int(ctx.get("min_samples_short", 2)),
+            short_drift_5m_minutes=float(ctx.get("short_drift_5m_minutes", 60)),
+            short_drift_15m_minutes=float(ctx.get("short_drift_15m_minutes", 60)),
+            volatility_lookback_minutes=float(ctx.get("volatility_lookback_minutes", 60)),
+            medium_volatility_pct=float(ctx.get("medium_volatility_pct", 0.15)) / 100.0
+            if float(ctx.get("medium_volatility_pct", 0.15)) > 1
+            else float(ctx.get("medium_volatility_pct", 0.15)),
+            high_volatility_pct=float(ctx.get("high_volatility_pct", 0.25)) / 100.0
+            if float(ctx.get("high_volatility_pct", 0.25)) > 1
+            else float(ctx.get("high_volatility_pct", 0.25)),
+        ),
+        cluster_log=ClusterLogConfig(
+            enabled=bool(cluster.get("enabled", True)),
+            drift_lookback_minutes=float(cluster.get("drift_lookback_minutes", 60)),
+            btc_weight=float(cluster.get("btc_weight", 0.45)),
+            eth_weight=float(cluster.get("eth_weight", 0.30)),
+            leader_assets=tuple(str(a) for a in cluster.get("leader_assets") or ["BTC", "ETH"]),
+        ),
+    )

alloccontext/rollup/comparison.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def _allocation_drift_lines(
+    prior: dict[str, Any],
+    current: dict[str, Any],
+) -> list[str]:
+    lines: list[str] = []
+    prior_alloc = (prior.get("portfolio") or {}).get("allocation_pct") or {}
+    current_alloc = (current.get("portfolio") or {}).get("allocation_pct") or {}
+    for asset in ("BTC", "ETH", "CASH"):
+        before = prior_alloc.get(asset)
+        after = current_alloc.get(asset)
+        if before is None or after is None:
+            continue
+        delta_pp = round((float(after) - float(before)) * 100, 1)
+        if abs(delta_pp) >= 1.0:
+            lines.append(f"{asset} allocation {delta_pp:+.1f} pp")
+    return lines
+
+
+def compare_context_bundles(
+    prior: dict[str, Any],
+    current: dict[str, Any],
+) -> dict[str, Any]:
+    """Structured diff between two archived or live ContextBundles."""
+    prior_as_of = prior.get("as_of")
+    current_as_of = current.get("as_of")
+    notable: list[str] = []
+
+    prior_delta = prior.get("delta") or {}
+    current_delta = current.get("delta") or {}
+    for block in (prior_delta, current_delta):
+        for line in block.get("notable_shifts") or []:
+            if line not in notable:
+                notable.append(str(line))
+
+    notable.extend(_allocation_drift_lines(prior, current))
+
+    prior_fg = ((prior.get("sentiment") or {}).get("fear_greed") or {}).get("value")
+    current_fg = ((current.get("sentiment") or {}).get("fear_greed") or {}).get("value")
+    if prior_fg is not None and current_fg is not None:
+        change = int(current_fg) - int(prior_fg)
+        if abs(change) >= 5 and not any("F&G" in line for line in notable):
+            notable.append(f"F&G {prior_fg} → {current_fg} ({change:+d})")
+
+    prior_nav = (prior.get("portfolio") or {}).get("nav_usd")
+    current_nav = (current.get("portfolio") or {}).get("nav_usd")
+    nav_change = None
+    if prior_nav is not None and current_nav is not None:
+        nav_change = round(float(current_nav) - float(prior_nav), 2)
+        if abs(nav_change) >= 100 and not any("Portfolio Δ" in line for line in notable):
+            notable.append(f"Portfolio Δ ${nav_change:+.2f} since prior snapshot")
+
+    return {
+        "prior_as_of": prior_as_of,
+        "current_as_of": current_as_of,
+        "notable_shifts": notable,
+        "portfolio_nav_change_usd": nav_change,
+        "fear_greed_change": (
+            int(current_fg) - int(prior_fg)
+            if prior_fg is not None and current_fg is not None
+            else None
+        ),
+    }