analysis-poly 0.1.0__py3-none-any.whl

analysis_poly/profit_engine.py

@@ -0,0 +1,417 @@
+from __future__ import annotations
+
+from collections import defaultdict, deque
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from .models import (
+    ActivityRecord,
+    MarketReport,
+    PolymarketMarket,
+    TokenReport,
+    WarningItem,
+)
+from .models import TradeRecord
+
+
+@dataclass
+class PnlDelta:
+    timestamp: int
+    market_slug: str
+    token_id: str
+    delta_pnl_usdc: float
+
+
+@dataclass
+class _Lot:
+    qty: float
+    cost_per_qty: float
+
+
+@dataclass
+class _TokenState:
+    token_id: str
+    outcome: str
+    lots: deque[_Lot]
+    realized_pnl_usdc: float = 0.0
+    taker_fee_usdc: float = 0.0
+    maker_reward_usdc: float = 0.0
+    buy_qty: float = 0.0
+    sell_qty: float = 0.0
+    split_qty: float = 0.0
+    redeem_qty: float = 0.0
+    trade_count: int = 0
+
+    @property
+    def position_qty(self) -> float:
+        return sum(lot.qty for lot in self.lots)
+
+
+@dataclass
+class _Event:
+    timestamp: int
+    tx: str
+    kind: str
+    token_id: str | None = None
+    side: str | None = None
+    size: float = 0.0
+    price: float = 0.0
+    usdc_size: float = 0.0
+    is_taker: bool = False
+
+
+class ProfitEngine:
+    def __init__(
+        self,
+        fee_rate_bps: float,
+        maker_reward_ratio: float,
+        missing_cost_warn_qty: float,
+        charge_taker_fee: bool = True,
+    ):
+        self._fee_rate_bps = fee_rate_bps
+        self._maker_reward_ratio = maker_reward_ratio
+        self._missing_cost_warn_qty = missing_cost_warn_qty
+        self._charge_taker_fee = charge_taker_fee
+
+    def process_market(
+        self,
+        market: PolymarketMarket,
+        taker_trades: list[TradeRecord],
+        all_trades: list[TradeRecord],
+        split_activities: list[ActivityRecord],
+        redeem_activities: list[ActivityRecord],
+    ) -> tuple[MarketReport, list[PnlDelta], list[WarningItem]]:
+        warnings: list[WarningItem] = []
+        token_states: dict[str, _TokenState] = {
+            market.up_token_id: _TokenState(token_id=market.up_token_id, outcome="Up", lots=deque()),
+            market.down_token_id: _TokenState(token_id=market.down_token_id, outcome="Down", lots=deque()),
+        }
+
+        taker_keys = {_trade_key(t) for t in taker_trades}
+        events: list[_Event] = []
+        maker_reward_enabled = _is_maker_reward_enabled_for_market(market.slug)
+        has_maker_trade = False
+
+        for trade in all_trades:
+            is_taker = _trade_key(trade) in taker_keys
+            if not is_taker:
+                has_maker_trade = True
+            events.append(
+                _Event(
+                    timestamp=trade.timestamp,
+                    tx=trade.transaction_hash,
+                    kind="TRADE",
+                    token_id=trade.asset,
+                    side=trade.side,
+                    size=float(trade.size),
+                    price=float(trade.price),
+                    is_taker=is_taker,
+                )
+            )
+
+        for split in split_activities:
+            events.append(
+                _Event(
+                    timestamp=split.timestamp,
+                    tx=split.transaction_hash,
+                    kind="SPLIT",
+                    size=float(split.size),
+                    usdc_size=float(split.usdc_size),
+                )
+            )
+
+        for redeem in redeem_activities:
+            winner_token = _resolve_winner_token(market)
+            if not winner_token:
+                warnings.append(
+                    WarningItem(
+                        timestamp=redeem.timestamp,
+                        market_slug=market.slug,
+                        code="REDEEM_SKIP_UNKNOWN_WINNER",
+                        message="skip redeem because winner outcome cannot be uniquely inferred",
+                    )
+                )
+                continue
+
+            events.append(
+                _Event(
+                    timestamp=redeem.timestamp,
+                    tx=redeem.transaction_hash,
+                    kind="REDEEM",
+                    token_id=winner_token,
+                    size=float(redeem.size),
+                    usdc_size=float(redeem.usdc_size),
+                )
+            )
+
+        events.sort(key=lambda e: (e.timestamp, e.tx, _event_priority(e.kind)))
+
+        pnl_deltas: list[PnlDelta] = []
+        for event in events:
+            if event.kind == "TRADE" and event.token_id in token_states:
+                token_state = token_states[event.token_id]
+                token_state.trade_count += 1
+                delta, new_warnings = self._apply_trade(
+                    market_slug=market.slug,
+                    token_state=token_state,
+                    event=event,
+                    maker_reward_enabled=maker_reward_enabled,
+                )
+                pnl_deltas.extend(delta)
+                warnings.extend(new_warnings)
+            elif event.kind == "SPLIT":
+                up_state = token_states[market.up_token_id]
+                down_state = token_states[market.down_token_id]
+
+                qty_each = event.size / 2.0
+                usdc_each = event.usdc_size / 2.0
+                if qty_each > 0:
+                    up_state.lots.append(_Lot(qty=qty_each, cost_per_qty=usdc_each / qty_each))
+                    down_state.lots.append(_Lot(qty=qty_each, cost_per_qty=usdc_each / qty_each))
+                up_state.split_qty += qty_each
+                down_state.split_qty += qty_each
+            elif event.kind == "REDEEM" and event.token_id in token_states:
+                token_state = token_states[event.token_id]
+                delta, new_warnings = self._close_position(
+                    market_slug=market.slug,
+                    token_state=token_state,
+                    timestamp=event.timestamp,
+                    quantity=event.size,
+                    proceeds=event.usdc_size,
+                    missing_cost_warn_code="REDEEM_OVERSELL_ZERO_COST",
+                )
+                token_state.redeem_qty += event.size
+                pnl_deltas.extend(delta)
+                warnings.extend(new_warnings)
+
+        if not maker_reward_enabled and has_maker_trade:
+            warnings.append(
+                WarningItem(
+                    market_slug=market.slug,
+                    code="MAKER_REWARD_DEFERRED_TODAY",
+                    message=(
+                        "maker reward for markets on/after current UTC day 00:00 is excluded "
+                        "because Polymarket settles maker rewards once per day"
+                    ),
+                )
+            )
+
+        token_reports: list[TokenReport] = []
+        for token_state in token_states.values():
+            token_reports.append(
+                TokenReport(
+                    token_id=token_state.token_id,
+                    outcome=token_state.outcome,
+                    realized_pnl_usdc=round(token_state.realized_pnl_usdc, 10),
+                    taker_fee_usdc=round(token_state.taker_fee_usdc, 10),
+                    maker_reward_usdc=round(token_state.maker_reward_usdc, 10),
+                    buy_qty=round(token_state.buy_qty, 10),
+                    sell_qty=round(token_state.sell_qty, 10),
+                    split_qty=round(token_state.split_qty, 10),
+                    redeem_qty=round(token_state.redeem_qty, 10),
+                    ending_position_qty=round(token_state.position_qty, 10),
+                    trade_count=token_state.trade_count,
+                )
+            )
+
+        market_report = MarketReport(
+            market_slug=market.slug,
+            condition_id=market.condition_id,
+            up_token_id=market.up_token_id,
+            down_token_id=market.down_token_id,
+            realized_pnl_usdc=round(sum(t.realized_pnl_usdc for t in token_reports), 10),
+            taker_fee_usdc=round(sum(t.taker_fee_usdc for t in token_reports), 10),
+            maker_reward_usdc=round(sum(t.maker_reward_usdc for t in token_reports), 10),
+            ending_position_up=round(token_states[market.up_token_id].position_qty, 10),
+            ending_position_down=round(token_states[market.down_token_id].position_qty, 10),
+            tokens=sorted(token_reports, key=lambda x: x.token_id),
+        )
+
+        return market_report, pnl_deltas, warnings
+
+    def _apply_trade(
+        self,
+        market_slug: str,
+        token_state: _TokenState,
+        event: _Event,
+        maker_reward_enabled: bool,
+    ) -> tuple[list[PnlDelta], list[WarningItem]]:
+        deltas: list[PnlDelta] = []
+        warnings: list[WarningItem] = []
+
+        adjusted_size, _, fee_usdc = _fee_adjust(event.size, event.price, self._fee_rate_bps)
+
+        if event.side == "BUY":
+            qty_add = event.size
+            if event.is_taker and self._charge_taker_fee:
+                qty_add = adjusted_size
+            total_cost = event.size * event.price
+            if qty_add > 0:
+                token_state.lots.append(_Lot(qty=qty_add, cost_per_qty=total_cost / qty_add))
+            token_state.buy_qty += qty_add
+            if event.is_taker and self._charge_taker_fee:
+                token_state.taker_fee_usdc += fee_usdc
+        elif event.side == "SELL":
+            token_state.sell_qty += event.size
+            proceeds = event.size * event.price
+            if event.is_taker and self._charge_taker_fee:
+                proceeds = adjusted_size * event.price
+            close_deltas, close_warnings = self._close_position(
+                market_slug=market_slug,
+                token_state=token_state,
+                timestamp=event.timestamp,
+                quantity=event.size,
+                proceeds=proceeds,
+                missing_cost_warn_code="SELL_OVERSELL_ZERO_COST",
+            )
+            deltas.extend(close_deltas)
+            warnings.extend(close_warnings)
+            if event.is_taker and self._charge_taker_fee:
+                token_state.taker_fee_usdc += fee_usdc
+
+        if not event.is_taker and maker_reward_enabled:
+            maker_reward = fee_usdc * self._maker_reward_ratio
+            token_state.realized_pnl_usdc += maker_reward
+            token_state.maker_reward_usdc += maker_reward
+            deltas.append(
+                PnlDelta(
+                    timestamp=event.timestamp,
+                    market_slug=market_slug,
+                    token_id=token_state.token_id,
+                    delta_pnl_usdc=maker_reward,
+                )
+            )
+
+        return deltas, warnings
+
+    def _close_position(
+        self,
+        market_slug: str,
+        token_state: _TokenState,
+        timestamp: int,
+        quantity: float,
+        proceeds: float,
+        missing_cost_warn_code: str,
+    ) -> tuple[list[PnlDelta], list[WarningItem]]:
+        warnings: list[WarningItem] = []
+        quantity = max(0.0, quantity)
+        if quantity == 0:
+            return [], warnings
+
+        remaining = quantity
+        realized_cost = 0.0
+        while remaining > 1e-12 and token_state.lots:
+            lot = token_state.lots[0]
+            take = min(lot.qty, remaining)
+            realized_cost += take * lot.cost_per_qty
+            lot.qty -= take
+            remaining -= take
+            if lot.qty <= 1e-12:
+                token_state.lots.popleft()
+
+        if remaining > self._missing_cost_warn_qty:
+            warnings.append(
+                WarningItem(
+                    timestamp=timestamp,
+                    market_slug=market_slug,
+                    token_id=token_state.token_id,
+                    code=missing_cost_warn_code,
+                    message=(
+                        "position shortfall consumed at zero cost basis, "
+                        f"missing_qty={remaining:.6f}"
+                    ),
+                )
+            )
+
+        realized = proceeds - realized_cost
+        token_state.realized_pnl_usdc += realized
+
+        return [
+            PnlDelta(
+                timestamp=timestamp,
+                market_slug=market_slug,
+                token_id=token_state.token_id,
+                delta_pnl_usdc=realized,
+            )
+        ], warnings
+
+
+
+def _fee_adjust(size: float, price: float, fee_rate_bps: float) -> tuple[float, float, float]:
+    fee_multiplier = fee_rate_bps / 1000 if fee_rate_bps else 0.0
+    fee = 0.25 * (price * (1 - price)) ** 2 * fee_multiplier
+    adjusted_size = (1 - fee) * size
+    fee_token = size - adjusted_size
+    fee_usdc = fee_token * price
+    return adjusted_size, fee_token, fee_usdc
+
+
+
+def _event_priority(kind: str) -> int:
+    if kind == "SPLIT":
+        return 0
+    if kind == "TRADE":
+        return 1
+    if kind == "REDEEM":
+        return 2
+    return 9
+
+
+
+def _trade_key(trade: TradeRecord) -> tuple[str, str, str, float, float, int]:
+    return (
+        trade.transaction_hash,
+        trade.asset,
+        trade.side,
+        float(trade.price),
+        float(trade.size),
+        int(trade.timestamp),
+    )
+
+
+
+def _resolve_winner_token(market: PolymarketMarket) -> str | None:
+    if len(market.outcome_prices) < 2:
+        return None
+    up_price = market.outcome_prices[0]
+    down_price = market.outcome_prices[1]
+    if up_price == 1 and down_price == 0:
+        return market.up_token_id
+    if up_price == 0 and down_price == 1:
+        return market.down_token_id
+    return None
+
+
+def _market_ts_from_slug(market_slug: str) -> int | None:
+    try:
+        return int(str(market_slug).rsplit("-", 1)[-1])
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _utc_day_start_ts(now: datetime | None = None) -> int:
+    dt = now or datetime.now(timezone.utc)
+    start = datetime(dt.year, dt.month, dt.day, tzinfo=timezone.utc)
+    return int(start.timestamp())
+
+
+def _is_maker_reward_enabled_for_market(market_slug: str) -> bool:
+    market_ts = _market_ts_from_slug(market_slug)
+    if market_ts is None:
+        return True
+    return market_ts < _utc_day_start_ts()
+
+
+
+def build_curve(deltas: list[PnlDelta]) -> list[tuple[int, float, float]]:
+    by_ts: dict[int, float] = defaultdict(float)
+    for delta in deltas:
+        by_ts[delta.timestamp] += delta.delta_pnl_usdc
+
+    cumulative = 0.0
+    points: list[tuple[int, float, float]] = []
+    for ts in sorted(by_ts.keys()):
+        delta = by_ts[ts]
+        cumulative += delta
+        points.append((ts, delta, cumulative))
+    return points

