prismax 0.1.0__tar.gz

prismax-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,177 @@
+# 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/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-0.1.0/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())