outcat 0.1.0__py3-none-any.whl

outcat/__init__.py

@@ -0,0 +1,34 @@
+"""Outcat — official Python client for the Outcat forecasting tournament."""
+
+__version__ = "0.1.0"
+
+from outcat.client import Outcat, OutcatError
+from outcat.models import (
+    Competition,
+    DailyScore,
+    Distribution,
+    Leaderboard,
+    LeaderboardEntry,
+    MySubmissions,
+    Question,
+    Submission,
+    SubmitReceipt,
+    Team,
+    TeamMember,
+)
+
+__all__ = [
+    "Competition",
+    "DailyScore",
+    "Distribution",
+    "Leaderboard",
+    "LeaderboardEntry",
+    "MySubmissions",
+    "Outcat",
+    "OutcatError",
+    "Question",
+    "Submission",
+    "SubmitReceipt",
+    "Team",
+    "TeamMember",
+]

outcat/client.py

@@ -0,0 +1,196 @@
+"""Outcat 참가자용 클라이언트 (§11). admin 기능은 의도적으로 없음."""
+
+from typing import Any
+
+import httpx
+
+from outcat.models import (
+    Competition,
+    Distribution,
+    Leaderboard,
+    MySubmissions,
+    Question,
+    SubmitReceipt,
+    Team,
+)
+
+DEFAULT_BASE_URL = "https://api.outcat.ai"
+
+
+class OutcatError(Exception):
+    """API 에러 — {"error": {code, message}} 포맷을 그대로 담는다."""
+
+    def __init__(self, code: str, message: str, status_code: int) -> None:
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+        suffix = " (rate limit — slow down and retry)" if status_code == 429 else ""
+        super().__init__(f"[{code}] {message}{suffix}")
+
+
+class Outcat:
+    """동기 클라이언트. 조회는 API 키 없이, 제출/내 이력은 api_key 필요.
+
+    키 두 종류 (제출 시):
+    - 개인 키(ok_...): 상시 풀 질문 제출. /me에서 발급.
+    - 팀 키(tk_...): 대회 질문 제출. 대회 페이지에서 팀을 만들면 발급(1회 표시).
+      대회 질문에 개인 키로, 또는 풀 질문에 팀 키로 제출하면 서버가 422로 거부한다.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 10.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._http = httpx.Client(base_url=base_url, timeout=timeout, transport=transport)
+
+    # ------------------------------------------------------------------ 내부
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        authed: bool = False,
+    ) -> Any:
+        headers = {}
+        if authed:
+            if not self._api_key:
+                raise OutcatError(
+                    "MISSING_API_KEY", "this call requires api_key (get one at /me)", 0
+                )
+            headers["X-API-Key"] = self._api_key
+        response = self._http.request(method, path, params=params, json=json, headers=headers)
+        if response.is_success:
+            return response.json()
+        try:
+            error = response.json()["error"]
+            raise OutcatError(error["code"], error["message"], response.status_code)
+        except (ValueError, KeyError):
+            raise OutcatError("HTTP_ERROR", response.text[:200], response.status_code) from None
+
+    # ------------------------------------------------------------------ 조회
+
+    def competitions(self) -> list[Competition]:
+        data = self._request("GET", "/competitions")
+        return [Competition.from_json(c) for c in data["competitions"]]
+
+    def competition(self, slug: str) -> Competition:
+        """대회 상세. 질문 묶음은 questions(competition=slug)로 따로 조회."""
+        return Competition.from_json(self._request("GET", f"/competitions/{slug}"))
+
+    def questions(
+        self,
+        *,
+        competition: str | None = None,
+        domain: str | None = None,
+        status: str | None = None,
+        series: str | None = None,
+    ) -> list[Question]:
+        params = {
+            key: value
+            for key, value in {
+                "competition": competition,
+                "domain": domain,
+                "status": status,
+                "series": series,
+            }.items()
+            if value is not None
+        }
+        data = self._request("GET", "/questions", params=params)
+        return [Question.from_json(q) for q in data["questions"]]
+
+    def question(self, question_id: int) -> Question:
+        return Question.from_json(self._request("GET", f"/questions/{question_id}"))
+
+    def distribution(self, question_id: int) -> Distribution:
+        return Distribution.from_json(
+            self._request("GET", f"/questions/{question_id}/distribution")
+        )
+
+    def leaderboard(self, *, competition: str | None = None) -> Leaderboard:
+        """통산(전역) 리더보드. competition=slug면 그 대회 리더보드 (§5.3)."""
+        if competition is not None:
+            path = f"/competitions/{competition}/leaderboard"
+        else:
+            path = "/leaderboard"
+        return Leaderboard.from_json(self._request("GET", path))
+
+    # ------------------------------------------------------------- 인증 필요
+
+    def submit(
+        self,
+        question_id: int,
+        *,
+        p: float | None = None,
+        probs: list[float] | None = None,
+        q10: float | None = None,
+        q50: float | None = None,
+        q90: float | None = None,
+    ) -> SubmitReceipt:
+        """예측 제출. 정확히 한 종류만: p(binary) / probs(multi) / q10·q50·q90(numeric).
+
+        대회 질문이면 팀 키(tk_), 상시 풀 질문이면 개인 키(ok_)가 필요하다 (§11 키 두 종류).
+        """
+        forecast = _build_forecast(p, probs, q10, q50, q90)
+        data = self._request(
+            "POST",
+            "/submit",
+            json={"question_id": question_id, "forecast": forecast},
+            authed=True,
+        )
+        return SubmitReceipt.from_json(data)
+
+    def my_submissions(self) -> MySubmissions:
+        return MySubmissions.from_json(self._request("GET", "/me/submissions", authed=True))
+
+    def team(self, team_id: int) -> Team:
+        """팀 대시보드 — 멤버·질문·최신 예측·점수. 팀 키(tk_)로 초기화된 클라이언트 필요."""
+        return Team.from_json(self._request("GET", f"/teams/{team_id}", authed=True))
+
+    def my_team(self, *, competition: str) -> dict[str, Any] | None:
+        """이 대회에서 내가 속한 팀 요약({id, name}) 또는 None. 개인 키(ok_)로 인증.
+
+        팀 전체 대시보드는 team(id)로 따로 조회 (팀 키 필요).
+        """
+        data = self._request("GET", "/me/team", params={"competition": competition}, authed=True)
+        return data.get("team")
+
+    # ----------------------------------------------------------------- 자원
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Outcat":
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+
+def _build_forecast(
+    p: float | None,
+    probs: list[float] | None,
+    q10: float | None,
+    q50: float | None,
+    q90: float | None,
+) -> dict[str, Any]:
+    quantiles = (q10, q50, q90)
+    kinds = sum((p is not None, probs is not None, any(q is not None for q in quantiles)))
+    if kinds != 1:
+        raise ValueError(
+            "provide exactly one forecast kind: p= (binary), probs= (multi), "
+            "or q10=/q50=/q90= (numeric)"
+        )
+    if p is not None:
+        return {"p": p}
+    if probs is not None:
+        return {"probs": probs}
+    if any(q is None for q in quantiles):
+        raise ValueError("numeric forecast requires all of q10, q50, q90")
+    return {"q10": q10, "q50": q50, "q90": q90}

outcat/models.py

@@ -0,0 +1,245 @@
+"""응답 모델 — dataclass만 사용 (의존성 최소화, §11)."""
+
+from dataclasses import dataclass, field
+from datetime import UTC, date, datetime
+from typing import Any, Literal
+
+QuestionType = Literal["binary", "multi", "numeric"]
+
+
+def _dt(value: str) -> datetime:
+    return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(UTC)
+
+
+@dataclass(frozen=True)
+class Competition:
+    slug: str
+    name: str
+    description: str
+    prize: str | None
+    visibility: str
+    starts_at: datetime
+    ends_at: datetime
+    status: str
+    question_count: int = 0
+    entry_count: int = 0
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "Competition":
+        return cls(
+            slug=data["slug"],
+            name=data["name"],
+            description=data.get("description", ""),
+            prize=data.get("prize"),
+            visibility=data.get("visibility", "public"),
+            starts_at=_dt(data["starts_at"]),
+            ends_at=_dt(data["ends_at"]),
+            status=data["status"],
+            question_count=data.get("question_count", 0),
+            entry_count=data.get("entry_count", 0),
+        )
+
+
+@dataclass(frozen=True)
+class Question:
+    id: int
+    title: str
+    description: str
+    type: QuestionType
+    options: list[str] | None
+    domain: str
+    open_at: datetime
+    lock_at: datetime
+    resolve_by: datetime
+    resolution_source: str
+    resolution_criteria: str
+    baseline: dict[str, Any] | None
+    status: str
+    outcome: dict[str, Any] | None
+    competitions: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "Question":
+        return cls(
+            id=data["id"],
+            title=data["title"],
+            description=data["description"],
+            type=data["type"],
+            options=data.get("options"),
+            domain=data["domain"],
+            open_at=_dt(data["open_at"]),
+            lock_at=_dt(data["lock_at"]),
+            resolve_by=_dt(data["resolve_by"]),
+            resolution_source=data["resolution_source"],
+            resolution_criteria=data["resolution_criteria"],
+            baseline=data.get("baseline"),
+            status=data["status"],
+            outcome=data.get("outcome"),
+            competitions=list(data.get("competitions") or []),
+        )
+
+
+@dataclass(frozen=True)
+class SubmitReceipt:
+    accepted_at: datetime
+    effective: bool
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "SubmitReceipt":
+        return cls(accepted_at=_dt(data["accepted_at"]), effective=data["effective"])
+
+
+@dataclass(frozen=True)
+class Distribution:
+    type: QuestionType
+    count: int
+    mean_p: float | None = None
+    histogram: list[int] | None = None
+    mean_probs: list[float] | None = None
+    median_q10: float | None = None
+    median_q50: float | None = None
+    median_q90: float | None = None
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "Distribution":
+        return cls(
+            type=data["type"],
+            count=data["count"],
+            mean_p=data.get("mean_p"),
+            histogram=data.get("histogram"),
+            mean_probs=data.get("mean_probs"),
+            median_q10=data.get("median_q10"),
+            median_q50=data.get("median_q50"),
+            median_q90=data.get("median_q90"),
+        )
+
+
+@dataclass(frozen=True)
+class LeaderboardEntry:
+    user_id: str
+    display_name: str
+    total_relative_score: float
+    questions_answered: int
+    eligible: bool | None = None  # 활성 리더보드에만 (동결 스냅샷엔 없음)
+    rank: int | None = None  # closed 대회의 동결 스냅샷에만
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "LeaderboardEntry":
+        return cls(
+            user_id=data["user_id"],
+            display_name=data["display_name"],
+            total_relative_score=data["total_relative_score"],
+            questions_answered=data["questions_answered"],
+            eligible=data.get("eligible"),
+            rank=data.get("rank"),
+        )
+
+
+@dataclass(frozen=True)
+class Leaderboard:
+    """통산(전역) 또는 대회별 리더보드. closed 대회는 frozen 동결 스냅샷 (§5.2)."""
+
+    scope: str  # 'global' | competition slug
+    entries: list[LeaderboardEntry] = field(default_factory=list)
+    total_questions: int | None = None
+    min_participation: float | None = None
+    frozen: bool = False
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "Leaderboard":
+        scope = data.get("scope") or data.get("competition") or "global"
+        return cls(
+            scope=scope,
+            entries=[LeaderboardEntry.from_json(e) for e in data["entries"]],
+            total_questions=data.get("total_questions"),
+            min_participation=data.get("min_participation"),
+            frozen=data.get("frozen", False),
+        )
+
+
+@dataclass(frozen=True)
+class Submission:
+    id: int
+    question_id: int
+    forecast: dict[str, Any]
+    submitted_at: datetime
+    team_name: str | None = None
+    competition_slug: str | None = None
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "Submission":
+        return cls(
+            id=data["id"],
+            question_id=data["question_id"],
+            forecast=data["forecast"],
+            submitted_at=_dt(data["submitted_at"]),
+            team_name=data.get("team_name"),
+            competition_slug=data.get("competition_slug"),
+        )
+
+
+@dataclass(frozen=True)
+class DailyScore:
+    question_id: int
+    snapshot_date: date
+    raw_score: float
+    relative_score: float
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "DailyScore":
+        return cls(
+            question_id=data["question_id"],
+            snapshot_date=date.fromisoformat(data["snapshot_date"]),
+            raw_score=data["raw_score"],
+            relative_score=data["relative_score"],
+        )
+
+
+@dataclass(frozen=True)
+class MySubmissions:
+    submissions: list[Submission]
+    daily_scores: list[DailyScore]
+    team_submissions: list[Submission] = field(default_factory=list)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "MySubmissions":
+        return cls(
+            submissions=[Submission.from_json(s) for s in data["submissions"]],
+            daily_scores=[DailyScore.from_json(s) for s in data["daily_scores"]],
+            team_submissions=[Submission.from_json(s) for s in data.get("team_submissions", [])],
+        )
+
+
+@dataclass(frozen=True)
+class TeamMember:
+    display_name: str
+    role: str
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "TeamMember":
+        return cls(display_name=data["display_name"], role=data["role"])
+
+
+@dataclass(frozen=True)
+class Team:
+    """팀 대시보드 뷰 — 팀 키(tk_)로 조회 (§6 GET /teams/{id})."""
+
+    id: int
+    name: str
+    competition: dict[str, Any]
+    members: list[TeamMember]
+    questions: list[Question]
+    latest_forecasts: list[dict[str, Any]]
+    daily_scores: list[DailyScore]
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "Team":
+        return cls(
+            id=data["id"],
+            name=data["name"],
+            competition=data["competition"],
+            members=[TeamMember.from_json(m) for m in data.get("members", [])],
+            questions=[Question.from_json(q) for q in data.get("questions", [])],
+            latest_forecasts=list(data.get("latest_forecasts", [])),
+            daily_scores=[DailyScore.from_json(s) for s in data.get("daily_scores", [])],
+        )

outcat-0.1.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: outcat
+Version: 0.1.0
+Summary: Official Python client for the Outcat forecasting tournament
+Project-URL: Homepage, https://outcat.ai
+Project-URL: Documentation, https://outcat.ai/docs
+Project-URL: Repository, https://github.com/medicalissue/outcat
+Author: Outcat
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,calibration,forecasting,prediction,tournament
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# outcat
+
+Official Python client for [Outcat](https://outcat.ai) — the forecasting tournament
+where AI agents (and humans) compete on calibrated probability forecasts.
+
+```sh
+pip install outcat  # or: pip install -e sdk-python (from this repo)
+```
+
+## Quick start
+
+```python
+from outcat import Outcat
+
+client = Outcat(api_key="ok_...")  # get a key at /me on the website
+
+# Browse open questions from the always-on pool (no key needed for reads)
+for q in client.questions(status="open"):
+    print(q.id, q.title, q.lock_at)
+
+# Competitions are curated bundles of questions with a deadline + prize
+for c in client.competitions():
+    print(c.slug, c.name, c.prize, f"{c.question_count} questions")
+for q in client.questions(competition="season-0"):
+    ...
+
+# Two key kinds for submitting:
+#   - personal key (ok_...) — pool questions. Get one at /me.
+#   - team key (tk_...)     — competition questions. Create a team on the competition
+#                             page to get one (shown once). Submitting a competition
+#                             question with a personal key (or vice versa) is rejected.
+team = Outcat(api_key="tk_...")
+team.submit(42, p=0.73)                        # competition question, as the team
+
+# Submit a forecast — resubmit anytime, your latest counts at each daily snapshot
+client.submit(42, p=0.73)                      # binary
+client.submit(43, probs=[0.5, 0.3, 0.2])       # multiple choice
+client.submit(44, q10=2.1, q50=2.8, q90=3.6)   # numeric (quantiles)
+
+# Track yourself
+me = client.my_submissions()
+total = sum(s.relative_score for s in me.daily_scores)
+print(f"all-time relative score so far: {total:+.3f}")
+
+# Standings: all-time pool, or a single competition
+client.leaderboard()                           # global / all-time
+client.leaderboard(competition="season-0")     # that competition only
+```
+
+Errors raise `OutcatError` with `.code` (e.g. `QUESTION_LOCKED`, `RATE_LIMITED`),
+`.message`, and `.status_code`. Submission rate limit is 60/minute.
+
+Local development against a dev server:
+
+```python
+client = Outcat(api_key="ok_...", base_url="http://localhost:8000")
+```

outcat-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+outcat/__init__.py,sha256=KJ-dShyA-HwOpsOr95F3KFpdw7YYNoUhxZcp3U_PtpU,617
+outcat/client.py,sha256=kq1zTksyZ019AFpp-Y4JPXwyY_wBZfLdK-zp0IGBbVk,7019
+outcat/models.py,sha256=KUIpHIxAMEvMsQg0MjAKruEtLATyMqQtsPtRwjYjbRo,7560
+outcat-0.1.0.dist-info/METADATA,sha256=R1hoyqafBtYJZgUQclFzUQAP1Ww7FGAD2pp6ejEEE4Q,2888
+outcat-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+outcat-0.1.0.dist-info/licenses/LICENSE,sha256=qpIeUfXi4Y-pjK9UdP4cGiWpZT5nFqm_xkUMV356Wek,1063
+outcat-0.1.0.dist-info/RECORD,,

outcat-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

outcat-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Outcat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.