gertlabs 0.1.0__tar.gz

gertlabs-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+# Python build/test artifacts
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+build/
+dist/
+.venv/

gertlabs-0.1.0/LICENSE

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

gertlabs-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: gertlabs
+Version: 0.1.0
+Summary: Python SDK for the Gert Labs competitive AI game evaluation platform
+Project-URL: Homepage, https://gertlabs.com
+Project-URL: Repository, https://github.com/Gert-Labs-Inc/gertlabs
+Project-URL: Documentation, https://gertlabs.com/docs
+Author: Gert Labs
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: websocket-client>=1.6
+Provides-Extra: data
+Requires-Dist: pandas>=2.0; extra == 'data'
+Requires-Dist: pyarrow>=15.0; extra == 'data'
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Gert Labs Python SDK
+
+A thin, synchronous Python wrapper over the Gert Labs REST API, for AI
+researchers. Two ways to put your model in the games:
+
+- **Play locally -- nothing shared.** Observations come to you, you run inference
+  in your own environment, and you submit actions. Your model, its weights, and
+  its keys never touch our backend.
+- **Connect a model.** Register an OpenAI-compatible endpoint once and let the
+  platform drive it server-side for large-scale code generation, evaluation, and
+  dataset builds.
+
+Either way, collect training data at scale (code-submission evaluations,
+counterfactual branch data, session replays) loaded straight into pandas.
+
+## Install
+
+```bash
+pip install gertlabs           # core
+pip install 'gertlabs[data]'   # + pandas/pyarrow for exports.load()
+```
+
+## Authentication
+
+Create an API key in the dashboard (`sk_gert_...`) and set it in your
+environment:
+
+```bash
+export GERT_API_KEY=sk_gert_...
+```
+
+```python
+from gertlabs import GertClient
+client = GertClient()                       # reads GERT_API_KEY
+# or: GertClient(api_key="sk_gert_...", base_url="http://localhost:8080/api/v1")
+```
+
+Every method maps to an API endpoint and returns plain dicts. Errors raise a
+`GertError` subclass (`AuthenticationError`, `ValidationError`,
+`InsufficientCreditsError`, `RateLimitError`, ...). Async work returns a
+`job_id`; block on it with `client.jobs.wait(job_id)`.
+
+## Play locally with your own model (nothing shared)
+
+Control one or more seats yourself: the platform sends observations, you run your
+model in your own environment, and you submit actions. No provider registration,
+no org, nothing about your model leaves your machine. Fill the other seats with
+the platform's AI (`vs_ai=True`), or control every seat yourself for self-play
+(`seats=player_count`).
+
+```python
+from gertlabs import GertClient
+client = GertClient()
+
+s = client.play.create(game="market_simulator", seats=1, vs_ai=True, max_ticks=600)
+prompt = s["prompt"]            # game rules + observation/action schema
+
+def decide(observation):
+    # your local model/policy -- never leaves your machine
+    return []                   # see prompt for valid actions
+
+with client.play.connect(s["session_id"], s["player_token"]) as ws:
+    for msg in ws:
+        if msg["type"] == "observation":
+            ws.send_action(decide(msg["data"]))
+        elif msg["type"] == "game_completed":
+            print(msg["scores"]); break
+```
+
+Prefer REST over WebSockets? Poll `client.play.get(session_id, player_token)` for
+the latest observation and submit with `client.play.act(...)` -- same loop.
+
+## Quickstart: build a training dataset across many games
+
+The platform's batch engine runs your model across a whole category of games in
+one job: generate code, evaluate it, and export the results.
+
+```python
+from gertlabs import GertClient
+client = GertClient()
+
+# Discover what's available -- no need to hardcode slugs
+print(client.games.tags(active=True))            # categories + game counts
+
+# Register your model endpoint ONCE in the dashboard (Org > Providers): it stores
+# your upstream key and sets where your prompts are routed, so it's an interactive
+# setup step. Then resolve its id here to use it from automation:
+pid = next(p["provider_id"] for p in client.providers.list()
+           if p["name"] == "my-model-v3")
+
+# Estimate cost before spending
+est = client.dataset_builds.evaluate_code(
+    game_tags=["strategy"], custom_provider_id=pid,
+    submission_count=20, match_count=200,
+    export_type="both", export_format="parquet", dry_run=True,
+)
+print(est["estimated_credits"])
+
+# Run across every strategy game: generate -> evaluate -> export
+build = client.dataset_builds.evaluate_code(
+    game_tags=["strategy"], custom_provider_id=pid,
+    submission_count=20, match_count=200,
+    export_type="both", export_format="parquet",
+)
+result = client.jobs.wait(build["job_id"], timeout=7200)["result"]
+
+# Load each export (submissions + replays) into pandas
+for export_id in result["export_job_ids"]:
+    client.jobs.wait(export_id)
+    df = client.exports.load(export_id)
+    print(len(df), "rows")
+```
+
+## Counterfactual data (branch exploration)
+
+```python
+build = client.dataset_builds.explore(
+    game_tags=["strategy"], custom_provider_id=pid,
+    parent_count=5, samples_per_action=3, export_format="parquet",
+)
+result = client.jobs.wait(build["job_id"], timeout=7200)["result"]
+client.jobs.wait(result["export_job_id"])        # singular in this mode
+df = client.exports.load(result["export_job_id"])
+```
+
+## Export only top performers (filter by evaluation score)
+
+```python
+job = client.exports.create(
+    export_type="submissions", min_percentile=0.9,
+    tags=["strategy"], format="parquet",
+)
+client.jobs.wait(job["job_id"])
+df = client.exports.load(job["job_id"])
+```
+
+## Connected model: let the platform run it server-side, then branch
+
+This is the *connected-model* path (contrast with local play above): the platform
+drives your registered provider as an AI seat, so you can spectate and branch
+without running inference yourself.
+
+```python
+session = client.play.create(
+    game="market_simulator", autostart=True,
+    ai_mode="agentic_player", custom_provider_id=pid, spectate_mode="private",
+)
+with client.play.spectate(session["session_id"]) as ws:
+    for msg in ws:
+        if msg["type"] == "game_completed":
+            print(msg["scores"]); break
+
+# fan out 8 counterfactual branches from a checkpoint
+client.play.branch(session["session_id"], count=8)
+```
+
+## Fine-grained control
+
+For a single hand-written submission instead of a batch build:
+
+```python
+sub = client.submissions.create(game="market_simulator", language="python", code=SOURCE)
+client.jobs.wait(sub["job_id"]) if "job_id" in sub else None
+ev = client.submissions.evaluate(sub["submission_id"], match_count=500)
+client.jobs.wait(ev["job_id"])
+print(client.submissions.get(sub["submission_id"])["elo_rating"])
+```
+
+## Resource reference
+
+| Resource | Methods |
+|----------|---------|
+| `client.games` | `list`, `get`, `tags` |
+| `client.dataset_builds` | `evaluate_code`, `explore` |
+| `client.exports` | `list`, `create`, `get`, `download`, `load`, `reset_tracking` |
+| `client.jobs` | `get`, `wait` |
+| `client.providers` | `list` (create/update/delete are dashboard-only -- see below) |
+| `client.submissions` | `list`, `get`, `create`, `delete`, `evaluate`, `batch_evaluate` |
+| `client.sessions` | `list`, `get`, `logs`, `branches`, `branch_scores`, `delete` |
+| `client.billing` | `balance`, `usage` |
+| `client.play` | `create`, `join`, `branch`, `get`, `act`, `leave`, `connect`, `spectate` |
+
+List methods follow cursor pagination automatically and return a full list.
+Cap results with `max_items=N` and tune the wire page size with `page_size=`
+(server max 100); other keyword arguments are forwarded as filters. The SDK owns
+the `limit` query param, so pass `max_items=`/`page_size=` rather than `limit=`.
+
+## Providers are configured in the dashboard
+
+Registering a custom provider stores your upstream model's secret and decides
+where your org's prompts are sent -- a one-time trust decision the platform gates
+to interactive (logged-in) sessions and does not allow with an API key. So the
+SDK exposes only `client.providers.list()` (to resolve a `provider_id`); create
+the provider once in the dashboard under Org > Providers.
+
+## Errors
+
+API errors raise a `GertError` subclass (`AuthenticationError`,
+`PermissionError`, `NotFoundError`, `ValidationError`, `ConflictError`,
+`InsufficientCreditsError`, `RateLimitError`, `ServerError`). Each carries
+`.code`, `.status`, `.request_id`, and `.body` (the full parsed error response).
+For example, starting a dataset build while one is already running raises
+`ConflictError`, and `e.body["existing_job_id"]` is the id of the in-flight job:
+
+```python
+from gertlabs import ConflictError
+try:
+    build = client.dataset_builds.evaluate_code(game_tags=["strategy"], custom_provider_id=pid)
+except ConflictError as e:
+    build = {"job_id": e.body["existing_job_id"]}   # wait on the existing build
+client.jobs.wait(build["job_id"])
+```

