grid-sdk 0.1.1__tar.gz

grid_sdk-0.1.1/LICENSE

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

grid_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: grid-sdk
+Version: 0.1.1
+Summary: Python SDK for AI Power Grid open-model, OpenAI-compatible inference.
+Author: AI Power Grid
+License-Expression: MIT
+Project-URL: Homepage, https://aipowergrid.io
+Project-URL: Documentation, https://aipowergrid.io/docs
+Project-URL: Repository, https://github.com/AIPowerGrid/grid-sdk-python
+Keywords: ai,llm,inference,openai,decentralized,aipg
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.0.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: respx; extra == "test"
+Requires-Dist: httpx; extra == "test"
+Dynamic: license-file
+
+# AI Power Grid — Python SDK
+
+Open-model, OpenAI-compatible inference across community-operated GPUs.
+
+> **Release status:** `grid-sdk` is staged for its initial PyPI publication.
+> The install command below becomes available when the first verified release
+> is published; until then, use the OpenAI SDK with the Grid base URL shown below.
+
+The Grid API speaks the OpenAI protocol, so this SDK is a thin layer over the
+official `openai` package: it points at the Grid, reads your key from the
+environment, and adds Grid-specific conveniences. Everything you know from the
+OpenAI SDK works unchanged.
+
+## Install
+
+```bash
+pip install grid-sdk
+```
+
+## Quick start
+
+Sign in at the [Grid developer console](https://console.aipowergrid.io/dashboard/api-key),
+create an API key, then set it as `AIPG_API_KEY`:
+
+```python
+from grid_sdk import Grid
+
+client = Grid()  # reads AIPG_API_KEY from the environment
+
+stream = client.chat.completions.create(
+    model="gpt-oss-120b",
+    messages=[{"role": "user", "content": "Explain AI Power Grid in one line."}],
+    stream=True,
+)
+for chunk in stream:
+    print(chunk.choices[0].delta.content or "", end="", flush=True)
+```
+
+## See what's online
+
+The Grid's available models change as workers connect and disconnect. Don't
+hardcode a model blindly — ask which ones are servable right now:
+
+```python
+client = Grid()
+print(client.online_models())
+# ['gpt-oss-120b', 'qwen3-27b', ...]
+```
+
+An empty list means no workers are connected — requests will 503 until one is.
+
+## Credits
+
+```python
+credits = client.grid.credits()
+print(credits["total_spendable_usd"])
+```
+
+This is Core's canonical promotional, daily-free, and purchased account view.
+The SDK does not maintain a local free-use counter.
+
+## Async
+
+```python
+import asyncio
+from grid_sdk import AsyncGrid
+
+async def main():
+    client = AsyncGrid()
+    resp = await client.chat.completions.create(
+        model="gpt-oss-120b",
+        messages=[{"role": "user", "content": "Hi"}],
+    )
+    print(resp.choices[0].message.content)
+
+asyncio.run(main())
+```
+
+## Video, img2img, ControlNet, LoRAs — the full Grid
+
+The OpenAI-compatible surface covers text and basic txt2img. For the full media
+parameter surface, use `client.grid`, which calls the synchronous `/v1` image
+and video endpoints:
+
+```python
+client = Grid()
+
+# Video:
+result = client.grid.video(
+    prompt="a timelapse of a city at night",
+    model="LTX-2.3",
+    width=768, height=512, seconds=4, fps=24,
+)
+
+# img2img / ControlNet / LoRAs — anything the workers support:
+result = client.grid.image(
+    prompt="make it watercolor",
+    models=["FLUX.2 Klein 4B FP8"],
+    source_image="<base64>",
+    loras=[{"name": "watercolor", "model": 1.0}],
+)
+
+# Or full control with a raw payload:
+result = client.grid.generate({"prompt": "...", "models": [...], "params": {...}})
+```
+
+`client.grid` waits for the synchronous Grid response and returns the finished
+OpenAI-shaped result. Use `timeout` for long media jobs; there is no SDK
+submit/poll mode on this `/v1` client.
+
+## It's just OpenAI underneath
+
+`Grid` subclasses `openai.OpenAI`, so anything the OpenAI SDK does — images,
+tool calling, structured output, the full `.chat`/`.images`/`.models` surface —
+works here too. You can also point existing OpenAI code at the Grid by setting
+`base_url="https://api.aipowergrid.io/v1"` if you'd rather not switch packages.
+
+## Config
+
+| | |
+|---|---|
+| `Grid(api_key=...)` | Explicit key (overrides env) |
+| `AIPG_API_KEY` | Env var read when no key is passed |
+| `Grid(base_url=...)` | Override the endpoint (default `https://api.aipowergrid.io/v1`) |
+
+## Links
+
+- [Docs](https://aipowergrid.io/docs)
+- [Get an API key](https://console.aipowergrid.io/dashboard/api-key)
+- [Discord](https://discord.gg/W9D8j6HCtC)
+
+## License
+
+MIT

grid_sdk-0.1.1/README.md

@@ -0,0 +1,134 @@
+# AI Power Grid — Python SDK
+
+Open-model, OpenAI-compatible inference across community-operated GPUs.
+
+> **Release status:** `grid-sdk` is staged for its initial PyPI publication.
+> The install command below becomes available when the first verified release
+> is published; until then, use the OpenAI SDK with the Grid base URL shown below.
+
+The Grid API speaks the OpenAI protocol, so this SDK is a thin layer over the
+official `openai` package: it points at the Grid, reads your key from the
+environment, and adds Grid-specific conveniences. Everything you know from the
+OpenAI SDK works unchanged.
+
+## Install
+
+```bash
+pip install grid-sdk
+```
+
+## Quick start
+
+Sign in at the [Grid developer console](https://console.aipowergrid.io/dashboard/api-key),
+create an API key, then set it as `AIPG_API_KEY`:
+
+```python
+from grid_sdk import Grid
+
+client = Grid()  # reads AIPG_API_KEY from the environment
+
+stream = client.chat.completions.create(
+    model="gpt-oss-120b",
+    messages=[{"role": "user", "content": "Explain AI Power Grid in one line."}],
+    stream=True,
+)
+for chunk in stream:
+    print(chunk.choices[0].delta.content or "", end="", flush=True)
+```
+
+## See what's online
+
+The Grid's available models change as workers connect and disconnect. Don't
+hardcode a model blindly — ask which ones are servable right now:
+
+```python
+client = Grid()
+print(client.online_models())
+# ['gpt-oss-120b', 'qwen3-27b', ...]
+```
+
+An empty list means no workers are connected — requests will 503 until one is.
+
+## Credits
+
+```python
+credits = client.grid.credits()
+print(credits["total_spendable_usd"])
+```
+
+This is Core's canonical promotional, daily-free, and purchased account view.
+The SDK does not maintain a local free-use counter.
+
+## Async
+
+```python
+import asyncio
+from grid_sdk import AsyncGrid
+
+async def main():
+    client = AsyncGrid()
+    resp = await client.chat.completions.create(
+        model="gpt-oss-120b",
+        messages=[{"role": "user", "content": "Hi"}],
+    )
+    print(resp.choices[0].message.content)
+
+asyncio.run(main())
+```
+
+## Video, img2img, ControlNet, LoRAs — the full Grid
+
+The OpenAI-compatible surface covers text and basic txt2img. For the full media
+parameter surface, use `client.grid`, which calls the synchronous `/v1` image
+and video endpoints:
+
+```python
+client = Grid()
+
+# Video:
+result = client.grid.video(
+    prompt="a timelapse of a city at night",
+    model="LTX-2.3",
+    width=768, height=512, seconds=4, fps=24,
+)
+
+# img2img / ControlNet / LoRAs — anything the workers support:
+result = client.grid.image(
+    prompt="make it watercolor",
+    models=["FLUX.2 Klein 4B FP8"],
+    source_image="<base64>",
+    loras=[{"name": "watercolor", "model": 1.0}],
+)
+
+# Or full control with a raw payload:
+result = client.grid.generate({"prompt": "...", "models": [...], "params": {...}})
+```
+
+`client.grid` waits for the synchronous Grid response and returns the finished
+OpenAI-shaped result. Use `timeout` for long media jobs; there is no SDK
+submit/poll mode on this `/v1` client.
+
+## It's just OpenAI underneath
+
+`Grid` subclasses `openai.OpenAI`, so anything the OpenAI SDK does — images,
+tool calling, structured output, the full `.chat`/`.images`/`.models` surface —
+works here too. You can also point existing OpenAI code at the Grid by setting
+`base_url="https://api.aipowergrid.io/v1"` if you'd rather not switch packages.
+
+## Config
+
+| | |
+|---|---|
+| `Grid(api_key=...)` | Explicit key (overrides env) |
+| `AIPG_API_KEY` | Env var read when no key is passed |
+| `Grid(base_url=...)` | Override the endpoint (default `https://api.aipowergrid.io/v1`) |
+
+## Links
+
+- [Docs](https://aipowergrid.io/docs)
+- [Get an API key](https://console.aipowergrid.io/dashboard/api-key)
+- [Discord](https://discord.gg/W9D8j6HCtC)
+
+## License
+
+MIT

grid_sdk-0.1.1/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools==82.0.1", "wheel==0.48.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "grid-sdk"
+version = "0.1.1"
+description = "Python SDK for AI Power Grid open-model, OpenAI-compatible inference."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "AI Power Grid" }]
+keywords = ["ai", "llm", "inference", "openai", "decentralized", "aipg"]
+dependencies = [
+    "openai>=1.0.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-asyncio", "respx", "httpx"]
+
+[project.urls]
+Homepage = "https://aipowergrid.io"
+Documentation = "https://aipowergrid.io/docs"
+Repository = "https://github.com/AIPowerGrid/grid-sdk-python"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

grid_sdk-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

grid_sdk-0.1.1/src/grid_sdk/__init__.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+"""AI Power Grid Python SDK.
+
+The Grid API is OpenAI-compatible, so this SDK is a thin layer over the
+official `openai` client: it pre-points at the Grid, reads your key from the
+environment, and adds Grid-specific conveniences (listing online models, and
+`client.grid` for video / advanced image generation). Anything you can do
+with the `openai` package, you can do here — same `.chat`, `.images`,
+`.models`.
+
+    from grid_sdk import Grid
+
+    client = Grid()  # reads AIPG_API_KEY from the environment
+
+    stream = client.chat.completions.create(
+        model="grid/llama-3.3-70b-versatile",
+        messages=[{"role": "user", "content": "Hello!"}],
+        stream=True,
+    )
+    for chunk in stream:
+        print(chunk.choices[0].delta.content or "", end="")
+
+`AIPG` / `AsyncAIPG` are kept as aliases of `Grid` / `AsyncGrid`.
+"""
+
+from .client import AIPG, AsyncAIPG, AsyncGrid, Grid, DEFAULT_BASE_URL
+
+__all__ = ["Grid", "AsyncGrid", "AIPG", "AsyncAIPG", "DEFAULT_BASE_URL"]
+__version__ = "0.1.1"

grid_sdk-0.1.1/src/grid_sdk/client.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: MIT
+"""Grid clients — thin subclasses of the OpenAI client.
+
+We subclass rather than wrap so every current and future feature of the
+`openai` package (chat, images, streaming, tool use, etc.) is available with
+zero extra surface area. We only override the defaults (base URL, key source)
+and add Grid-specific helpers.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import List, Optional
+
+from openai import AsyncOpenAI, OpenAI
+
+from .grid import AsyncGridRaw, GridRaw
+
+DEFAULT_BASE_URL = "https://api.aipowergrid.io/v1"
+API_KEY_ENV = "AIPG_API_KEY"
+
+
+def _resolve_key(api_key: Optional[str]) -> str:
+    key = api_key or os.getenv(API_KEY_ENV)
+    if not key:
+        raise ValueError(
+            f"No API key provided. Pass api_key=... or set the {API_KEY_ENV} "
+            f"environment variable. Create a key at https://console.aipowergrid.io/dashboard/api-key"
+        )
+    return key
+
+
+class Grid(OpenAI):
+    """Synchronous AI Power Grid client.
+
+    Drop-in for `openai.OpenAI`, pre-configured for the Grid:
+
+        client = Grid()                       # key from AIPG_API_KEY
+        client = Grid(api_key="grid-...")     # or explicit
+
+    Use `client.chat`, `client.images`, etc. exactly as you would with the
+    OpenAI SDK. Plus `client.online_models()` for what's servable right now,
+    and `client.grid` for video / advanced image generation.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, base_url: str = DEFAULT_BASE_URL, **kwargs):
+        super().__init__(api_key=_resolve_key(api_key), base_url=base_url, **kwargs)
+        # Raw-Grid access (video, img2img, ControlNet, LoRAs) beyond the
+        # OpenAI-compatible surface. See grid_sdk.grid.GridRaw.
+        self.grid = GridRaw(self.api_key, str(self.base_url))
+
+    def online_models(self) -> List[str]:
+        """Return the model IDs currently served by connected workers.
+
+        An empty list means no workers are online right now — requests will
+        return 503 until one connects. Prefer this over a hardcoded model
+        name, since the Grid's available models shift with worker presence.
+        """
+        return [m.id for m in self.models.list().data]
+
+
+class AsyncGrid(AsyncOpenAI):
+    """Asynchronous AI Power Grid client. Async twin of :class:`Grid`."""
+
+    def __init__(self, api_key: Optional[str] = None, base_url: str = DEFAULT_BASE_URL, **kwargs):
+        super().__init__(api_key=_resolve_key(api_key), base_url=base_url, **kwargs)
+        self.grid = AsyncGridRaw(self.api_key, str(self.base_url))
+
+    async def online_models(self) -> List[str]:
+        """Async variant of :meth:`Grid.online_models`."""
+        models = await self.models.list()
+        return [m.id for m in models.data]
+
+
+# Backwards-friendly aliases. `Grid` is the preferred name; `AIPG` is kept so
+# existing references and the brand both resolve.
+AIPG = Grid
+AsyncAIPG = AsyncGrid

grid_sdk-0.1.1/src/grid_sdk/grid.py

@@ -0,0 +1,261 @@
+# SPDX-License-Identifier: MIT
+"""Raw Grid media access — video + advanced image beyond OpenAI-compat chat.
+
+The OpenAI-compatible ``/v1`` endpoints cover text and basic txt2img. This adds
+the grid's SYNCHRONOUS media endpoints — ``/v1/images/generations`` (full param
+surface: img2img, LoRAs, styles, samplers) and ``/v1/videos/generations`` — as
+``client.grid``. Both are synchronous: the call returns the finished result
+(hosted media.aipg.art URLs), no submit/poll. (Replaces the retired horde
+``/api/v2`` async queue.)
+
+    client = AIPG()
+
+    vid = client.grid.video("a city timelapse", model="LTX-2.3",
+                            width=768, height=512, seconds=4)
+    print(vid["data"][0]["url"])
+
+    img = client.grid.image("make it watercolor", model="FLUX.2 Klein 4B FP8",
+                            source_image="<base64>", strength=0.6,
+                            loras=[{"name": "watercolor", "model": 1.0}])
+    print(img["data"][0]["url"])
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+
+class GridError(RuntimeError):
+    pass
+
+
+def _v1_base(base_url: str) -> str:
+    """The client base already ends in /v1; just strip trailing slashes."""
+    return str(base_url).rstrip("/")
+
+
+def _image_body(
+    prompt: str,
+    model: Optional[str],
+    models: Optional[List[str]],
+    width: int,
+    height: int,
+    steps: Optional[int],
+    cfg_scale: Optional[float],
+    sampler_name: Optional[str],
+    n: int,
+    source_image: Optional[str],
+    strength: Optional[float],
+    negative_prompt: Optional[str],
+    loras: Optional[list],
+    style: Optional[str],
+    params: Dict[str, Any],
+) -> Dict[str, Any]:
+    body: Dict[str, Any] = {
+        "model": model or (models[0] if models else None),
+        "prompt": prompt,
+        "n": n,
+        "size": f"{width}x{height}",
+    }
+    if steps is not None:
+        body["steps"] = steps
+    if cfg_scale is not None:
+        body["cfg_scale"] = cfg_scale
+    if sampler_name is not None:
+        body["sampler"] = sampler_name
+    if negative_prompt is not None:
+        body["negative_prompt"] = negative_prompt
+    if loras is not None:
+        body["loras"] = loras
+    if style is not None:
+        body["style"] = style
+    if source_image is not None:
+        body["image"] = source_image
+        if strength is not None:
+            body["strength"] = strength
+    body.update(params)
+    return body
+
+
+def _video_body(
+    prompt: str,
+    model: Optional[str],
+    models: Optional[List[str]],
+    width: int,
+    height: int,
+    seconds: Optional[float],
+    fps: Optional[int],
+    source_image: Optional[str],
+    params: Dict[str, Any],
+) -> Dict[str, Any]:
+    body: Dict[str, Any] = {
+        "model": model or (models[0] if models else None),
+        "prompt": prompt,
+        "size": f"{width}x{height}",
+    }
+    if seconds is not None:
+        body["seconds"] = seconds
+    if fps is not None:
+        body["fps"] = fps
+    if source_image is not None:
+        body["image"] = source_image
+    body.update(params)
+    return body
+
+
+class GridRaw:
+    """Synchronous raw-Grid media client. Reached via ``AIPG().grid``."""
+
+    def __init__(self, api_key: str, base_url: str, timeout: float = 300.0):
+        self._headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
+        self._base = _v1_base(base_url)
+        self._timeout = timeout
+
+    def _post(self, path: str, body: Dict[str, Any], timeout: float) -> Dict[str, Any]:
+        with httpx.Client(timeout=timeout) as c:
+            r = c.post(f"{self._base}{path}", headers=self._headers, json=body)
+            if r.status_code != 200:
+                raise GridError(f"{path} failed [{r.status_code}]: {r.text[:300]}")
+            return r.json()
+
+    def _get(self, path: str, timeout: float = 30.0) -> Dict[str, Any]:
+        with httpx.Client(timeout=timeout) as c:
+            r = c.get(f"{self._base}{path}", headers=self._headers)
+            if r.status_code != 200:
+                raise GridError(f"{path} failed [{r.status_code}]: {r.text[:300]}")
+            return r.json()
+
+    def credits(self, *, timeout: float = 30.0) -> Dict[str, Any]:
+        """Return promotional, daily-free, purchased, and spendable credit pockets."""
+        return self._get("/account/credits", timeout)
+
+    def generate(
+        self, body: Dict[str, Any], *, endpoint: str = "/images/generations", timeout: float = 300.0
+    ) -> Dict[str, Any]:
+        """Raw passthrough: POST an arbitrary body to a media endpoint
+        (default ``/images/generations``). Returns the OpenAI-shaped response."""
+        return self._post(endpoint, body, timeout)
+
+    def image(
+        self,
+        prompt: str,
+        *,
+        model: Optional[str] = None,
+        models: Optional[List[str]] = None,
+        width: int = 1024,
+        height: int = 1024,
+        steps: Optional[int] = None,
+        cfg_scale: Optional[float] = None,
+        sampler_name: Optional[str] = None,
+        n: int = 1,
+        source_image: Optional[str] = None,
+        strength: Optional[float] = None,
+        negative_prompt: Optional[str] = None,
+        loras: Optional[list] = None,
+        style: Optional[str] = None,
+        timeout: float = 300.0,
+        **params: Any,
+    ) -> Dict[str, Any]:
+        """Image generation with the full param surface (img2img, LoRAs, styles).
+        ``models=[id]`` is accepted for back-compat; ``model=id`` is preferred.
+        Extra keywords (seed, scheduler, …) flow through to the request body."""
+        body = _image_body(
+            prompt, model, models, width, height, steps, cfg_scale, sampler_name,
+            n, source_image, strength, negative_prompt, loras, style, params,
+        )
+        return self._post("/images/generations", body, timeout)
+
+    def video(
+        self,
+        prompt: str,
+        *,
+        model: Optional[str] = None,
+        models: Optional[List[str]] = None,
+        width: int = 768,
+        height: int = 512,
+        seconds: Optional[float] = None,
+        fps: Optional[int] = None,
+        source_image: Optional[str] = None,
+        timeout: float = 600.0,
+        **params: Any,
+    ) -> Dict[str, Any]:
+        """Video generation (txt2video / img2video)."""
+        body = _video_body(prompt, model, models, width, height, seconds, fps, source_image, params)
+        return self._post("/videos/generations", body, timeout)
+
+
+class AsyncGridRaw:
+    """Asynchronous raw-Grid media client. Reached via ``AsyncAIPG().grid``."""
+
+    def __init__(self, api_key: str, base_url: str, timeout: float = 300.0):
+        self._headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
+        self._base = _v1_base(base_url)
+        self._timeout = timeout
+
+    async def _post(self, path: str, body: Dict[str, Any], timeout: float) -> Dict[str, Any]:
+        async with httpx.AsyncClient(timeout=timeout) as c:
+            r = await c.post(f"{self._base}{path}", headers=self._headers, json=body)
+            if r.status_code != 200:
+                raise GridError(f"{path} failed [{r.status_code}]: {r.text[:300]}")
+            return r.json()
+
+    async def _get(self, path: str, timeout: float = 30.0) -> Dict[str, Any]:
+        async with httpx.AsyncClient(timeout=timeout) as c:
+            r = await c.get(f"{self._base}{path}", headers=self._headers)
+            if r.status_code != 200:
+                raise GridError(f"{path} failed [{r.status_code}]: {r.text[:300]}")
+            return r.json()
+
+    async def credits(self, *, timeout: float = 30.0) -> Dict[str, Any]:
+        """Async variant of :meth:`GridRaw.credits`."""
+        return await self._get("/account/credits", timeout)
+
+    async def generate(
+        self, body: Dict[str, Any], *, endpoint: str = "/images/generations", timeout: float = 300.0
+    ) -> Dict[str, Any]:
+        return await self._post(endpoint, body, timeout)
+
+    async def image(
+        self,
+        prompt: str,
+        *,
+        model: Optional[str] = None,
+        models: Optional[List[str]] = None,
+        width: int = 1024,
+        height: int = 1024,
+        steps: Optional[int] = None,
+        cfg_scale: Optional[float] = None,
+        sampler_name: Optional[str] = None,
+        n: int = 1,
+        source_image: Optional[str] = None,
+        strength: Optional[float] = None,
+        negative_prompt: Optional[str] = None,
+        loras: Optional[list] = None,
+        style: Optional[str] = None,
+        timeout: float = 300.0,
+        **params: Any,
+    ) -> Dict[str, Any]:
+        body = _image_body(
+            prompt, model, models, width, height, steps, cfg_scale, sampler_name,
+            n, source_image, strength, negative_prompt, loras, style, params,
+        )
+        return await self._post("/images/generations", body, timeout)
+
+    async def video(
+        self,
+        prompt: str,
+        *,
+        model: Optional[str] = None,
+        models: Optional[List[str]] = None,
+        width: int = 768,
+        height: int = 512,
+        seconds: Optional[float] = None,
+        fps: Optional[int] = None,
+        source_image: Optional[str] = None,
+        timeout: float = 600.0,
+        **params: Any,
+    ) -> Dict[str, Any]:
+        body = _video_body(prompt, model, models, width, height, seconds, fps, source_image, params)
+        return await self._post("/videos/generations", body, timeout)

grid_sdk-0.1.1/src/grid_sdk.egg-info/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: grid-sdk
+Version: 0.1.1
+Summary: Python SDK for AI Power Grid open-model, OpenAI-compatible inference.
+Author: AI Power Grid
+License-Expression: MIT
+Project-URL: Homepage, https://aipowergrid.io
+Project-URL: Documentation, https://aipowergrid.io/docs
+Project-URL: Repository, https://github.com/AIPowerGrid/grid-sdk-python
+Keywords: ai,llm,inference,openai,decentralized,aipg
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.0.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: respx; extra == "test"
+Requires-Dist: httpx; extra == "test"
+Dynamic: license-file
+
+# AI Power Grid — Python SDK
+
+Open-model, OpenAI-compatible inference across community-operated GPUs.
+
+> **Release status:** `grid-sdk` is staged for its initial PyPI publication.
+> The install command below becomes available when the first verified release
+> is published; until then, use the OpenAI SDK with the Grid base URL shown below.
+
+The Grid API speaks the OpenAI protocol, so this SDK is a thin layer over the
+official `openai` package: it points at the Grid, reads your key from the
+environment, and adds Grid-specific conveniences. Everything you know from the
+OpenAI SDK works unchanged.
+
+## Install
+
+```bash
+pip install grid-sdk
+```
+
+## Quick start
+
+Sign in at the [Grid developer console](https://console.aipowergrid.io/dashboard/api-key),
+create an API key, then set it as `AIPG_API_KEY`:
+
+```python
+from grid_sdk import Grid
+
+client = Grid()  # reads AIPG_API_KEY from the environment
+
+stream = client.chat.completions.create(
+    model="gpt-oss-120b",
+    messages=[{"role": "user", "content": "Explain AI Power Grid in one line."}],
+    stream=True,
+)
+for chunk in stream:
+    print(chunk.choices[0].delta.content or "", end="", flush=True)
+```
+
+## See what's online
+
+The Grid's available models change as workers connect and disconnect. Don't
+hardcode a model blindly — ask which ones are servable right now:
+
+```python
+client = Grid()
+print(client.online_models())
+# ['gpt-oss-120b', 'qwen3-27b', ...]
+```
+
+An empty list means no workers are connected — requests will 503 until one is.
+
+## Credits
+
+```python
+credits = client.grid.credits()
+print(credits["total_spendable_usd"])
+```
+
+This is Core's canonical promotional, daily-free, and purchased account view.
+The SDK does not maintain a local free-use counter.
+
+## Async
+
+```python
+import asyncio
+from grid_sdk import AsyncGrid
+
+async def main():
+    client = AsyncGrid()
+    resp = await client.chat.completions.create(
+        model="gpt-oss-120b",
+        messages=[{"role": "user", "content": "Hi"}],
+    )
+    print(resp.choices[0].message.content)
+
+asyncio.run(main())
+```
+
+## Video, img2img, ControlNet, LoRAs — the full Grid
+
+The OpenAI-compatible surface covers text and basic txt2img. For the full media
+parameter surface, use `client.grid`, which calls the synchronous `/v1` image
+and video endpoints:
+
+```python
+client = Grid()
+
+# Video:
+result = client.grid.video(
+    prompt="a timelapse of a city at night",
+    model="LTX-2.3",
+    width=768, height=512, seconds=4, fps=24,
+)
+
+# img2img / ControlNet / LoRAs — anything the workers support:
+result = client.grid.image(
+    prompt="make it watercolor",
+    models=["FLUX.2 Klein 4B FP8"],
+    source_image="<base64>",
+    loras=[{"name": "watercolor", "model": 1.0}],
+)
+
+# Or full control with a raw payload:
+result = client.grid.generate({"prompt": "...", "models": [...], "params": {...}})
+```
+
+`client.grid` waits for the synchronous Grid response and returns the finished
+OpenAI-shaped result. Use `timeout` for long media jobs; there is no SDK
+submit/poll mode on this `/v1` client.
+
+## It's just OpenAI underneath
+
+`Grid` subclasses `openai.OpenAI`, so anything the OpenAI SDK does — images,
+tool calling, structured output, the full `.chat`/`.images`/`.models` surface —
+works here too. You can also point existing OpenAI code at the Grid by setting
+`base_url="https://api.aipowergrid.io/v1"` if you'd rather not switch packages.
+
+## Config
+
+| | |
+|---|---|
+| `Grid(api_key=...)` | Explicit key (overrides env) |
+| `AIPG_API_KEY` | Env var read when no key is passed |
+| `Grid(base_url=...)` | Override the endpoint (default `https://api.aipowergrid.io/v1`) |
+
+## Links
+
+- [Docs](https://aipowergrid.io/docs)
+- [Get an API key](https://console.aipowergrid.io/dashboard/api-key)
+- [Discord](https://discord.gg/W9D8j6HCtC)
+
+## License
+
+MIT

grid_sdk-0.1.1/src/grid_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/grid_sdk/__init__.py
+src/grid_sdk/client.py
+src/grid_sdk/grid.py
+src/grid_sdk.egg-info/PKG-INFO
+src/grid_sdk.egg-info/SOURCES.txt
+src/grid_sdk.egg-info/dependency_links.txt
+src/grid_sdk.egg-info/requires.txt
+src/grid_sdk.egg-info/top_level.txt
+tests/test_client.py
+tests/test_grid.py

grid_sdk-0.1.1/src/grid_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

grid_sdk-0.1.1/src/grid_sdk.egg-info/requires.txt

@@ -0,0 +1,7 @@
+openai>=1.0.0
+
+[test]
+pytest
+pytest-asyncio
+respx
+httpx

grid_sdk-0.1.1/src/grid_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+grid_sdk

grid_sdk-0.1.1/tests/test_client.py

@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: MIT
+"""Tests for the AIPG Python SDK.
+
+These don't hit the network — they verify the SDK's own behavior: key
+resolution, default base URL, that it really is an OpenAI client, and that
+online_models() maps the models response to a list of IDs.
+"""
+
+import os
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import pytest
+
+from grid_sdk import AIPG, AsyncAIPG, DEFAULT_BASE_URL
+from openai import AsyncOpenAI, OpenAI
+
+
+# ── key resolution + config ──
+
+
+def test_explicit_key_is_used():
+    client = AIPG(api_key="grid-explicit")
+    assert client.api_key == "grid-explicit"
+
+
+def test_key_falls_back_to_env(monkeypatch):
+    monkeypatch.setenv("AIPG_API_KEY", "grid-from-env")
+    client = AIPG()
+    assert client.api_key == "grid-from-env"
+
+
+def test_missing_key_raises_with_helpful_message(monkeypatch):
+    monkeypatch.delenv("AIPG_API_KEY", raising=False)
+    with pytest.raises(ValueError) as exc:
+        AIPG()
+    assert "AIPG_API_KEY" in str(exc.value)
+    assert "console.aipowergrid.io/dashboard/api-key" in str(exc.value)
+
+
+def test_default_base_url_points_at_grid():
+    client = AIPG(api_key="k")
+    assert str(client.base_url).rstrip("/") == DEFAULT_BASE_URL.rstrip("/")
+
+
+def test_base_url_override():
+    client = AIPG(api_key="k", base_url="http://localhost:9999/v1")
+    assert "localhost:9999" in str(client.base_url)
+
+
+def test_is_an_openai_client():
+    # Subclassing keeps all OpenAI client features (chat, images, streaming).
+    assert isinstance(AIPG(api_key="k"), OpenAI)
+    assert isinstance(AsyncAIPG(api_key="k"), AsyncOpenAI)
+
+
+# ── online_models() ──
+
+
+def test_online_models_maps_to_ids():
+    client = AIPG(api_key="k")
+    fake_models = SimpleNamespace(
+        data=[SimpleNamespace(id="grid/llama-3.3-70b-versatile"), SimpleNamespace(id="grid/qwen3-32b")]
+    )
+    client.models.list = MagicMock(return_value=fake_models)
+
+    assert client.online_models() == ["grid/llama-3.3-70b-versatile", "grid/qwen3-32b"]
+
+
+def test_online_models_empty_when_no_workers():
+    client = AIPG(api_key="k")
+    client.models.list = MagicMock(return_value=SimpleNamespace(data=[]))
+    assert client.online_models() == []
+
+
+@pytest.mark.asyncio
+async def test_async_online_models_maps_to_ids():
+    client = AsyncAIPG(api_key="k")
+
+    async def fake_list():
+        return SimpleNamespace(data=[SimpleNamespace(id="grid/qwen3-32b")])
+
+    client.models.list = fake_list
+    assert await client.online_models() == ["grid/qwen3-32b"]

grid_sdk-0.1.1/tests/test_grid.py

@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: MIT
+"""Tests for the raw-Grid media client (client.grid) on /v1.
+
+Verifies the image/video builders POST the right OpenAI-shaped body to the
+synchronous /v1 media endpoints (img2img, LoRAs, passthrough params). Network
+calls are stubbed.
+"""
+
+from unittest.mock import AsyncMock, MagicMock
+
+from grid_sdk import AIPG
+from grid_sdk.grid import AsyncGridRaw, GridRaw
+
+
+def test_client_exposes_grid():
+    client = AIPG(api_key="k")
+    assert isinstance(client.grid, GridRaw)
+    assert client.grid._base == "https://api.aipowergrid.io/v1"
+    assert client.grid._headers["Authorization"] == "Bearer k"
+
+
+def test_credits_uses_canonical_account_endpoint():
+    grid = GridRaw("k", "https://api.aipowergrid.io/v1")
+    grid._get = MagicMock(return_value={"promotional": {}, "free": {}, "paid": {}})
+    result = grid.credits()
+    grid._get.assert_called_once_with("/account/credits", 30.0)
+    assert set(result) == {"promotional", "free", "paid"}
+
+
+async def test_async_credits_uses_canonical_account_endpoint():
+    grid = AsyncGridRaw("k", "https://api.aipowergrid.io/v1")
+    grid._get = AsyncMock(return_value={"total_spendable_usd": 0.15})
+    result = await grid.credits()
+    grid._get.assert_awaited_once_with("/account/credits", 30.0)
+    assert result["total_spendable_usd"] == 0.15
+
+
+def _capture(grid: GridRaw):
+    """Replace _post with a capturing stub; return the captured call."""
+    cap = {}
+    grid._post = MagicMock(
+        side_effect=lambda path, body, timeout: cap.update({"path": path, "body": body})
+        or {"data": [{"url": "https://media.aipg.art/x.webp"}]}
+    )
+    return cap
+
+
+def test_image_posts_openai_shape():
+    grid = GridRaw("k", "https://api.aipowergrid.io/v1")
+    cap = _capture(grid)
+    grid.image("a cat", model="FLUX.2 Klein 4B FP8", width=512, height=768, steps=20, cfg_scale=3.5)
+    assert cap["path"] == "/images/generations"
+    b = cap["body"]
+    assert b["model"] == "FLUX.2 Klein 4B FP8"
+    assert b["prompt"] == "a cat"
+    assert b["size"] == "512x768"
+    assert b["steps"] == 20
+    assert b["cfg_scale"] == 3.5
+
+
+def test_models_list_back_compat():
+    grid = GridRaw("k", "https://api.aipowergrid.io/v1")
+    cap = _capture(grid)
+    grid.image("x", models=["z-image-turbo"])
+    assert cap["body"]["model"] == "z-image-turbo"
+
+
+def test_image_img2img_fields():
+    grid = GridRaw("k", "https://api.aipowergrid.io/v1")
+    cap = _capture(grid)
+    grid.image("watercolor", model="m", source_image="BASE64", strength=0.6)
+    assert cap["body"]["image"] == "BASE64"
+    assert cap["body"]["strength"] == 0.6
+
+
+def test_image_loras_and_passthrough():
+    grid = GridRaw("k", "https://api.aipowergrid.io/v1")
+    cap = _capture(grid)
+    grid.image("x", model="m", loras=[{"name": "watercolor", "model": 1.0}], seed=42)
+    assert cap["body"]["loras"] == [{"name": "watercolor", "model": 1.0}]
+    assert cap["body"]["seed"] == 42
+
+
+def test_video_posts_to_videos_endpoint():
+    grid = GridRaw("k", "https://api.aipowergrid.io/v1")
+    cap = _capture(grid)
+    grid.video("a timelapse", model="LTX-2.3", width=768, height=512, seconds=4, fps=24)
+    assert cap["path"] == "/videos/generations"
+    b = cap["body"]
+    assert b["model"] == "LTX-2.3"
+    assert b["size"] == "768x512"
+    assert b["seconds"] == 4
+    assert b["fps"] == 24