analysis_poly/run_manager.py

@@ -0,0 +1,289 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from fastapi import HTTPException
+from loguru import logger
+
+from .analyzer import AnalyzerHooks, PolymarketProfitAnalyzer
+from .models import (
+    AnalysisReport,
+    AnalysisRequest,
+    RunCreated,
+    RunState,
+    RunStatus,
+    RunStopAck,
+    WarningItem,
+    utc_now,
+)
+
+
+@dataclass
+class RunContext:
+    state: RunState
+    stop_event: asyncio.Event = field(default_factory=asyncio.Event)
+    queue: asyncio.Queue[str] = field(default_factory=asyncio.Queue)
+    result: AnalysisReport | None = None
+    task: asyncio.Task | None = None
+
+
+class RunHooks(AnalyzerHooks):
+    def __init__(self, manager: "RunManager", run_id: str):
+        self._manager = manager
+        self._run_id = run_id
+
+    async def on_run_started(self, total_markets: int) -> None:
+        ctx = self._manager._runs[self._run_id]
+        ctx.state.progress_total = total_markets
+        await self._manager._emit(
+            self._run_id,
+            "run_started",
+            {"run_id": self._run_id, "progress_total": total_markets},
+        )
+
+    async def on_progress(self, current: int, total: int, market_slug: str) -> None:
+        ctx = self._manager._runs[self._run_id]
+        ctx.state.progress_current = current
+        ctx.state.progress_total = total
+        ctx.state.message = market_slug
+        await self._manager._emit(
+            self._run_id,
+            "progress",
+            {
+                "current": current,
+                "total": total,
+                "market_slug": market_slug,
+            },
+        )
+
+    async def on_warning(self, warning: WarningItem) -> None:
+        logger.warning(
+            "warning run_id={} code={} market={} token={} msg={}",
+            self._run_id,
+            warning.code,
+            warning.market_slug or "-",
+            warning.token_id or "-",
+            warning.message,
+        )
+        await self._manager._emit(self._run_id, "warning", warning.model_dump())
+
+    async def on_total_point(self, timestamp: int, delta: float, cumulative: float) -> None:
+        await self._manager._emit(
+            self._run_id,
+            "point_total",
+            {
+                "timestamp": timestamp,
+                "delta_realized_pnl_usdc": delta,
+                "cumulative_realized_pnl_usdc": cumulative,
+            },
+        )
+
+    async def on_market_point(
+        self, market_slug: str, timestamp: int, delta: float, cumulative: float
+    ) -> None:
+        await self._manager._emit(
+            self._run_id,
+            "point_market",
+            {
+                "market_slug": market_slug,
+                "timestamp": timestamp,
+                "delta_realized_pnl_usdc": delta,
+                "cumulative_realized_pnl_usdc": cumulative,
+            },
+        )
+
+    async def on_total_point_no_fee(self, timestamp: int, delta: float, cumulative: float) -> None:
+        await self._manager._emit(
+            self._run_id,
+            "point_total_no_fee",
+            {
+                "timestamp": timestamp,
+                "delta_realized_pnl_usdc": delta,
+                "cumulative_realized_pnl_usdc": cumulative,
+            },
+        )
+
+    async def on_market_point_no_fee(
+        self, market_slug: str, timestamp: int, delta: float, cumulative: float
+    ) -> None:
+        await self._manager._emit(
+            self._run_id,
+            "point_market_no_fee",
+            {
+                "market_slug": market_slug,
+                "timestamp": timestamp,
+                "delta_realized_pnl_usdc": delta,
+                "cumulative_realized_pnl_usdc": cumulative,
+            },
+        )
+
+
+class RunManager:
+    def __init__(self):
+        self._lock = asyncio.Lock()
+        self._runs: dict[str, RunContext] = {}
+        self._active_run_id: str | None = None
+        self._analyzer = PolymarketProfitAnalyzer()
+
+    async def create_run(self, req: AnalysisRequest) -> RunCreated:
+        async with self._lock:
+            if self._active_run_id:
+                active = self._runs.get(self._active_run_id)
+                if active and active.state.status in {
+                    RunStatus.PENDING,
+                    RunStatus.RUNNING,
+                    RunStatus.STOPPING,
+                }:
+                    raise HTTPException(status_code=409, detail="another run is in progress")
+
+            run_id = uuid.uuid4().hex
+            state = RunState(run_id=run_id, status=RunStatus.PENDING)
+            ctx = RunContext(state=state)
+            self._runs[run_id] = ctx
+            self._active_run_id = run_id
+
+            ctx.task = asyncio.create_task(self._execute_run(run_id, req))
+            logger.info(
+                "create run run_id={} address={} range=[{}, {}] symbols={} intervals={}",
+                run_id,
+                req.address,
+                req.start_ts,
+                req.end_ts,
+                ",".join(req.symbols),
+                ",".join(str(v) for v in req.intervals),
+            )
+            return RunCreated(run_id=run_id, status=state.status)
+
+    async def stop_run(self, run_id: str) -> RunStopAck:
+        ctx = self._runs.get(run_id)
+        if not ctx:
+            raise HTTPException(status_code=404, detail="run not found")
+
+        if ctx.state.status in {RunStatus.COMPLETED, RunStatus.STOPPED, RunStatus.FAILED}:
+            return RunStopAck(run_id=run_id, status=ctx.state.status)
+
+        ctx.stop_event.set()
+        ctx.state.status = RunStatus.STOPPING
+        logger.warning("stop requested run_id={}", run_id)
+        await self._emit(run_id, "progress", {"message": "stopping requested"})
+        return RunStopAck(run_id=run_id, status=ctx.state.status)
+
+    async def get_result(self, run_id: str) -> AnalysisReport:
+        ctx = self._runs.get(run_id)
+        if not ctx:
+            raise HTTPException(status_code=404, detail="run not found")
+
+        if not ctx.result:
+            raise HTTPException(status_code=202, detail="run not finished")
+        return ctx.result
+
+    async def get_state(self, run_id: str) -> RunState:
+        ctx = self._runs.get(run_id)
+        if not ctx:
+            raise HTTPException(status_code=404, detail="run not found")
+        return ctx.state
+
+    async def stream(self, run_id: str):
+        ctx = self._runs.get(run_id)
+        if not ctx:
+            raise HTTPException(status_code=404, detail="run not found")
+
+        while True:
+            if ctx.task and ctx.task.done() and ctx.queue.empty():
+                break
+
+            try:
+                payload = await asyncio.wait_for(ctx.queue.get(), timeout=10)
+                yield payload
+            except asyncio.TimeoutError:
+                yield ": keep-alive\n\n"
+
+    async def _execute_run(self, run_id: str, req: AnalysisRequest) -> None:
+        ctx = self._runs[run_id]
+        hooks = RunHooks(self, run_id)
+
+        try:
+            ctx.state.status = RunStatus.RUNNING
+            ctx.state.started_at = utc_now()
+            logger.info("run started run_id={}", run_id)
+
+            report = await self._analyzer.run(req=req, stop_event=ctx.stop_event, hooks=hooks)
+
+            output_dir = Path(req.output_dir)
+            output_dir.mkdir(parents=True, exist_ok=True)
+            suffix = f"{run_id}_{'partial' if report.is_partial else 'final'}"
+
+            json_path = self._analyzer.save_json(report, str(output_dir / f"pnl_summary_{suffix}.json"))
+            total_csv_path = self._analyzer.save_total_curve_csv(
+                report, str(output_dir / f"pnl_total_curve_{suffix}.csv")
+            )
+            market_csv_path = self._analyzer.save_market_curve_csv(
+                report, str(output_dir / f"pnl_market_curve_{suffix}.csv")
+            )
+
+            report.artifacts = {
+                "json": json_path,
+                "total_curve_csv": total_csv_path,
+                "market_curve_csv": market_csv_path,
+            }
+
+            ctx.result = report
+            ctx.state.ended_at = utc_now()
+
+            if report.is_partial:
+                ctx.state.status = RunStatus.STOPPED
+                logger.warning("run stopped run_id={} (partial result saved)", run_id)
+                await self._emit(
+                    run_id,
+                    "stopped",
+                    {
+                        "run_id": run_id,
+                        "status": ctx.state.status,
+                        "artifacts": self._to_public_artifact_paths(report.artifacts),
+                    },
+                )
+            else:
+                ctx.state.status = RunStatus.COMPLETED
+                logger.info("run completed run_id={} markets_processed={}", run_id, report.summary.markets_processed)
+                await self._emit(
+                    run_id,
+                    "completed",
+                    {
+                        "run_id": run_id,
+                        "status": ctx.state.status,
+                        "artifacts": self._to_public_artifact_paths(report.artifacts),
+                        "summary": report.summary.model_dump(),
+                    },
+                )
+        except Exception as exc:  # noqa: BLE001
+            ctx.state.status = RunStatus.FAILED
+            ctx.state.ended_at = utc_now()
+            logger.exception("run failed run_id={} error={}", run_id, exc)
+            await self._emit(run_id, "run_error", {"message": str(exc)})
+        finally:
+            async with self._lock:
+                if self._active_run_id == run_id:
+                    self._active_run_id = None
+
+    async def _emit(self, run_id: str, event_name: str, data: dict) -> None:
+        ctx = self._runs.get(run_id)
+        if not ctx:
+            return
+        payload = self._format_sse(event_name, data)
+        await ctx.queue.put(payload)
+
+    @staticmethod
+    def _format_sse(event_name: str, data: dict) -> str:
+        return f"event: {event_name}\ndata: {json.dumps(data, ensure_ascii=False)}\n\n"
+
+    @staticmethod
+    def _to_public_artifact_paths(artifacts: dict[str, str]) -> dict[str, str]:
+        public: dict[str, str] = {}
+        for key, path in artifacts.items():
+            filename = Path(path).name
+            public[key] = f"/reports/{filename}"
+        return public