corent 0.1.0__tar.gz

corent-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+.env
+.env.local
+.env.*.local
+
+# Python
+backend/venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+
+# Node / Next.js
+frontend/node_modules/
+.next/
+frontend/out/
+
+# OS
+.DS_Store
+
+# MCP package
+mcp/node_modules/
+mcp/dist/
+.vercel
+
+# fund-agent local state (balance history)
+fund-agent/state/

corent-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: corent
+Version: 0.1.0
+Summary: Official Python SDK for Corent — one API for AI image, video, and voice generation with built-in routing, failover, and exact receipts.
+Project-URL: Homepage, https://corent.tech
+Project-URL: Documentation, https://corent.tech/docs
+Author-email: Corent <krrocicrypto@gmail.com>
+License-Expression: MIT
+Keywords: ai,api,corent,image-generation,text-to-speech,video-generation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Description-Content-Type: text/markdown
+
+# Corent Python SDK
+
+One API for AI **image, video, and voice** generation. You pick a quality tier; Corent's router picks the best live model, reroutes failures, verifies the output, and returns the exact charge on every response. Failed generations are never billed.
+
+```bash
+pip install corent
+```
+
+```python
+from corent import Corent
+
+client = Corent("co_live_...")  # get a key at https://corent.tech
+
+image = client.images.generate("a lighthouse at dusk", tier="premium", aspect_ratio="9:16")
+print(image.url, image.width, image.height, image.cost_cents)
+
+video = client.videos.generate("a paper boat drifting across a puddle",
+                               tier="premium", duration_s=5, resolution="1080p")
+print(video.url, video.resolution, video.cost_cents)
+
+speech = client.speech.generate("Welcome to Corent.")
+print(speech.url, speech.cost_cents)
+```
+
+## What the SDK handles for you
+
+- **Timeout-safe renders** — images submit as background jobs and are polled; a network hiccup can never lose a finished (and billed) result.
+- **Safe retries** — every generate call carries an auto idempotency key; retries can never double-charge.
+- **Backoff** — 429/5xx are retried with `Retry-After` respected.
+- **Honest receipts** — `width`/`height` are the *measured* pixels of the delivered file, and `cost_cents` is the exact charge.
+
+## Fine-grained control
+
+```python
+job = client.images.generate("...", tier="max_pro", wait=False)  # returns immediately
+job = client.jobs.wait(job.id)                                    # resume any time
+
+client.tiers()          # live catalog with honest min-max price ranges
+client.balance_cents()  # prepaid balance
+```
+
+Tiers: `air` | `lite` | `premium` | `pro` | `max_pro` — see [corent.tech/pricing](https://corent.tech/pricing). Docs: [corent.tech/docs](https://corent.tech/docs).

corent-0.1.0/README.md

@@ -0,0 +1,42 @@
+# Corent Python SDK
+
+One API for AI **image, video, and voice** generation. You pick a quality tier; Corent's router picks the best live model, reroutes failures, verifies the output, and returns the exact charge on every response. Failed generations are never billed.
+
+```bash
+pip install corent
+```
+
+```python
+from corent import Corent
+
+client = Corent("co_live_...")  # get a key at https://corent.tech
+
+image = client.images.generate("a lighthouse at dusk", tier="premium", aspect_ratio="9:16")
+print(image.url, image.width, image.height, image.cost_cents)
+
+video = client.videos.generate("a paper boat drifting across a puddle",
+                               tier="premium", duration_s=5, resolution="1080p")
+print(video.url, video.resolution, video.cost_cents)
+
+speech = client.speech.generate("Welcome to Corent.")
+print(speech.url, speech.cost_cents)
+```
+
+## What the SDK handles for you
+
+- **Timeout-safe renders** — images submit as background jobs and are polled; a network hiccup can never lose a finished (and billed) result.
+- **Safe retries** — every generate call carries an auto idempotency key; retries can never double-charge.
+- **Backoff** — 429/5xx are retried with `Retry-After` respected.
+- **Honest receipts** — `width`/`height` are the *measured* pixels of the delivered file, and `cost_cents` is the exact charge.
+
+## Fine-grained control
+
+```python
+job = client.images.generate("...", tier="max_pro", wait=False)  # returns immediately
+job = client.jobs.wait(job.id)                                    # resume any time
+
+client.tiers()          # live catalog with honest min-max price ranges
+client.balance_cents()  # prepaid balance
+```
+
+Tiers: `air` | `lite` | `premium` | `pro` | `max_pro` — see [corent.tech/pricing](https://corent.tech/pricing). Docs: [corent.tech/docs](https://corent.tech/docs).

corent-0.1.0/corent/__init__.py

@@ -0,0 +1,31 @@
+"""Corent Python SDK — one API for AI image, video, and voice.
+
+    from corent import Corent
+
+    client = Corent("co_live_...")
+    image = client.images.generate("a lighthouse at dusk", tier="premium")
+    print(image.url, image.width, image.height, image.cost_cents)
+"""
+
+from .client import Corent
+from .errors import (
+    CorentError,
+    InsufficientBalanceError,
+    InvalidRequestError,
+    RateLimitedError,
+)
+from .types import GeneratedImage, GeneratedSpeech, GeneratedVideo, Job
+
+__all__ = [
+    "Corent",
+    "CorentError",
+    "InsufficientBalanceError",
+    "InvalidRequestError",
+    "RateLimitedError",
+    "GeneratedImage",
+    "GeneratedVideo",
+    "GeneratedSpeech",
+    "Job",
+]
+
+__version__ = "0.1.0"

corent-0.1.0/corent/client.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+"""The Corent client. Hides everything the raw HTTP caller has to hand-roll:
+auth headers, idempotency keys, 429/5xx retries with backoff, and job polling.
+
+Design choices worth knowing:
+
+- Image generation submits with async=true and polls the job. A finished
+  render can then never be lost to a client-side timeout — the job id exists
+  from the first response, and the SDK just resumes polling.
+- Every generate call sends an auto-generated Idempotency-Key, so the SDK's
+  own retries (and yours) can never double-charge.
+- Failed generations are never billed by the API; the SDK surfaces them as
+  GenerationFailedError with the API's sanitized error code.
+"""
+
+import time
+import uuid
+
+import httpx
+
+from .errors import (
+    CorentError,
+    GenerationFailedError,
+    InsufficientBalanceError,
+    InvalidRequestError,
+    RateLimitedError,
+)
+from .types import GeneratedImage, GeneratedSpeech, GeneratedVideo, Job
+
+DEFAULT_BASE_URL = "https://api.corent.tech"
+MAX_RETRIES = 3
+POLL_INTERVAL_S = 3.0
+DEFAULT_WAIT_TIMEOUT_S = 900  # videos can take minutes; images far less
+
+
+class Corent:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 60.0,
+    ):
+        self._http = httpx.Client(
+            base_url=base_url,
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "User-Agent": "corent-python/0.1.0",
+            },
+        )
+        self.images = _Images(self)
+        self.videos = _Videos(self)
+        self.speech = _Speech(self)
+        self.jobs = _Jobs(self)
+
+    # -- account & discovery -------------------------------------------------
+
+    def balance_cents(self) -> int:
+        return self._request("GET", "/v1/account/balance")["balance_cents"]
+
+    def tiers(self) -> list[dict]:
+        """The live tier catalog with honest price ranges. Public endpoint."""
+        return self._request("GET", "/v1/tiers")["tiers"]
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    # -- plumbing ------------------------------------------------------------
+
+    def _request(self, method: str, path: str, json: dict | None = None,
+                 idempotent: bool = False) -> dict:
+        headers = {}
+        if idempotent:
+            headers["Idempotency-Key"] = str(uuid.uuid4())
+        last_exc: Exception | None = None
+        for attempt in range(MAX_RETRIES + 1):
+            try:
+                resp = self._http.request(method, path, json=json, headers=headers)
+            except httpx.TransportError as exc:
+                last_exc = exc
+                time.sleep(min(2**attempt, 8))
+                continue
+            if resp.status_code < 400:
+                return resp.json()
+            if resp.status_code == 429:
+                retry_after = float(resp.headers.get("Retry-After", 2 ** (attempt + 1)))
+                if attempt < MAX_RETRIES:
+                    time.sleep(min(retry_after, 30))
+                    continue
+                raise RateLimitedError("rate limited", retry_after_s=retry_after)
+            if resp.status_code in (502, 503) and attempt < MAX_RETRIES:
+                time.sleep(min(2 ** (attempt + 1), 8))
+                continue
+            self._raise_for(resp)
+        raise CorentError(f"request failed after {MAX_RETRIES} retries: {last_exc}")
+
+    @staticmethod
+    def _raise_for(resp: httpx.Response) -> None:
+        try:
+            detail = resp.json().get("detail", resp.text)
+        except Exception:
+            detail = resp.text
+        message = detail if isinstance(detail, str) else str(detail)
+        if resp.status_code == 402:
+            raise InsufficientBalanceError(message, 402)
+        if resp.status_code in (400, 422):
+            raise InvalidRequestError(message, resp.status_code)
+        raise CorentError(message, resp.status_code)
+
+    def _wait(self, job_id: str, timeout_s: float) -> dict:
+        deadline = time.monotonic() + timeout_s
+        while time.monotonic() < deadline:
+            job = self._request("GET", f"/v1/jobs/{job_id}")
+            if job["status"] == "completed":
+                return job
+            if job["status"] == "failed":
+                raise GenerationFailedError(job.get("error") or "generation_failed")
+            time.sleep(POLL_INTERVAL_S)
+        raise CorentError(f"job {job_id} still processing after {timeout_s:.0f}s; "
+                          f"poll client.jobs.get('{job_id}') to resume")
+
+
+class _Images:
+    def __init__(self, client: Corent):
+        self._c = client
+
+    def generate(
+        self,
+        prompt: str,
+        tier: str | None = None,
+        style: str | None = None,
+        aspect_ratio: str = "1:1",
+        wait: bool = True,
+        timeout_s: float = DEFAULT_WAIT_TIMEOUT_S,
+    ) -> "GeneratedImage | Job":
+        """Render an image. tier: air | lite | premium | pro | max_pro.
+        wait=False returns the Job immediately; poll with client.jobs."""
+        body = {"prompt": prompt, "aspect_ratio": aspect_ratio, "async": True}
+        if tier:
+            body["tier"] = tier
+        if style:
+            body["style"] = style
+        submitted = self._c._request("POST", "/v1/images/generate", json=body, idempotent=True)
+        if submitted["status"] == "completed":  # idempotent replay of a finished job
+            return _image_from_job(submitted)
+        if not wait:
+            return Job(id=submitted["id"], status=submitted["status"], raw=submitted)
+        return _image_from_job(self._c._wait(submitted["id"], timeout_s))
+
+
+class _Videos:
+    def __init__(self, client: Corent):
+        self._c = client
+
+    def generate(
+        self,
+        prompt: str,
+        tier: str | None = None,
+        aspect_ratio: str = "16:9",
+        duration_s: int | None = None,
+        resolution: str | None = None,
+        image_url: str | None = None,
+        wait: bool = True,
+        timeout_s: float = DEFAULT_WAIT_TIMEOUT_S,
+    ) -> "GeneratedVideo | Job":
+        """Render a video (1-5 minutes typical). resolution: 720p | 1080p | 4k
+        (tier-capped; clamped down, never rejected). image_url animates an
+        existing image instead of starting from text."""
+        body: dict = {"prompt": prompt, "aspect_ratio": aspect_ratio}
+        if tier:
+            body["tier"] = tier
+        if duration_s is not None:
+            body["duration_s"] = duration_s
+        if resolution:
+            body["resolution"] = resolution
+        if image_url:
+            body["image_url"] = image_url
+        submitted = self._c._request("POST", "/v1/videos/generate", json=body, idempotent=True)
+        if not wait:
+            return Job(id=submitted["id"], status=submitted["status"], raw=submitted)
+        return _video_from_job(self._c._wait(submitted["id"], timeout_s))
+
+
+class _Speech:
+    def __init__(self, client: Corent):
+        self._c = client
+
+    def generate(self, text: str, voice_id: str | None = None) -> GeneratedSpeech:
+        """Text to speech; synchronous, returns the finished audio."""
+        body: dict = {"text": text}
+        if voice_id:
+            body["voice_id"] = voice_id
+        r = self._c._request("POST", "/v1/audio/speech", json=body, idempotent=True)
+        meta = r.get("meta") or {}
+        return GeneratedSpeech(id=r["id"], url=r["audio_url"],
+                               model=meta.get("model"), cost_cents=meta.get("cost_cents"))
+
+
+class _Jobs:
+    def __init__(self, client: Corent):
+        self._c = client
+
+    def get(self, job_id: str) -> Job:
+        raw = self._c._request("GET", f"/v1/jobs/{job_id}")
+        return Job(id=raw["id"], status=raw["status"], raw=raw)
+
+    def wait(self, job_id: str, timeout_s: float = DEFAULT_WAIT_TIMEOUT_S) -> Job:
+        raw = self._c._wait(job_id, timeout_s)
+        return Job(id=raw["id"], status=raw["status"], raw=raw)
+
+
+def _image_from_job(job: dict) -> GeneratedImage:
+    image = (job.get("images") or [{}])[0]
+    meta = job.get("meta") or {}
+    return GeneratedImage(
+        id=job["id"], url=image.get("url"), width=image.get("width"),
+        height=image.get("height"), model=meta.get("model"), cost_cents=meta.get("cost_cents"),
+    )
+
+
+def _video_from_job(job: dict) -> GeneratedVideo:
+    video = (job.get("videos") or [{}])[0]
+    meta = job.get("meta") or {}
+    return GeneratedVideo(
+        id=job["id"], url=video.get("url"), width=video.get("width"),
+        height=video.get("height"), resolution=video.get("resolution"),
+        duration_s=video.get("duration_s"), model=meta.get("model"),
+        cost_cents=meta.get("cost_cents"),
+    )

