feat: add first SDK implementation

.github/workflows/ci.yml

@@ -0,0 +1,130 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint & Format Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install UV
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Add UV to PATH
+        run: echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Check formatting with Black
+        run: uv run black --check decart_sdk/ tests/ examples/
+
+      - name: Lint with Ruff
+        run: uv run ruff check decart_sdk/ tests/ examples/
+
+      - name: Type check with MyPy
+        run: uv run mypy decart_sdk/
+        continue-on-error: true # Don't fail on type errors yet
+
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install UV
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Add UV to PATH
+        run: echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run tests
+        run: uv run pytest tests/ -v --cov=decart_sdk --cov-report=xml --cov-report=term
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        if: matrix.python-version == '3.12'
+        with:
+          file: ./coverage.xml
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: false
+
+  test-examples:
+    name: Test Examples (Syntax Check)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install UV
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Add UV to PATH
+        run: echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Check examples for syntax errors
+        run: |
+          echo "Checking examples compile without syntax errors..."
+          uv run python -m py_compile examples/process_video.py
+          uv run python -m py_compile examples/process_image.py
+          uv run python -m py_compile examples/realtime_synthetic.py
+          uv run python -m py_compile examples/realtime_file.py
+          echo "✅ All examples have valid syntax"
+
+      # Note: Examples require DECART_API_KEY to actually run
+      # They are only syntax-checked in CI
+
+  build:
+    name: Build Package
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install UV
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Add UV to PATH
+        run: echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Check package
+        run: |
+          uv run pip install twine
+          uv run twine check dist/*
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

.gitignore

@@ -0,0 +1,60 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv/
+.venv
+
+# UV
+.python-version
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.mp4
+*.mov
+*.png
+*.jpg
+*.jpeg

README.md

@@ -0,0 +1,113 @@
+# Decart Python SDK
+
+A Python SDK for Decart's models.
+
+## Installation
+
+### Using UV
+
+```bash
+uv pip install decart-sdk
+```
+
+### Using pip
+
+```bash
+pip install decart-sdk
+```
+
+## Documentation
+
+For complete documentation, guides, and examples, visit:
+**https://docs.platform.decart.ai/sdks/python**
+
+## Quick Start
+
+### Process Files
+
+```python
+import asyncio
+import os
+from decart_sdk import DecartClient, models
+
+async def main():
+    async with DecartClient(api_key=os.getenv("DECART_API_KEY")) as client:
+        # Generate a video from text
+        result = await client.process({
+            "model": models.video("lucy-pro-t2v"),
+            "prompt": "A cat walking in a lego world",
+        })
+
+        # Save the result
+        with open("output.mp4", "wb") as f:
+            f.write(result)
+
+asyncio.run(main())
+```
+
+### Video Transformation
+
+```python
+async with DecartClient(api_key=os.getenv("DECART_API_KEY")) as client:
+    # Transform a video file
+    with open("input.mp4", "rb") as video_file:
+        result = await client.process({
+            "model": models.video("lucy-pro-v2v"),
+            "prompt": "Anime style with vibrant colors",
+            "data": video_file,
+            "enhance_prompt": True,
+        })
+
+    # Save the result
+    with open("output.mp4", "wb") as f:
+        f.write(result)
+```
+
+## Development
+
+### Setup with UV
+
+```bash
+# Clone the repository
+git clone https://github.com/decartai/decart-python
+cd decart-python
+
+# Install UV
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install all dependencies (including dev dependencies)
+uv sync --all-extras
+
+# Run tests
+uv run pytest
+
+# Run linting
+uv run ruff check decart_sdk/
+
+# Format code
+uv run black decart_sdk/ tests/ examples/
+
+# Type check
+uv run mypy decart_sdk/
+```
+
+### Common Commands
+
+```bash
+# Install dependencies
+uv sync --all-extras
+
+# Run tests with coverage
+uv run pytest --cov=decart_sdk --cov-report=html
+
+# Run examples
+uv run python examples/process_video.py
+uv run python examples/realtime_synthetic.py
+
+# Update dependencies
+uv lock --upgrade
+```
+
+## License
+
+MIT

decart_sdk/__init__.py

@@ -0,0 +1,53 @@
+from .client import DecartClient
+from .errors import (
+    DecartSDKError,
+    InvalidAPIKeyError,
+    InvalidBaseURLError,
+    InvalidInputError,
+    ModelNotFoundError,
+    ProcessingError,
+    WebRTCError,
+)
+from .models import models, ModelDefinition
+from .types import FileInput, ModelState, Prompt
+
+try:
+    from .realtime import (
+        RealtimeClient,
+        RealtimeConnectOptions,
+        ConnectionState,
+    )
+
+    REALTIME_AVAILABLE = True
+except ImportError:
+    REALTIME_AVAILABLE = False
+    RealtimeClient = None  # type: ignore
+    RealtimeConnectOptions = None  # type: ignore
+    ConnectionState = None  # type: ignore
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "DecartClient",
+    "DecartSDKError",
+    "InvalidAPIKeyError",
+    "InvalidBaseURLError",
+    "InvalidInputError",
+    "ModelNotFoundError",
+    "ProcessingError",
+    "WebRTCError",
+    "models",
+    "ModelDefinition",
+    "FileInput",
+    "ModelState",
+    "Prompt",
+]
+
+if REALTIME_AVAILABLE:
+    __all__.extend(
+        [
+            "RealtimeClient",
+            "RealtimeConnectOptions",
+            "ConnectionState",
+        ]
+    )