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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runapi-core
-Version: 0.1.1
+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
@@ -35,29 +35,29 @@ runapi.configure(api_key="sk-...")  # or set RUNAPI_API_KEY in the environment
 
 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 model SDK methods currently return parsed response bodies. When an integration needs to send a client request id or read `X-RunAPI-Task-Id`, make the call through direct HTTP or a custom transport so response headers stay available.
+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
 
-import httpx
-
-response = httpx.post(
-    "https://runapi.ai/api/v1/suno/text_to_music",
-    headers={
-        "Authorization": f"Bearer {os.environ['RUNAPI_API_KEY']}",
-        "X-Client-Request-Id": "order-123",
-    },
-    json={
-        "prompt": "A chill lo-fi beat",
-        "model": "suno-v4.5-plus",
-        "vocal_mode": "instrumental",
-    },
-    timeout=900,
+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,
 )
-response.raise_for_status()
-runapi_task_id = response.headers.get("X-RunAPI-Task-Id")
-body = response.json()
+
+runapi_task_id = response.runapi_task_id
+# Equivalent case-insensitive lookup:
+runapi_task_id = response.response_headers["X-RunAPI-Task-Id"]
 ```
 
 ```python

{runapi_core-0.1.1 → runapi_core-0.1.2}/README.md

@@ -10,7 +10,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
@@ -22,29 +22,29 @@ runapi.configure(api_key="sk-...")  # or set RUNAPI_API_KEY in the environment
 
 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 model SDK methods currently return parsed response bodies. When an integration needs to send a client request id or read `X-RunAPI-Task-Id`, make the call through direct HTTP or a custom transport so response headers stay available.
+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
 
-import httpx
-
-response = httpx.post(
-    "https://runapi.ai/api/v1/suno/text_to_music",
-    headers={
-        "Authorization": f"Bearer {os.environ['RUNAPI_API_KEY']}",
-        "X-Client-Request-Id": "order-123",
-    },
-    json={
-        "prompt": "A chill lo-fi beat",
-        "model": "suno-v4.5-plus",
-        "vocal_mode": "instrumental",
-    },
-    timeout=900,
+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,
 )
-response.raise_for_status()
-runapi_task_id = response.headers.get("X-RunAPI-Task-Id")
-body = response.json()
+
+runapi_task_id = response.runapi_task_id
+# Equivalent case-insensitive lookup:
+runapi_task_id = response.response_headers["X-RunAPI-Task-Id"]
 ```
 
 ```python

{runapi_core-0.1.1 → 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.1 → runapi_core-0.1.2}/src/runapi/core/contract_gen.py

@@ -603,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": {
@@ -624,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"]

