delphi-kit 0.1.0__py3-none-any.whl

delphi_kit/limits.py

@@ -0,0 +1,93 @@
+"""Spending limits for agents. Every trade made through the MCP server (or any code that uses ``Guard``) is
+checked against a per-trade cap, a rolling daily cap and an optional market allow-list, and recorded in a small
+ledger file so the daily cap survives restarts."""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+class LimitExceeded(Exception):
+    pass
+
+
+def _env_float(name: str, default: float) -> float:
+    v = os.environ.get(name)
+    return float(v) if v not in (None, "") else default
+
+
+@dataclass
+class Limits:
+    trading_enabled: bool = False
+    max_trade_usd: float = 5.0
+    max_daily_usd: float = 20.0
+    max_slippage: float = 0.03
+    allowed_markets: frozenset[str] | None = None
+
+    @classmethod
+    def from_env(cls) -> "Limits":
+        allow = os.environ.get("DELPHI_ALLOWED_MARKETS")
+        return cls(
+            trading_enabled=os.environ.get("DELPHI_ALLOW_TRADING", "").lower() in ("1", "true", "yes"),
+            max_trade_usd=_env_float("DELPHI_MAX_TRADE_USD", 5.0),
+            max_daily_usd=_env_float("DELPHI_MAX_DAILY_USD", 20.0),
+            max_slippage=_env_float("DELPHI_MAX_SLIPPAGE", 0.03),
+            allowed_markets=frozenset(a.strip().lower() for a in allow.split(",") if a.strip()) if allow else None,
+        )
+
+
+class Guard:
+    def __init__(self, limits: Limits, ledger: Path | None = None):
+        self.limits = limits
+        base = Path(os.environ.get("DELPHI_KIT_CACHE") or Path.home() / ".cache" / "delphi-kit")
+        base.mkdir(parents=True, exist_ok=True)
+        self.ledger = ledger or base / "spend.json"
+        self._lock = threading.Lock()
+
+    def _today(self) -> str:
+        return datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+    def _read(self) -> dict:
+        try:
+            return json.loads(self.ledger.read_text())
+        except (FileNotFoundError, ValueError):
+            return {}
+
+    def spent_today(self) -> float:
+        return float(self._read().get(self._today(), 0.0))
+
+    def check(self, market: str, usd: float) -> None:
+        lim = self.limits
+        if not lim.trading_enabled:
+            raise LimitExceeded("trading is off. Set DELPHI_ALLOW_TRADING=true to let this agent trade.")
+        if lim.allowed_markets is not None and market.lower() not in lim.allowed_markets:
+            raise LimitExceeded("this market is not in DELPHI_ALLOWED_MARKETS")
+        if usd > lim.max_trade_usd + 1e-9:
+            raise LimitExceeded(f"${usd:.2f} is over the per-trade limit of ${lim.max_trade_usd:.2f} (DELPHI_MAX_TRADE_USD)")
+        left = lim.max_daily_usd - self.spent_today()
+        if usd > left + 1e-9:
+            raise LimitExceeded(f"${usd:.2f} is over today's remaining budget of ${max(0.0, left):.2f} (DELPHI_MAX_DAILY_USD)")
+
+    def record(self, usd: float) -> None:
+        with self._lock:
+            data = self._read()
+            day = self._today()
+            data[day] = round(float(data.get(day, 0.0)) + usd, 6)
+            data = {k: v for k, v in data.items() if k >= sorted(data)[-30:][0]}  # keep 30 days
+            self.ledger.write_text(json.dumps(data, indent=1))
+
+    def status(self) -> dict:
+        lim = self.limits
+        return {
+            "trading_enabled": lim.trading_enabled,
+            "max_trade_usd": lim.max_trade_usd,
+            "max_daily_usd": lim.max_daily_usd,
+            "spent_today_usd": round(self.spent_today(), 4),
+            "max_slippage": lim.max_slippage,
+            "allowed_markets": sorted(lim.allowed_markets) if lim.allowed_markets is not None else "all",
+        }

delphi_kit/mcp_server.py

