prismax 0.1.0__py3-none-any.whl

prismax/__init__.py

@@ -0,0 +1,28 @@
+from .client import PrismaXClient
+from .errors import (
+    PrismaxApiError,
+    PrismaxAuthError,
+    PrismaxError,
+    PrismaxValidationError,
+)
+from .scanner import episode_keys, scan_folder, select_primary_video_paths, validate_mcap_mp4
+from .upload import resume, status, upload, wait_for_upload
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PrismaXClient",
+    "PrismaxApiError",
+    "PrismaxAuthError",
+    "PrismaxError",
+    "PrismaxValidationError",
+    "__version__",
+    "episode_keys",
+    "resume",
+    "scan_folder",
+    "select_primary_video_paths",
+    "status",
+    "upload",
+    "validate_mcap_mp4",
+    "wait_for_upload",
+]

prismax/cli.py

@@ -0,0 +1,107 @@
+import argparse
+import json
+import sys
+
+from .errors import PrismaxError
+from .upload import resume, status, upload
+
+
+def _print_json(payload):
+    print(json.dumps(payload, indent=2, default=str))
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="prismax")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    upload_parser = subparsers.add_parser("upload")
+    upload_parser.add_argument("folder")
+    upload_parser.add_argument("--task-id", required=True, type=int)
+    upload_parser.add_argument("--serial-number", required=True)
+    upload_parser.add_argument("--api-key")
+    upload_parser.add_argument("--base-url")
+    upload_parser.add_argument("--wait", action="store_true")
+    upload_parser.add_argument("--max-wait", type=int, default=1800)
+    upload_parser.add_argument("--poll-interval", type=int, default=10)
+    upload_parser.add_argument("--timeout", type=int, default=60)
+    upload_parser.add_argument("--retries", type=int, default=3)
+    upload_parser.add_argument("--max-poll-errors", type=int, default=3)
+    upload_parser.add_argument("--concurrency", type=int, default=5)
+
+    resume_parser = subparsers.add_parser("resume")
+    resume_parser.add_argument("upload_id", type=int)
+    resume_parser.add_argument("folder")
+    resume_parser.add_argument("--api-key")
+    resume_parser.add_argument("--base-url")
+    resume_parser.add_argument("--wait", action="store_true")
+    resume_parser.add_argument("--max-wait", type=int, default=1800)
+    resume_parser.add_argument("--poll-interval", type=int, default=10)
+    resume_parser.add_argument("--timeout", type=int, default=60)
+    resume_parser.add_argument("--retries", type=int, default=3)
+    resume_parser.add_argument("--max-poll-errors", type=int, default=3)
+    resume_parser.add_argument("--concurrency", type=int, default=5)
+
+    status_parser = subparsers.add_parser("status")
+    status_parser.add_argument("upload_id", type=int)
+    status_parser.add_argument("--api-key")
+    status_parser.add_argument("--base-url")
+    status_parser.add_argument("--timeout", type=int, default=60)
+    status_parser.add_argument("--retries", type=int, default=3)
+
+    args = parser.parse_args(argv)
+
+    try:
+        if args.command == "upload":
+            result = upload(
+                args.folder,
+                task_id=args.task_id,
+                serial_number=args.serial_number,
+                api_key=args.api_key,
+                base_url=args.base_url,
+                wait=args.wait,
+                poll_interval=args.poll_interval,
+                max_wait=args.max_wait,
+                max_poll_errors=args.max_poll_errors,
+                timeout=args.timeout,
+                concurrency=args.concurrency,
+                retries=args.retries,
+            )
+            _print_json(result)
+            return 0
+
+        if args.command == "resume":
+            result = resume(
+                args.upload_id,
+                args.folder,
+                api_key=args.api_key,
+                base_url=args.base_url,
+                wait=args.wait,
+                poll_interval=args.poll_interval,
+                max_wait=args.max_wait,
+                max_poll_errors=args.max_poll_errors,
+                timeout=args.timeout,
+                concurrency=args.concurrency,
+                retries=args.retries,
+            )
+            _print_json(result)
+            return 0
+
+        if args.command == "status":
+            _print_json(status(
+                args.upload_id,
+                api_key=args.api_key,
+                base_url=args.base_url,
+                timeout=args.timeout,
+                retries=args.retries,
+            ))
+            return 0
+    except PrismaxError as exc:
+        print(f"prismax: {exc}", file=sys.stderr)
+        return 1
+
+    parser.error(f"Unknown command: {args.command}")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