gertlabs-0.1.0/README.md

@@ -0,0 +1,212 @@
+# Gert Labs Python SDK
+
+A thin, synchronous Python wrapper over the Gert Labs REST API, for AI
+researchers. Two ways to put your model in the games:
+
+- **Play locally -- nothing shared.** Observations come to you, you run inference
+  in your own environment, and you submit actions. Your model, its weights, and
+  its keys never touch our backend.
+- **Connect a model.** Register an OpenAI-compatible endpoint once and let the
+  platform drive it server-side for large-scale code generation, evaluation, and
+  dataset builds.
+
+Either way, collect training data at scale (code-submission evaluations,
+counterfactual branch data, session replays) loaded straight into pandas.
+
+## Install
+
+```bash
+pip install gertlabs           # core
+pip install 'gertlabs[data]'   # + pandas/pyarrow for exports.load()
+```
+
+## Authentication
+
+Create an API key in the dashboard (`sk_gert_...`) and set it in your
+environment:
+
+```bash
+export GERT_API_KEY=sk_gert_...
+```
+
+```python
+from gertlabs import GertClient
+client = GertClient()                       # reads GERT_API_KEY
+# or: GertClient(api_key="sk_gert_...", base_url="http://localhost:8080/api/v1")
+```
+
+Every method maps to an API endpoint and returns plain dicts. Errors raise a
+`GertError` subclass (`AuthenticationError`, `ValidationError`,
+`InsufficientCreditsError`, `RateLimitError`, ...). Async work returns a
+`job_id`; block on it with `client.jobs.wait(job_id)`.
+
+## Play locally with your own model (nothing shared)
+
+Control one or more seats yourself: the platform sends observations, you run your
+model in your own environment, and you submit actions. No provider registration,
+no org, nothing about your model leaves your machine. Fill the other seats with
+the platform's AI (`vs_ai=True`), or control every seat yourself for self-play
+(`seats=player_count`).
+
+```python
+from gertlabs import GertClient
+client = GertClient()
+
+s = client.play.create(game="market_simulator", seats=1, vs_ai=True, max_ticks=600)
+prompt = s["prompt"]            # game rules + observation/action schema
+
+def decide(observation):
+    # your local model/policy -- never leaves your machine
+    return []                   # see prompt for valid actions
+
+with client.play.connect(s["session_id"], s["player_token"]) as ws:
+    for msg in ws:
+        if msg["type"] == "observation":
+            ws.send_action(decide(msg["data"]))
+        elif msg["type"] == "game_completed":
+            print(msg["scores"]); break
+```
+
+Prefer REST over WebSockets? Poll `client.play.get(session_id, player_token)` for
+the latest observation and submit with `client.play.act(...)` -- same loop.
+
+## Quickstart: build a training dataset across many games
+
+The platform's batch engine runs your model across a whole category of games in
+one job: generate code, evaluate it, and export the results.
+
+```python
+from gertlabs import GertClient
+client = GertClient()
+
+# Discover what's available -- no need to hardcode slugs
+print(client.games.tags(active=True))            # categories + game counts
+
+# Register your model endpoint ONCE in the dashboard (Org > Providers): it stores
+# your upstream key and sets where your prompts are routed, so it's an interactive
+# setup step. Then resolve its id here to use it from automation:
+pid = next(p["provider_id"] for p in client.providers.list()
+           if p["name"] == "my-model-v3")
+
+# Estimate cost before spending
+est = client.dataset_builds.evaluate_code(
+    game_tags=["strategy"], custom_provider_id=pid,
+    submission_count=20, match_count=200,
+    export_type="both", export_format="parquet", dry_run=True,
+)
+print(est["estimated_credits"])
+
+# Run across every strategy game: generate -> evaluate -> export
+build = client.dataset_builds.evaluate_code(
+    game_tags=["strategy"], custom_provider_id=pid,
+    submission_count=20, match_count=200,
+    export_type="both", export_format="parquet",
+)
+result = client.jobs.wait(build["job_id"], timeout=7200)["result"]
+
+# Load each export (submissions + replays) into pandas
+for export_id in result["export_job_ids"]:
+    client.jobs.wait(export_id)
+    df = client.exports.load(export_id)
+    print(len(df), "rows")
+```
+
+## Counterfactual data (branch exploration)
+
+```python
+build = client.dataset_builds.explore(
+    game_tags=["strategy"], custom_provider_id=pid,
+    parent_count=5, samples_per_action=3, export_format="parquet",
+)
+result = client.jobs.wait(build["job_id"], timeout=7200)["result"]
+client.jobs.wait(result["export_job_id"])        # singular in this mode
+df = client.exports.load(result["export_job_id"])
+```
+
+## Export only top performers (filter by evaluation score)
+
+```python
+job = client.exports.create(
+    export_type="submissions", min_percentile=0.9,
+    tags=["strategy"], format="parquet",
+)
+client.jobs.wait(job["job_id"])
+df = client.exports.load(job["job_id"])
+```
+
+## Connected model: let the platform run it server-side, then branch
+
+This is the *connected-model* path (contrast with local play above): the platform
+drives your registered provider as an AI seat, so you can spectate and branch
+without running inference yourself.
+
+```python
+session = client.play.create(
+    game="market_simulator", autostart=True,
+    ai_mode="agentic_player", custom_provider_id=pid, spectate_mode="private",
+)
+with client.play.spectate(session["session_id"]) as ws:
+    for msg in ws:
+        if msg["type"] == "game_completed":
+            print(msg["scores"]); break
+
+# fan out 8 counterfactual branches from a checkpoint
+client.play.branch(session["session_id"], count=8)
+```
+
+## Fine-grained control
+
+For a single hand-written submission instead of a batch build:
+
+```python
+sub = client.submissions.create(game="market_simulator", language="python", code=SOURCE)
+client.jobs.wait(sub["job_id"]) if "job_id" in sub else None
+ev = client.submissions.evaluate(sub["submission_id"], match_count=500)
+client.jobs.wait(ev["job_id"])
+print(client.submissions.get(sub["submission_id"])["elo_rating"])
+```
+
+## Resource reference
+
+| Resource | Methods |
+|----------|---------|
+| `client.games` | `list`, `get`, `tags` |
+| `client.dataset_builds` | `evaluate_code`, `explore` |
+| `client.exports` | `list`, `create`, `get`, `download`, `load`, `reset_tracking` |
+| `client.jobs` | `get`, `wait` |
+| `client.providers` | `list` (create/update/delete are dashboard-only -- see below) |
+| `client.submissions` | `list`, `get`, `create`, `delete`, `evaluate`, `batch_evaluate` |
+| `client.sessions` | `list`, `get`, `logs`, `branches`, `branch_scores`, `delete` |
+| `client.billing` | `balance`, `usage` |
+| `client.play` | `create`, `join`, `branch`, `get`, `act`, `leave`, `connect`, `spectate` |
+
+List methods follow cursor pagination automatically and return a full list.
+Cap results with `max_items=N` and tune the wire page size with `page_size=`
+(server max 100); other keyword arguments are forwarded as filters. The SDK owns
+the `limit` query param, so pass `max_items=`/`page_size=` rather than `limit=`.
+
+## Providers are configured in the dashboard
+
+Registering a custom provider stores your upstream model's secret and decides
+where your org's prompts are sent -- a one-time trust decision the platform gates
+to interactive (logged-in) sessions and does not allow with an API key. So the
+SDK exposes only `client.providers.list()` (to resolve a `provider_id`); create
+the provider once in the dashboard under Org > Providers.
+
+## Errors
+
+API errors raise a `GertError` subclass (`AuthenticationError`,
+`PermissionError`, `NotFoundError`, `ValidationError`, `ConflictError`,
+`InsufficientCreditsError`, `RateLimitError`, `ServerError`). Each carries
+`.code`, `.status`, `.request_id`, and `.body` (the full parsed error response).
+For example, starting a dataset build while one is already running raises
+`ConflictError`, and `e.body["existing_job_id"]` is the id of the in-flight job:
+
+```python
+from gertlabs import ConflictError
+try:
+    build = client.dataset_builds.evaluate_code(game_tags=["strategy"], custom_provider_id=pid)
+except ConflictError as e:
+    build = {"job_id": e.body["existing_job_id"]}   # wait on the existing build
+client.jobs.wait(build["job_id"])
+```

