runapi-core 0.1.0__py3-none-any.whl

runapi/core/models.py

@@ -0,0 +1,248 @@
+"""Lightweight response models with typed field declarations and recursive coercion.
+
+A faithful port of Ruby's ``Core::BaseModel``. Subclasses declare fields with
+:func:`required` / :func:`optional` as class attributes; the field name is the
+attribute name::
+
+    class Image(BaseModel):
+        url = optional(str)
+
+    class TextToImageResponse(TaskResponse):
+        id = required(str)
+        images = optional([lambda: Image])
+
+Declared fields are coerced and enum-validated on construction. Undeclared
+fields are preserved and exposed via attribute and item access.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional, Type, Union
+
+from .errors import ValidationError
+
+# A field's declared type. ``None`` means "untyped" (coerced dynamically); a
+# class is used directly; a callable is invoked lazily to resolve a forward
+# reference (e.g. ``lambda: Image``); a one-element list marks a list of items.
+FieldType = Union[None, type, Callable[[], Any], List[Any]]
+EnumType = Union[None, List[Any], Callable[[], List[Any]]]
+
+
+class Field:
+    """A declared model field. Doubles as a descriptor that reads from the instance."""
+
+    def __init__(self, required: bool, type: FieldType = None, enum: EnumType = None) -> None:
+        self.required = required
+        self.enum = enum
+        self.name: Optional[str] = None
+
+        if isinstance(type, list):
+            if len(type) != 1:
+                raise ValueError("Array field type must contain exactly one item type")
+            self.type: FieldType = list
+            self.item_type: FieldType = type[0]
+        else:
+            self.type = type
+            self.item_type = None
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        self.name = name
+
+    def __get__(self, obj: Any, objtype: Optional[type] = None) -> Any:
+        if obj is None:
+            return self
+        return obj._attributes.get(self.name)
+
+
+def required(type: FieldType = None, *, enum: EnumType = None) -> Field:
+    return Field(required=True, type=type, enum=enum)
+
+
+def optional(type: FieldType = None, *, enum: EnumType = None) -> Field:
+    return Field(required=False, type=type, enum=enum)
+
+
+def _resolve_type(type_: FieldType) -> Any:
+    if type_ is None:
+        return None
+    if isinstance(type_, type):
+        return type_
+    if callable(type_):
+        return type_()
+    return type_
+
+
+class BaseModel:
+    _fields: Dict[str, Field] = {}
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        merged: Dict[str, Field] = dict(getattr(cls, "_fields", {}))
+        for value in vars(cls).values():
+            if isinstance(value, Field) and value.name is not None:
+                merged[value.name] = value
+        cls._fields = merged
+
+    def __init__(self, attributes: Optional[Dict[str, Any]] = None) -> None:
+        source = self._normalize_input(attributes)
+        self._attributes: Dict[str, Any] = {}
+
+        for field in self._fields.values():
+            if field.name in source:
+                value = self._coerce_declared_value(source.pop(field.name), field)
+                self._attributes[field.name] = value
+            elif field.required:
+                raise ValidationError(f"{field.name} is required")
+
+        for key, value in source.items():
+            self._attributes[key] = self._coerce_dynamic_value(value)
+
+    # --- construction helpers -------------------------------------------------
+
+    @classmethod
+    def from_dict(cls, payload: Any) -> "BaseModel":
+        if isinstance(payload, cls):
+            return payload
+        if not isinstance(payload, dict):
+            raise TypeError(f"Expected dict for {cls.__name__}, got {type(payload).__name__}")
+        return cls(payload)
+
+    @classmethod
+    def coerce(cls, value: Any, as_: FieldType = None) -> Any:
+        target = _resolve_type(as_) or DynamicModel
+
+        if value is None:
+            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 value
+        if isinstance(value, dict):
+            model = target if (isinstance(target, type) and issubclass(target, BaseModel)) else DynamicModel
+            return model.from_dict(value)
+        if isinstance(value, list):
+            return [cls.coerce(item, as_=target) for item in value]
+        return value
+
+    # --- access ---------------------------------------------------------------
+
+    def __getattr__(self, name: str) -> Any:
+        attributes = self.__dict__.get("_attributes", {})
+        if name in attributes:
+            return attributes[name]
+        raise AttributeError(name)
+
+    def __getitem__(self, key: Any) -> Any:
+        return self._attributes.get(str(key))
+
+    def dig(self, *keys: Any) -> Any:
+        current: Any = self
+        for key in keys:
+            if isinstance(current, BaseModel):
+                current = current[key]
+            elif isinstance(current, dict):
+                current = current.get(key)
+            elif isinstance(current, list):
+                current = current[key] if isinstance(key, int) else None
+            else:
+                return None
+            if current is None:
+                return None
+        return current
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {key: self._serialize(value) for key, value in self._attributes.items()}
+
+    def __eq__(self, other: Any) -> bool:
+        if isinstance(other, BaseModel):
+            return self.to_dict() == other.to_dict()
+        if isinstance(other, dict):
+            return self.to_dict() == _stringify_keys(other)
+        return NotImplemented
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self._attributes!r})"
+
+    # --- internals ------------------------------------------------------------
+
+    def _coerce_declared_value(self, value: Any, field: Field) -> Any:
+        if field.type is list and isinstance(value, list):
+            coerced: Any = [self._coerce_with_type(item, field.item_type) for item in value]
+        else:
+            coerced = self._coerce_with_type(value, field.type)
+        self._validate_enum(field, coerced)
+        return coerced
+
+    def _coerce_with_type(self, value: Any, type_: FieldType) -> Any:
+        if type_ is None:
+            return self._coerce_dynamic_value(value)
+
+        resolved = _resolve_type(type_)
+        if resolved is None:
+            return self._coerce_dynamic_value(value)
+        if isinstance(resolved, type) and issubclass(resolved, BaseModel) and isinstance(value, dict):
+            return resolved.from_dict(value)
+        return value
+
+    def _coerce_dynamic_value(self, value: Any) -> Any:
+        if isinstance(value, dict):
+            return DynamicModel.from_dict(value)
+        if isinstance(value, list):
+            return [self._coerce_dynamic_value(item) for item in value]
+        return value
+
+    def _validate_enum(self, field: Field, value: Any) -> None:
+        if value is None or field.enum is None:
+            return
+        allowed = field.enum() if callable(field.enum) else field.enum
+        if not allowed:
+            return
+
+        candidates = value if isinstance(value, list) else [value]
+        for item in candidates:
+            if not any(option == item or str(option) == str(item) for option in allowed):
+                joined = ", ".join(str(option) for option in allowed)
+                raise ValidationError(f"Invalid {field.name}: {item}. Must be one of: {joined}")
+
+    def _serialize(self, value: Any) -> Any:
+        if isinstance(value, BaseModel):
+            return value.to_dict()
+        if isinstance(value, list):
+            return [self._serialize(item) for item in value]
+        return value
+
+    @staticmethod
+    def _normalize_input(attributes: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+        if attributes is None:
+            return {}
+        if not isinstance(attributes, dict):
+            raise TypeError(f"Expected dict, got {type(attributes).__name__}")
+        return {str(key): value for key, value in attributes.items()}
+
+
+class DynamicModel(BaseModel):
+    """Generic response model used when no typed model is provided."""
+
+
+def _stringify_keys(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {str(key): _stringify_keys(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_stringify_keys(item) for item in value]
+    return value
+
+
+class TaskResponse(BaseModel):
+    """Typed response for async task operations. Extra fields are preserved."""
+
+    class Status:
+        PENDING = "pending"
+        PROCESSING = "processing"
+        COMPLETED = "completed"
+        FAILED = "failed"
+
+        ALL = [PENDING, PROCESSING, COMPLETED, FAILED]
+
+    id = optional(str)
+    status = optional(str)
+    error = optional(str)

runapi/core/multipart.py

@@ -0,0 +1,23 @@
+"""Multipart upload payloads."""
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class MultipartFile:
+    path: str
+    filename: Optional[str] = None
+    content_type: Optional[str] = None
+
+
+class MultipartBody:
+    """A multipart/form-data request body of plain fields plus file parts."""
+
+    def __init__(
+        self,
+        fields: Optional[Dict[str, Any]] = None,
+        files: Optional[Dict[str, MultipartFile]] = None,
+    ) -> None:
+        self.fields: Dict[str, Any] = {str(key): value for key, value in (fields or {}).items()}
+        self.files: Dict[str, MultipartFile] = {str(key): value for key, value in (files or {}).items()}

runapi/core/options.py

@@ -0,0 +1,54 @@
+"""Client, request, and polling option dataclasses."""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+from . import config, constants
+
+
+@dataclass
+class ClientOptions:
+    """Configuration for an API client.
+
+    ``http_client`` lets callers inject a custom transport (for tests or
+    advanced use). When set, the SDK delegates all HTTP calls to it instead of
+    building its own :class:`HttpClient`. It must expose
+    ``request(method, path, body=None, options=None)``.
+    """
+
+    api_key: Optional[str] = None
+    base_url: Optional[str] = None
+    timeout: Optional[int] = None
+    max_retries: Optional[int] = None
+    retry_base_delay: Optional[float] = None
+    retry_max_delay: Optional[float] = None
+    http_client: Optional[Any] = None
+
+    def __post_init__(self) -> None:
+        if self.base_url is None:
+            self.base_url = config.base_url
+        if self.timeout is None:
+            self.timeout = constants.HTTP_REQUEST_TIMEOUT
+        if self.max_retries is None:
+            self.max_retries = constants.MAX_RETRIES
+        if self.retry_base_delay is None:
+            self.retry_base_delay = constants.RETRY_BASE_DELAY
+        if self.retry_max_delay is None:
+            self.retry_max_delay = constants.RETRY_MAX_DELAY
+
+
+@dataclass
+class RequestOptions:
+    """Per-request overrides of client-level defaults."""
+
+    headers: Optional[Dict[str, str]] = None
+    timeout: Optional[int] = None
+    max_retries: Optional[int] = None
+
+
+@dataclass
+class PollingOptions:
+    """Options for polling async task completion."""
+
+    poll_interval: int = field(default=constants.POLLING_INTERVAL)
+    max_wait: int = field(default=constants.POLLING_MAX_WAIT)

runapi/core/polling.py

@@ -0,0 +1,55 @@
+"""Polling loop for async task completion."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Optional
+
+from .errors import TaskFailedError, TaskTimeoutError
+from .models import BaseModel
+from .options import PollingOptions
+
+ACTIVE_STATUSES = ("pending", "processing")
+
+
+def poll_until_complete(fetch: Callable[[], Any], options: Optional[PollingOptions] = None) -> Any:
+    """Call ``fetch`` repeatedly until the task completes.
+
+    Returns the completed response. Raises :class:`TaskFailedError` on a failed
+    or unknown status, and :class:`TaskTimeoutError` once ``max_wait`` elapses.
+    """
+    if options is None:
+        options = PollingOptions()
+
+    deadline = time.monotonic() + options.max_wait
+
+    while True:
+        response = fetch()
+        status = str(_value_for(response, "status") or "").lower()
+
+        if status == "completed":
+            return response
+
+        if status == "failed":
+            message = _value_for(response, "error") or "Task failed"
+            raise TaskFailedError(message, details=_details_for(response))
+
+        if time.monotonic() >= deadline:
+            raise TaskTimeoutError(f"Task polling timed out after {options.max_wait}s")
+
+        if status not in ACTIVE_STATUSES:
+            raise TaskFailedError(f"Unknown task status: {status}", details=_details_for(response))
+
+        time.sleep(options.poll_interval)
+
+
+def _value_for(response: Any, key: str) -> Any:
+    if isinstance(response, BaseModel):
+        return response[key]
+    if isinstance(response, dict):
+        return response.get(key)
+    return None
+
+
+def _details_for(response: Any) -> Any:
+    return response.to_dict() if isinstance(response, BaseModel) else response