prismax/client.py

@@ -0,0 +1,158 @@
+import json
+import os
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from importlib.metadata import PackageNotFoundError, version
+from urllib.parse import urlparse
+
+import requests
+
+from .errors import PrismaxApiError, PrismaxAuthError, PrismaxValidationError
+
+
+DEFAULT_BASE_URL = "https://data.prismaxserver.com"
+LOCAL_HOSTS = {"127.0.0.1", "localhost", "::1"}
+
+
+def _sdk_version():
+    try:
+        return version("prismax")
+    except PackageNotFoundError:
+        return "0.1.0"
+
+
+def _validate_base_url(base_url):
+    parsed = urlparse(base_url)
+    if parsed.scheme not in ("http", "https"):
+        raise PrismaxValidationError(
+            f"base_url must start with https:// (got: {base_url!r})."
+        )
+    host = parsed.hostname or ""
+    if parsed.scheme != "https" and host not in LOCAL_HOSTS:
+        raise PrismaxValidationError(
+            "base_url must use https:// for non-local hosts "
+            f"(got: {base_url!r}). Plain http is only allowed for localhost."
+        )
+
+
+class PrismaXClient:
+    def __init__(self, api_key=None, base_url=None, timeout=60, concurrency=5, retries=3):
+        self.api_key = api_key or os.getenv("PRISMAX_API_KEY")
+        if not self.api_key:
+            raise PrismaxAuthError("api_key is required or PRISMAX_API_KEY must be set.")
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        _validate_base_url(self.base_url)
+        self.timeout = timeout
+        self.concurrency = max(1, int(concurrency))
+        self.retries = max(1, int(retries))
+
+    def _headers(self):
+        return {
+            "X-API-Key": self.api_key,
+            "Content-Type": "application/json",
+            "User-Agent": f"prismax-sdk/{_sdk_version()}",
+        }
+
+    def _request(self, method, path, **kwargs):
+        url = f"{self.base_url}{path}"
+        try:
+            response = requests.request(
+                method,
+                url,
+                headers=self._headers(),
+                timeout=self.timeout,
+                **kwargs,
+            )
+        except requests.RequestException as exc:
+            raise PrismaxApiError(f"PrismaX API request failed: {exc}") from exc
+
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = {"success": False, "msg": response.text}
+
+        if not response.ok or payload.get("success") is False:
+            message = payload.get("msg") or payload.get("error") or f"PrismaX API request failed: {response.status_code}"
+            if response.status_code in (401, 403):
+                raise PrismaxAuthError(message)
+            raise PrismaxApiError(message)
+        return payload.get("data", payload)
+
+    def create_upload_session(self, *, task_id, serial_number, files):
+        return self._request(
+            "POST",
+            "/v1/data/upload-sessions",
+            json={
+                "task_id": task_id,
+                "serial_number": serial_number,
+                "files": files,
+            },
+        )
+
+    def resume_upload_session(self, *, upload_id, files):
+        return self._request(
+            "POST",
+            f"/v1/data/upload-sessions/{upload_id}/resume",
+            json={"files": files},
+        )
+
+    def get_upload(self, upload_id):
+        return self._request("GET", f"/v1/data/uploads/{upload_id}")
+
+    def upload_file_to_signed_url(self, *, signed_url, path, content_type, relative_path=None):
+        display_path = relative_path or path
+        for attempt in range(1, self.retries + 1):
+            try:
+                with open(path, "rb") as handle:
+                    response = requests.put(
+                        signed_url,
+                        data=handle,
+                        headers={"Content-Type": content_type or "application/octet-stream"},
+                        timeout=self.timeout,
+                    )
+                if response.ok:
+                    return
+                message = f"Upload failed with status {response.status_code}: {response.text[:200]}"
+            except requests.RequestException as exc:
+                message = str(exc)
+
+            if attempt == self.retries:
+                raise PrismaxApiError(f"Failed to upload {display_path}: {message}")
+            time.sleep(min(2 ** attempt, 10))
+
+    def upload_json_to_signed_url(self, *, signed_url, payload):
+        body = json.dumps(payload, indent=2).encode("utf-8")
+        for attempt in range(1, self.retries + 1):
+            try:
+                response = requests.put(
+                    signed_url,
+                    data=body,
+                    headers={"Content-Type": "application/json"},
+                    timeout=self.timeout,
+                )
+                if response.ok:
+                    return
+                message = f"Manifest upload failed with status {response.status_code}: {response.text[:200]}"
+            except requests.RequestException as exc:
+                message = str(exc)
+
+            if attempt == self.retries:
+                raise PrismaxApiError(message)
+            time.sleep(min(2 ** attempt, 10))
+
+    def upload_files(self, upload_items):
+        if not upload_items:
+            return
+        with ThreadPoolExecutor(max_workers=self.concurrency) as executor:
+            futures = [
+                executor.submit(
+                    self.upload_file_to_signed_url,
+                    signed_url=item["signed_url"],
+                    path=item["path"],
+                    content_type=item["content_type"],
+                    relative_path=item.get("relative_path"),
+                )
+                for item in upload_items
+            ]
+            for future in as_completed(futures):
+                future.result()

