langbot-sdk 0.1.0__py3-none-any.whl

langbot/__init__.py

@@ -0,0 +1,147 @@
+"""Langbot SDK: data and simulation for every market on Kalshi and Polymarket.
+
+Quick start (one strategy protocol for ``langbot run``, ``langbot backtest`` and
+``langbot sim run``)::
+
+    class Mention:
+        markets = ["KXEARNINGSMENTIONNVDA-*"]
+        phrases = ["blackwell"]
+
+        def on_event(self, evt, ctx):
+            if evt["type"] == "phrase_detected":
+                for ticker in evt["market_refs"]:
+                    book = ctx.book(ticker)
+                    if book and book.yes_ask and book.yes_ask < 0.60:
+                        ctx.buy(ticker, "yes", 10, limit=book.yes_ask, tif="ioc")
+
+Run it with ``langbot run strategy.py --mode demo``.
+"""
+
+from . import receipts
+from .backtest import Backtester, BacktestResult, backtest_events, backtest_file, load_jsonl
+from .client import (
+    Langbot,
+    LangbotAPIError,
+    LangbotApiError,
+    LangbotClient,
+    LangbotError,
+    StreamRefused,
+)
+from .kalshi import KalshiAuth, KalshiClient, KalshiError, KalshiRateLimiter, TokenBucket
+from .notify import (
+    DiscordNotifier,
+    MultiNotifier,
+    NullNotifier,
+    SlackNotifier,
+    TelegramNotifier,
+    notifier_from_env,
+)
+from .schemas import (
+    BaseRateMonth,
+    BaseRates,
+    Book,
+    CalendarEntry,
+    Candle,
+    CandlesPage,
+    Event,
+    EventType,
+    Fact,
+    FactKind,
+    Fill,
+    LiveEvent,
+    Market,
+    MarketBrief,
+    MarketContext,
+    MarketOutcome,
+    Mention,
+    Order,
+    OutcomesPage,
+    SourceKind,
+    Speaker,
+    SpeakerProfile,
+    Subscription,
+    TextPosted,
+    Transcript,
+    TranscriptWord,
+    Verdict,
+    new_event_id,
+    new_id,
+    now_ms,
+)
+from .strategy import (
+    KalshiBroker,
+    LiveModeRefused,
+    PaperBroker,
+    Position,
+    RiskRails,
+    RiskViolation,
+    Strategy,
+)
+from .x402 import PaymentRequired
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BacktestResult",
+    "Backtester",
+    "BaseRateMonth",
+    "BaseRates",
+    "Book",
+    "CalendarEntry",
+    "DiscordNotifier",
+    "Event",
+    "EventType",
+    "Fact",
+    "FactKind",
+    "Fill",
+    "KalshiAuth",
+    "KalshiBroker",
+    "KalshiClient",
+    "KalshiError",
+    "KalshiRateLimiter",
+    "Langbot",
+    "LangbotAPIError",
+    "LangbotApiError",
+    "LangbotClient",
+    "LangbotError",
+    "PaymentRequired",
+    "LiveEvent",
+    "LiveModeRefused",
+    "Market",
+    "MarketBrief",
+    "MarketContext",
+    "MarketOutcome",
+    "Mention",
+    "MultiNotifier",
+    "NullNotifier",
+    "Order",
+    "OutcomesPage",
+    "Candle",
+    "CandlesPage",
+    "PaperBroker",
+    "Position",
+    "RiskRails",
+    "RiskViolation",
+    "SlackNotifier",
+    "SourceKind",
+    "Speaker",
+    "SpeakerProfile",
+    "Strategy",
+    "StreamRefused",
+    "Subscription",
+    "TextPosted",
+    "TelegramNotifier",
+    "TokenBucket",
+    "Transcript",
+    "TranscriptWord",
+    "Verdict",
+    "__version__",
+    "backtest_events",
+    "backtest_file",
+    "load_jsonl",
+    "new_event_id",
+    "new_id",
+    "notifier_from_env",
+    "now_ms",
+    "receipts",
+]

langbot/adapter.py

