fraime-sdk 1.0.0__tar.gz

fraime_sdk-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Santiago Melo Medina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fraime_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: fraime-sdk
+Version: 1.0.0
+Summary: Python SDK for the Fraime video generation API
+Author: Santiago Melo Medina
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx
+Requires-Dist: pydantic
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# Fraime SDK
+
+Python client for the [Fraime API](../api/README.md) — build a request with
+typed models/enums instead of hand-writing JSON, point it at a running
+Fraime instance, get a generated video back.
+
+## Prerequisites
+
+- Python 3.11+
+- A running Fraime API instance to talk to (see [`api/README.md`](../api/README.md)
+  for how to run one) — you'll need its base URL, and its API key if one is
+  configured (`AUTH_API_KEY` on the API side).
+
+## Install
+
+### Option 1 — pip
+
+```bash
+pip install fraime-sdk
+```
+
+### Option 2 — from a local clone
+
+Step by step, from scratch:
+
+```bash
+# 1. Clone the repo (skip if you already have it)
+git clone <this-repo-url>
+cd fraime
+
+# 2. (Recommended) create a virtualenv for your own project
+python3 -m venv .venv
+source .venv/bin/activate
+
+# 3. Install the SDK from the sdk/ folder
+pip install ./sdk
+#   or, for local development on the SDK itself (editable install):
+pip install -e ./sdk
+```
+
+That's it — `import fraime` is now available in that environment.
+
+### Option 3 — straight from git, no local clone needed
+
+```bash
+pip install "git+ssh://git@santiago/santiagoMeloMedina/fraime.git#subdirectory=sdk"
+```
+
+(Adjust the URL to whatever remote you actually have push/pull access to —
+this is this repo's own `origin` in SSH form.)
+
+## Usage
+
+```python
+from fraime import FraimeClient, VideoType, GenerationParams, CinematicPromptFields
+
+client = FraimeClient(
+    base_url="http://127.0.0.1:8000",  # or set FRAIME_BASE_URL instead
+    api_key="your-api-key",             # or set FRAIME_API_KEY instead; omit both if the API has none configured
+)
+
+response = client.generate(
+    video_type=VideoType.PIXAR,
+    fields=CinematicPromptFields(
+        subject="a small orange fox with oversized ears",
+        action="hops between rocks, pauses, and looks up curiously",
+        scene="a sunlit forest clearing at golden hour",
+        camera="medium shot, slow dolly-in",
+        lighting="warm rim lighting from the low sun",
+        style="3D animated feature style, stylized proportions, warm rim lighting",
+    ),
+    params=GenerationParams(duration_s=3, fps=16, resolution="768x512"),
+    # model=...              # optional: pin an exact model instead of auto-selecting
+    # references=[...]       # optional: Reference(url=...) list, for image-to-video
+)
+
+print(response.video_path, response.model)
+```
+
+`model` is optional on `client.generate()` — omit it and the API auto-selects
+by hardware, same as calling it directly.
+
+### Picking the right fields class per video type
+
+Every `video_type` has its own field set — some add fields the base six
+(`subject`, `action`, `scene`, `camera`, `lighting`, `style`,
+`negative_prompt`) don't cover:
+
+| `VideoType` | Fields class | Extra fields |
+|---|---|---|
+| `PIXAR`, `ACTION`, `ANIMATION`, `ANIME`, `DOCUMENTARY`, `FASHION` | `CinematicPromptFields` | — |
+| `UGC_PRODUCT_REVIEW`, `COMMERCIAL_PRODUCT_AD`, `EXPLAINER_TESTIMONIAL` | `UGCPromptFields` | `dialogue`, `reference_image` |
+| `PRESENTER_AVATAR` | `PresenterPromptFields` | + `voice_tone` |
+| `SOCIAL_SHORT_FORM_AD` | `SocialAdPromptFields` | + `text_overlay`, `aspect_ratio` |
+| `MUSIC_VIDEO` | `MusicVideoPromptFields` | `audio_reference`, `tempo_bpm` |
+| `MOTION_GRAPHICS` | `MotionGraphicsPromptFields` | `text_content`, `transitions` |
+
+Not sure which class a given `VideoType` needs? Look it up instead of
+guessing:
+
+```python
+from fraime import PROMPT_FIELDS_BY_VIDEO_TYPE, VideoType
+
+fields_class = PROMPT_FIELDS_BY_VIDEO_TYPE[VideoType.SOCIAL_SHORT_FORM_AD]
+# -> SocialAdPromptFields
+```
+
+### Reference images (image-to-video)
+
+```python
+from fraime import Reference
+
+response = client.generate(
+    video_type=VideoType.UGC_PRODUCT_REVIEW,
+    fields=ugc_fields,
+    params=params,
+    references=[Reference(url="https://example.com/product-photo.jpg")],
+)
+```
+
+### Error handling
+
+```python
+from fraime import FraimeAuthError, FraimeAPIError, FraimeConnectionError
+
+try:
+    response = client.generate(video_type=VideoType.PIXAR, fields=fields, params=params)
+except FraimeAuthError:
+    ...  # missing/invalid API key
+except FraimeAPIError as e:
+    ...  # e.status_code, e.detail — the API reached but returned an error
+except FraimeConnectionError:
+    ...  # couldn't reach the API at all
+```
+
+## Configuration reference
+
+| `FraimeClient(...)` argument | Env var fallback | Default |
+|---|---|---|
+| `base_url` | `FRAIME_BASE_URL` | `http://127.0.0.1:8000` |
+| `api_key` | `FRAIME_API_KEY` | none (open API) |
+| `timeout` | — | `600.0` seconds |
+
+`timeout` defaults high on purpose — real generation runs can take several
+minutes; see [`api/README.md`](../api/README.md) for why.

fraime_sdk-1.0.0/README.md

@@ -0,0 +1,145 @@
+# Fraime SDK
+
+Python client for the [Fraime API](../api/README.md) — build a request with
+typed models/enums instead of hand-writing JSON, point it at a running
+Fraime instance, get a generated video back.
+
+## Prerequisites
+
+- Python 3.11+
+- A running Fraime API instance to talk to (see [`api/README.md`](../api/README.md)
+  for how to run one) — you'll need its base URL, and its API key if one is
+  configured (`AUTH_API_KEY` on the API side).
+
+## Install
+
+### Option 1 — pip
+
+```bash
+pip install fraime-sdk
+```
+
+### Option 2 — from a local clone
+
+Step by step, from scratch:
+
+```bash
+# 1. Clone the repo (skip if you already have it)
+git clone <this-repo-url>
+cd fraime
+
+# 2. (Recommended) create a virtualenv for your own project
+python3 -m venv .venv
+source .venv/bin/activate
+
+# 3. Install the SDK from the sdk/ folder
+pip install ./sdk
+#   or, for local development on the SDK itself (editable install):
+pip install -e ./sdk
+```
+
+That's it — `import fraime` is now available in that environment.
+
+### Option 3 — straight from git, no local clone needed
+
+```bash
+pip install "git+ssh://git@santiago/santiagoMeloMedina/fraime.git#subdirectory=sdk"
+```
+
+(Adjust the URL to whatever remote you actually have push/pull access to —
+this is this repo's own `origin` in SSH form.)
+
+## Usage
+
+```python
+from fraime import FraimeClient, VideoType, GenerationParams, CinematicPromptFields
+
+client = FraimeClient(
+    base_url="http://127.0.0.1:8000",  # or set FRAIME_BASE_URL instead
+    api_key="your-api-key",             # or set FRAIME_API_KEY instead; omit both if the API has none configured
+)
+
+response = client.generate(
+    video_type=VideoType.PIXAR,
+    fields=CinematicPromptFields(
+        subject="a small orange fox with oversized ears",
+        action="hops between rocks, pauses, and looks up curiously",
+        scene="a sunlit forest clearing at golden hour",
+        camera="medium shot, slow dolly-in",
+        lighting="warm rim lighting from the low sun",
+        style="3D animated feature style, stylized proportions, warm rim lighting",
+    ),
+    params=GenerationParams(duration_s=3, fps=16, resolution="768x512"),
+    # model=...              # optional: pin an exact model instead of auto-selecting
+    # references=[...]       # optional: Reference(url=...) list, for image-to-video
+)
+
+print(response.video_path, response.model)
+```
+
+`model` is optional on `client.generate()` — omit it and the API auto-selects
+by hardware, same as calling it directly.
+
+### Picking the right fields class per video type
+
+Every `video_type` has its own field set — some add fields the base six
+(`subject`, `action`, `scene`, `camera`, `lighting`, `style`,
+`negative_prompt`) don't cover:
+
+| `VideoType` | Fields class | Extra fields |
+|---|---|---|
+| `PIXAR`, `ACTION`, `ANIMATION`, `ANIME`, `DOCUMENTARY`, `FASHION` | `CinematicPromptFields` | — |
+| `UGC_PRODUCT_REVIEW`, `COMMERCIAL_PRODUCT_AD`, `EXPLAINER_TESTIMONIAL` | `UGCPromptFields` | `dialogue`, `reference_image` |
+| `PRESENTER_AVATAR` | `PresenterPromptFields` | + `voice_tone` |
+| `SOCIAL_SHORT_FORM_AD` | `SocialAdPromptFields` | + `text_overlay`, `aspect_ratio` |
+| `MUSIC_VIDEO` | `MusicVideoPromptFields` | `audio_reference`, `tempo_bpm` |
+| `MOTION_GRAPHICS` | `MotionGraphicsPromptFields` | `text_content`, `transitions` |
+
+Not sure which class a given `VideoType` needs? Look it up instead of
+guessing:
+
+```python
+from fraime import PROMPT_FIELDS_BY_VIDEO_TYPE, VideoType
+
+fields_class = PROMPT_FIELDS_BY_VIDEO_TYPE[VideoType.SOCIAL_SHORT_FORM_AD]
+# -> SocialAdPromptFields
+```
+
+### Reference images (image-to-video)
+
+```python
+from fraime import Reference
+
+response = client.generate(
+    video_type=VideoType.UGC_PRODUCT_REVIEW,
+    fields=ugc_fields,
+    params=params,
+    references=[Reference(url="https://example.com/product-photo.jpg")],
+)
+```
+
+### Error handling
+
+```python
+from fraime import FraimeAuthError, FraimeAPIError, FraimeConnectionError
+
+try:
+    response = client.generate(video_type=VideoType.PIXAR, fields=fields, params=params)
+except FraimeAuthError:
+    ...  # missing/invalid API key
+except FraimeAPIError as e:
+    ...  # e.status_code, e.detail — the API reached but returned an error
+except FraimeConnectionError:
+    ...  # couldn't reach the API at all
+```
+
+## Configuration reference
+
+| `FraimeClient(...)` argument | Env var fallback | Default |
+|---|---|---|
+| `base_url` | `FRAIME_BASE_URL` | `http://127.0.0.1:8000` |
+| `api_key` | `FRAIME_API_KEY` | none (open API) |
+| `timeout` | — | `600.0` seconds |
+
+`timeout` defaults high on purpose — real generation runs can take several
+minutes; see [`api/README.md`](../api/README.md) for why.

fraime_sdk-1.0.0/fraime/__init__.py

@@ -0,0 +1,45 @@
+from fraime.exceptions import (
+    FraimeAPIError,
+    FraimeAuthError,
+    FraimeConnectionError,
+    FraimeError,
+)
+from fraime.main import FraimeClient
+from fraime.model import (
+    PROMPT_FIELDS_BY_VIDEO_TYPE,
+    AspectRatio,
+    CinematicPromptFields,
+    GenerateVideoRequest,
+    GenerateVideoResponse,
+    GenerationParams,
+    MotionGraphicsPromptFields,
+    MusicVideoPromptFields,
+    PresenterPromptFields,
+    PromptFields,
+    Reference,
+    SocialAdPromptFields,
+    UGCPromptFields,
+    VideoType,
+)
+
+__all__ = [
+    "FraimeClient",
+    "VideoType",
+    "PROMPT_FIELDS_BY_VIDEO_TYPE",
+    "AspectRatio",
+    "GenerationParams",
+    "Reference",
+    "PromptFields",
+    "CinematicPromptFields",
+    "UGCPromptFields",
+    "PresenterPromptFields",
+    "SocialAdPromptFields",
+    "MusicVideoPromptFields",
+    "MotionGraphicsPromptFields",
+    "GenerateVideoRequest",
+    "GenerateVideoResponse",
+    "FraimeError",
+    "FraimeConnectionError",
+    "FraimeAuthError",
+    "FraimeAPIError",
+]

fraime_sdk-1.0.0/fraime/exceptions.py

@@ -0,0 +1,19 @@
+class FraimeError(Exception):
+    """Base class for all Fraime SDK errors."""
+
+
+class FraimeConnectionError(FraimeError):
+    """The API couldn't be reached at all (network/DNS/timeout)."""
+
+
+class FraimeAuthError(FraimeError):
+    """The API rejected the request due to a missing or invalid API key."""
+
+
+class FraimeAPIError(FraimeError):
+    """The API reached and responded, but with an error status."""
+
+    def __init__(self, status_code: int, detail: str):
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"Fraime API returned {status_code}: {detail}")

fraime_sdk-1.0.0/fraime/main.py

@@ -0,0 +1,51 @@
+import os
+
+from fraime.model import (
+    GenerateVideoRequest,
+    GenerateVideoResponse,
+    GenerationParams,
+    PromptFields,
+    Reference,
+    VideoType,
+)
+from fraime.repository import GenerationRepository
+from fraime.service import GenerationService
+
+DEFAULT_BASE_URL = "http://127.0.0.1:8000"
+
+
+class FraimeClient:
+    def __init__(
+        self,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        timeout: float = 600.0,
+    ):
+        base_url = base_url or os.environ.get("FRAIME_BASE_URL", DEFAULT_BASE_URL)
+        api_key = api_key or os.environ.get("FRAIME_API_KEY")
+
+        repository = GenerationRepository(base_url=base_url, api_key=api_key, timeout=timeout)
+        self._service = GenerationService(repository)
+
+    def generate(
+        self,
+        video_type: VideoType,
+        fields: PromptFields,
+        params: GenerationParams,
+        model: str | None = None,
+        references: list[Reference] | None = None,
+        vram_safety_margin: bool = True,
+        low_memory_decode: bool = True,
+        cpu_offload: bool = True,
+    ) -> GenerateVideoResponse:
+        request = GenerateVideoRequest(
+            video_type=video_type,
+            fields=fields,
+            params=params,
+            model=model,
+            references=references,
+            vram_safety_margin=vram_safety_margin,
+            low_memory_decode=low_memory_decode,
+            cpu_offload=cpu_offload,
+        )
+        return self._service.generate_video(request)

fraime_sdk-1.0.0/fraime/model.py

@@ -0,0 +1,142 @@
+from abc import ABC
+from enum import Enum
+
+from pydantic import BaseModel, Field, HttpUrl
+
+
+class VideoType(str, Enum):
+    PIXAR = "pixar"
+    ACTION = "action"
+    ANIMATION = "animation"
+    ANIME = "anime"
+    DOCUMENTARY = "documentary"
+    FASHION = "fashion"
+    UGC_PRODUCT_REVIEW = "ugc_product_review"
+    COMMERCIAL_PRODUCT_AD = "commercial_product_ad"
+    EXPLAINER_TESTIMONIAL = "explainer_testimonial"
+    PRESENTER_AVATAR = "presenter_avatar"
+    SOCIAL_SHORT_FORM_AD = "social_short_form_ad"
+    MUSIC_VIDEO = "music_video"
+    MOTION_GRAPHICS = "motion_graphics"
+
+
+class AspectRatio(str, Enum):
+    VERTICAL_9_16 = "9:16"
+    VERTICAL_4_5 = "4:5"
+
+
+class Reference(BaseModel):
+    url: HttpUrl = Field(description="Publicly accessible URL the file is downloaded from")
+
+
+class GenerationParams(BaseModel):
+    duration_s: float = Field(gt=0, description="Requested clip duration in seconds")
+    fps: int = Field(gt=0, description="Frames per second")
+    resolution: str = Field(description="Target resolution, e.g. '1024x576'")
+    seed: int | None = Field(default=None, description="Seed for reproducible generation")
+    num_inference_steps: int | None = Field(
+        default=None,
+        gt=0,
+        description="Denoising steps; lower is faster/lower quality. Defaults to the model's own default (usually 50) when unset.",
+    )
+
+
+class PromptFields(BaseModel, ABC):
+    """Fields shared by every video type."""
+
+    subject: str = Field(description="Main focus of the video: who/what")
+    action: str = Field(description="What happens over time; the motion")
+    scene: str = Field(description="Environment, background, time of day")
+    camera: str = Field(description="Shot type and camera movement")
+    lighting: str = Field(description="Lighting style and mood")
+    style: str = Field(description="Visual/cinematic style reference")
+    negative_prompt: str | None = Field(default=None, description="What to avoid in the generation")
+
+
+class CinematicPromptFields(PromptFields):
+    """pixar, action, animation, anime, documentary, fashion — no extra fields."""
+
+
+class UGCPromptFields(PromptFields):
+    """ugc_product_review, commercial_product_ad, explainer_testimonial."""
+
+    dialogue: str | None = Field(
+        default=None, description="Spoken script/dialogue delivered by the subject"
+    )
+    reference_image: str | None = Field(
+        default=None, description="Reference image URL for product/subject fidelity"
+    )
+
+
+class PresenterPromptFields(UGCPromptFields):
+    """presenter_avatar."""
+
+    voice_tone: str | None = Field(
+        default=None, description="Directive for how the voice should sound, e.g. 'warm, confident, corporate'"
+    )
+
+
+class SocialAdPromptFields(UGCPromptFields):
+    """social_short_form_ad."""
+
+    text_overlay: str | None = Field(default=None, description="On-screen text/captions overlaid on the video")
+    aspect_ratio: AspectRatio = Field(default=AspectRatio.VERTICAL_9_16, description="Target aspect ratio")
+
+
+class MusicVideoPromptFields(PromptFields):
+    """music_video. No catalog model currently supports this — expect no viable model today."""
+
+    audio_reference: str = Field(description="Reference audio track/URL the visuals should sync to")
+    tempo_bpm: int | None = Field(default=None, description="Beats per minute to sync visual cuts to")
+
+
+class MotionGraphicsPromptFields(PromptFields):
+    """motion_graphics."""
+
+    text_content: str = Field(description="On-screen text/copy driving the animation")
+    transitions: str | None = Field(
+        default=None, description="Transition style between graphic elements, e.g. 'fade, slide, zoom'"
+    )
+
+
+PROMPT_FIELDS_BY_VIDEO_TYPE: dict[VideoType, type[PromptFields]] = {
+    VideoType.PIXAR: CinematicPromptFields,
+    VideoType.ACTION: CinematicPromptFields,
+    VideoType.ANIMATION: CinematicPromptFields,
+    VideoType.ANIME: CinematicPromptFields,
+    VideoType.DOCUMENTARY: CinematicPromptFields,
+    VideoType.FASHION: CinematicPromptFields,
+    VideoType.UGC_PRODUCT_REVIEW: UGCPromptFields,
+    VideoType.COMMERCIAL_PRODUCT_AD: UGCPromptFields,
+    VideoType.EXPLAINER_TESTIMONIAL: UGCPromptFields,
+    VideoType.PRESENTER_AVATAR: PresenterPromptFields,
+    VideoType.SOCIAL_SHORT_FORM_AD: SocialAdPromptFields,
+    VideoType.MUSIC_VIDEO: MusicVideoPromptFields,
+    VideoType.MOTION_GRAPHICS: MotionGraphicsPromptFields,
+}
+
+
+class GenerateVideoRequest(BaseModel):
+    video_type: VideoType
+    fields: PromptFields
+    params: GenerationParams
+    model: str | None = Field(
+        default=None, description="Explicit Hugging Face model id; omit to auto-select by hardware"
+    )
+    references: list[Reference] | None = Field(
+        default=None, description="Reference images; presence requires image-to-video capability"
+    )
+    vram_safety_margin: bool = Field(
+        default=True, description="Match against 85% of detected VRAM instead of 100%, for headroom"
+    )
+    low_memory_decode: bool = Field(
+        default=True, description="Decode the VAE output in slices/tiles instead of all at once"
+    )
+    cpu_offload: bool = Field(
+        default=True, description="Move pipeline components between CPU and accelerator instead of holding all at once"
+    )
+
+
+class GenerateVideoResponse(BaseModel):
+    video_path: str = Field(description="Path to the generated .mp4 on the API server")
+    model: str = Field(description="Hugging Face model id that actually ran")

fraime_sdk-1.0.0/fraime/repository.py

@@ -0,0 +1,30 @@
+import httpx
+
+from fraime.exceptions import FraimeAPIError, FraimeAuthError, FraimeConnectionError
+
+
+class GenerationRepository:
+    """Raw HTTP transport to the Fraime API — no model knowledge beyond JSON in/out."""
+
+    def __init__(self, base_url: str, api_key: str | None = None, timeout: float = 600.0):
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._timeout = timeout
+
+    def post_generate(self, payload: dict) -> dict:
+        url = f"{self._base_url}/generate"
+        headers = {"Content-Type": "application/json"}
+        if self._api_key:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+
+        try:
+            response = httpx.post(url, json=payload, headers=headers, timeout=self._timeout)
+        except httpx.RequestError as e:
+            raise FraimeConnectionError(f"Failed to reach Fraime API at {url}: {e}") from e
+
+        if response.status_code == 401:
+            raise FraimeAuthError(response.text or "Invalid or missing API key")
+        if response.status_code >= 400:
+            raise FraimeAPIError(response.status_code, response.text)
+
+        return response.json()

fraime_sdk-1.0.0/fraime/service.py

@@ -0,0 +1,14 @@
+from fraime.model import GenerateVideoRequest, GenerateVideoResponse
+from fraime.repository import GenerationRepository
+
+
+class GenerationService:
+    def __init__(self, repository: GenerationRepository):
+        self._repository = repository
+
+    def generate_video(self, request: GenerateVideoRequest) -> GenerateVideoResponse:
+        payload = request.model_dump(mode="json", exclude_none=True, exclude={"fields"})
+        payload["fields"] = request.fields.model_dump(mode="json", exclude_none=True)
+
+        raw = self._repository.post_generate(payload)
+        return GenerateVideoResponse.model_validate(raw)

fraime_sdk-1.0.0/fraime_sdk.egg-info/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: fraime-sdk
+Version: 1.0.0
+Summary: Python SDK for the Fraime video generation API
+Author: Santiago Melo Medina
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx
+Requires-Dist: pydantic
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# Fraime SDK
+
+Python client for the [Fraime API](../api/README.md) — build a request with
+typed models/enums instead of hand-writing JSON, point it at a running
+Fraime instance, get a generated video back.
+
+## Prerequisites
+
+- Python 3.11+
+- A running Fraime API instance to talk to (see [`api/README.md`](../api/README.md)
+  for how to run one) — you'll need its base URL, and its API key if one is
+  configured (`AUTH_API_KEY` on the API side).
+
+## Install
+
+### Option 1 — pip
+
+```bash
+pip install fraime-sdk
+```
+
+### Option 2 — from a local clone
+
+Step by step, from scratch:
+
+```bash
+# 1. Clone the repo (skip if you already have it)
+git clone <this-repo-url>
+cd fraime
+
+# 2. (Recommended) create a virtualenv for your own project
+python3 -m venv .venv
+source .venv/bin/activate
+
+# 3. Install the SDK from the sdk/ folder
+pip install ./sdk
+#   or, for local development on the SDK itself (editable install):
+pip install -e ./sdk
+```
+
+That's it — `import fraime` is now available in that environment.
+
+### Option 3 — straight from git, no local clone needed
+
+```bash
+pip install "git+ssh://git@santiago/santiagoMeloMedina/fraime.git#subdirectory=sdk"
+```
+
+(Adjust the URL to whatever remote you actually have push/pull access to —
+this is this repo's own `origin` in SSH form.)
+
+## Usage
+
+```python
+from fraime import FraimeClient, VideoType, GenerationParams, CinematicPromptFields
+
+client = FraimeClient(
+    base_url="http://127.0.0.1:8000",  # or set FRAIME_BASE_URL instead
+    api_key="your-api-key",             # or set FRAIME_API_KEY instead; omit both if the API has none configured
+)
+
+response = client.generate(
+    video_type=VideoType.PIXAR,
+    fields=CinematicPromptFields(
+        subject="a small orange fox with oversized ears",
+        action="hops between rocks, pauses, and looks up curiously",
+        scene="a sunlit forest clearing at golden hour",
+        camera="medium shot, slow dolly-in",
+        lighting="warm rim lighting from the low sun",
+        style="3D animated feature style, stylized proportions, warm rim lighting",
+    ),
+    params=GenerationParams(duration_s=3, fps=16, resolution="768x512"),
+    # model=...              # optional: pin an exact model instead of auto-selecting
+    # references=[...]       # optional: Reference(url=...) list, for image-to-video
+)
+
+print(response.video_path, response.model)
+```
+
+`model` is optional on `client.generate()` — omit it and the API auto-selects
+by hardware, same as calling it directly.
+
+### Picking the right fields class per video type
+
+Every `video_type` has its own field set — some add fields the base six
+(`subject`, `action`, `scene`, `camera`, `lighting`, `style`,
+`negative_prompt`) don't cover:
+
+| `VideoType` | Fields class | Extra fields |
+|---|---|---|
+| `PIXAR`, `ACTION`, `ANIMATION`, `ANIME`, `DOCUMENTARY`, `FASHION` | `CinematicPromptFields` | — |
+| `UGC_PRODUCT_REVIEW`, `COMMERCIAL_PRODUCT_AD`, `EXPLAINER_TESTIMONIAL` | `UGCPromptFields` | `dialogue`, `reference_image` |
+| `PRESENTER_AVATAR` | `PresenterPromptFields` | + `voice_tone` |
+| `SOCIAL_SHORT_FORM_AD` | `SocialAdPromptFields` | + `text_overlay`, `aspect_ratio` |
+| `MUSIC_VIDEO` | `MusicVideoPromptFields` | `audio_reference`, `tempo_bpm` |
+| `MOTION_GRAPHICS` | `MotionGraphicsPromptFields` | `text_content`, `transitions` |
+
+Not sure which class a given `VideoType` needs? Look it up instead of
+guessing:
+
+```python
+from fraime import PROMPT_FIELDS_BY_VIDEO_TYPE, VideoType
+
+fields_class = PROMPT_FIELDS_BY_VIDEO_TYPE[VideoType.SOCIAL_SHORT_FORM_AD]
+# -> SocialAdPromptFields
+```
+
+### Reference images (image-to-video)
+
+```python
+from fraime import Reference
+
+response = client.generate(
+    video_type=VideoType.UGC_PRODUCT_REVIEW,
+    fields=ugc_fields,
+    params=params,
+    references=[Reference(url="https://example.com/product-photo.jpg")],
+)
+```
+
+### Error handling
+
+```python
+from fraime import FraimeAuthError, FraimeAPIError, FraimeConnectionError
+
+try:
+    response = client.generate(video_type=VideoType.PIXAR, fields=fields, params=params)
+except FraimeAuthError:
+    ...  # missing/invalid API key
+except FraimeAPIError as e:
+    ...  # e.status_code, e.detail — the API reached but returned an error
+except FraimeConnectionError:
+    ...  # couldn't reach the API at all
+```
+
+## Configuration reference
+
+| `FraimeClient(...)` argument | Env var fallback | Default |
+|---|---|---|
+| `base_url` | `FRAIME_BASE_URL` | `http://127.0.0.1:8000` |
+| `api_key` | `FRAIME_API_KEY` | none (open API) |
+| `timeout` | — | `600.0` seconds |
+
+`timeout` defaults high on purpose — real generation runs can take several
+minutes; see [`api/README.md`](../api/README.md) for why.

fraime_sdk-1.0.0/fraime_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+fraime/__init__.py
+fraime/exceptions.py
+fraime/main.py
+fraime/model.py
+fraime/repository.py
+fraime/service.py
+fraime_sdk.egg-info/PKG-INFO
+fraime_sdk.egg-info/SOURCES.txt
+fraime_sdk.egg-info/dependency_links.txt
+fraime_sdk.egg-info/requires.txt
+fraime_sdk.egg-info/top_level.txt

fraime_sdk-1.0.0/fraime_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fraime_sdk-1.0.0/fraime_sdk.egg-info/requires.txt

@@ -0,0 +1,6 @@
+httpx
+pydantic
+
+[dev]
+build
+twine

fraime_sdk-1.0.0/fraime_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+fraime

fraime_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fraime-sdk"
+version = "1.0.0"
+description = "Python SDK for the Fraime video generation API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [
+    { name = "Santiago Melo Medina" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "httpx",
+    "pydantic",
+]
+
+[project.optional-dependencies]
+dev = [
+    "build",
+    "twine",
+]
+
+[tool.setuptools]
+packages = ["fraime"]

fraime_sdk-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+