prismax/errors.py

@@ -0,0 +1,14 @@
+class PrismaxError(Exception):
+    """Base SDK error."""
+
+
+class PrismaxAuthError(PrismaxError):
+    """Raised when an API key is missing or rejected."""
+
+
+class PrismaxValidationError(PrismaxError):
+    """Raised when local upload input is invalid."""
+
+
+class PrismaxApiError(PrismaxError):
+    """Raised when the PrismaX API returns an error."""

prismax/manifest.py

@@ -0,0 +1,36 @@
+from datetime import datetime, timezone
+
+from .scanner import LocalFile
+
+
+def manifest_placeholder(episode_key: str) -> dict:
+    return {
+        "relative_path": f"{episode_key}/_MANIFEST.json",
+        "size_bytes": None,
+        "content_type": "application/json",
+    }
+
+
+def build_manifest_payload(
+    *,
+    episode_key: str,
+    upload_id,
+    machine_id,
+    task_id,
+    files: list[LocalFile],
+) -> dict:
+    episode_files = []
+    for item in files:
+        relative_path = item.relative_path
+        if relative_path == f"{episode_key}.mcap" or relative_path.startswith(f"{episode_key}/"):
+            episode_files.append(item.as_api_payload())
+
+    return {
+        "manifest_version": 1,
+        "upload_id": upload_id,
+        "episode_key": episode_key,
+        "machine_id": machine_id,
+        "task_id": task_id,
+        "created_at_utc": datetime.now(timezone.utc).isoformat(),
+        "files": episode_files,
+    }

prismax/scanner.py

