dojozero 0.2.2__tar.gz → 0.3.0__tar.gz

{dojozero-0.2.2 → dojozero-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dojozero
-Version: 0.2.2
+Version: 0.3.0
 Summary: A platform for running AI agents on realtime sport data and make predictions about game outcomes.
 Project-URL: Homepage, https://github.com/agentscope-ai/DojoZero
 Project-URL: Repository, https://github.com/agentscope-ai/DojoZero

{dojozero-0.2.2 → dojozero-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dojozero"
-version = "0.2.2"
+version = "0.3.0"
 description = "A platform for running AI agents on realtime sport data and make predictions about game outcomes."
 readme = "README.md"
 requires-python = ">=3.11"

{dojozero-0.2.2 → dojozero-0.3.0}/src/dojozero/arena_server/_cache.py

@@ -63,6 +63,7 @@ from dojozero.arena_server._config import ArenaServerConfig  # noqa: E402
 
 DEFAULT_CACHE_CONFIG = CacheConfig()
 CACHEABLE_LEAGUES: frozenset[str] = frozenset({"NBA", "NFL"})
+LEADERBOARD_PERIODS: tuple[str, ...] = ("7d", "14d", "30d")
 
 
 @dataclass
@@ -124,8 +125,13 @@ class LandingPageCache:
     _stats_by_league: dict[str, CacheEntry] = field(default_factory=dict)
     _games_by_league: dict[str, CacheEntry] = field(default_factory=dict)
     _leaderboard_by_league: dict[str, CacheEntry] = field(default_factory=dict)
+    _leaderboard_by_period: dict[str, CacheEntry] = field(default_factory=dict)
+    _leaderboard_by_league_period: dict[str, CacheEntry] = field(default_factory=dict)
     _agent_actions_by_league: dict[str, CacheEntry] = field(default_factory=dict)
 
+    # Agent bets index - per-agent bet records (agent_id -> list[BetRecord])
+    _agent_bets_index: dict[str, list] = field(default_factory=dict)
+
     # Agent info cache - single source of truth (agent_id -> AgentInfo)
     _agent_info: dict[str, AgentInfo] = field(default_factory=dict)
 
@@ -185,9 +191,32 @@ class LandingPageCache:
         return None
 
     def get_leaderboard(
-        self, league: str | None = None
+        self, league: str | None = None, period: str | None = None
     ) -> list[LeaderboardEntry] | None:
-        """Get cached leaderboard. Returns None if not cached."""
+        """Get cached leaderboard. Returns None if not cached.
+
+        Args:
+            league: Optional league filter (e.g. "NBA", "NFL").
+            period: Optional period filter ("7d", "14d", "30d").
+                    None or "all" returns the full leaderboard.
+        """
+        # Normalize period: None and "all" both mean full leaderboard
+        effective_period = period if period and period != "all" else None
+
+        if effective_period:
+            if league:
+                # Per-league + per-period
+                key = f"{league.upper()}:{effective_period}"
+                entry = self._leaderboard_by_league_period.get(key)
+                if entry is not None and entry.is_valid():
+                    return entry.data
+                return None
+            # Global + per-period
+            entry = self._leaderboard_by_period.get(effective_period)
+            if entry is not None and entry.is_valid():
+                return entry.data
+            return None
+
         if league:
             league_key = league.upper()
             if league_key in CACHEABLE_LEAGUES:
@@ -247,6 +276,15 @@ class LandingPageCache:
         """Get all cached agent info (for batch operations)."""
         return self._agent_info
 
+    def get_agent_bets_index(self) -> dict[str, list]:
+        """Get cached agent bets index (agent_id -> sorted list[BetRecord])."""
+        return self._agent_bets_index
+
+    def set_agent_bets_index(self, data: dict[str, list]) -> None:
+        """Set agent bets index (overwrites previous)."""
+        self._agent_bets_index = data
+        LOGGER.debug("Cache SET: agent_bets_index (%d agents)", len(data))
+
     def get_total_agents(self) -> int:
         """Get total number of cached agents."""
         return len(self._agent_info)
@@ -372,13 +410,37 @@ class LandingPageCache:
         LOGGER.debug("Cache SET: games (global)")
 
     def set_leaderboard(
-        self, data: list[LeaderboardEntry], league: str | None = None
+        self,
+        data: list[LeaderboardEntry],
+        league: str | None = None,
+        period: str | None = None,
     ) -> None:
-        """Set leaderboard cache (overwrites previous)."""
+        """Set leaderboard cache (overwrites previous).
+
+        Args:
+            data: Leaderboard entries.
+            league: Optional league filter.
+            period: Optional period filter ("7d", "14d", "30d").
+                    None or "all" sets the full leaderboard.
+        """
         entry = CacheEntry(
             data=data,
             expires_at=time.time() + self.config.max_cache_ttl,
         )
+        effective_period = period if period and period != "all" else None
+
+        if effective_period:
+            if league:
+                key = f"{league.upper()}:{effective_period}"
+                self._leaderboard_by_league_period[key] = entry
+                LOGGER.debug(
+                    "Cache SET: leaderboard[%s][%s]", league.upper(), effective_period
+                )
+                return
+            self._leaderboard_by_period[effective_period] = entry
+            LOGGER.debug("Cache SET: leaderboard[period=%s]", effective_period)
+            return
+
         if league:
             league_key = league.upper()
             if league_key in CACHEABLE_LEAGUES:
@@ -436,6 +498,8 @@ class LandingPageCache:
         self._stats_by_league.clear()
         self._games_by_league.clear()
         self._leaderboard_by_league.clear()
+        self._leaderboard_by_period.clear()
+        self._leaderboard_by_league_period.clear()
         self._agent_actions_by_league.clear()
         # Clear agent info cache
         self._agent_info.clear()
@@ -485,6 +549,12 @@ class LandingPageCache:
                 "leaderboard": _league_cache_info(self._leaderboard_by_league),
                 "agent_actions": _league_cache_info(self._agent_actions_by_league),
             },
+            "caches_by_period": {
+                "leaderboard": _league_cache_info(self._leaderboard_by_period),
+                "leaderboard_by_league": _league_cache_info(
+                    self._leaderboard_by_league_period
+                ),
+            },
         }
 
 