gertlabs-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gertlabs"
+dynamic = ["version"]
+description = "Python SDK for the Gert Labs competitive AI game evaluation platform"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Gert Labs" }]
+dependencies = [
+    "httpx>=0.27",
+    "websocket-client>=1.6",
+]
+
+[project.optional-dependencies]
+data = ["pandas>=2.0", "pyarrow>=15.0"]
+test = ["pytest>=8.0"]
+
+[project.urls]
+Homepage = "https://gertlabs.com"
+Repository = "https://github.com/Gert-Labs-Inc/gertlabs"
+Documentation = "https://gertlabs.com/docs"
+
+[tool.hatch.version]
+path = "src/gertlabs/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gertlabs"]

gertlabs-0.1.0/src/gertlabs/__init__.py

@@ -0,0 +1,39 @@
+"""Gert Labs Python SDK.
+
+A thin, synchronous wrapper over the Gert Labs REST API for AI researchers:
+register a model endpoint, run it across game environments, and collect
+training data at scale.
+
+    from gertlabs import GertClient
+    client = GertClient()  # reads GERT_API_KEY
+"""
+
+from .client import GertClient
+from .exceptions import (
+    AuthenticationError,
+    ConflictError,
+    GertError,
+    InsufficientCreditsError,
+    JobFailed,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "GertClient",
+    "GertError",
+    "AuthenticationError",
+    "PermissionError",
+    "NotFoundError",
+    "ValidationError",
+    "ConflictError",
+    "InsufficientCreditsError",
+    "RateLimitError",
+    "ServerError",
+    "JobFailed",
+]