@@ -0,0 +1,191 @@
+import mimetypes
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import PrismaxValidationError
+
+
+MANIFEST_FILENAME = "_MANIFEST.json"
+MIN_VIDEO_COUNT = 3
+VIDEO_SLOTS = ("env", "left", "right")
+
+
+@dataclass(frozen=True)
+class LocalFile:
+    relative_path: str
+    path: Path
+    size_bytes: int
+    content_type: str
+
+    def as_api_payload(self):
+        return {
+            "relative_path": self.relative_path,
+            "size_bytes": self.size_bytes,
+            "content_type": self.content_type,
+        }
+
+
+def _content_type(path: Path) -> str:
+    suffix = path.suffix.lower()
+    if suffix == ".mp4":
+        return "video/mp4"
+    if suffix == ".json":
+        return "application/json"
+    guessed, _ = mimetypes.guess_type(str(path))
+    return guessed or "application/octet-stream"
+
+
+def _video_slot(file_name: str) -> str:
+    normalized = file_name.lower()
+    if "left" in normalized:
+        return "left"
+    if "right" in normalized:
+        return "right"
+    return "env"
+
+
+def _primary_sort_key(file_name: str, slot: str):
+    base_name = Path(str(file_name or "")).name.lower()
+    stem = base_name.rsplit(".", 1)[0]
+    exact_primary = {
+        "env": {"high", "env"},
+        "left": {"left"},
+        "right": {"right"},
+    }
+    return (0 if stem in exact_primary.get(slot, set()) else 1, base_name)
+
+
+def _is_hidden_path(path: Path) -> bool:
+    return any(part.startswith(".") for part in path.parts)
+
+
+def select_primary_video_paths(video_paths: list[str]) -> dict[str, str]:
+    """Return the deterministic primary env/left/right paths from a list of mp4 paths."""
+    grouped = {slot: [] for slot in VIDEO_SLOTS}
+    for path in video_paths:
+        if not str(path).endswith(".mp4"):
+            continue
+        slot = _video_slot(Path(str(path)).name)
+        grouped[slot].append(path)
+    selected = {}
+    for slot in VIDEO_SLOTS:
+        candidates = sorted(grouped[slot], key=lambda item: _primary_sort_key(Path(str(item)).name, slot))
+        if candidates:
+            selected[slot] = candidates[0]
+    return selected
+
+
+def scan_folder(folder) -> list[LocalFile]:
+    root = Path(folder).expanduser().resolve()
+    if not root.exists():
+        raise PrismaxValidationError(f"Folder does not exist: {root}")
+    if not root.is_dir():
+        raise PrismaxValidationError(f"Path must be a folder: {root}")
+
+    files = []
+    for path in sorted(root.rglob("*")):
+        if not path.is_file():
+            continue
+        relative_path = path.relative_to(root).as_posix()
+        if _is_hidden_path(Path(relative_path)):
+            continue
+        if relative_path == MANIFEST_FILENAME or relative_path.endswith(f"/{MANIFEST_FILENAME}"):
+            continue
+        files.append(LocalFile(
+            relative_path=relative_path,
+            path=path,
+            size_bytes=path.stat().st_size,
+            content_type=_content_type(path),
+        ))
+
+    if not files:
+        raise PrismaxValidationError("No uploadable files found.")
+    return files
+
+
+def validate_mcap_mp4(files: list[LocalFile]) -> list[str]:
+    errors = []
+    stats = {}
+
+    def ensure_episode(episode_key):
+        if episode_key not in stats:
+            stats[episode_key] = {
+                "mcap_count": 0,
+                "mp4_count": 0,
+                "video_paths": [],
+            }
+        return stats[episode_key]
+
+    for item in files:
+        relative_path = item.relative_path
+        if "/" in relative_path:
+            parts = relative_path.split("/")
+            if len(parts) != 2:
+                errors.append(f"Nested folders are not allowed: {relative_path}")
+                continue
+            folder_name, file_name = parts
+            if not folder_name or not file_name:
+                errors.append(f"Invalid path: {relative_path}")
+                continue
+            if folder_name.endswith(".mcap"):
+                errors.append(f"Video folder name must not end with .mcap: {folder_name}")
+                continue
+            if not file_name.endswith(".mp4"):
+                errors.append(f"Only .mp4 files are allowed inside episode folders: {relative_path}")
+                continue
+            episode_stats = ensure_episode(folder_name)
+            episode_stats["mp4_count"] += 1
+            episode_stats["video_paths"].append(relative_path)
+            continue
+
+        if relative_path.endswith(".mcap"):
+            episode_key = relative_path[:-5]
+            if not episode_key:
+                errors.append(f"Invalid .mcap filename at root: {relative_path}")
+                continue
+            ensure_episode(episode_key)["mcap_count"] += 1
+            continue
+
+        errors.append(f"Only .mcap files are allowed at root: {relative_path}")
+
+    episode_keys = sorted(stats.keys())
+    if not episode_keys:
+        errors.append(
+            "No valid episodes found. Expected {episode}.mcap at root and at least "
+            "3 .mp4 files under {episode}/."
+        )
+
+    for episode_key in episode_keys:
+        episode_stats = stats[episode_key]
+        if episode_stats["mcap_count"] != 1:
+            errors.append(
+                f"Episode {episode_key} must have exactly 1 .mcap file "
+                f"(found {episode_stats['mcap_count']})."
+            )
+        if episode_stats["mp4_count"] < MIN_VIDEO_COUNT:
+            errors.append(
+                f"Episode {episode_key} must have at least {MIN_VIDEO_COUNT} "
+                f".mp4 files (found {episode_stats['mp4_count']})."
+            )
+        else:
+            primary_videos = select_primary_video_paths(episode_stats["video_paths"])
+            missing_slots = [slot for slot in VIDEO_SLOTS if slot not in primary_videos]
+            if missing_slots:
+                errors.append(
+                    f"Episode {episode_key} must include primary env/high, left, and right MP4s "
+                    f"(missing: {', '.join(missing_slots)}). Use one filename containing "
+                    '"left", one containing "right", and one containing neither.'
+                )
+
+    return errors
+
+
+def episode_keys(files: list[LocalFile]) -> list[str]:
+    keys = set()
+    for item in files:
+        path = item.relative_path
+        if path.endswith(".mcap") and "/" not in path:
+            keys.add(path[:-5])
+        elif path.endswith(".mp4") and "/" in path:
+            keys.add(path.split("/", 1)[0])
+    return sorted(keys, key=lambda item: (len(item), item))