{dojozero-0.2.2 → dojozero-0.3.0}/src/dojozero/arena_server/_config.py

@@ -81,7 +81,8 @@ class SLSConfig(BaseModel):
 
     page_size: int = Field(default=100, description="Page size for SLS queries")
     max_total: int = Field(
-        default=100000, description="Safety limit for total rows fetched"
+        default=1000000,
+        description="Safety limit for total rows fetched per paginated query",
     )
 
 

{dojozero-0.2.2 → dojozero-0.3.0}/src/dojozero/arena_server/_endpoints.py

@@ -40,6 +40,9 @@ from ._server import (
     TrialReplayController,
     get_server_state,
 )
+from ._utils import (
+    _compute_agent_profile,
+)
 from ._utils import _load_replay_data
 
 LOGGER = logging.getLogger("dojozero.arena_server.endpoints")
@@ -363,31 +366,166 @@ def register_rest_endpoints(app: FastAPI) -> None:
             ge=1,
             le=1000,
         ),
+        page: int = Query(
+            default=1,
+            description="Page number (1-based).",
+            ge=1,
+        ),
+        page_size: int = Query(
+            default=20,
+            description="Number of entries per page.",
+            ge=1,
+            le=100,
+        ),
+        period: str = Query(
+            default="all",
+            description="Time period filter: 'all', '7d', '14d', '30d'.",
+        ),
+        agent_type: str | None = Query(
+            default=None,
+            description="Agent type filter: 'built_in' or 'external'.",
+        ),
+        sort_by: str = Query(
+            default="winnings",
+            description="Sort field: 'winnings', 'win_rate', 'roi', 'total_bets'.",
+        ),
+        sort_order: str = Query(
+            default="desc",
+            description="Sort direction: 'asc' or 'desc'.",
+        ),
     ) -> JSONResponse:
-        """Get agent leaderboard ranked by winnings.
+        """Get agent leaderboard ranked by specified field.
 