@@ -0,0 +1,180 @@
+"""An MCP server that lets any AI agent (Claude, Cursor, Hermes, your own) read and trade Delphi markets.
+
+Reading needs nothing. Trading is off until you set ``DELPHI_ALLOW_TRADING=true`` and a wallet key, and every
+trade is held to a per-trade cap, a daily cap and a slippage cap (see ``limits.py``).
+
+    uvx --from "delphi-kit[mcp]" delphi-mcp        # stdio, for Claude Desktop / Claude Code / Cursor
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+from mcp.server.mcpserver import MCPServer
+from mcp.types import ToolAnnotations
+
+from .client import Delphi, DelphiError
+from .limits import Guard, LimitExceeded, Limits
+
+INSTRUCTIONS = """Delphi is a prediction market on the Gensyn chain, settled by an AI judge that reads each
+market's rules and named sources. Prices are probabilities (0-1). Before buying: read the market's rules and
+sources with get_market, quote with quote_buy, and check probability_after: thin markets move a lot on small
+trades. Trades are held to spending limits shown by wallet_status; never try to work around them."""
+
+READ = ToolAnnotations(read_only_hint=True, open_world_hint=True)
+WRITE = ToolAnnotations(read_only_hint=False, destructive_hint=False, idempotent_hint=False, open_world_hint=True)
+
+server = MCPServer(name="delphi", instructions=INSTRUCTIONS)
+_client: Optional[Delphi] = None
+_guard: Optional[Guard] = None
+
+
+def client() -> Delphi:
+    global _client
+    if _client is None:
+        _client = Delphi(os.environ.get("DELPHI_NETWORK", "mainnet"))
+    return _client
+
+
+def guard() -> Guard:
+    global _guard
+    if _guard is None:
+        _guard = Guard(Limits.from_env())
+    return _guard
+
+
+def _brief(m) -> dict:
+    return {
+        "address": m.address, "question": m.question, "status": m.status,
+        "outcomes": [{"label": o, "probability": round(p, 4)} for o, p in zip(m.outcomes, m.probabilities)],
+        "trading_closes_at": m.trading_closes_at.isoformat() if m.trading_closes_at else None,
+        "pool_usd": round(m.pool_usd or 0, 2), "type": m.deployment,
+    }
+
+
+def _fail(e: Exception) -> dict:
+    return {"error": str(e)}
+
+
+@server.tool(annotations=READ)
+def list_markets(status: str = "open", query: str = "", limit: int = 20) -> Any:
+    """List Delphi markets with live probabilities. status: open | awaiting_settlement | settled | expired | failed | all.
+    query: optional keywords to search questions, outcomes and rules. Open markets come soonest-closing first."""
+    try:
+        st = None if status == "all" else status
+        ms = client().search(query, status=st, limit=limit) if query.strip() else client().markets(status=st, limit=limit)
+        return [_brief(m) for m in ms]
+    except (DelphiError, ValueError) as e:
+        return _fail(e)
+
+
+@server.tool(annotations=READ)
+def get_market(market: str) -> Any:
+    """Everything about one market: question, outcomes and probabilities, the rules the AI judge will apply,
+    its sources, deadlines, pool size, fee, and whether the rules file matches its on-chain hash."""
+    try:
+        m = client().market(market)
+        d = m.to_dict()
+        d.pop("raw_metadata", None)
+        return d
+    except (DelphiError, ValueError) as e:
+        return _fail(e)
+
+
+@server.tool(annotations=READ)
+def quote_buy(market: str, outcome: str, usd: float) -> Any:
+    """What spending `usd` on `outcome` (label like "Yes" or an index) buys right now: shares, average price,
+    and the probability after the trade. Fees included; nothing is sent."""
+    try:
+        return client().quote_buy(market, outcome, usd=usd).to_dict()
+    except (DelphiError, ValueError) as e:
+        return _fail(e)
+
+
+@server.tool(annotations=READ)
+def quote_sell(market: str, outcome: str, shares: float) -> Any:
+    """What selling `shares` of `outcome` back to the market returns right now. Nothing is sent."""
+    try:
+        return client().quote_sell(market, outcome, shares).to_dict()
+    except (DelphiError, ValueError) as e:
+        return _fail(e)
+
+
+@server.tool(annotations=READ)
+def get_positions(wallet: str = "") -> Any:
+    """Shares a wallet holds across every Delphi market, their current value, and what can be collected
+    (redeem after settlement, liquidate after a failed or expired market). Defaults to the agent's own wallet."""
+    try:
+        return [p.to_dict() for p in client().positions(wallet or None)]
+    except (DelphiError, ValueError) as e:
+        return _fail(e)
+
+
+@server.tool(annotations=READ)
+def wallet_status() -> Any:
+    """The agent's wallet address, USDC and gas balance, and its spending limits and spend so far today."""
+    c = client()
+    out: dict[str, Any] = {"network": c.network.name, "limits": guard().status()}
+    if c.address:
+        try:
+            out.update(c.balance())
+        except Exception as e:  # noqa: BLE001
+            out["balance_error"] = str(e)
+    else:
+        out["wallet"] = None
+        out["note"] = "Read-only: no DELPHI_PRIVATE_KEY set."
+    return out
+
+
+@server.tool(annotations=WRITE)
+def buy(market: str, outcome: str, usd: float) -> Any:
+    """Buy shares of `outcome` with up to `usd` of USDC. Held to the per-trade, daily and slippage limits.
+    Quote first and read the rules; this sends a real transaction."""
+    g = guard()
+    try:
+        g.check(market, usd)
+        t = client().buy(market, outcome, usd=usd, max_slippage=g.limits.max_slippage)
+        g.record(t.usd)
+        return t.to_dict()
+    except (LimitExceeded, DelphiError, ValueError) as e:
+        return _fail(e)
+
+
+@server.tool(annotations=WRITE)
+def sell(market: str, outcome: str, shares: float = 0) -> Any:
+    """Sell `shares` of `outcome` back to the market (0 = everything held). Sends a real transaction."""
+    g = guard()
+    try:
+        if not g.limits.trading_enabled:
+            raise LimitExceeded("trading is off. Set DELPHI_ALLOW_TRADING=true to let this agent trade.")
+        return client().sell(market, outcome, shares or None, max_slippage=g.limits.max_slippage).to_dict()
+    except (LimitExceeded, DelphiError, ValueError) as e:
+        return _fail(e)
+
+
+@server.tool(annotations=WRITE)
+def collect(market: str) -> Any:
+    """Collect what a closed market owes the agent: redeems winnings from a settled market, or liquidates
+    shares in an expired or failed market at their final prices."""
+    g = guard()
+    try:
+        if not g.limits.trading_enabled:
+            raise LimitExceeded("trading is off. Set DELPHI_ALLOW_TRADING=true to let this agent trade.")
+        c = client()
+        m = c.market(market, with_rules=False)
+        if m.status == "settled":
+            return c.redeem(market)
+        if m.status in ("expired", "failed"):
+            return c.liquidate(market)
+        return _fail(DelphiError(f"market is {m.status}; nothing to collect yet"))
+    except (LimitExceeded, DelphiError, ValueError) as e:
+        return _fail(e)
+
+
+def main() -> None:
+    server.run("stdio")
+
+
+if __name__ == "__main__":
+    main()