prismax/upload.py

@@ -0,0 +1,240 @@
+import time
+
+from .client import PrismaXClient
+from .errors import PrismaxApiError, PrismaxValidationError
+from .manifest import build_manifest_payload, manifest_placeholder
+from .scanner import scan_folder, validate_mcap_mp4, episode_keys
+
+
+TERMINAL_STATUSES = {
+    "DERIVED_READY",
+    "DERIVED_VALIDATION_FAILED",
+    "FAILED",
+    "DERIVED_PARTIALLY_READY",
+}
+DEFAULT_POLL_ERROR_LIMIT = 3
+
+
+def _build_files_payload(files, keys):
+    payload = [item.as_api_payload() for item in files]
+    payload.extend(manifest_placeholder(key) for key in keys)
+    return payload
+
+
+def upload(
+    folder,
+    *,
+    task_id,
+    serial_number,
+    api_key=None,
+    base_url=None,
+    wait=False,
+    poll_interval=10,
+    max_wait=1800,
+    max_poll_errors=DEFAULT_POLL_ERROR_LIMIT,
+    timeout=60,
+    concurrency=5,
+    retries=3,
+):
+    if task_id is None:
+        raise PrismaxValidationError("task_id is required.")
+    if not serial_number:
+        raise PrismaxValidationError("serial_number is required.")
+    client = PrismaXClient(
+        api_key=api_key,
+        base_url=base_url,
+        timeout=timeout,
+        concurrency=concurrency,
+        retries=retries,
+    )
+    files = scan_folder(folder)
+    errors = validate_mcap_mp4(files)
+    if errors:
+        raise PrismaxValidationError("; ".join(errors))
+
+    keys = episode_keys(files)
+    session = client.create_upload_session(
+        task_id=task_id,
+        serial_number=serial_number,
+        files=_build_files_payload(files, keys),
+    )
+    resolved_machine_id = session.get("machine_id")
+    try:
+        _upload_session_files(
+            client=client,
+            session=session,
+            files=files,
+            episode_keys_value=keys,
+            task_id=task_id,
+            machine_id=resolved_machine_id,
+        )
+    except PrismaxApiError as exc:
+        upload_id = session.get("upload_id")
+        raise PrismaxApiError(
+            f"Upload {upload_id} was created but file upload failed. "
+            f"Resume with: prismax resume {upload_id} {folder}. Original error: {exc}"
+        ) from exc
+
+    if wait:
+        return wait_for_upload(
+            session["upload_id"],
+            api_key=api_key,
+            base_url=base_url,
+            poll_interval=poll_interval,
+            max_wait=max_wait,
+            max_poll_errors=max_poll_errors,
+            timeout=timeout,
+            retries=retries,
+        )
+    return _public_session_result(session)
+
+
+def resume(
+    upload_id,
+    folder,
+    *,
+    api_key=None,
+    base_url=None,
+    wait=False,
+    poll_interval=10,
+    max_wait=1800,
+    max_poll_errors=DEFAULT_POLL_ERROR_LIMIT,
+    timeout=60,
+    concurrency=5,
+    retries=3,
+):
+    client = PrismaXClient(
+        api_key=api_key,
+        base_url=base_url,
+        timeout=timeout,
+        concurrency=concurrency,
+        retries=retries,
+    )
+    files = scan_folder(folder)
+    errors = validate_mcap_mp4(files)
+    if errors:
+        raise PrismaxValidationError("; ".join(errors))
+
+    keys = episode_keys(files)
+    session = client.resume_upload_session(
+        upload_id=upload_id,
+        files=_build_files_payload(files, keys),
+    )
+    try:
+        _upload_session_files(
+            client=client,
+            session=session,
+            files=files,
+            episode_keys_value=keys,
+            task_id=session.get("task_id"),
+            machine_id=session.get("machine_id"),
+        )
+    except PrismaxApiError as exc:
+        raise PrismaxApiError(
+            f"Resume for upload {upload_id} failed while uploading files. "
+            f"Retry with: prismax resume {upload_id} {folder}. Original error: {exc}"
+        ) from exc
+
+    if wait:
+        return wait_for_upload(
+            upload_id,
+            api_key=api_key,
+            base_url=base_url,
+            poll_interval=poll_interval,
+            max_wait=max_wait,
+            max_poll_errors=max_poll_errors,
+            timeout=timeout,
+            retries=retries,
+        )
+    return _public_session_result(session)
+
+
+def status(upload_id, *, api_key=None, base_url=None, timeout=60, retries=3):
+    client = PrismaXClient(api_key=api_key, base_url=base_url, timeout=timeout, retries=retries)
+    return client.get_upload(upload_id)
+
+
+def wait_for_upload(
+    upload_id,
+    *,
+    api_key=None,
+    base_url=None,
+    poll_interval=10,
+    max_wait=1800,
+    timeout=60,
+    retries=3,
+    max_poll_errors=DEFAULT_POLL_ERROR_LIMIT,
+):
+    client = PrismaXClient(api_key=api_key, base_url=base_url, timeout=timeout, retries=retries)
+    started_at = time.monotonic()
+    last_status = None
+    poll_errors = 0
+    while True:
+        try:
+            current = client.get_upload(upload_id)
+            poll_errors = 0
+            last_status = str(current.get("status") or "").upper()
+            if last_status in TERMINAL_STATUSES:
+                return current
+        except PrismaxApiError as exc:
+            poll_errors += 1
+            if max_poll_errors is not None and poll_errors >= int(max_poll_errors):
+                raise PrismaxApiError(
+                    f"Failed to poll upload {upload_id} status after {poll_errors} consecutive errors: {exc}"
+                ) from exc
+        if max_wait is not None and time.monotonic() - started_at >= int(max_wait):
+            raise PrismaxApiError(
+                f"Timed out waiting for upload {upload_id} after {int(max_wait)} seconds "
+                f"(last status: {last_status or 'unknown'})."
+            )
+        time.sleep(max(1, int(poll_interval)))
+
+
+def _upload_session_files(*, client, session, files, episode_keys_value, task_id, machine_id):
+    signed_urls = session.get("signed_urls") or []
+    signed_url_by_path = {
+        item.get("relative_path"): item
+        for item in signed_urls
+        if item.get("relative_path") and item.get("signed_url")
+    }
+
+    raw_uploads = []
+    local_file_by_relative_path = {item.relative_path: item for item in files}
+    for local_file in files:
+        signed_item = signed_url_by_path.get(local_file.relative_path)
+        if not signed_item:
+            continue
+        raw_uploads.append({
+            "signed_url": signed_item["signed_url"],
+            "relative_path": local_file.relative_path,
+            "path": local_file.path,
+            "content_type": local_file.content_type,
+        })
+    client.upload_files(raw_uploads)
+
+    upload_id = session.get("upload_id")
+    for episode_key in episode_keys_value:
+        manifest_path = f"{episode_key}/_MANIFEST.json"
+        signed_item = signed_url_by_path.get(manifest_path)
+        if not signed_item:
+            continue
+        payload = build_manifest_payload(
+            episode_key=episode_key,
+            upload_id=upload_id,
+            machine_id=machine_id,
+            task_id=task_id,
+            files=list(local_file_by_relative_path.values()),
+        )
+        client.upload_json_to_signed_url(
+            signed_url=signed_item["signed_url"],
+            payload=payload,
+        )
+
+
+def _public_session_result(session):
+    hidden = {"signed_urls"}
+    return {
+        key: value
+        for key, value in session.items()
+        if key not in hidden
+    }