-        Returns agents sorted by total winnings with win rate and ROI.
-        Data is served from cache (background refresh keeps it fresh).
-        On cache miss, triggers on-demand refresh.
+        Returns agents sorted by the requested field with win rate and ROI.
+        Supports period-based filtering (pre-computed: all/7d/14d/30d),
+        agent type filtering, custom sorting, and pagination.
         """
         state = get_server_state()
         refresher = state.refresher
         assert refresher is not None, "BackgroundRefresher not initialized"
 
-        # Get leaderboard from cache, or refresh on demand
-        leaderboard = state.cache.get_leaderboard(league=league)
+        # Validate period
+        valid_periods = {"all", "7d", "14d", "30d"}
+        if period not in valid_periods:
+            return JSONResponse(
+                status_code=400,
+                content={
+                    "error": f"Invalid period '{period}'. Must be one of: {', '.join(sorted(valid_periods))}"
+                },
+            )
+
+        # All paths now read from pre-computed cache
+        effective_period = period if period != "all" else None
+        leaderboard = state.cache.get_leaderboard(
+            league=league,
+            period=effective_period,
+        )
         if leaderboard is None:
-            leaderboard = await refresher.refresh_leaderboard_on_demand(league=league)
+            # Fallback: try on-demand refresh for the base (all) leaderboard
+            if effective_period is None:
+                leaderboard = await refresher.refresh_leaderboard_on_demand(
+                    league=league
+                )
+            else:
+                leaderboard = []
+
+        # --- Unified post-processing: filter → sort → rank → limit → paginate ---
+
+        # 1. Filter by agent_type
+        if agent_type == "external":
+            leaderboard = [e for e in leaderboard if e.agent.is_external]
+        elif agent_type == "built_in":
+            leaderboard = [e for e in leaderboard if not e.agent.is_external]
+
+        # 2. Sort (cached path is already sorted by winnings desc; re-sort only when needed)
+        if sort_by != "winnings" or sort_order != "desc":
+            sort_key_map = {
+                "winnings": lambda x: x.winnings,
+                "win_rate": lambda x: x.win_rate,
+                "roi": lambda x: x.roi,
+                "sharpe": lambda x: x.sharpe,
+                "total_bets": lambda x: x.total_bets,
+            }
+            key_fn = sort_key_map.get(sort_by, sort_key_map["winnings"])
+            leaderboard = sorted(leaderboard, key=key_fn, reverse=(sort_order != "asc"))
 
-        # Apply limit only if specified
+        # 3. Limit
         if limit is not None:
             leaderboard = leaderboard[:limit]
 
-        response = LeaderboardResponse(leaderboard=leaderboard)
+        total = len(leaderboard)
+
+        # 4. Paginate + assign global rank (once)
+        start_idx = (page - 1) * page_size
+        page_entries = [
+            e.model_copy(update={"rank": start_idx + i + 1})
+            for i, e in enumerate(leaderboard[start_idx : start_idx + page_size])
+        ]
+
+        response = LeaderboardResponse(
+            leaderboard=page_entries,
+            total=total,
+            page=page,
+            page_size=page_size,
+        )
         return JSONResponse(
             content=response.model_dump(by_alias=state.by_alias),
         )
 
+    @app.get("/api/agent/{agent_id}/profile")
+    async def get_agent_profile(
+        agent_id: str,
+        page: int = Query(
+            default=1,
+            description="Page number for bet history (1-based).",
+            ge=1,
+        ),
+        page_size: int = Query(
+            default=20,
+            description="Number of bet records per page.",
+            ge=1,
+            le=100,
+        ),
+    ) -> JSONResponse:
+        """Get agent profile with stats and paginated bet history.
+
+        Returns agent info, aggregate stats, and a paginated list of
+        individual bets sorted by game_date descending.
+        """
+        state = get_server_state()
+        refresher = state.refresher
+        assert refresher is not None, "BackgroundRefresher not initialized"
+
+        # Stats from leaderboard cache, bets from bets index — zero recomputation
+        leaderboard = state.cache.get_leaderboard() or []
+        agent_bets_index = state.cache.get_agent_bets_index()
+        agent_info_cache = state.cache.get_all_agent_info()
+
+        # Check if agent exists in any cache; return 404 if unknown
+        agent_known = (
+            agent_id in agent_info_cache
+            or agent_id in agent_bets_index
+            or any(e.agent.agent_id == agent_id for e in leaderboard)
+        )
+        if not agent_known:
+            return JSONResponse(
+                status_code=404,
+                content={"detail": f"Agent '{agent_id}' not found"},
+            )
+
+        profile = _compute_agent_profile(
+            agent_id=agent_id,
+            leaderboard=leaderboard,
+            agent_bets_index=agent_bets_index,
+            agent_info_cache=agent_info_cache,
+            page=page,
+            page_size=page_size,
+        )
+
+        return JSONResponse(
+            content=profile.model_dump(by_alias=state.by_alias),
+        )
+
     @app.get("/api/agent-actions")
     async def get_agent_actions(
         limit: int = Query(

{dojozero-0.2.2 → dojozero-0.3.0}/src/dojozero/arena_server/_models.py

@@ -16,6 +16,48 @@ from dojozero.betting._models import AgentInfo
 from dojozero.core._models import AgentAction, LeaderboardEntry
 from dojozero.data._models import TeamIdentity
 
+
+class BetRecord(BaseModel):
+    """A single bet record for agent profile display."""
+
+    model_config = ConfigDict(frozen=True, populate_by_name=True)
+
+    trial_id: str = Field(serialization_alias="trialId")
+    league: str = ""
+    home_team: str = Field(default="", serialization_alias="homeTeam")
+    away_team: str = Field(default="", serialization_alias="awayTeam")
+    game_date: str = Field(default="", serialization_alias="gameDate")
+    selection: str = ""
+    amount: float = 0.0
+    result: str = "pending"  # "win", "loss", "pending"
+    payout: float = 0.0
+
+
+class AgentProfileStats(BaseModel):
+    """Aggregate stats for an agent profile."""
+
+    model_config = ConfigDict(frozen=True, populate_by_name=True)
+
+    winnings: float = 0.0
+    win_rate: float = Field(default=0.0, serialization_alias="winRate")
+    total_bets: int = Field(default=0, serialization_alias="totalBets")
+    roi: float = 0.0
+
+
+class AgentProfileResponse(BaseModel):
+    """Response for GET /api/agent/{agent_id}/profile."""
+
+    model_config = ConfigDict(frozen=True, populate_by_name=True)
+
+    agent: AgentInfo
+    stats: AgentProfileStats
+    created_at: str | None = Field(default=None, serialization_alias="createdAt")
+    bets: list[BetRecord] = Field(default_factory=list)
+    total_bets_count: int = Field(default=0, serialization_alias="totalBetsCount")
+    page: int = 1
+    page_size: int = Field(default=20, serialization_alias="pageSize")
+
+
 # ============================================================================
 # Type Aliases
 # ============================================================================
@@ -123,9 +165,12 @@ class LandingResponse(BaseModel):
 class LeaderboardResponse(BaseModel):
     """Response for /api/leaderboard."""
 
-    model_config = ConfigDict(frozen=True)
+    model_config = ConfigDict(frozen=True, populate_by_name=True)
 
     leaderboard: list[LeaderboardEntry] = Field(default_factory=list)
+    total: int = 0
+    page: int = 1
+    page_size: int = Field(default=20, serialization_alias="pageSize")
 
 
 class BetSummary(BaseModel):
@@ -261,6 +306,9 @@ class ReplayResponse(BaseModel):
 __all__ = [
     # API Response Models
     "AgentActionsResponse",
+    "AgentProfileResponse",
+    "AgentProfileStats",
+    "BetRecord",
     "BetSummary",
     "GameCardData",
     "GamesResponse",

{dojozero-0.2.2 → dojozero-0.3.0}/src/dojozero/arena_server/_redis_reader.py

@@ -17,9 +17,10 @@ from datetime import datetime
 
 from dojozero.arena_server._cache import (
     CACHEABLE_LEAGUES,
+    LEADERBOARD_PERIODS,
     LandingPageCache,
 )
-from dojozero.arena_server._models import GamesResponse, StatsResponse
+from dojozero.arena_server._models import BetRecord, GamesResponse, StatsResponse
 from dojozero.betting import AgentInfo
 from dojozero.core import AgentAction, LeaderboardEntry
 from dojozero.core._tracing import SpanData
@@ -161,6 +162,21 @@ class RedisReader:
                 lb = [LeaderboardEntry.model_validate(e) for e in lb_data]
                 self.cache.set_leaderboard(lb, league=league)
 
+        # Period leaderboards (global + per-league)
+        for period in LEADERBOARD_PERIODS:
+            p_data = await self.redis_client.get_leaderboard(period=period)
+            if p_data:
+                p_lb = [LeaderboardEntry.model_validate(e) for e in p_data]
+                self.cache.set_leaderboard(p_lb, period=period)
+            for league in CACHEABLE_LEAGUES:
+                lp_data = await self.redis_client.get_leaderboard(
+                    league=league,
+                    period=period,
+                )
+                if lp_data:
+                    lp_lb = [LeaderboardEntry.model_validate(e) for e in lp_data]
+                    self.cache.set_leaderboard(lp_lb, league=league, period=period)
+
         # Agent actions (global + per-league)
         actions_data = await self.redis_client.get_agent_actions(league=None)
         if actions_data:
@@ -197,6 +213,14 @@ class RedisReader:
                 g = GamesResponse.model_validate(g_data)
                 self.cache.set_games(g, league=league)
 
+        # Agent bets index
+        bets_index_data = await self.redis_client.get_agent_bets_index()
+        if bets_index_data:
+            agent_bets_index: dict[str, list[BetRecord]] = {}
+            for aid, bets_list in bets_index_data.items():
+                agent_bets_index[aid] = [BetRecord.model_validate(b) for b in bets_list]
+            self.cache.set_agent_bets_index(agent_bets_index)
+
         # Live trials are derived from trial_info, not stored separately
         # Redis provides them for convenience but cache derives from trial_info
         await self.redis_client.get_live_trials()