runapi-core 0.1.0__tar.gz → 0.1.2__tar.gz

{runapi_core-0.1.0 → runapi_core-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runapi-core
-Version: 0.1.0
+Version: 0.1.2
 Summary: Core module for the RunAPI Python SDK
 Project-URL: Homepage, https://runapi.ai
 Project-URL: Documentation, https://runapi.ai/docs#sdk
@@ -23,7 +23,7 @@ pip install runapi-core
 
 ## Notes
 
-Use the core package for common client options, error classes, request helpers, file uploads, and task polling behavior that model SDKs share. Configure it globally or per client:
+Use the core package for common client options, error classes, request helpers, file uploads, and task polling behavior that Provider Clients share. Configure it globally or per client:
 
 ```python
 import runapi.core as runapi
@@ -31,11 +31,42 @@ import runapi.core as runapi
 runapi.configure(api_key="sk-...")  # or set RUNAPI_API_KEY in the environment
 ```
 
+## Request identifiers
+
+RunAPI accepts an optional `X-Client-Request-Id` header on public API calls. Use printable ASCII values up to 512 characters. Accepted values are echoed in the response and stored with the RunAPI task for support and reconciliation.
+
+High-level Python Provider Client resource methods accept per-request options and keep response headers on the returned model object. This example uses the Suno Provider Client; install `runapi-suno` to run it.
+
+```python
+import os
+
+from runapi.core import RequestOptions
+from runapi.suno import SunoClient
+
+client = SunoClient(api_key=os.environ["RUNAPI_API_KEY"])
+options = RequestOptions(
+    headers={"X-Client-Request-Id": "order-123"},
+)
+
+response = client.text_to_music.create(
+    prompt="A chill lo-fi beat",
+    model="suno-v4.5-plus",
+    vocal_mode="instrumental",
+    options=options,
+)
+
+runapi_task_id = response.runapi_task_id
+# Equivalent case-insensitive lookup:
+runapi_task_id = response.response_headers["X-RunAPI-Task-Id"]
+```
+
 ```python
 from runapi.core import FilesClient
 
 files = FilesClient()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
 uploaded = files.create(file="./input.png")
+remote = files.create(source="https://cdn.runapi.ai/public/samples/input.png")
+inline = files.create(source="iVBORw0KGgo...")
 print(uploaded.url)
 ```
 

runapi_core-0.1.2/README.md

@@ -0,0 +1,64 @@
+# RunAPI Core Python SDK
+
+The RunAPI Core Python SDK provides shared authentication, HTTP, retry, error, and polling primitives for RunAPI model packages. Install `runapi-core` only when you are building SDK infrastructure or shared Python tooling; application code should normally install a concrete model package such as `runapi-flux-2`.
+
+## Install
+
+```bash
+pip install runapi-core
+```
+
+## Notes
+
+Use the core package for common client options, error classes, request helpers, file uploads, and task polling behavior that Provider Clients share. Configure it globally or per client:
+
+```python
+import runapi.core as runapi
+
+runapi.configure(api_key="sk-...")  # or set RUNAPI_API_KEY in the environment
+```
+
+## Request identifiers
+
+RunAPI accepts an optional `X-Client-Request-Id` header on public API calls. Use printable ASCII values up to 512 characters. Accepted values are echoed in the response and stored with the RunAPI task for support and reconciliation.
+
+High-level Python Provider Client resource methods accept per-request options and keep response headers on the returned model object. This example uses the Suno Provider Client; install `runapi-suno` to run it.
+
+```python
+import os
+
+from runapi.core import RequestOptions
+from runapi.suno import SunoClient
+
+client = SunoClient(api_key=os.environ["RUNAPI_API_KEY"])
+options = RequestOptions(
+    headers={"X-Client-Request-Id": "order-123"},
+)
+
+response = client.text_to_music.create(
+    prompt="A chill lo-fi beat",
+    model="suno-v4.5-plus",
+    vocal_mode="instrumental",
+    options=options,
+)
+
+runapi_task_id = response.runapi_task_id
+# Equivalent case-insensitive lookup:
+runapi_task_id = response.response_headers["X-RunAPI-Task-Id"]
+```
+
+```python
+from runapi.core import FilesClient
+
+files = FilesClient()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
+uploaded = files.create(file="./input.png")
+remote = files.create(source="https://cdn.runapi.ai/public/samples/input.png")
+inline = files.create(source="iVBORw0KGgo...")
+print(uploaded.url)
+```
+
+Public SDK docs live at https://runapi.ai/docs#runapi-sdks and the model catalog lives at https://runapi.ai/models.
+
+## License
+
+Licensed under the Apache License, Version 2.0.

{runapi_core-0.1.0 → runapi_core-0.1.2}/pyproject.toml

@@ -28,3 +28,6 @@ package = true
 
 [dependency-groups]
 dev = ["pytest>=8", "httpx>=0.27"]
+
+[tool.runapi]
+slug = "core"

{runapi_core-0.1.0 → runapi_core-0.1.2}/src/runapi/core/__init__.py

@@ -29,6 +29,7 @@ from .http_client import HttpClient
 from .models import BaseModel, DynamicModel, TaskResponse, optional, required
 from .multipart import MultipartBody, MultipartFile
 from .options import ClientOptions, PollingOptions, RequestOptions
+from .response import ApiResponse, ResponseHeaders
 from .resource import Resource
 from .version import __version__
 
@@ -57,6 +58,8 @@ __all__ = [
     "ClientOptions",
     "RequestOptions",
     "PollingOptions",
+    "ApiResponse",
+    "ResponseHeaders",
     "BaseModel",
     "DynamicModel",
     "TaskResponse",

{runapi_core-0.1.0 → runapi_core-0.1.2}/src/runapi/core/contract_gen.py

@@ -1,5 +1,3 @@
-# Code generated by SdkContractGenerator. DO NOT EDIT.
-
 CONTRACT = {
     "elevenlabs/isolate-audio": {
         "models": ["audio-isolation"],
@@ -148,6 +146,9 @@ CONTRACT = {
         "models": ["gpt-image-2"],
         "fields_by_model": {
             "gpt-image-2": {
+                "aspect_ratio": {
+                    "enum": ["auto", "1:1", "3:2", "2:3", "4:3", "3:4", "5:4", "4:5", "16:9", "9:16", "2:1", "1:2", "3:1", "1:3", "21:9", "9:21"]
+                },
                 "output_resolution": {
                     "enum": ["1k", "2k", "4k"]
                 }
@@ -158,6 +159,9 @@ CONTRACT = {
         "models": ["gpt-image-2"],
         "fields_by_model": {
             "gpt-image-2": {
+                "aspect_ratio": {
+                    "enum": ["auto", "1:1", "3:2", "2:3", "4:3", "3:4", "5:4", "4:5", "16:9", "9:16", "2:1", "1:2", "3:1", "1:3", "21:9", "9:21"]
+                },
                 "output_resolution": {
                     "enum": ["1k", "2k", "4k"]
                 }
@@ -167,13 +171,27 @@ CONTRACT = {
     "gpt-image/edit-image": {
         "models": ["gpt-image-1.5"],
         "fields_by_model": {
-            "gpt-image-1.5": {}
+            "gpt-image-1.5": {
+                "aspect_ratio": {
+                    "enum": ["1:1", "2:3", "3:2"]
+                },
+                "quality": {
+                    "enum": ["medium", "high"]
+                }
+            }
         }
     },
     "gpt-image/text-to-image": {
         "models": ["gpt-image-1.5"],
         "fields_by_model": {
-            "gpt-image-1.5": {}
+            "gpt-image-1.5": {
+                "aspect_ratio": {
+                    "enum": ["1:1", "2:3", "3:2"]
+                },
+                "quality": {
+                    "enum": ["medium", "high"]
+                }
+            }
         }
     },
     "grok-imagine/edit-image": {
@@ -585,7 +603,7 @@ CONTRACT = {
         }
     },
     "nano-banana/text-to-image": {
-        "models": ["nano-banana", "nano-banana-2", "nano-banana-pro"],
+        "models": ["nano-banana", "nano-banana-2", "nano-banana-2-lite", "nano-banana-pro"],
         "fields_by_model": {
             "nano-banana": {
                 "aspect_ratio": {
@@ -606,6 +624,11 @@ CONTRACT = {
                     "enum": ["1k", "2k", "4k"]
                 }
             },
+            "nano-banana-2-lite": {
+                "aspect_ratio": {
+                    "enum": ["1:1", "1:4", "1:8", "2:3", "3:2", "3:4", "4:1", "4:3", "4:5", "5:4", "8:1", "9:16", "16:9", "21:9", "auto"]
+                }
+            },
             "nano-banana-pro": {
                 "aspect_ratio": {
                     "enum": ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9", "auto"]
@@ -713,9 +736,6 @@ CONTRACT = {
                 "aspect_ratio": {
                     "enum": ["1:1", "4:3", "3:4", "16:9", "9:16", "21:9"]
                 },
-                "duration_seconds": {
-                    "enum": [4, 8, 12]
-                },
                 "output_resolution": {
                     "enum": ["480p", "720p", "1080p"]
                 }

{runapi_core-0.1.0 → runapi_core-0.1.2}/src/runapi/core/errors.py

@@ -8,6 +8,8 @@ from datetime import datetime, timezone
 from email.utils import parsedate_to_datetime
 from typing import Any, Dict, Optional
 
+from .response import ResponseHeaders
+
 _HTML_MARKER = re.compile(r"<!doctype|<html", re.IGNORECASE)
 _TITLE = re.compile(r"<title>(.*?)</title>", re.IGNORECASE | re.DOTALL)
 _H1 = re.compile(r"<h1>(.*?)</h1>", re.IGNORECASE | re.DOTALL)
@@ -29,12 +31,23 @@ class Error(Exception):
         status: Optional[int] = None,
         request_id: Optional[str] = None,
         details: Any = None,
+        response_headers: Any = None,
     ) -> None:
         super().__init__(message)
         self.message = message
         self.status = status
         self.request_id = request_id
         self.details = details
+        self.response_headers = (
+            response_headers if isinstance(response_headers, ResponseHeaders) else ResponseHeaders(response_headers)
+        )
+
+    def response_header(self, name: str) -> Optional[str]:
+        return self.response_headers.get(name)
+
+    @property
+    def runapi_task_id(self) -> Optional[str]:
+        return self.response_header("X-RunAPI-Task-Id")
 
     def to_dict(self) -> Dict[str, Any]:
         data = {
@@ -184,7 +197,12 @@ def error_from_response(response: "Any") -> Error:
 
     error_class = STATUS_MAP.get(status, Error)
 
-    kwargs: Dict[str, Any] = {"status": status, "request_id": request_id, "details": parsed_body}
+    kwargs: Dict[str, Any] = {
+        "status": status,
+        "request_id": request_id,
+        "details": parsed_body,
+        "response_headers": response.headers,
+    }
     if error_class is RateLimitError:
         kwargs["retry_after"] = _parse_retry_after(response.headers.get("retry-after"))
 

{runapi_core-0.1.0 → runapi_core-0.1.2}/src/runapi/core/files.py

@@ -6,13 +6,14 @@ local file or register a remote URL and receive a usable file reference.
 
 from __future__ import annotations
 
+import base64
+import hashlib
 import os
-from typing import Any, Optional
+from typing import Any, Mapping, Optional, Union
 
 from . import auth
 from .http_client import HttpClient
 from .models import BaseModel, optional, required
-from .multipart import MultipartBody, MultipartFile
 from .options import ClientOptions, RequestOptions
 from .resource import Resource
 
@@ -28,6 +29,8 @@ class UploadResponse(BaseModel):
 
 class FilesClient(Resource):
     ENDPOINT = "/api/v1/files"
+    PREPARE_ENDPOINT = f"{ENDPOINT}/prepare"
+    CONFIRM_ENDPOINT = f"{ENDPOINT}/confirm"
 
     RESPONSE_CLASS = UploadResponse
 
@@ -40,7 +43,7 @@ class FilesClient(Resource):
     def create(
         self,
         file: Any = None,
-        source: Optional[str] = None,
+        source: Optional[Union[str, Mapping[str, Any]]] = None,
         file_name: Optional[str] = None,
         options: Optional[RequestOptions] = None,
     ) -> Any:
@@ -50,7 +53,8 @@ class FilesClient(Resource):
 
         Args:
             file: Local file path or file-like object to upload.
-            source: Remote URL to register instead of uploading a local file.
+            source: Remote URL, base64 data, or canonical source object to
+                register instead of uploading a local file.
             file_name: Optional name to record for the uploaded file.
             options: Optional per-request options.
 
@@ -60,14 +64,42 @@ class FilesClient(Resource):
         self._validate_source(file, source)
 
         if file is not None:
-            body: Any = self._multipart_body(file, file_name)
-        else:
-            body = self._compact_params({"source": source, "file_name": file_name})
+            return self._upload_direct(file, file_name, options)
 
+        body = self._compact_params(
+            {"source": self._source_object(source), "file_name": file_name}
+        )
         return self._request("post", self.ENDPOINT, body=body, options=options)
 
+    def _upload_direct(self, file: Any, file_name: Optional[str], options: Optional[RequestOptions]) -> Any:
+        """Local files upload straight to storage: ask for a pre-authorized target,
+        PUT the bytes there (never through the API), then confirm. The caller still
+        makes a single create call."""
+        path = self._file_path(file)
+        with open(path, "rb") as handle:
+            data = handle.read()
+
+        prepared = self._http.request(
+            "post",
+            self.PREPARE_ENDPOINT,
+            body=self._compact_params(
+                {
+                    "filename": file_name or os.path.basename(path),
+                    "byte_size": len(data),
+                    "checksum": base64.b64encode(hashlib.md5(data).digest()).decode("ascii"),
+                }
+            ),
+            options=options,
+        )
+
+        self._http.upload(prepared["upload_url"], headers=prepared["headers"], body=data)
+
+        return self._request(
+            "post", self.CONFIRM_ENDPOINT, body={"signed_id": prepared["signed_id"]}, options=options
+        )
+
     @staticmethod
-    def _validate_source(file: Any, source: Optional[str]) -> None:
+    def _validate_source(file: Any, source: Optional[Union[str, Mapping[str, Any]]]) -> None:
         def present(value: Any) -> bool:
             if value is None:
                 return False
@@ -79,13 +111,18 @@ class FilesClient(Resource):
         if provided != 1:
             raise ValueError("Exactly one source is required: file or source")
 
-    def _multipart_body(self, file: Any, file_name: Optional[str]) -> MultipartBody:
-        path = self._file_path(file)
-        filename = file_name or os.path.basename(path)
-        return MultipartBody(
-            fields=self._compact_params({"file_name": file_name}),
-            files={"file": MultipartFile(path=path, filename=filename)},
-        )
+    @staticmethod
+    def _source_object(source: Optional[Union[str, Mapping[str, Any]]]) -> Any:
+        if isinstance(source, Mapping):
+            return dict(source)
+
+        if isinstance(source, str):
+            value = source.strip()
+            if value.lower().startswith(("http://", "https://")):
+                return {"type": "url", "url": value}
+            return {"type": "base64", "data": value}
+
+        return source
 
     @staticmethod
     def _file_path(file: Any) -> str:

{runapi_core-0.1.0 → runapi_core-0.1.2}/src/runapi/core/http_client.py

@@ -13,6 +13,7 @@ from . import constants
 from .errors import NetworkError, RateLimitError, TimeoutError, error_from_response
 from .multipart import MultipartBody
 from .options import ClientOptions, RequestOptions
+from .response import ApiResponse
 
 _NO_BODY = object()
 
@@ -37,6 +38,9 @@ class HttpClient:
                 "User-Agent": constants.SDK_USER_AGENT,
             },
         )
+        # A bare client for direct uploads: the pre-authorized upload URL lives
+        # outside the API host and must not receive the API key.
+        self._upload_client = httpx.Client(timeout=options.timeout, transport=transport)
 
     def request(
         self,
@@ -74,7 +78,12 @@ class HttpClient:
                     raise NetworkError(str(exc))
 
                 if response.is_success:
-                    return self._parse_body(response.text)
+                    body = self._parse_body(response.text)
+                    if body is None:
+                        return None
+                    if isinstance(body, (dict, list)):
+                        return ApiResponse(body, response.headers)
+                    return body
 
                 error = error_from_response(response)
                 if self._retryable(method, response.status_code) and retries < max_retries:
@@ -87,8 +96,23 @@ class HttpClient:
             for handle in opened:
                 handle.close()
 
+    def upload(self, url: str, headers: Dict[str, str], body: bytes) -> None:
+        """PUT bytes straight to a pre-authorized upload URL with the exact headers
+        issued for it. No auth, no retries: the URL is single-use and the body is
+        not safe to replay."""
+        try:
+            response = self._upload_client.put(url, content=body, headers=headers)
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(str(exc))
+        except httpx.TransportError as exc:
+            raise NetworkError(str(exc))
+
+        if not response.is_success:
+            raise error_from_response(response)
+
     def close(self) -> None:
         self._client.close()
+        self._upload_client.close()
 
     def _build_payload(
         self, body: Any

{runapi_core-0.1.0 → runapi_core-0.1.2}/src/runapi/core/models.py

@@ -20,6 +20,7 @@ from __future__ import annotations
 from typing import Any, Callable, Dict, List, Optional, Type, Union
 
 from .errors import ValidationError
+from .response import ResponseHeaders
 
 # A field's declared type. ``None`` means "untyped" (coerced dynamically); a
 # class is used directly; a callable is invoked lazily to resolve a forward
@@ -86,6 +87,7 @@ class BaseModel:
     def __init__(self, attributes: Optional[Dict[str, Any]] = None) -> None:
         source = self._normalize_input(attributes)
         self._attributes: Dict[str, Any] = {}
+        self._response_headers = ResponseHeaders()
 
         for field in self._fields.values():
             if field.name in source:
@@ -115,7 +117,7 @@ class BaseModel:
             return None
         if isinstance(value, BaseModel):
             if isinstance(target, type) and issubclass(target, BaseModel) and not isinstance(value, target):
-                return target.from_dict(value.to_dict())
+                return target.from_dict(value.to_dict())._with_response_headers(value.response_headers)
             return value
         if isinstance(value, dict):
             model = target if (isinstance(target, type) and issubclass(target, BaseModel)) else DynamicModel
@@ -153,6 +155,21 @@ class BaseModel:
     def to_dict(self) -> Dict[str, Any]:
         return {key: self._serialize(value) for key, value in self._attributes.items()}
 
+    @property
+    def response_headers(self) -> ResponseHeaders:
+        return self._response_headers
+
+    def response_header(self, name: str) -> Optional[str]:
+        return self._response_headers.get(name)
+
+    @property
+    def runapi_task_id(self) -> Optional[str]:
+        return self.response_header("X-RunAPI-Task-Id")
+
+    def _with_response_headers(self, headers: Any) -> "BaseModel":
+        self._response_headers = headers if isinstance(headers, ResponseHeaders) else ResponseHeaders(headers)
+        return self
+
     def __eq__(self, other: Any) -> bool:
         if isinstance(other, BaseModel):
             return self.to_dict() == other.to_dict()

{runapi_core-0.1.0 → runapi_core-0.1.2}/src/runapi/core/polling.py

@@ -32,13 +32,25 @@ def poll_until_complete(fetch: Callable[[], Any], options: Optional[PollingOptio
 
         if status == "failed":
             message = _value_for(response, "error") or "Task failed"
-            raise TaskFailedError(message, details=_details_for(response))
+            raise TaskFailedError(
+                message,
+                details=_details_for(response),
+                response_headers=_response_headers_for(response),
+            )
 
         if time.monotonic() >= deadline:
-            raise TaskTimeoutError(f"Task polling timed out after {options.max_wait}s")
+            raise TaskTimeoutError(
+                f"Task polling timed out after {options.max_wait}s",
+                details=_details_for(response),
+                response_headers=_response_headers_for(response),
+            )
 
         if status not in ACTIVE_STATUSES:
-            raise TaskFailedError(f"Unknown task status: {status}", details=_details_for(response))
+            raise TaskFailedError(
+                f"Unknown task status: {status}",
+                details=_details_for(response),
+                response_headers=_response_headers_for(response),
+            )
 
         time.sleep(options.poll_interval)
 
@@ -53,3 +65,7 @@ def _value_for(response: Any, key: str) -> Any:
 
 def _details_for(response: Any) -> Any:
     return response.to_dict() if isinstance(response, BaseModel) else response
+
+
+def _response_headers_for(response: Any) -> Any:
+    return response.response_headers if hasattr(response, "response_headers") else None