prismax-0.1.0.dist-info/METADATA

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: prismax
+Version: 0.1.0
+Summary: PrismaX Python SDK for data uploads
+Author: PrismaX
+License: PolyForm Noncommercial License 1.0.0
+Project-URL: Homepage, https://github.com/ChrisPrismax/prismax-sdk-python
+Project-URL: Repository, https://github.com/ChrisPrismax/prismax-sdk-python
+Project-URL: Issues, https://github.com/ChrisPrismax/prismax-sdk-python/issues
+Keywords: prismax,upload,sdk,robotics,mcap
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Dynamic: license-file
+
+# PrismaX Python SDK
+
+Minimal upload SDK for PrismaX data uploads.
+
+## License
+
+This SDK is source-available for noncommercial use under the PolyForm
+Noncommercial License 1.0.0. Commercial use is not permitted unless PrismaX
+grants a separate commercial license.
+
+## Quickstart
+
+You need:
+
+- a PrismaX upload API key with the `pxu_` prefix
+- a PrismaX task ID
+- the robot serial number for the machine that produced the data
+
+```bash
+pip install prismax
+export PRISMAX_API_KEY="pxu_your_upload_api_key"
+```
+
+Download API keys are not valid for uploads.
+
+```python
+import prismax
+
+result = prismax.upload("./data", task_id=123, serial_number="robot_serial_number")
+print(result["upload_id"])
+```
+
+The SDK scans the folder, creates an upload session, uploads raw files to signed
+Google Cloud URLs, generates episode manifests in memory, uploads manifests last,
+and returns the upload summary.
+
+You can also pass the API key directly:
+
+```python
+import prismax
+
+result = prismax.upload(
+    "./data",
+    task_id=123,
+    serial_number="robot_serial_number",
+    api_key="pxu_your_upload_api_key",
+)
+```
+
+## Expected Folder Structure
+
+```text
+data/
+  1.mcap
+  1/
+    high.mp4
+    left.mp4
+    right.mp4
+    high2.mp4
+    left2.mp4
+    right2.mp4
+```
+
+Each episode must contain one root `{episode}.mcap` file and at least three MP4
+files under `{episode}/`: one primary filename containing `left`, one containing
+`right`, and one environment/high video filename containing neither. Additional
+MP4 files are uploaded as raw files, included in downloads, and checked for
+duration consistency. A duration mismatch across any episode videos can fail the
+upload. Only the primary three videos are processed for derived previews, QA,
+and duplicate detection.
+
+Use lowercase `.mp4` extensions. Uppercase variants such as `.MP4` are rejected
+so client validation, worker processing, and download manifests choose the same
+primary videos. Hidden files are ignored, including macOS metadata files such as
+`.DS_Store` and `._left.mp4`.
+
+Primary video selection is based on filename:
+
+- filenames containing `left` are treated as left videos
+- filenames containing `right` are treated as right videos
+- other MP4 files are treated as environment/high videos
+- exact names are preferred, for example `high.mp4`, `left.mp4`, and
+  `right.mp4` are selected before `high2.mp4`, `left2.mp4`, and `right2.mp4`
+
+Example:
+
+```text
+data/
+  1.mcap
+  1/
+    high.mp4
+    left.mp4
+    right.mp4
+    high2.mp4
+    left2.mp4
+    right2.mp4
+```
+
+Primary videos:
+
+```text
+env/high: high.mp4
+left: left.mp4
+right: right.mp4
+```
+
+Additional videos:
+
+```text
+high2.mp4
+left2.mp4
+right2.mp4
+```
+
+## CLI
+
+```bash
+prismax upload ./data --task-id 123 --serial-number robot_serial_number
+prismax status 123
+```
+
+Use `--wait` to wait for the worker to finish. The default maximum wait time is
+30 minutes.
+
+```bash
+prismax upload ./data --task-id 123 --serial-number robot_serial_number --wait
+prismax upload ./data --task-id 123 --serial-number robot_serial_number --wait --max-wait 3600
+```
+
+Useful CLI options:
+
+```bash
+prismax upload ./data --task-id 123 --serial-number robot_serial_number --timeout 120 --retries 5
+prismax upload ./data --task-id 123 --serial-number robot_serial_number --wait --poll-interval 5 --max-poll-errors 3
+```
+
+## Status and Resume
+
+```python
+import prismax
+
+upload_status = prismax.status(123)
+
+resume_result = prismax.resume(
+    123,
+    "./data",
+)
+```
+
+```bash
+prismax status 123
+prismax resume 123 ./data
+```
+
+Resume expects the same complete upload folder/file list, not only the files
+that are missing from cloud storage. The SDK will ask the API which files still
+need signed upload URLs. Resume is only allowed while the upload is still in
+`UPLOADING` status; once processing has started or the upload reaches a terminal
+status, create a new upload instead.
+
+## Error Handling
+
+```python
+import prismax
+
+try:
+    prismax.upload("./data", task_id=123, serial_number="robot_serial_number")
+except prismax.PrismaxValidationError as exc:
+    print(f"Invalid upload folder: {exc}")
+except prismax.PrismaxAuthError as exc:
+    print(f"API key or permission error: {exc}")
+except prismax.PrismaxApiError as exc:
+    print(f"PrismaX API error: {exc}")
+```
+
+If raw file upload fails after the session is created, the SDK error includes
+the upload ID and a `prismax resume <upload_id> <folder>` command.