{runapi_core-0.1.1 → 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.1 → 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()
 
@@ -77,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:

{runapi_core-0.1.1 → 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.1 → 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

{runapi_core-0.1.1 → runapi_core-0.1.2}/src/runapi/core/resource.py

@@ -8,6 +8,7 @@ from . import polling
 from .errors import ValidationError
 from .models import BaseModel, TaskResponse
 from .options import PollingOptions, RequestOptions
+from .response import ApiResponse
 
 
 class Resource:
@@ -33,7 +34,11 @@ class Resource:
         response_class: Optional[type] = None,
     ) -> Any:
         response = self._http.request(method, path, body=body, options=options)
-        return BaseModel.coerce(response, as_=response_class or type(self).RESPONSE_CLASS)
+        payload = response.body if isinstance(response, ApiResponse) else response
+        result = BaseModel.coerce(payload, as_=response_class or type(self).RESPONSE_CLASS)
+        if isinstance(response, ApiResponse):
+            self._attach_response_headers(result, response.response_headers)
+        return result
 
     @staticmethod
     def _compact_params(params: Dict[str, Any]) -> Dict[str, Any]:
@@ -196,4 +201,14 @@ class Resource:
             return response
 
         payload = response.to_dict() if isinstance(response, BaseModel) else response
-        return completed_class.from_dict(payload)
+        completed = completed_class.from_dict(payload)
+        if isinstance(response, BaseModel):
+            completed._with_response_headers(response.response_headers)
+        return completed
+
+    def _attach_response_headers(self, result: Any, headers: Any) -> None:
+        if isinstance(result, BaseModel):
+            result._with_response_headers(headers)
+        elif isinstance(result, list):
+            for item in result:
+                self._attach_response_headers(item, headers)

runapi_core-0.1.2/src/runapi/core/response.py

@@ -0,0 +1,56 @@
+"""Response metadata containers shared by transports and typed models."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping, Sequence
+from typing import Any, Optional
+
+
+class ResponseHeaders(Mapping[str, str]):
+    """Case-insensitive response headers."""
+
+    def __init__(self, headers: Optional[Mapping[str, Any]] = None) -> None:
+        self._headers = {str(key).lower(): str(value) for key, value in (headers or {}).items()}
+
+    def __getitem__(self, key: str) -> str:
+        return self._headers[str(key).lower()]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._headers)
+
+    def __len__(self) -> int:
+        return len(self._headers)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._headers.get(str(key).lower(), default)
+
+    def to_dict(self) -> dict[str, str]:
+        return dict(self._headers)
+
+
+class ApiResponse(dict[str, Any]):
+    """Parsed response body plus HTTP response headers.
+
+    The object delegates common body access so existing direct transport users
+    that index the returned JSON body keep working.
+    """
+
+    def __init__(self, body: Mapping[str, Any] | Sequence[Any], headers: Optional[Mapping[str, Any]] = None) -> None:
+        super().__init__(body if isinstance(body, Mapping) else {})
+        self.body = self if isinstance(body, Mapping) else body
+        self.response_headers = headers if isinstance(headers, ResponseHeaders) else ResponseHeaders(headers)
+        self.headers = self.response_headers
+
+    def __getitem__(self, key: Any) -> Any:
+        if self.body is not self:
+            return self.body[key]  # type: ignore[index]
+        return super().__getitem__(key)
+
+    def __eq__(self, other: Any) -> bool:
+        if isinstance(other, ApiResponse):
+            left = dict(self) if self.body is self else self.body
+            right = dict(other) if other.body is other else other.body
+            return left == right
+        if self.body is self:
+            return dict(self) == other
+        return self.body == other

runapi_core-0.1.2/src/runapi/core/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.2"

{runapi_core-0.1.1 → runapi_core-0.1.2}/tests/test_http_client.py

@@ -4,7 +4,7 @@ import tempfile
 import httpx
 import pytest
 
-from runapi.core import constants, errors, http_client
+from runapi.core import ApiResponse, constants, errors, http_client
 from runapi.core.http_client import HttpClient
 from runapi.core.multipart import MultipartBody, MultipartFile
 from runapi.core.options import ClientOptions, RequestOptions
@@ -31,6 +31,55 @@ def test_returns_parsed_json_on_success():
     assert client.request("get", "/api/v1/test") == {"id": "123"}
 
 
+def test_keeps_response_headers_on_success():
+    client = make_client(
+        lambda request: httpx.Response(
+            200,
+            json={"id": "task-1"},
+            headers={"X-RunAPI-Task-Id": "task-ref-1"},
+        )
+    )
+    result = client.request("post", "/api/v1/test", body={"prompt": "hello"})
+    assert result == {"id": "task-1"}
+    assert result.response_headers["X-RunAPI-Task-Id"] == "task-ref-1"
+    assert result.response_headers["x-runapi-task-id"] == "task-ref-1"
+
+
+def test_keeps_response_headers_on_successful_array_response():
+    client = make_client(
+        lambda request: httpx.Response(
+            200,
+            json=[{"id": "task-1"}],
+            headers={"X-RunAPI-Task-Id": "task-ref-1"},
+        )
+    )
+
+    result = client.request("get", "/api/v1/test")
+
+    assert isinstance(result, ApiResponse)
+    assert result == [{"id": "task-1"}]
+    assert result.body == [{"id": "task-1"}]
+    assert result[0] == {"id": "task-1"}
+    assert result.response_headers["x-runapi-task-id"] == "task-ref-1"
+
+
+def test_keeps_response_headers_on_error():
+    client = make_client(
+        lambda request: httpx.Response(
+            500,
+            json={"error": "fail"},
+            headers={"X-RunAPI-Task-Id": "task-ref-1"},
+        ),
+        max_retries=0,
+    )
+
+    with pytest.raises(errors.ServerError) as info:
+        client.request("get", "/api/v1/test")
+
+    assert info.value.runapi_task_id == "task-ref-1"
+    assert info.value.response_headers["x-runapi-task-id"] == "task-ref-1"
+
+
 def test_sends_bearer_and_user_agent():
     captured = {}
 

{runapi_core-0.1.1 → runapi_core-0.1.2}/tests/test_models.py

@@ -110,3 +110,10 @@ def test_field_inheritance_override():
     with pytest.raises(ValidationError, match="value is required"):
         Child({})
     assert Child({"value": "ok"}).value == "ok"
+
+
+def test_response_headers_stay_outside_serialized_body():
+    model = Sample({"id": "abc"})._with_response_headers({"X-RunAPI-Task-Id": "task-ref-1"})
+    assert model.response_header("x-runapi-task-id") == "task-ref-1"
+    assert model.runapi_task_id == "task-ref-1"
+    assert model.to_dict() == {"id": "abc"}

{runapi_core-0.1.1 → runapi_core-0.1.2}/tests/test_polling.py

@@ -64,12 +64,36 @@ def test_serializes_model_details():
     assert info.value.details == {"status": "failed", "error": "oops", "code": 500}
 
 
+def test_task_failed_keeps_response_headers():
+    response = TaskResponse({"status": "failed", "error": "oops"})._with_response_headers(
+        {"X-RunAPI-Task-Id": "task-ref-1"}
+    )
+    with pytest.raises(TaskFailedError) as info:
+        polling.poll_until_complete(lambda: response, options())
+    assert info.value.runapi_task_id == "task-ref-1"
+    assert info.value.response_headers["x-runapi-task-id"] == "task-ref-1"
+
+
 def test_raises_timeout():
     short = PollingOptions(poll_interval=0.01, max_wait=0)
     with pytest.raises(TaskTimeoutError):
         polling.poll_until_complete(lambda: {"status": "processing"}, short)
 
 
+def test_task_timeout_keeps_last_response_headers():
+    short = PollingOptions(poll_interval=0.01, max_wait=0)
+    response = TaskResponse({"status": "processing"})._with_response_headers(
+        {"X-RunAPI-Task-Id": "task-ref-1"}
+    )
+
+    with pytest.raises(TaskTimeoutError) as info:
+        polling.poll_until_complete(lambda: response, short)
+
+    assert info.value.details == {"status": "processing"}
+    assert info.value.runapi_task_id == "task-ref-1"
+    assert info.value.response_headers["x-runapi-task-id"] == "task-ref-1"
+
+
 def test_normalizes_uppercase_status():
     response = {"status": "COMPLETED", "images": [{"url": "u"}]}
     assert polling.poll_until_complete(lambda: response, options()) == response

{runapi_core-0.1.1 → runapi_core-0.1.2}/tests/test_resource.py

@@ -1,6 +1,6 @@
 import pytest
 
-from runapi.core import BaseModel, Resource, TaskResponse, optional, required
+from runapi.core import ApiResponse, BaseModel, Resource, TaskResponse, optional, required
 from runapi.core.errors import ValidationError
 from runapi.core.options import PollingOptions
 
@@ -36,6 +36,31 @@ def test_request_coerces_to_response_class():
     assert result.id == "1"
 
 
+def test_request_attaches_response_headers_to_model():
+    resource = SampleResource(
+        FakeHttp(ApiResponse({"id": "1", "status": "pending"}, {"X-RunAPI-Task-Id": "task-ref-1"}))
+    )
+    result = resource._request("post", "/x", body={"a": 1})
+    assert isinstance(result, TaskResponse)
+    assert result.runapi_task_id == "task-ref-1"
+    assert result.response_headers["X-RunAPI-Task-Id"] == "task-ref-1"
+    assert result.to_dict() == {"id": "1", "status": "pending"}
+
+
+def test_request_attaches_response_headers_to_array_items():
+    resource = SampleResource(
+        FakeHttp(ApiResponse([{"id": "1", "status": "pending"}], {"X-RunAPI-Task-Id": "task-ref-1"}))
+    )
+
+    result = resource._request("post", "/x", body={"a": 1})
+
+    assert len(result) == 1
+    assert isinstance(result[0], TaskResponse)
+    assert result[0].runapi_task_id == "task-ref-1"
+    assert result[0].response_headers["X-RunAPI-Task-Id"] == "task-ref-1"
+    assert result[0].to_dict() == {"id": "1", "status": "pending"}
+
+
 def test_compact_params_drops_none_and_blank():
     assert Resource._compact_params({"a": 1, "b": None, "c": "", "d": "  ", "e": "x"}) == {"a": 1, "e": "x"}
 

runapi_core-0.1.1/src/runapi/core/version.py

@@ -1 +0,0 @@
-__version__ = "0.1.1"