aimage-sdk 0.1.0__py3-none-any.whl

aimage_sdk/__init__.py

@@ -0,0 +1,34 @@
+"""Python SDK for the AI-Mage Search public API."""
+
+from .client import AimageClient, ProgressStage
+from .errors import AimageApiError
+from .types import (
+    Clip,
+    DeleteVideoResponse,
+    MeProject,
+    MeResponse,
+    PingResponse,
+    ProcessingStatus,
+    ProjectRole,
+    SearchClipsResponse,
+    UploadUrlResponse,
+    Video,
+    VideoListResponse,
+)
+
+__all__ = [
+    "AimageApiError",
+    "AimageClient",
+    "Clip",
+    "DeleteVideoResponse",
+    "MeProject",
+    "MeResponse",
+    "PingResponse",
+    "ProcessingStatus",
+    "ProgressStage",
+    "ProjectRole",
+    "SearchClipsResponse",
+    "UploadUrlResponse",
+    "Video",
+    "VideoListResponse",
+]

aimage_sdk/client.py

@@ -0,0 +1,236 @@
+import mimetypes
+import time
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, Literal, cast
+
+import httpx
+
+from .errors import AimageApiError
+from .types import (
+    DeleteVideoResponse,
+    MeResponse,
+    PingResponse,
+    SearchClipsResponse,
+    UploadUrlResponse,
+    Video,
+    VideoListResponse,
+)
+
+ProgressStage = Literal["minting_upload_url", "uploading", "registering", "done"]
+
+
+class AimageClient:
+    """Thin client for the AI-Mage Search public API (/v0), httpx-based.
+
+    ``base_url`` is the API server origin, e.g. ``https://api.search.ai-mage.jp``;
+    the client calls ``{base_url}/v0/...``. ``transport`` exists for testing
+    with ``httpx.MockTransport``.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        *,
+        timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        # No default Authorization header: presigned S3 PUTs go through the
+        # same client and S3 rejects requests carrying both auth mechanisms.
+        self._client = httpx.Client(timeout=timeout, transport=transport)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "AimageClient":
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    # -- thin endpoint wrappers ------------------------------------------------
+
+    def ping(self) -> PingResponse:
+        return cast(PingResponse, self._request("GET", "/ping"))
+
+    def me(self) -> MeResponse:
+        return cast(MeResponse, self._request("GET", "/me"))
+
+    def mint_upload_url(
+        self, *, project_id: str, file_name: str, content_type: str
+    ) -> UploadUrlResponse:
+        body = {"project_id": project_id, "file_name": file_name, "content_type": content_type}
+        return cast(UploadUrlResponse, self._request("POST", "/videos/upload-url", json=body))
+
+    def register_video(
+        self,
+        *,
+        project_id: str,
+        name: str,
+        file_name: str | None = None,
+        s3_key: str | None = None,
+        season: int | None = None,
+        episode: int | None = None,
+        auto_process: bool = True,
+    ) -> Video:
+        if (file_name is None) == (s3_key is None):
+            raise ValueError("Provide exactly one of file_name or s3_key.")
+        body: dict[str, Any] = {
+            "project_id": project_id,
+            "name": name,
+            "auto_process": auto_process,
+        }
+        if file_name is not None:
+            body["file_name"] = file_name
+        if s3_key is not None:
+            body["s3_key"] = s3_key
+        if season is not None:
+            body["season"] = season
+        if episode is not None:
+            body["episode"] = episode
+        return cast(Video, self._request("POST", "/videos", json=body))
+
+    def get_video(self, video_id: str) -> Video:
+        return cast(Video, self._request("GET", f"/videos/{video_id}"))
+
+    def list_videos(
+        self, *, project_id: str, page: int = 1, page_size: int = 20
+    ) -> VideoListResponse:
+        params = {"project_id": project_id, "page": page, "page_size": page_size}
+        return cast(VideoListResponse, self._request("GET", "/videos", params=params))
+
+    def delete_video(self, video_id: str) -> DeleteVideoResponse:
+        return cast(DeleteVideoResponse, self._request("DELETE", f"/videos/{video_id}"))
+
+    def search_clips(
+        self, *, project_id: str, query: str, page: int = 1, page_size: int = 20
+    ) -> SearchClipsResponse:
+        body = {"project_id": project_id, "query": query, "page": page, "page_size": page_size}
+        return cast(SearchClipsResponse, self._request("POST", "/search/clips", json=body))
+
+    # -- high-level orchestration ----------------------------------------------
+
+    def upload_video(
+        self,
+        *,
+        project_id: str,
+        file: str | Path | bytes,
+        name: str,
+        file_name: str | None = None,
+        content_type: str | None = None,
+        season: int | None = None,
+        episode: int | None = None,
+        auto_process: bool = True,
+        on_progress: Callable[[ProgressStage], None] | None = None,
+    ) -> Video:
+        """Full upload orchestration: mint a presigned URL, PUT the file bytes
+        with the exact Content-Type, then register the video via its s3_key.
+        """
+        if isinstance(file, bytes):
+            if file_name is None:
+                raise ValueError("file_name is required when uploading bytes.")
+            data = file
+        else:
+            path = Path(file)
+            file_name = file_name or path.name
+            data = path.read_bytes()
+
+        if content_type is None:
+            content_type, _ = mimetypes.guess_type(file_name)
+        if content_type is None:
+            raise ValueError(
+                f'Cannot infer content_type from file name "{file_name}". Pass it explicitly.'
+            )
+
+        if on_progress:
+            on_progress("minting_upload_url")
+        minted = self.mint_upload_url(
+            project_id=project_id, file_name=file_name, content_type=content_type
+        )
+
+        if on_progress:
+            on_progress("uploading")
+        upload_response = self._client.put(
+            minted["upload_url"], content=data, headers={"Content-Type": content_type}
+        )
+        if upload_response.is_error:
+            raise AimageApiError(
+                code="UPLOAD_FAILED",
+                message=f"Upload to presigned URL failed with status {upload_response.status_code}",
+                status=upload_response.status_code,
+            )
+
+        if on_progress:
+            on_progress("registering")
+        video = self.register_video(
+            project_id=project_id,
+            name=name,
+            s3_key=minted["s3_key"],
+            season=season,
+            episode=episode,
+            auto_process=auto_process,
+        )
+
+        if on_progress:
+            on_progress("done")
+        return video
+
+    def wait_for_processing(
+        self,
+        video_id: str,
+        *,
+        poll_interval_s: float = 5.0,
+        timeout_s: float = 600.0,
+    ) -> Video:
+        """Polls GET /videos/{id} until processing reaches a terminal state and
+        returns the final video — check processing_status ('completed' or
+        'failed') and processing_error yourself. Raises TimeoutError on timeout.
+        """
+        deadline = time.monotonic() + timeout_s
+        while True:
+            video = self.get_video(video_id)
+            if video["processing_status"] in ("completed", "failed"):
+                return video
+            if time.monotonic() + poll_interval_s >= deadline:
+                raise TimeoutError(
+                    f"Timed out waiting for video {video_id} to finish processing "
+                    f"after {timeout_s}s"
+                )
+            time.sleep(poll_interval_s)
+
+    # -- internals ---------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+    ) -> Any:
+        response = self._client.request(
+            method,
+            f"{self._base_url}/v0{path}",
+            params=params,
+            json=json,
+            headers={"Authorization": f"Bearer {self._api_key}"},
+        )
+        if response.is_error:
+            raise _to_api_error(response)
+        return response.json()
+
+
+def _to_api_error(response: httpx.Response) -> AimageApiError:
+    code = "UNKNOWN"
+    message = f"Request failed with status {response.status_code}"
+    try:
+        envelope = response.json().get("error")
+        if isinstance(envelope, dict):
+            code = str(envelope.get("code", code))
+            message = str(envelope.get("message", message))
+    except ValueError:
+        pass
+    return AimageApiError(code=code, message=message, status=response.status_code)

aimage_sdk/errors.py

@@ -0,0 +1,12 @@
+class AimageApiError(Exception):
+    """Raised when the AI-Mage Search API responds with a non-2xx status.
+
+    ``code`` and ``message`` come from the API error envelope
+    ``{"error": {"code", "message"}}``; ``status`` is the HTTP status code.
+    """
+
+    def __init__(self, code: str, message: str, status: int) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status

aimage_sdk/types.py

@@ -0,0 +1,84 @@
+"""Wire-format types of the AI-Mage Search public API (/v0).
+
+Field names are snake_case to match the HTTP payloads exactly; the source of
+truth is packages/api-contract/src/schemas/public-api.ts in the monorepo.
+"""
+
+from typing import Literal, TypedDict
+
+ProcessingStatus = Literal["pending", "queued", "processing", "completed", "failed"]
+
+ProjectRole = Literal["viewer", "admin"]
+
+
+class Video(TypedDict):
+    id: str
+    project_id: str
+    name: str
+    season: int | None
+    episode: int | None
+    duration: int
+    width: int
+    height: int
+    processing_status: ProcessingStatus
+    processing_error: str | None
+    created_at: str
+
+
+class Clip(TypedDict):
+    clip_id: str
+    video_id: str
+    project_id: str
+    start_time: float
+    end_time: float
+    subtitle: str | None
+    similarity: float
+    thumbnail_url: str
+    episode_title: str | None
+    season: int | None
+    episode: int | None
+    tags: list[str]
+    characters: list[str]
+
+
+class UploadUrlResponse(TypedDict):
+    upload_url: str
+    s3_key: str
+    expires_at: str
+
+
+class VideoListResponse(TypedDict):
+    videos: list[Video]
+    total: int
+    page: int
+    page_size: int
+
+
+class DeleteVideoResponse(TypedDict):
+    deleted: Literal[True]
+    id: str
+
+
+class SearchClipsResponse(TypedDict):
+    clips: list[Clip]
+    total_available: int
+    page: int
+    page_size: int
+
+
+class MeProject(TypedDict):
+    id: str
+    name: str
+    role: ProjectRole
+
+
+class MeResponse(TypedDict):
+    key_name: str
+    key_preview: str
+    projects: list[MeProject]
+
+
+class PingResponse(TypedDict):
+    status: Literal["ok"]
+    version: str
+    time: str

aimage_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: aimage-sdk
+Version: 0.1.0
+Summary: Python SDK for the AI-Mage Search public API
+Project-URL: Documentation, https://api.search.ai-mage.jp/docs
+Project-URL: Repository, https://github.com/aimagexyz/aimage-monorepo
+Author: AI-Mage
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx<1,>=0.28
+Description-Content-Type: text/markdown
+
+# aimage-sdk
+
+Python SDK for the AI-Mage Search public API (`/v0`). Python 3.12+, `httpx`
+is the only dependency.
+
+## Install
+
+The package is not yet published to PyPI. Install from the repository:
+
+```sh
+uv add "aimage-sdk @ file:///path/to/aimage-monorepo/sdks/python"
+# or: pip install /path/to/aimage-monorepo/sdks/python
+```
+
+## Quickstart
+
+```python
+import os
+
+from aimage_sdk import AimageClient
+
+client = AimageClient(
+    api_key=os.environ["AIMAGE_API_KEY"],  # "aimage_api_..."
+    base_url="https://api.search.ai-mage.jp",  # API server origin; the client calls {base_url}/v0/...
+)
+
+# Discover accessible projects.
+me = client.me()
+project_id = me["projects"][0]["id"]
+
+# Upload a video: mints a presigned URL, PUTs the bytes, registers the video.
+video = client.upload_video(
+    project_id=project_id,
+    file="./episode-01.mp4",  # str | pathlib.Path | bytes (bytes need file_name=)
+    name="Episode 1",
+    season=1,
+    episode=1,
+    on_progress=print,
+)
+
+# Wait until clip extraction and AI tagging finish.
+processed = client.wait_for_processing(video["id"], poll_interval_s=10, timeout_s=1800)
+if processed["processing_status"] == "failed":
+    raise RuntimeError(processed["processing_error"])
+
+# Search clips with a natural-language query.
+result = client.search_clips(project_id=project_id, query="two characters arguing in the rain")
+for clip in result["clips"]:
+    print(clip["start_time"], clip["subtitle"], clip["tags"], clip["characters"])
+```
+
+## API surface
+
+- `ping()` / `me()`
+- `mint_upload_url(project_id=, file_name=, content_type=)`
+- `register_video(project_id=, name=, file_name=|s3_key=, season=, episode=, auto_process=)`
+- `get_video(video_id)` / `list_videos(project_id=, page=, page_size=)` / `delete_video(video_id)`
+- `search_clips(project_id=, query=, page=, page_size=)`
+- `upload_video(project_id=, file=, name=, ...)` — full 3-step upload orchestration
+- `wait_for_processing(video_id, poll_interval_s=, timeout_s=)`
+
+Failed API calls raise `AimageApiError` with `code`, `message`, and HTTP
+`status` parsed from the `{"error": {"code", "message"}}` envelope.
+
+## Development
+
+```sh
+cd sdks/python
+uv sync
+uv run pytest
+uv run ruff check .
+```

aimage_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+aimage_sdk/__init__.py,sha256=t6MViCk3c0qXdjip-UUbDWXqmXSm-HvmBVU7WIEK6iM,669
+aimage_sdk/client.py,sha256=eh3QtlMGSX21dFQfVKm4KWTEJcTJ9fVRJE0lVWBQj7c,8079
+aimage_sdk/errors.py,sha256=z8gyggro1uUb2JTQkSpaCvDp5hAnBYn3TvWjy1DBb9U,444
+aimage_sdk/types.py,sha256=IUadXu1p2YoL2eqgVJaLlDthenMYjtH4MCW3uQo33Ig,1631
+aimage_sdk-0.1.0.dist-info/METADATA,sha256=tz0Bzd3yqKbEzlweXbNkm7eD-ekg3SAPSdTddljv9y0,2812
+aimage_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+aimage_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=JHz8EsONffU_-p1_yWwd7VnkRGoWukmQsAI0kHC2eAo,1069
+aimage_sdk-0.1.0.dist-info/RECORD,,

aimage_sdk-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

aimage_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI-Mage Inc.
+
+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.