prismax-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+prismax/__init__.py,sha256=iVLWIeMPcOAjNm1wHgPFUPWsflZRK2g1VDByDWDQ6I0,639
+prismax/cli.py,sha256=81xB8w-Q7XIAZmWRZ4oOB6OXin0xqU9TE8QWRRWnSqA,3936
+prismax/client.py,sha256=nZG321roCN_93WMoavRhlpRJPN7Nn1dlmosFVfVFvpU,5760
+prismax/errors.py,sha256=3ZsglvM2i3YCm6dhbG3yITtOZ6kE8kNDoohzOtEQB8A,348
+prismax/manifest.py,sha256=APNuXtUzBKAT9z9wZTb7VWVCELO7bALI1CQa_l7VNBg,939
+prismax/scanner.py,sha256=KKNF25EtFGSf0a0ZvdG1NO48v868SvC6-Awlac0KSDI,6463
+prismax/upload.py,sha256=n7hJL4-RTbRCFIhcYlhn-Yr72FeLrsVRDaAHWD6rJ0s,7195
+prismax-0.1.0.dist-info/licenses/LICENSE,sha256=FFp83etv6SWxufS_dkHzTCVx7LHtJjUfUjMEkLIjrxE,4589
+prismax-0.1.0.dist-info/METADATA,sha256=xr9Yd9YcZ_Fneb_GbPNRsIUt-Gqw-_3vBMww60-PFn4,5473
+prismax-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+prismax-0.1.0.dist-info/entry_points.txt,sha256=nhoZLNfrZJGwEnmdOFY2lIWtBEGizlaP5R2fLgZUKXw,45
+prismax-0.1.0.dist-info/top_level.txt,sha256=Ydwy8p_-tArcn3AaCyEOEEAMQBh-2p9VJNZScG3H3Iw,8
+prismax-0.1.0.dist-info/RECORD,,