delphi_kit/models.py

@@ -0,0 +1,118 @@
+"""Plain data objects returned by the client. Money is in USD (the collateral token), shares are decimal numbers."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+STATUSES = ("open", "awaiting_settlement", "settled", "expired", "failed")
+
+
+def ts(seconds: int | None) -> Optional[datetime]:
+    return datetime.fromtimestamp(seconds, tz=timezone.utc) if seconds else None
+
+
+def _jsonable(v: Any) -> Any:
+    if isinstance(v, datetime):
+        return v.isoformat()
+    if isinstance(v, dict):
+        return {k: _jsonable(x) for k, x in v.items()}
+    if isinstance(v, (list, tuple)):
+        return [_jsonable(x) for x in v]
+    return v
+
+
+class _Dict:
+    def to_dict(self) -> dict:
+        return _jsonable(asdict(self))  # type: ignore[arg-type]
+
+
+@dataclass
+class Market(_Dict):
+    address: str
+    deployment: str                    # "lmsr" | "dpm" | "dpm-legacy"
+    mechanism: str                     # "lmsr" | "dpm"
+    status: str                        # one of STATUSES
+    question: Optional[str]
+    outcomes: list[str]
+    probabilities: list[float]         # implied probability per outcome, sums to ~1
+    prices: list[float]                # USD cost of one more share, per outcome (spot)
+    trading_closes_at: Optional[datetime]
+    settlement_deadline: Optional[datetime]
+    earliest_resolve_at: Optional[datetime] = None
+    winning_outcome: Optional[int] = None
+    pool_usd: Optional[float] = None
+    trading_fee: Optional[float] = None
+    rules: Optional[str] = None        # what the AI judge is told to check
+    sources: list[str] = field(default_factory=list)
+    judge_model: Optional[str] = None
+    metadata_uri: Optional[str] = None
+    metadata_verified: Optional[bool] = None   # True when the rules file matches its on-chain hash
+    url: Optional[str] = None
+    gateway: Optional[str] = None
+    raw_metadata: Optional[dict] = field(default=None, repr=False)
+
+    @property
+    def is_open(self) -> bool:
+        return self.status == "open"
+
+    def outcome_index(self, outcome: int | str) -> int:
+        """Accept an index or a label ("Yes", "no", ...)."""
+        if isinstance(outcome, int) or (isinstance(outcome, str) and outcome.isdigit()):
+            i = int(outcome)
+            if not 0 <= i < len(self.outcomes or self.probabilities):
+                raise ValueError(f"outcome {i} out of range for {self.address}")
+            return i
+        labels = [o.lower().strip() for o in self.outcomes]
+        try:
+            return labels.index(str(outcome).lower().strip())
+        except ValueError:
+            raise ValueError(f"{outcome!r} is not an outcome of this market; outcomes are {self.outcomes}") from None
+
+    def summary(self) -> str:
+        odds = ", ".join(f"{o} {p:.0%}" for o, p in zip(self.outcomes, self.probabilities))
+        close = self.trading_closes_at.strftime("%Y-%m-%d %H:%M UTC") if self.trading_closes_at else "?"
+        return f"{self.question}  [{odds}]  {self.status}, trading closes {close}"
+
+
+@dataclass
+class Quote(_Dict):
+    market: str
+    outcome: int
+    outcome_label: Optional[str]
+    side: str                          # "buy" | "sell"
+    shares: float
+    usd: float                         # cost for a buy, proceeds for a sell (fees included)
+    average_price: Optional[float]
+    probability_before: Optional[float]
+    probability_after: Optional[float] = None
+    shares_raw: int = 0
+    usd_raw: int = 0
+
+
+@dataclass
+class Trade(_Dict):
+    market: str
+    outcome: int
+    outcome_label: Optional[str]
+    side: str
+    shares: float
+    usd: float
+    tx_hash: str
+    explorer_url: str
+    approval_tx: Optional[str] = None
+
+
+@dataclass
+class Position(_Dict):
+    market: str
+    question: Optional[str]
+    outcome: int
+    outcome_label: Optional[str]
+    shares: float
+    probability: Optional[float]
+    value_usd: Optional[float]          # shares x current probability (open markets) or payout (settled)
+    status: str
+    action: Optional[str] = None        # "redeem" | "liquidate" | None
+    claimable_usd: Optional[float] = None

delphi_kit/networks.py

@@ -0,0 +1,98 @@
+"""Where Delphi lives on each network.
+
+Delphi has shipped three generations of contracts. Each generation has its own factory (which creates markets)
+and gateway (which every trade, quote and settlement goes through). A market belongs to exactly one generation
+for life, so every call has to be sent to the right gateway. The official TypeScript SDK 2.1.0 knows the two
+pari-mutuel generations; the LMSR generation, which carries live trading on mainnet since September 2026, is
+listed here too.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Deployment:
+    name: str          # short label, e.g. "lmsr"
+    kind: str          # "lmsr" | "dpm" | "dpm_legacy" (selects the ABI)
+    factory: str
+    gateway: str
+    note: str = ""
+
+
+@dataclass(frozen=True)
+class Network:
+    name: str
+    chain_id: int
+    rpc_url: str
+    token: str                      # USDC (or the competition token)
+    token_decimals: int
+    multicall3: str
+    explorer_url: str
+    app_url: str
+    deployments: tuple[Deployment, ...] = field(default_factory=tuple)
+
+
+MULTICALL3 = "0xcA11bde05977b3631167028862bE2a173976CA11"
+
+NETWORKS: dict[str, Network] = {
+    "mainnet": Network(
+        name="mainnet",
+        chain_id=685689,
+        rpc_url="https://gensyn-mainnet.g.alchemy.com/public",
+        token="0x5b32c997211621d55a89Cc5abAF1cC21F3A6ddF5",
+        token_decimals=6,
+        multicall3=MULTICALL3,
+        explorer_url="https://gensyn-mainnet.explorer.alchemy.com",
+        app_url="https://delphi.fyi",
+        deployments=(
+            Deployment("lmsr", "lmsr", "0x1819a2aeEb96DA9BA1C5262A5c82B6F9c347f99c",
+                       "0x7fd914D05D1FE4Fa3EC84E2Cd1D81be6CBe03747",
+                       "LMSR, AI-settled. Live trading since Sep 2026. Not in SDK 2.1.0 defaults."),
+            Deployment("dpm", "dpm", "0x9C73417f79a1361c6aF9Bd828343badEE1b84936",
+                       "0x982a67aE92D8de361957249fB2BB4a62BCc6A8d5",
+                       "Pari-mutuel, AI-settled."),
+            Deployment("dpm-legacy", "dpm_legacy", "0x4596d847eA56DCf9A37944c13793Af802Fc5D1eC",
+                       "0x4e4e85c52E0F414cc67eE88d0C649Ec81698d700",
+                       "Pari-mutuel, creator-settled. First generation."),
+        ),
+    ),
+    "testnet": Network(
+        name="testnet",
+        chain_id=685685,
+        rpc_url="https://gensyn-testnet.g.alchemy.com/public",
+        token="0x0724D6079b986F8e44bDafB8a09B60C0bd6A45a1",
+        token_decimals=6,
+        multicall3=MULTICALL3,
+        explorer_url="https://gensyn-testnet.explorer.alchemy.com",
+        app_url="https://testnet.delphi.fyi",
+        deployments=(
+            Deployment("dpm", "dpm", "0x97d2b3F0614C8189343A38094629FCE2910b727A",
+                       "0x22ea355D7218Dc86b4c83732cBbd01f7Ff2332b3"),
+            Deployment("dpm-legacy", "dpm_legacy", "0xd03CEC55802f0D44D844384E1144B25717315E5A",
+                       "0x7b8FDBD187B0Be5e30e48B1995df574A62667147"),
+        ),
+    ),
+    "competition-testnet": Network(
+        name="competition-testnet",
+        chain_id=685685,
+        rpc_url="https://gensyn-testnet.g.alchemy.com/public",
+        token="0x8A2d75753362Eb5D5669a2c22cbf394b26a0571F",
+        token_decimals=6,
+        multicall3=MULTICALL3,
+        explorer_url="https://gensyn-testnet.explorer.alchemy.com",
+        app_url="https://agent-competition.gensyn.ai",
+        deployments=(
+            Deployment("lmsr", "lmsr", "0xEa9D0a78d0209916e88e363B8FDa3e23206Ff49b",
+                       "0x097599c9D966fF496284b892A8F13BF885b258ef", "Agent competition."),
+        ),
+    ),
+}
+
+
+def get_network(name: str) -> Network:
+    try:
+        return NETWORKS[name]
+    except KeyError:
+        raise ValueError(f"unknown network {name!r}; choose one of {', '.join(NETWORKS)}") from None