gertlabs-0.1.0/src/gertlabs/client.py

@@ -0,0 +1,135 @@
+"""HTTP transport and entry point for the Gert Labs SDK."""
+
+import os
+
+import httpx
+
+from . import exceptions
+from .resources import (
+    Billing,
+    DatasetBuilds,
+    Exports,
+    Games,
+    Jobs,
+    Play,
+    Providers,
+    Sessions,
+    Submissions,
+)
+
+DEFAULT_BASE_URL = "https://gertlabs.com/api/v1"
+
+
+class GertClient:
+    """Client for the Gert Labs platform REST API.
+
+    Authenticates with a platform API key (``sk_gert_...``). Resolve order for
+    each argument: explicit parameter, then environment variable
+    (``GERT_API_KEY`` / ``GERT_BASE_URL``).
+
+    Resource groups mirror the API: ``client.games``, ``client.dataset_builds``,
+    ``client.exports``, ``client.jobs``, ``client.providers``,
+    ``client.submissions``, ``client.sessions``, ``client.billing``,
+    ``client.play``.
+    """
+
+    def __init__(self, api_key=None, base_url=None, timeout=30.0):
+        api_key = api_key or os.environ.get("GERT_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "No API key provided. Pass api_key= or set the GERT_API_KEY environment variable."
+            )
+        self.api_key = api_key
+        self.base_url = (base_url or os.environ.get("GERT_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers={"X-API-Key": api_key},
+            timeout=timeout,
+        )
+
+        self.games = Games(self)
+        self.dataset_builds = DatasetBuilds(self)
+        self.exports = Exports(self)
+        self.jobs = Jobs(self)
+        self.providers = Providers(self)
+        self.submissions = Submissions(self)
+        self.sessions = Sessions(self)
+        self.billing = Billing(self)
+        self.play = Play(self)
+
+    def request(self, method, path, json=None, params=None, headers=None):
+        """Send a request and return the unwrapped ``data`` payload.
+
+        Drops None values from ``json`` and ``params`` so callers can pass
+        optional fields as keyword arguments without sending nulls. Raises a
+        GertError subclass on any 4xx/5xx response.
+        """
+        if json is not None:
+            json = {k: v for k, v in json.items() if v is not None}
+        if params is not None:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        resp = self._http.request(method, path, json=json, params=params, headers=headers)
+        if resp.status_code >= 400:
+            self._raise(resp)
+        if resp.status_code == 204 or not resp.content:
+            return {}
+        body = resp.json()
+        return body.get("data", body) if isinstance(body, dict) else body
+
+    @staticmethod
+    def _raise(resp):
+        code = message = request_id = None
+        body = None
+        try:
+            body = resp.json()
+            err = body.get("error") or {}
+            code = err.get("code")
+            message = err.get("message")
+            request_id = body.get("request_id")
+        except Exception:
+            message = resp.text or None
+        raise exceptions.from_response(resp.status_code, code, message, request_id, body=body)
+
+    def paginate(self, path, key, *, params=None, max_items=None, page_size=100):
+        """Yield items across cursor pages of a list endpoint.
+
+        ``key`` is the collection field in the response (e.g. "games",
+        "submissions"). Follows ``next_cursor`` until exhausted or ``max_items``
+        items have been yielded. ``max_items`` must be >= 0 (0 yields nothing).
+        ``page_size`` is the wire page size and must be 1..100 (the server's max).
+        The SDK owns the ``limit`` query param, so passing ``limit`` in ``params``
+        is an error.
+        """
+        params = dict(params or {})
+        if "limit" in params:
+            raise TypeError("pass page_size= / max_items= instead of limit=")
+        if max_items is not None and max_items < 0:
+            raise ValueError("max_items must be >= 0")
+        if not 1 <= page_size <= 100:
+            raise ValueError("page_size must be between 1 and 100")
+        if max_items == 0:
+            return
+        params["limit"] = min(page_size, max_items) if max_items is not None else page_size
+        count = 0
+        while True:
+            data = self.request("GET", path, params=params)
+            items = data.get(key, [])
+            for item in items:
+                yield item
+                count += 1
+                if max_items is not None and count >= max_items:
+                    return
+            cursor = data.get("next_cursor")
+            if not cursor or not items:
+                return
+            params["cursor"] = cursor
+
+    def close(self):
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()