prismax-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

prismax-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+prismax = prismax.cli:main

prismax-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,132 @@
+Required Notice: Copyright 2026 PrismaX
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all your
+licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software
+to do everything you might do with the software that would
+otherwise infringe the licensor's copyright in it for any
+permitted purpose. However, you may only distribute the software
+according to [Distribution License](#distribution-license) and
+make changes or new works based on the software according to
+[Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to
+distribute copies of the software. Your license to distribute
+covers distributing the software with changes and new works
+permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the
+software from you also gets a copy of these terms or the URL for
+them above, as well as copies of any plain-text lines beginning
+with `Required Notice:` that the licensor provided with the
+software. For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make
+changes and new works based on the software for any permitted
+purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the
+benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application, is
+use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization, or
+government institution is use for a permitted purpose regardless
+of the source of funding or obligations resulting from the
+funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law.
+These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else. These terms do not imply any
+other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms, and
+take practical steps to correct past violations, within 32 days
+of receiving notice. Otherwise, all your licenses end
+immediately.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without any
+warranty or condition, and the licensor will not be liable to
+you for any damages arising out of these terms or the use or
+nature of the software, under any kind of legal claim.
+
+## Definitions
+
+The licensor is the individual or entity offering these terms,
+and the software is the software the licensor makes available
+under these terms.
+
+You refers to the individual or entity agreeing to these terms.
+
+Your company is any legal entity, sole proprietorship, or other
+kind of organization that you work for, plus all organizations
+that have control over, are under the control of, or are under
+common control with that organization. Control means ownership
+of substantially all the assets of an entity, or the power to
+direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+Your licenses are all the licenses granted to you for the
+software under these terms.
+
+Use means anything you do with the software requiring one of
+your licenses.
+
+© PolyForm Project Inc.

prismax-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+prismax