delphi_kit/search.py

@@ -0,0 +1,40 @@
+"""Keyword search over markets. Small and dependency-free: word matches in the question count most, then
+outcomes, then the rules; prefixes count ("elect" finds "election"); ties go to the market that closes first."""
+
+from __future__ import annotations
+
+import math
+import re
+
+from .models import Market
+
+_WORD = re.compile(r"[a-z0-9$%.]+")
+_STOP = {"the", "a", "an", "of", "in", "on", "by", "to", "will", "be", "is", "for", "and", "or", "at", "before", "after"}
+
+
+def _words(text: str | None) -> list[str]:
+    return [w.strip(".") for w in _WORD.findall((text or "").lower()) if w.strip(".") and w not in _STOP]
+
+
+def score(m: Market, terms: list[str]) -> float:
+    fields = ((_words(m.question), 3.0), (_words(" ".join(m.outcomes)), 2.0), (_words(m.rules), 1.0))
+    total = 0.0
+    for t in terms:
+        best = 0.0
+        for words, weight in fields:
+            if t in words:
+                best = max(best, weight)
+            elif any(w.startswith(t) for w in words) and len(t) >= 3:
+                best = max(best, weight * 0.6)
+        total += best
+    return total
+
+
+def rank(markets: list[Market], query: str) -> list[Market]:
+    terms = _words(query)
+    if not terms:
+        return markets
+    scored = [(score(m, terms), m) for m in markets]
+    scored = [(s, m) for s, m in scored if s > 0]
+    scored.sort(key=lambda x: (-x[0], x[1].trading_closes_at.timestamp() if x[1].trading_closes_at else math.inf))
+    return [m for _, m in scored]