runapi/core/resource.py

@@ -0,0 +1,65 @@
+"""Base class for API resources: request coercion, param helpers, polling."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional, Sequence
+
+from . import polling
+from .errors import ValidationError
+from .models import BaseModel, TaskResponse
+from .options import PollingOptions, RequestOptions
+
+
+class Resource:
+    """Shared behavior for resource classes.
+
+    Subclasses set ``RESPONSE_CLASS`` (the typed model for responses) and
+    optionally ``COMPLETED_RESPONSE_CLASS`` (a narrowed model that ``run()``
+    re-coerces to once the task completes).
+    """
+
+    RESPONSE_CLASS: type = TaskResponse
+    COMPLETED_RESPONSE_CLASS: Optional[type] = None
+
+    def __init__(self, http: Any) -> None:
+        self._http = http
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Any = None,
+        options: Optional[RequestOptions] = None,
+        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)
+
+    @staticmethod
+    def _compact_params(params: Dict[str, Any]) -> Dict[str, Any]:
+        return {
+            key: value
+            for key, value in params.items()
+            if not (value is None or (isinstance(value, str) and value.strip() == ""))
+        }
+
+    @staticmethod
+    def _validate_optional(params: Dict[str, Any], key: str, allowed: Sequence[Any]) -> None:
+        value = params.get(key)
+        if value is None:
+            return
+        if value not in allowed:
+            joined = ", ".join(str(option) for option in allowed)
+            raise ValidationError(f"Invalid {key}: {value}. Must be one of: {joined}")
+
+    def _poll_until_complete(
+        self, fetch: Callable[[], Any], polling_opts: Optional[PollingOptions] = None
+    ) -> Any:
+        response = polling.poll_until_complete(fetch, polling_opts or PollingOptions())
+
+        completed_class = type(self).COMPLETED_RESPONSE_CLASS
+        if completed_class is None or isinstance(response, completed_class):
+            return response
+
+        payload = response.to_dict() if isinstance(response, BaseModel) else response
+        return completed_class.from_dict(payload)

runapi/core/version.py

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

runapi_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: runapi-core
+Version: 0.1.0
+Summary: Core module for the RunAPI Python SDK
+Project-URL: Homepage, https://runapi.ai
+Project-URL: Documentation, https://runapi.ai/docs#sdk
+Author-email: RunAPI <contact@runapi.ai>
+License-Expression: Apache-2.0
+Keywords: ai,api,runapi,sdk
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# 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 model SDKs 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
+```
+
+```python
+from runapi.core import FilesClient
+
+files = FilesClient()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
+uploaded = files.create(file="./input.png")
+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.dist-info/RECORD

@@ -0,0 +1,18 @@
+runapi/core/__init__.py,sha256=hJ_3FVD39iVgkQ9QpFMImEdi9q7Ge_xj1fkfBdDZUJg,1694
+runapi/core/auth.py,sha256=woKMW_oidp9xEmPHb2-7QVvNc8aIitycuIaTdv2Pacw,1053
+runapi/core/config.py,sha256=9HoDPKzkV1Zhwi8qdZPuB_MQhEv59KTW-rly-Xre0YY,728
+runapi/core/constants.py,sha256=peWEesxVWjyGMVbBzXBr4C7ZgWjzXKgh4T4q7EI-IwQ,400
+runapi/core/contract_gen.py,sha256=9gfXFv5n05AHCpQobjcaB-HEou7Zga4vywxFdEONe9Q,46457
+runapi/core/errors.py,sha256=g4hqy_FNeTMi_pvMecmu_jkwlBNPpnKDinTjqJjAuBE,7802
+runapi/core/files.py,sha256=hUNsXBUwYRysWlOVpO18cHuaowj6CwXeAE6i-6psrgg,3507
+runapi/core/http_client.py,sha256=Yh1ZlGHiBX0tZfXuwMXOl0ccD8WAvsEoy7n_aLmhOZI,4566
+runapi/core/models.py,sha256=useACuEJ3Ob5QALyazBN7AVyFSw8GEPp94efRa1KUEs,9007
+runapi/core/multipart.py,sha256=Hv6T6FCnTkB4KEC_gIicK9zppCA6_jseb4RKRrLdtHw,687
+runapi/core/options.py,sha256=MlXzPWEdyuL1-JcUWfszfWZ-5MuaEHUelEatZzHj7f0,1719
+runapi/core/polling.py,sha256=v2_tjrDGlRjn6LWcshQgIdLsXoJX4AjQQ4YSy0dUcHE,1735
+runapi/core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+runapi/core/resource.py,sha256=ZIxRA2izZeX6cnV_6_417kR4F1qW2IE7rfaGUrQRULo,2308
+runapi/core/version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+runapi_core-0.1.0.dist-info/METADATA,sha256=WvqR5b2-S9VB9kunCfH2KzmMwL24aVamJjwGbQIOyjo,1459
+runapi_core-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+runapi_core-0.1.0.dist-info/RECORD,,

runapi_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any