corent-0.1.0/corent/errors.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+
+class CorentError(Exception):
+    """Base error: carries the HTTP status and the API's error detail."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class InvalidRequestError(CorentError):
+    """400/422: fix the highlighted field and resend."""
+
+
+class InsufficientBalanceError(CorentError):
+    """402: add funds at https://corent.tech/dashboard."""
+
+
+class RateLimitedError(CorentError):
+    """429 after retries were exhausted: slow down or raise your key limits."""
+
+    def __init__(self, message: str, retry_after_s: float | None = None):
+        self.retry_after_s = retry_after_s
+        super().__init__(message, 429)
+
+
+class GenerationFailedError(CorentError):
+    """The job reached a terminal failed state. You were not charged."""

corent-0.1.0/corent/types.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class GeneratedImage:
+    """A finished image. width/height are the MEASURED pixels of the delivered
+    file (Corent parses the file itself, never echoes your request)."""
+
+    id: str
+    url: str
+    width: int | None
+    height: int | None
+    model: str | None  # Corent tier that served it, e.g. "image-premium"
+    cost_cents: int | None
+
+
+@dataclass
+class GeneratedVideo:
+    id: str
+    url: str
+    width: int | None
+    height: int | None
+    resolution: str | None
+    duration_s: int | None
+    model: str | None
+    cost_cents: int | None
+
+
+@dataclass
+class GeneratedSpeech:
+    id: str
+    url: str
+    model: str | None
+    cost_cents: int | None
+
+
+@dataclass
+class Job:
+    """Raw job state for callers driving their own polling."""
+
+    id: str
+    status: str  # "processing" | "completed" | "failed"
+    raw: dict