@@ -0,0 +1,310 @@
+"""One strategy protocol for `langbot sim run`, `langbot run` and `langbot backtest`.
+
+A strategy is any object with a synchronous ``on_event(evt, ctx)`` (``evt`` is the wire dict, as
+the stream sends it) and, optionally, ``on_book(ticker, book, ctx)``, ``on_fill(fill, ctx)``,
+``on_start(ctx)`` and ``on_end(ctx)``: the sim's protocol (:mod:`langbot.sim`). ``ctx`` is the
+same surface everywhere: ``now``, ``tickers``, ``book(ticker)``, ``position(ticker)``,
+``orders(ticker)``, ``buy(ticker, side, qty, limit=None, tif=None)``, ``sell(...)``,
+``cancel_all(ticker)``.
+
+:func:`adapt` wraps such an object as a :class:`langbot.strategy.Strategy` so the live runner and
+the backtester drive it unchanged: orders a hook places are sent, through the risk rails, as soon
+as the hook returns. The older async ``Strategy`` subclass protocol keeps working, with a
+deprecation warning (:func:`warn_legacy`).
+
+Mapping onto the YES book the brokers trade: buying No at ``p`` is offering Yes at ``1 - p``;
+selling No is bidding Yes at ``1 - p``. A market order (``limit=None``) is immediate-or-cancel at
+the top of the book; a limit order rests unless ``tif="ioc"``.
+"""
+
+from __future__ import annotations
+
+import logging
+import warnings
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from .schemas import Book, Event, Fill, new_id, now_ms
+from .sim.engine import BookState
+from .sim.engine import Position as SimPosition
+from .strategy import Strategy
+
+log = logging.getLogger("langbot.adapter")
+
+LEGACY_MESSAGE = (
+    "{name}: the async Strategy subclass protocol is deprecated and will be removed in a later "
+    "release; write the sim protocol instead: a class with a synchronous on_event(evt, ctx) "
+    "(and optional on_book(ticker, book, ctx)), which `langbot run`, `langbot backtest` and "
+    "`langbot sim run` all drive. See docs/strategies.md."
+)
+
+
+def warn_legacy(cls: type) -> None:
+    """Warn once per class that it uses the old async ``Strategy`` protocol."""
+    if getattr(cls, "_langbot_legacy_warned", False):
+        return
+    cls._langbot_legacy_warned = True  # type: ignore[attr-defined]
+    msg = LEGACY_MESSAGE.format(name=cls.__name__)
+    warnings.warn(msg, DeprecationWarning, stacklevel=3)
+    log.warning(msg)
+
+
+@dataclass
+class PendingOrder:
+    """What ``ctx.buy`` / ``ctx.sell`` return live: the order is sent when the hook returns."""
+
+    ticker: str
+    side: str  # "yes" | "no"
+    action: str  # "buy" | "sell"
+    qty: float
+    limit: float | None
+    tif: str | None
+    id: str = field(default_factory=lambda: new_id("ord"))
+    status: str = "pending"
+    order_id: str | None = None  # the broker's id once sent
+
+    @property
+    def open(self) -> bool:
+        return self.status in ("pending", "resting")
+
+
+class LiveContext:
+    """The sim's ``ctx`` over a live (or paper) broker."""
+
+    def __init__(self, host: SimStrategyAdapter) -> None:
+        self._host = host
+        self.queue: list[PendingOrder] = []
+        self.event_id: str | None = None
+        self._now: int | None = None
+        self.latency_ms = 0
+
+    @property
+    def now(self) -> int:
+        return self._now if self._now is not None else now_ms()
+
+    @property
+    def tickers(self) -> list[str]:
+        return sorted(self._host.known_tickers)
+
+    def market(self, ticker: str) -> dict[str, Any] | None:
+        return {"ticker": ticker, "title": None} if ticker in self._host.known_tickers else None
+
+    @property
+    def cash(self) -> float | None:
+        """Unknown live (the venue holds it); ``None``."""
+        return None
+
+    def book(self, ticker: str) -> BookState | None:
+        b = self._host.books.get(ticker)
+        return None if b is None else BookState.from_row(b.model_dump())
+
+    def position(self, ticker: str) -> SimPosition:
+        count = self._host.position(ticker).count
+        return SimPosition(ticker, yes=float(max(count, 0)), no=float(max(-count, 0)))
+
+    def orders(self, ticker: str | None = None) -> list[PendingOrder]:
+        return [o for o in self._host.sent if o.open and (ticker is None or o.ticker == ticker)]
+
+    def buy(
+        self,
+        ticker: str,
+        side: str = "yes",
+        qty: float = 1,
+        limit: float | None = None,
+        tif: str | None = None,
+    ) -> PendingOrder:
+        o = PendingOrder(ticker, side, "buy", qty, limit, tif)
+        self.queue.append(o)
+        return o
+
+    def sell(
+        self,
+        ticker: str,
+        side: str = "yes",
+        qty: float = 1,
+        limit: float | None = None,
+        tif: str | None = None,
+    ) -> PendingOrder:
+        o = PendingOrder(ticker, side, "sell", qty, limit, tif)
+        self.queue.append(o)
+        return o
+
+    def cancel(self, order_id: str) -> bool:
+        before = len(self.queue)
+        self.queue = [o for o in self.queue if o.id != order_id]
+        return len(self.queue) < before
+
+    def cancel_all(self, ticker: str | None = None) -> int:
+        self._host.cancel_requests.append(ticker)
+        return len(self.orders(ticker))
+
+
+class SimStrategyAdapter(Strategy):
+    """A sim-protocol strategy object driven as a :class:`Strategy` (see :func:`adapt`)."""
+
+    factory: Callable[[], Any] = staticmethod(lambda: None)  # type: ignore[assignment]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.inner: Any = type(self).factory()
+        self.name = getattr(self.inner, "name", None) or type(self.inner).__name__
+        self.markets = list(getattr(self.inner, "markets", None) or [])
+        self.phrases = list(getattr(self.inner, "phrases", None) or [])
+        self.known_tickers: set[str] = set()
+        self.sent: list[PendingOrder] = []
+        self.cancel_requests: list[str | None] = []
+        self.ctx = LiveContext(self)
+
+    def __getattr__(self, name: str) -> Any:
+        # Only called for attributes the adapter does not have: read them off the strategy.
+        if name.startswith("__") or name == "inner" or "inner" not in self.__dict__:
+            raise AttributeError(name)
+        return getattr(self.__dict__["inner"], name)
+
+    # -------------------------------------------------------------- hooks → sim protocol
+
+    async def on_start(self) -> None:
+        await self._call("on_start", self.ctx)
+
+    async def on_stop(self) -> None:
+        await self._call("on_end", self.ctx)
+
+    async def on_event(self, evt: Event) -> None:
+        wire = evt.to_wire()
+        self.ctx._now = evt.t_emitted or evt.t_spoken
+        self.ctx.event_id = evt.event_id
+        self.known_tickers |= {t for t in evt.market_refs if self.matches_market(t)}
+        await self._call("on_event", wire, self.ctx)
+
+    async def on_book(self, book: Book) -> None:
+        if self.matches_market(book.ticker):
+            self.known_tickers.add(book.ticker)
+        if getattr(self.inner, "on_book", None) is None:
+            return
+        self.ctx._now = book.ts
+        await self._call("on_book", book.ticker, BookState.from_row(book.model_dump()), self.ctx)
+
+    async def on_fill(self, fill: Fill) -> None:
+        for o in self.sent:
+            if o.order_id == fill.order_id and o.status == "resting":
+                o.status = "filled"
+                break
+        await self._call("on_fill", fill.model_dump(), self.ctx)
+
+    # ------------------------------------------------------------------ order flushing
+
+    async def _call(self, hook: str, *args: Any) -> None:
+        fn = getattr(self.inner, hook, None)
+        if fn is None:
+            return
+        fn(*args)
+        await self._flush()
+
+    async def _flush(self) -> None:
+        while self.cancel_requests:
+            await self.cancel_all(self.cancel_requests.pop(0))
+            for o in self.sent:
+                o.status = "canceled" if o.open else o.status
+        queue, self.ctx.queue = self.ctx.queue, []
+        for o in queue:
+            await self._send(o)
+
+    async def _send(self, o: PendingOrder) -> None:
+        book = self.books.get(o.ticker)
+        # (YES-book side, YES price) for each intent
+        yes_buy = (o.action == "buy") == (o.side == "yes")
+        if o.limit is not None:
+            price = o.limit if o.side == "yes" else round(1.0 - o.limit, 4)
+        elif book is not None:
+            price = book.yes_ask if yes_buy else book.yes_bid
+        else:
+            price = None
+        if price is None:
+            o.status = "rejected"
+            self.log(f"no price for {o.action} {o.side} {o.ticker}: no limit and no book")
+            return
+        tif = "immediate_or_cancel" if (o.limit is None or o.tif == "ioc") else "good_till_canceled"
+        count = int(round(o.qty))
+        order = await (self.buy_yes if yes_buy else self.sell_yes)(
+            o.ticker, price, count, time_in_force=tif
+        )
+        o.order_id = getattr(order, "order_id", None)
+        status = str(getattr(order, "status", "")).lower()
+        o.status = "resting" if status == "resting" else "done"
+        self.sent.append(o)
+
+
+def _class_constants(cls: type) -> dict[str, Any]:
+    """The public, non-callable class attributes of ``cls`` and its bases (``markets``,
+    ``phrases``, thresholds ...), so the adapted class reads like the strategy it wraps."""
+    out: dict[str, Any] = {}
+    for klass in reversed(cls.__mro__[:-1]):  # skip object
+        for k, v in vars(klass).items():
+            if (
+                k.startswith("_")
+                or callable(v)
+                or isinstance(v, (property, staticmethod, classmethod))
+            ):
+                continue
+            if k in _ADAPTER_OWN:
+                continue
+            out[k] = _FromInner(k, v)
+    return out
+
+
+class _FromInner:
+    """A class constant of the wrapped strategy: the class value on the adapted class, the
+    wrapped instance's current value on an adapter instance."""
+
+    def __init__(self, key: str, default: Any) -> None:
+        self.key, self.default = key, default
+
+    def __get__(self, obj: Any, owner: type | None = None) -> Any:
+        if obj is None or "inner" not in obj.__dict__:
+            return self.default
+        return getattr(obj.__dict__["inner"], self.key, self.default)
+
+
+def adapt(factory: Callable[[], Any], name: str | None = None) -> type[Strategy]:
+    """A :class:`Strategy` subclass that builds the sim-protocol strategy from ``factory`` and
+    drives it (the live runner and the backtester instantiate it with no arguments).
+
+    When ``factory`` is the strategy class itself, the adapted class takes its name and its
+    class constants (``markets``, ``phrases``, ``max_price`` ...); instances read any other
+    attribute (``ended``, a ``price_ceiling`` property) from the wrapped strategy."""
+    import inspect
+
+    attrs: dict[str, Any] = {"factory": staticmethod(factory), "__module__": __name__}
+    if inspect.isclass(factory):
+        cls_name = factory.__name__
+        attrs.update(_class_constants(factory))
+        attrs["__doc__"] = factory.__doc__
+    else:
+        cls_name = f"{name or getattr(factory, '__name__', None) or 'SimStrategy'}Live"
+    return type(cls_name, (SimStrategyAdapter,), attrs)
+
+
+_ADAPTER_OWN = frozenset(
+    {"factory", "name", "inner", "ctx", "known_tickers", "sent", "cancel_requests"}
+)
+
+
+def is_sim_protocol(obj: Any) -> bool:
+    """True for a class or object whose ``on_event`` is synchronous (the sim protocol)."""
+    import inspect
+
+    if inspect.isclass(obj) and issubclass(obj, Strategy):
+        return False
+    fn = getattr(obj, "on_event", None)
+    return fn is not None and not inspect.iscoroutinefunction(fn)
+
+
+__all__ = [
+    "LiveContext",
+    "PendingOrder",
+    "SimStrategyAdapter",
+    "adapt",
+    "is_sim_protocol",
+    "warn_legacy",
+]