feat: allow custom models

Author: AdirAmsalem

README.md

@@ -89,6 +89,71 @@ async with DecartClient(api_key=os.getenv("DECART_API_KEY")) as client:
             f.write(data)
 ```
 
+### Custom Models
+
+For preview, experimental, or private models that are not yet in the SDK registry,
+create a custom model definition and pass it directly to the matching API.
+`models.realtime(...)`, `models.video(...)`, and `models.image(...)` remain registry-only helpers;
+use `models.custom(...)` when you need to send an arbitrary model name.
+
+```python
+from decart import DecartClient, RealtimeClient, RealtimeConnectOptions, models
+
+# Realtime: default url_path is /v1/stream.
+custom_realtime_model = models.custom(
+    "lucy_2_rt_preview",
+    fps=20,
+    width=1280,
+    height=720,
+)
+
+realtime_client = await RealtimeClient.connect(
+    base_url=client.realtime_base_url,
+    api_key=client.api_key,
+    local_track=track,
+    options=RealtimeConnectOptions(
+        model=custom_realtime_model,
+        on_remote_stream=lambda stream: print("remote stream", stream),
+    ),
+)
+
+# Process API: use a generation endpoint; the default realtime url_path is
+# not valid for client.process().
+custom_image_model = models.custom(
+    "lucy_image_preview",
+    url_path="/v1/generate/lucy_image_preview",
+    fps=25,
+    width=1280,
+    height=704,
+)
+
+image = await client.process({
+    "model": custom_image_model,
+    "prompt": "Apply a preview model treatment",
+    "data": open("input.png", "rb"),
+})
+
+# Queue API: add queue_url_path for async jobs.
+custom_video_model = models.custom(
+    "lucy_video_preview",
+    url_path="/v1/generate/lucy_video_preview",
+    queue_url_path="/v1/jobs/lucy_video_preview",
+    fps=20,
+    width=1280,
+    height=720,
+)
+
+job = await client.queue.submit({
+    "model": custom_video_model,
+    "prompt": "Use the preview video model",
+    "data": open("input.mp4", "rb"),
+})
+```
+
+If `input_schema` is omitted, custom process and queue inputs are sent through without
+client-side schema validation; the backend still validates whether the model name, endpoint,
+and inputs are supported.
+
 ## Development
 
 ### Setup with UV

decart/__init__.py

@@ -12,7 +12,7 @@
     QueueResultError,
     TokenCreateError,
 )
-from .models import models, ModelDefinition, VideoRestyleInput
+from .models import models, ModelDefinition, CustomModelDefinition, VideoRestyleInput
 from .types import FileInput, ModelState, Prompt
 from .queue import (
     QueueClient,
@@ -69,6 +69,7 @@
     "QueueResultError",
     "models",
     "ModelDefinition",
+    "CustomModelDefinition",
     "VideoRestyleInput",
     "FileInput",
     "ModelState",

decart/client.py

@@ -1,9 +1,10 @@
 import os
+from types import TracebackType
 from typing import Any, Optional
 import aiohttp
-from pydantic import ValidationError
+from pydantic import BaseModel, ValidationError
 from .errors import InvalidAPIKeyError, InvalidBaseURLError, InvalidInputError
-from .models import ImageModelDefinition, _MODELS
+from .models import ModelDefinition, _MODELS
 from .process.request import send_request
 from .queue.client import QueueClient
 from .tokens.client import TokensClient
@@ -128,25 +129,30 @@ async def close(self) -> None:
         if self._session and not self._session.closed:
             await self._session.close()
 
-    async def __aenter__(self):
+    async def __aenter__(self) -> "DecartClient":
         """Async context manager entry."""
         return self
 
-    async def __aexit__(self, exc_type, exc_val, exc_tb):
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
         """Async context manager exit."""
         await self.close()
 
     async def process(self, options: dict[str, Any]) -> bytes:
         """
         Process image editing synchronously.
-        Only image models support the process API.
+        Image models and custom process model definitions support the process API.
 
         For video editing, use the queue API instead:
             result = await client.queue.submit_and_poll({...})
 
         Args:
             options: Processing options including model and inputs
-                - model: ImageModelDefinition from models.image()
+                - model: ImageModelDefinition from models.image(), or a custom definition from models.custom()
                 - prompt: Text instructions describing the requested edit
                 - Additional model-specific inputs
 
@@ -160,14 +166,31 @@ async def process(self, options: dict[str, Any]) -> bytes:
         if "model" not in options:
             raise InvalidInputError("model is required")
 
-        model: ImageModelDefinition = options["model"]
+        model: ModelDefinition[str] = options["model"]
 
-        # Validate that this is an image model (check against registry)
-        if model.name not in _MODELS["image"]:
+        # Keep known non-image registry definitions on their intended APIs, but
+        # allow custom definitions with arbitrary names (even if a custom name
+        # happens to overlap a registry name).
+        is_known_image_model = model == _MODELS["image"].get(model.name)
+        is_known_video_model = model == _MODELS["video"].get(model.name)
+        is_known_realtime_model = model == _MODELS["realtime"].get(model.name)
+
+        if is_known_video_model or is_known_realtime_model:
+            next_step = (
+                "For realtime models, use RealtimeClient.connect() instead."
+                if is_known_realtime_model
+                else "For video models, use client.queue.submit_and_poll() instead."
+            )
             raise InvalidInputError(
                 f"Model '{model.name}' is not supported by process(). "
-                f"Only image models support sync processing. "
-                f"For video models, use client.queue.submit_and_poll() instead."
+                f"Only image/custom process models support sync processing. "
+                f"{next_step}"
+            )
+
+        if not is_known_image_model and model.url_path == "/v1/stream":
+            raise InvalidInputError(
+                f"Custom process model '{model.name}' must define a process url_path. "
+                f"Pass url_path when using models.custom(...) with client.process()."
             )
 
         cancel_token = options.get("cancel_token")
@@ -181,22 +204,27 @@ async def process(self, options: dict[str, Any]) -> bytes:
         file_inputs = {k: v for k, v in inputs.items() if k in FILE_FIELDS}
         non_file_inputs = {k: v for k, v in inputs.items() if k not in FILE_FIELDS}
 
-        # Validate non-file inputs and create placeholder for file fields
-        validation_inputs = {
-            **non_file_inputs,
-            **{k: b"" for k in file_inputs.keys()},  # Placeholder bytes for validation
-        }
-
-        try:
-            validated_inputs = model.input_schema(**validation_inputs)
-        except ValidationError as e:
-            raise InvalidInputError(f"Invalid inputs for {model.name}: {str(e)}") from e
-
-        # Build final inputs: validated non-file inputs + original file inputs
-        processed_inputs = {
-            **validated_inputs.model_dump(exclude_none=True),
-            **file_inputs,  # Override placeholders with actual file data
-        }
+        if model.input_schema is BaseModel:
+            # Custom models can omit an input schema; in that case we pass
+            # arbitrary fields through and let the backend validate them.
+            processed_inputs = {k: v for k, v in inputs.items() if v is not None}
+        else:
+            # Validate non-file inputs and create placeholder for file fields
+            validation_inputs = {
+                **non_file_inputs,
+                **{k: b"" for k in file_inputs.keys()},  # Placeholder bytes for validation
+            }
+
+            try:
+                validated_inputs = model.input_schema(**validation_inputs)
+            except ValidationError as e:
+                raise InvalidInputError(f"Invalid inputs for {model.name}: {str(e)}") from e
+
+            # Build final inputs: validated non-file inputs + original file inputs
+            processed_inputs = {
+                **validated_inputs.model_dump(exclude_none=True),
+                **file_inputs,  # Override placeholders with actual file data
+            }
 
         session = await self._get_session()
         response = await send_request(

decart/models.py

@@ -4,7 +4,6 @@
 from .errors import ModelNotFoundError
 from .types import FileInput, MotionTrajectoryInput
 
-
 RealTimeModels = Literal[
     # Canonical names
     "lucy",
@@ -89,10 +88,11 @@ class DecartBaseModel(BaseModel):
 class ModelDefinition(DecartBaseModel, Generic[ModelT]):
     name: ModelT
     url_path: str
+    queue_url_path: Optional[str] = None
     fps: int = Field(ge=1)
     width: int = Field(ge=1)
     height: int = Field(ge=1)
-    input_schema: type[BaseModel]
+    input_schema: type[BaseModel] = BaseModel
 
 
 # Type aliases for model definitions that support specific APIs
@@ -105,6 +105,13 @@ class ModelDefinition(DecartBaseModel, Generic[ModelT]):
 RealTimeModelDefinition = ModelDefinition[RealTimeModels]
 """Type alias for model definitions that support realtime streaming."""
 
+CustomModelDefinition = ModelDefinition[str]
+"""Type alias for custom model definitions with arbitrary model names.
+
+Useful for preview, experimental, or private models that are not yet
+in the SDK's built-in registry.
+"""
+
 
 class VideoToVideoInput(DecartBaseModel):
     prompt: str = Field(
@@ -299,6 +306,7 @@ class ImageToImageInput(DecartBaseModel):
         "lucy-clip": ModelDefinition(
             name="lucy-clip",
             url_path="/v1/jobs/lucy-clip",
+            queue_url_path="/v1/jobs/lucy-clip",
             fps=25,
             width=1280,
             height=704,
@@ -307,6 +315,7 @@ class ImageToImageInput(DecartBaseModel):
         "lucy-2.1": ModelDefinition(
             name="lucy-2.1",
             url_path="/v1/jobs/lucy-2.1",
+            queue_url_path="/v1/jobs/lucy-2.1",
             fps=20,
             width=1088,
             height=624,
@@ -315,6 +324,7 @@ class ImageToImageInput(DecartBaseModel):
         "lucy-2.1-vton": ModelDefinition(
             name="lucy-2.1-vton",
             url_path="/v1/jobs/lucy-2.1-vton",
+            queue_url_path="/v1/jobs/lucy-2.1-vton",
             fps=20,
             width=1088,
             height=624,
@@ -323,6 +333,7 @@ class ImageToImageInput(DecartBaseModel):
         "lucy-restyle-2": ModelDefinition(
             name="lucy-restyle-2",
             url_path="/v1/jobs/lucy-restyle-2",
+            queue_url_path="/v1/jobs/lucy-restyle-2",
             fps=22,
             width=1280,
             height=704,
@@ -331,6 +342,7 @@ class ImageToImageInput(DecartBaseModel):
         "lucy-motion": ModelDefinition(
             name="lucy-motion",
             url_path="/v1/jobs/lucy-motion",
+            queue_url_path="/v1/jobs/lucy-motion",
             fps=25,
             width=1280,
             height=704,
@@ -340,6 +352,7 @@ class ImageToImageInput(DecartBaseModel):
         "lucy-latest": ModelDefinition(
             name="lucy-latest",
             url_path="/v1/jobs/lucy-latest",
+            queue_url_path="/v1/jobs/lucy-latest",
             fps=20,
             width=1088,
             height=624,
@@ -348,6 +361,7 @@ class ImageToImageInput(DecartBaseModel):
         "lucy-vton-latest": ModelDefinition(
             name="lucy-vton-latest",
             url_path="/v1/jobs/lucy-vton-latest",
+            queue_url_path="/v1/jobs/lucy-vton-latest",
             fps=20,
             width=1088,
             height=624,
@@ -356,6 +370,7 @@ class ImageToImageInput(DecartBaseModel):
         "lucy-restyle-latest": ModelDefinition(
             name="lucy-restyle-latest",
             url_path="/v1/jobs/lucy-restyle-latest",
+            queue_url_path="/v1/jobs/lucy-restyle-latest",
             fps=22,
             width=1280,
             height=704,
@@ -364,6 +379,7 @@ class ImageToImageInput(DecartBaseModel):
         "lucy-clip-latest": ModelDefinition(
             name="lucy-clip-latest",
             url_path="/v1/jobs/lucy-clip-latest",
+            queue_url_path="/v1/jobs/lucy-clip-latest",
             fps=25,
             width=1280,
             height=704,
@@ -372,6 +388,7 @@ class ImageToImageInput(DecartBaseModel):
         "lucy-motion-latest": ModelDefinition(
             name="lucy-motion-latest",
             url_path="/v1/jobs/lucy-motion-latest",
+            queue_url_path="/v1/jobs/lucy-motion-latest",
             fps=25,
             width=1280,
             height=704,
@@ -381,6 +398,7 @@ class ImageToImageInput(DecartBaseModel):
         "lucy-pro-v2v": ModelDefinition(
             name="lucy-pro-v2v",
             url_path="/v1/jobs/lucy-pro-v2v",
+            queue_url_path="/v1/jobs/lucy-pro-v2v",
             fps=25,
             width=1280,
             height=704,
@@ -389,6 +407,7 @@ class ImageToImageInput(DecartBaseModel):
         "lucy-restyle-v2v": ModelDefinition(
             name="lucy-restyle-v2v",
             url_path="/v1/jobs/lucy-restyle-v2v",
+            queue_url_path="/v1/jobs/lucy-restyle-v2v",
             fps=22,
             width=1280,
             height=704,
@@ -428,6 +447,41 @@ class ImageToImageInput(DecartBaseModel):
 
 
 class Models:
+    @staticmethod
+    def custom(
+        name: str,
+        *,
+        fps: int,
+        width: int,
+        height: int,
+        url_path: str = "/v1/stream",
+        input_schema: type[BaseModel] = BaseModel,
+        queue_url_path: Optional[str] = None,
+    ) -> CustomModelDefinition:
+        """Create a custom model definition with an arbitrary model name.
+
+        This is useful for preview, experimental, or private models that are
+        not yet in the SDK's built-in registry. Pass the returned definition
+        directly to the matching client API.
+
+        For realtime models, keep the default ``url_path="/v1/stream"``.
+        For process/custom image models, pass the generation endpoint as
+        ``url_path``; the default realtime stream path is not valid for
+        ``client.process()``. For queue/custom video models, pass
+        ``queue_url_path``.
+        If ``input_schema`` is omitted, process and queue inputs are sent
+        through without client-side schema validation.
+        """
+        return CustomModelDefinition(
+            name=name,
+            url_path=url_path,
+            queue_url_path=queue_url_path,
+            fps=fps,
+            width=width,
+            height=height,
+            input_schema=input_schema,
+        )
+
     @staticmethod
     def realtime(model: RealTimeModels) -> RealTimeModelDefinition:
         """Get a realtime model definition for WebRTC streaming."""

decart/process/request.py

@@ -80,7 +80,7 @@ async def send_request(
     session: aiohttp.ClientSession,
     base_url: str,
     api_key: str,
-    model: ModelDefinition,
+    model: ModelDefinition[str],
     inputs: dict[str, Any],
     cancel_token: Optional[asyncio.Event] = None,
     integration: Optional[str] = None,