corent-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "corent"
+version = "0.1.0"
+description = "Official Python SDK for Corent — one API for AI image, video, and voice generation with built-in routing, failover, and exact receipts."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Corent", email = "krrocicrypto@gmail.com" }]
+keywords = ["ai", "image-generation", "video-generation", "text-to-speech", "api", "corent"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://corent.tech"
+Documentation = "https://corent.tech/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["corent"]

corent-0.1.0/tests/test_client.py

@@ -0,0 +1,87 @@
+"""SDK behavior tests against a mock transport: no network, no spend."""
+
+import json
+
+import httpx
+import pytest
+
+import corent.client as client_mod
+from corent import Corent, InsufficientBalanceError
+from corent.errors import GenerationFailedError
+
+
+def make_client(handler) -> Corent:
+    c = Corent("co_live_test", base_url="https://api.test")
+    c._http = httpx.Client(
+        base_url="https://api.test",
+        transport=httpx.MockTransport(handler),
+        headers={"Authorization": "Bearer co_live_test"},
+    )
+    return c
+
+
+def test_image_generate_submits_async_and_polls(monkeypatch):
+    monkeypatch.setattr(client_mod, "POLL_INTERVAL_S", 0)
+    calls = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append((request.method, request.url.path))
+        if request.url.path == "/v1/images/generate":
+            body = json.loads(request.content)
+            assert body["async"] is True  # timeout-safety by default
+            assert request.headers.get("Idempotency-Key")  # auto retry-safety
+            return httpx.Response(202, json={"id": "j1", "status": "processing"})
+        if len(calls) < 3:
+            return httpx.Response(200, json={"id": "j1", "status": "processing"})
+        return httpx.Response(200, json={
+            "id": "j1", "status": "completed",
+            "images": [{"url": "https://cdn/x.jpg", "width": 608, "height": 1088}],
+            "meta": {"model": "image-air", "cost_cents": 2},
+        })
+
+    image = make_client(handler).images.generate("a lighthouse", tier="air", aspect_ratio="9:16")
+    assert (image.width, image.height, image.cost_cents) == (608, 1088, 2)
+    assert calls[0] == ("POST", "/v1/images/generate")
+
+
+def test_failed_job_raises_and_names_the_error(monkeypatch):
+    monkeypatch.setattr(client_mod, "POLL_INTERVAL_S", 0)
+
+    def handler(request):
+        if request.url.path == "/v1/images/generate":
+            return httpx.Response(202, json={"id": "j2", "status": "processing"})
+        return httpx.Response(200, json={"id": "j2", "status": "failed", "error": "all_providers_failed"})
+
+    with pytest.raises(GenerationFailedError, match="all_providers_failed"):
+        make_client(handler).images.generate("x")
+
+
+def test_402_maps_to_insufficient_balance():
+    def handler(request):
+        return httpx.Response(402, json={"detail": "Insufficient balance"})
+
+    with pytest.raises(InsufficientBalanceError):
+        make_client(handler).images.generate("x")
+
+
+def test_429_retries_then_succeeds(monkeypatch):
+    monkeypatch.setattr(client_mod.time, "sleep", lambda s: None)
+    attempts = []
+
+    def handler(request):
+        attempts.append(1)
+        if len(attempts) == 1:
+            return httpx.Response(429, headers={"Retry-After": "0"})
+        return httpx.Response(200, json={"balance_cents": 845})
+
+    assert make_client(handler).balance_cents() == 845
+    assert len(attempts) == 2
+
+
+def test_wait_false_returns_job_handle():
+    def handler(request):
+        return httpx.Response(202, json={"id": "j3", "status": "processing"})
+
+    job = make_client(handler).images.generate("x", wait=False)
+    assert job.id == "j3"
+    assert job.status == "processing"