magisterial 0.1.0__tar.gz

magisterial-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e . pytest anyio
+      - run: pytest -q

magisterial-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+# Publishes on GitHub release. Uses PyPI Trusted Publishing (OIDC) — configure
+# this repo as a trusted publisher for the `magisterial` project on PyPI;
+# no API token secret needed.
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

magisterial-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/
+.DS_Store

magisterial-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Magisterial
+
+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.

magisterial-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: magisterial
+Version: 0.1.0
+Summary: Official Python SDK for the Magisterial college sports data API
+Project-URL: Homepage, https://magisterial.ai
+Project-URL: Documentation, https://api.magisterial.ai/v1/docs
+Project-URL: Repository, https://github.com/bluemens/magisterial-python
+Project-URL: API reference (llms.txt), https://api.magisterial.ai/v1/llms.txt
+Author-email: Magisterial <comfere@magisterial.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,college sports,magisterial,ncaa,sdk,transfer portal
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.5.0
+Description-Content-Type: text/markdown
+
+# Magisterial Python SDK
+
+The official Python library for the [Magisterial](https://magisterial.ai) developer API —
+college sports data across NCAA D1/D2/D3, NAIA, and NJCAA: players, teams, rosters,
+cross-program careers, games, the live transfer portal, and an agent-backed
+natural-language query endpoint.
+
+- Interactive API reference: https://api.magisterial.ai/v1/docs
+- OpenAPI spec: https://api.magisterial.ai/v1/openapi.json
+- Agent-ready one-file reference: https://api.magisterial.ai/v1/llms.txt
+
+## Installation
+
+```bash
+pip install magisterial
+```
+
+Requires Python 3.10+.
+
+## Usage
+
+Create an API key at [magisterial.ai/console/api-keys](https://magisterial.ai/console/api-keys)
+and set `MAGISTERIAL_API_KEY` (or pass `api_key=` to the client).
+
+```python
+from magisterial import Magisterial
+
+client = Magisterial()
+
+# Search players (auto-pagination follows the cursor for you)
+page = client.players.search(
+    sport="soccer", division="D1", gender="women",
+    position="Forward", sort_by="goals",
+)
+for player in page.auto_paging_iter():
+    print(player.name, player.team, player.stats.get("goals"))
+
+# One player's full profile
+player = client.players.get(184223, sport="soccer", division="D3")
+
+# Live transfer portal (usage-billed; use `since` for incremental polling)
+portal = client.portal.list(sport="basketball", division="D1", status="INC")
+
+# Natural-language query (usage-billed): submit and wait for the answer
+run = client.query.create_and_poll(
+    prompt="Who led the NESCAC in assists this season?",
+    sport="soccer", division="D3", gender="men",
+)
+print(run.answer)
+```
+
+### Async
+
+Every method is mirrored on `AsyncMagisterial`:
+
+```python
+import asyncio
+from magisterial import AsyncMagisterial
+
+async def main():
+    async with AsyncMagisterial() as client:
+        page = await client.players.search(sport="soccer", division="D1")
+        async for player in page.auto_paging_iter():
+            print(player.name)
+
+asyncio.run(main())
+```
+
+### Errors
+
+Non-2xx responses raise typed exceptions carrying the API's error envelope:
+
+```python
+from magisterial import Magisterial, NotFoundError, RateLimitError
+
+client = Magisterial()
+try:
+    client.players.get(1, sport="soccer", division="D1")
+except NotFoundError as e:
+    print(e.error_code)   # "player_not_found"
+except RateLimitError as e:
+    print(e.retry_after)  # seconds, from the Retry-After header
+```
+
+`BillingError` (402) means API billing is not enabled or the monthly budget is
+exhausted — manage both in the [developer console](https://magisterial.ai/console).
+
+### Retries
+
+Idempotent requests (and `players.search`) are retried automatically on 429s,
+5xx and connection failures — up to `max_retries` (default 2), honoring the
+server's `Retry-After`. Billable creates (`query.create`, `alerts.create`)
+are never retried automatically.
+
+## Types
+
+All request/response models live in `magisterial.types` and are generated from
+the published OpenAPI spec (`scripts/sync-types.sh`), so they cannot drift
+from the live API contract.
+
+## License
+
+MIT

magisterial-0.1.0/README.md

@@ -0,0 +1,103 @@
+# Magisterial Python SDK
+
+The official Python library for the [Magisterial](https://magisterial.ai) developer API —
+college sports data across NCAA D1/D2/D3, NAIA, and NJCAA: players, teams, rosters,
+cross-program careers, games, the live transfer portal, and an agent-backed
+natural-language query endpoint.
+
+- Interactive API reference: https://api.magisterial.ai/v1/docs
+- OpenAPI spec: https://api.magisterial.ai/v1/openapi.json
+- Agent-ready one-file reference: https://api.magisterial.ai/v1/llms.txt
+
+## Installation
+
+```bash
+pip install magisterial
+```
+
+Requires Python 3.10+.
+
+## Usage
+
+Create an API key at [magisterial.ai/console/api-keys](https://magisterial.ai/console/api-keys)
+and set `MAGISTERIAL_API_KEY` (or pass `api_key=` to the client).
+
+```python
+from magisterial import Magisterial
+
+client = Magisterial()
+
+# Search players (auto-pagination follows the cursor for you)
+page = client.players.search(
+    sport="soccer", division="D1", gender="women",
+    position="Forward", sort_by="goals",
+)
+for player in page.auto_paging_iter():
+    print(player.name, player.team, player.stats.get("goals"))
+
+# One player's full profile
+player = client.players.get(184223, sport="soccer", division="D3")
+
+# Live transfer portal (usage-billed; use `since` for incremental polling)
+portal = client.portal.list(sport="basketball", division="D1", status="INC")
+
+# Natural-language query (usage-billed): submit and wait for the answer
+run = client.query.create_and_poll(
+    prompt="Who led the NESCAC in assists this season?",
+    sport="soccer", division="D3", gender="men",
+)
+print(run.answer)
+```
+
+### Async
+
+Every method is mirrored on `AsyncMagisterial`:
+
+```python
+import asyncio
+from magisterial import AsyncMagisterial
+
+async def main():
+    async with AsyncMagisterial() as client:
+        page = await client.players.search(sport="soccer", division="D1")
+        async for player in page.auto_paging_iter():
+            print(player.name)
+
+asyncio.run(main())
+```
+
+### Errors
+
+Non-2xx responses raise typed exceptions carrying the API's error envelope:
+
+```python
+from magisterial import Magisterial, NotFoundError, RateLimitError
+
+client = Magisterial()
+try:
+    client.players.get(1, sport="soccer", division="D1")
+except NotFoundError as e:
+    print(e.error_code)   # "player_not_found"
+except RateLimitError as e:
+    print(e.retry_after)  # seconds, from the Retry-After header
+```
+
+`BillingError` (402) means API billing is not enabled or the monthly budget is
+exhausted — manage both in the [developer console](https://magisterial.ai/console).
+
+### Retries
+
+Idempotent requests (and `players.search`) are retried automatically on 429s,
+5xx and connection failures — up to `max_retries` (default 2), honoring the
+server's `Retry-After`. Billable creates (`query.create`, `alerts.create`)
+are never retried automatically.
+
+## Types
+
+All request/response models live in `magisterial.types` and are generated from
+the published OpenAPI spec (`scripts/sync-types.sh`), so they cannot drift
+from the live API contract.
+
+## License
+
+MIT

magisterial-0.1.0/magisterial/__init__.py

@@ -0,0 +1,44 @@
+# Magisterial — official Python SDK for the Magisterial developer API.
+# Docs: https://api.magisterial.ai/v1/docs   Spec: https://api.magisterial.ai/v1/openapi.json
+
+from . import types
+from ._client import AsyncMagisterial, Magisterial
+from ._exceptions import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    BillingError,
+    InternalServerError,
+    MagisterialError,
+    NotFoundError,
+    PermissionDeniedError,
+    QueryPollTimeout,
+    RateLimitError,
+    UnprocessableEntityError,
+)
+from ._pagination import AsyncPage, SyncPage
+from ._version import __version__
+
+__all__ = [
+    "Magisterial",
+    "AsyncMagisterial",
+    "SyncPage",
+    "AsyncPage",
+    "types",
+    "MagisterialError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "BadRequestError",
+    "AuthenticationError",
+    "BillingError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "UnprocessableEntityError",
+    "RateLimitError",
+    "InternalServerError",
+    "QueryPollTimeout",
+    "__version__",
+]

magisterial-0.1.0/magisterial/_client.py

@@ -0,0 +1,304 @@
+# The Magisterial client core: auth, transport, retries, and JSON<->model
+# plumbing shared by every resource namespace. Public entry points are
+# ``Magisterial`` (sync) and ``AsyncMagisterial``.
+
+from __future__ import annotations
+
+import os
+import random
+from typing import Any, Dict, Mapping, Optional, Type, TypeVar
+
+import httpx
+from pydantic import BaseModel
+
+from ._exceptions import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    MagisterialError,
+    error_from_response,
+)
+from ._version import __version__
+
+M = TypeVar("M", bound=BaseModel)
+
+DEFAULT_BASE_URL = "https://api.magisterial.ai"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+
+# Methods safe to retry unconditionally. POSTs are retried only when the
+# caller opts in (search is a read; query/alert creates are billable).
+_IDEMPOTENT_METHODS = {"GET", "DELETE"}
+
+
+def _clean_params(params: Optional[Mapping[str, Any]]) -> Dict[str, Any]:
+    return {k: v for k, v in (params or {}).items() if v is not None}
+
+
+class _ClientConfig:
+    def __init__(
+        self,
+        api_key: Optional[str],
+        base_url: Optional[str],
+        timeout: float,
+        max_retries: int,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("MAGISTERIAL_API_KEY")
+        if not self.api_key:
+            raise MagisterialError(
+                "No API key provided. Pass api_key=... or set the "
+                "MAGISTERIAL_API_KEY environment variable. Create keys at "
+                "https://magisterial.ai/console/api-keys"
+            )
+        self.base_url = (
+            base_url
+            or os.environ.get("MAGISTERIAL_BASE_URL")
+            or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+    @property
+    def headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"magisterial-python/{__version__}",
+        }
+
+
+def _retry_delay(response: Optional[httpx.Response], attempt: int) -> float:
+    """Seconds to sleep before retry `attempt` (0-based), honoring Retry-After."""
+    if response is not None:
+        header = response.headers.get("Retry-After")
+        if header:
+            try:
+                return max(0.0, float(header))
+            except ValueError:
+                pass
+    # Exponential backoff with jitter: ~0.5s, ~1s, ~2s ...
+    return 0.5 * (2**attempt) * (1 + random.random() * 0.25)
+
+
+def _should_retry(response: httpx.Response) -> bool:
+    return response.status_code == 429 or response.status_code >= 500
+
+
+class Magisterial:
+    """Synchronous client for the Magisterial developer API.
+
+    >>> client = Magisterial()  # reads MAGISTERIAL_API_KEY
+    >>> page = client.players.search(sport="soccer", division="D1")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._config = _ClientConfig(api_key, base_url, timeout, max_retries)
+        self._http = http_client or httpx.Client(timeout=timeout)
+
+        from .resources.alerts import Alerts
+        from .resources.games import Games
+        from .resources.persons import Persons
+        from .resources.players import Players
+        from .resources.portal import Portal
+        from .resources.query import Query
+        from .resources.reference import Reference
+        from .resources.teams import Teams
+
+        self.reference = Reference(self)
+        self.players = Players(self)
+        self.teams = Teams(self)
+        self.persons = Persons(self)
+        self.games = Games(self)
+        self.portal = Portal(self)
+        self.query = Query(self)
+        self.alerts = Alerts(self)
+
+    # -- transport ---------------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json: Optional[Any] = None,
+        retryable: Optional[bool] = None,
+    ) -> Any:
+        """Perform a request and return decoded JSON, retrying 429/5xx and
+        connection failures for idempotent (or explicitly retryable) calls."""
+        import time
+
+        url = self._config.base_url + path
+        can_retry = (
+            method in _IDEMPOTENT_METHODS if retryable is None else retryable
+        )
+        attempts = self._config.max_retries + 1 if can_retry else 1
+        last_exc: Optional[Exception] = None
+
+        for attempt in range(attempts):
+            try:
+                response = self._http.request(
+                    method,
+                    url,
+                    params=_clean_params(params),
+                    json=json,
+                    headers=self._config.headers,
+                )
+            except httpx.TimeoutException as exc:
+                last_exc = APITimeoutError()
+                last_exc.__cause__ = exc
+                response = None
+            except httpx.HTTPError as exc:
+                last_exc = APIConnectionError(str(exc) or "Connection error.")
+                last_exc.__cause__ = exc
+                response = None
+
+            if response is not None:
+                if response.status_code < 400:
+                    return response.json()
+                last_exc = error_from_response(response)
+                if not (attempt < attempts - 1 and _should_retry(response)):
+                    raise last_exc
+            elif attempt >= attempts - 1:
+                raise last_exc  # type: ignore[misc]
+
+            time.sleep(
+                _retry_delay(
+                    getattr(last_exc, "response", None)
+                    if isinstance(last_exc, APIStatusError)
+                    else None,
+                    attempt,
+                )
+            )
+
+        raise last_exc  # type: ignore[misc]  # unreachable, defensive
+
+    def get_model(self, path: str, model: Type[M], **params: Any) -> M:
+        return model.model_validate(self.request("GET", path, params=params))
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Magisterial":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+class AsyncMagisterial:
+    """Asynchronous client for the Magisterial developer API.
+
+    >>> client = AsyncMagisterial()
+    >>> page = await client.players.search(sport="soccer", division="D1")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._config = _ClientConfig(api_key, base_url, timeout, max_retries)
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+
+        from .resources.alerts import AsyncAlerts
+        from .resources.games import AsyncGames
+        from .resources.persons import AsyncPersons
+        from .resources.players import AsyncPlayers
+        from .resources.portal import AsyncPortal
+        from .resources.query import AsyncQuery
+        from .resources.reference import AsyncReference
+        from .resources.teams import AsyncTeams
+
+        self.reference = AsyncReference(self)
+        self.players = AsyncPlayers(self)
+        self.teams = AsyncTeams(self)
+        self.persons = AsyncPersons(self)
+        self.games = AsyncGames(self)
+        self.portal = AsyncPortal(self)
+        self.query = AsyncQuery(self)
+        self.alerts = AsyncAlerts(self)
+
+    # -- transport ---------------------------------------------------------
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json: Optional[Any] = None,
+        retryable: Optional[bool] = None,
+    ) -> Any:
+        import asyncio
+
+        url = self._config.base_url + path
+        can_retry = (
+            method in _IDEMPOTENT_METHODS if retryable is None else retryable
+        )
+        attempts = self._config.max_retries + 1 if can_retry else 1
+        last_exc: Optional[Exception] = None
+
+        for attempt in range(attempts):
+            try:
+                response = await self._http.request(
+                    method,
+                    url,
+                    params=_clean_params(params),
+                    json=json,
+                    headers=self._config.headers,
+                )
+            except httpx.TimeoutException as exc:
+                last_exc = APITimeoutError()
+                last_exc.__cause__ = exc
+                response = None
+            except httpx.HTTPError as exc:
+                last_exc = APIConnectionError(str(exc) or "Connection error.")
+                last_exc.__cause__ = exc
+                response = None
+
+            if response is not None:
+                if response.status_code < 400:
+                    return response.json()
+                last_exc = error_from_response(response)
+                if not (attempt < attempts - 1 and _should_retry(response)):
+                    raise last_exc
+            elif attempt >= attempts - 1:
+                raise last_exc  # type: ignore[misc]
+
+            await asyncio.sleep(
+                _retry_delay(
+                    getattr(last_exc, "response", None)
+                    if isinstance(last_exc, APIStatusError)
+                    else None,
+                    attempt,
+                )
+            )
+
+        raise last_exc  # type: ignore[misc]  # unreachable, defensive
+
+    async def get_model(self, path: str, model: Type[M], **params: Any) -> M:
+        return model.model_validate(
+            await self.request("GET", path, params=params)
+        )
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncMagisterial":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()