qualia-sdk 0.1.0__tar.gz

qualia_sdk-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# qualia
+qcore.config.toml
+.qdev/*
+.env
+
+# python-generated
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.pytest_cache/*
+.coverage
+
+# virtual envs
+.venv
+venv/*
+
+# ruff stuff:
+.ruff_cache/
+
+# mac
+.DS_Store
+
+# Jupyter Notebook
+.ipynb_checkpoints
+.ipython
+
+# Terraform
+*/*/.terraform/
+*.tfstate
+*.tfstate.backup
+*.tfplan
+
+# supabase
+.temp
+reset.sql

qualia_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: qualia-sdk
+Version: 0.1.0
+Summary: Python SDK for Qualia Studios VLA fine-tuning platform
+Project-URL: Homepage, https://qualiastudios.dev
+Project-URL: Documentation, https://docs.qualiastudios.dev
+Author: Qualia Studios
+License-Expression: MIT
+Keywords: fine-tuning,machine-learning,qualia,robotics,vla
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# Qualia Python SDK
+
+The official Python SDK for the [Qualia](https://app.qualiastudios.dev) VLA fine-tuning platform.
+
+## Installation
+
+```bash
+pip install qualia-sdk
+```
+
+## Quick Start
+
+```python
+from qualia import Qualia
+
+# Initialize the client
+client = Qualia(api_key="your-api-key")
+
+# Or use the QUALIA_API_KEY environment variable
+client = Qualia()
+
+# List available VLA models
+models = client.models.list()
+for model in models:
+    print(f"{model.id}: {model.name}")
+    print(f"  Camera slots: {model.camera_slots}")
+
+# Create a project
+project = client.projects.create(name="My Robot Project")
+print(f"Created project: {project.project_id}")
+
+# Get dataset image keys for camera mapping
+image_keys = client.datasets.get_image_keys("lerobot/pusht")
+print(f"Available keys: {image_keys.image_keys}")
+
+# Start a finetune job
+job = client.finetune.create(
+    project_id=project.project_id,
+    model_id="lerobot/smolvla_base",
+    vla_type="smolvla",
+    dataset_id="lerobot/pusht",
+    hours=2.0,
+    camera_mappings={"cam_1": "observation.images.top"},
+)
+print(f"Started job: {job.job_id}")
+
+# Check job status
+status = client.finetune.get(job.job_id)
+print(f"Status: {status.status.status}")
+print(f"Current phase: {status.status.current_phase}")
+
+# Cancel a job if needed
+result = client.finetune.cancel(job.job_id)
+```
+
+## Resources
+
+### Credits
+
+```python
+# Get your credit balance
+balance = client.credits.get()
+print(f"Available credits: {balance.balance}")
+```
+
+### Datasets
+
+```python
+# Get image keys from a HuggingFace dataset
+image_keys = client.datasets.get_image_keys("lerobot/pusht")
+# Use these keys as values in camera_mappings
+```
+
+### Finetune
+
+```python
+# Create a finetune job
+job = client.finetune.create(
+    project_id="...",
+    model_id="lerobot/smolvla_base",  # HuggingFace model ID
+    vla_type="smolvla",                # smolvla, pi0, or pi0.5
+    dataset_id="lerobot/pusht",        # HuggingFace dataset ID
+    hours=2.0,                         # Training duration (max 168)
+    camera_mappings={                  # Map model slots to dataset keys
+        "cam_1": "observation.images.top",
+    },
+    # Optional parameters:
+    instance_type="gpu_1x_a100",       # From client.instances.list()
+    region="us-east-1",
+    batch_size=32,
+    name="My training run",
+)
+
+# Get job status
+status = client.finetune.get(job.job_id)
+
+# Cancel a job
+result = client.finetune.cancel(job.job_id)
+```
+
+### Instances
+
+```python
+# List available GPU instances
+instances = client.instances.list()
+for inst in instances:
+    print(f"{inst.id}: {inst.gpu_description} - {inst.credits_per_hour} credits/hr")
+    print(f"  Specs: {inst.specs.gpu_count}x GPU, {inst.specs.memory_gib}GB RAM")
+    print(f"  Regions: {[r.name for r in inst.regions]}")
+```
+
+### Models
+
+```python
+# List available VLA model types
+models = client.models.list()
+for model in models:
+    print(f"{model.id}: {model.name}")
+    print(f"  Base model: {model.base_model_id}")
+    print(f"  Camera slots: {model.camera_slots}")
+```
+
+### Projects
+
+```python
+# Create a project
+project = client.projects.create(
+    name="My Project",
+    description="Optional description",
+)
+
+# List all projects
+projects = client.projects.list()
+for p in projects:
+    print(f"{p.name}: {len(p.jobs)} jobs")
+
+# Delete a project (fails if it has active jobs)
+client.projects.delete(project.project_id)
+```
+
+## Configuration
+
+### Environment Variables
+
+- `QUALIA_API_KEY`: Your API key (used if not passed to constructor)
+- `QUALIA_BASE_URL`: Override the API base URL (default: `https://api.qualiastudios.dev`)
+
+### Custom HTTP Client
+
+```python
+import httpx
+
+# Use a custom httpx client for advanced configuration
+custom_client = httpx.Client(
+    timeout=60.0,
+    limits=httpx.Limits(max_connections=10),
+)
+
+client = Qualia(api_key="...", httpx_client=custom_client)
+```
+
+### Context Manager
+
+```python
+# Automatically close the client when done
+with Qualia(api_key="...") as client:
+    models = client.models.list()
+```
+
+## Error Handling
+
+```python
+from qualia import (
+    Qualia,
+    QualiaError,
+    QualiaAPIError,
+    AuthenticationError,
+    NotFoundError,
+    ValidationError,
+    RateLimitError,
+)
+
+try:
+    client = Qualia(api_key="invalid-key")
+    client.models.list()
+except AuthenticationError as e:
+    print(f"Auth failed: {e}")
+except NotFoundError as e:
+    print(f"Not found: {e}")
+except ValidationError as e:
+    print(f"Validation error: {e}")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after: {e.retry_after}s")
+except QualiaAPIError as e:
+    print(f"API error [{e.status_code}]: {e.message}")
+except QualiaError as e:
+    print(f"SDK error: {e}")
+```
+
+## Requirements
+
+- Python 3.10+
+- httpx
+- pydantic
+
+## License
+
+MIT

qualia_sdk-0.1.0/README.md

@@ -0,0 +1,208 @@
+# Qualia Python SDK
+
+The official Python SDK for the [Qualia](https://app.qualiastudios.dev) VLA fine-tuning platform.
+
+## Installation
+
+```bash
+pip install qualia-sdk
+```
+
+## Quick Start
+
+```python
+from qualia import Qualia
+
+# Initialize the client
+client = Qualia(api_key="your-api-key")
+
+# Or use the QUALIA_API_KEY environment variable
+client = Qualia()
+
+# List available VLA models
+models = client.models.list()
+for model in models:
+    print(f"{model.id}: {model.name}")
+    print(f"  Camera slots: {model.camera_slots}")
+
+# Create a project
+project = client.projects.create(name="My Robot Project")
+print(f"Created project: {project.project_id}")
+
+# Get dataset image keys for camera mapping
+image_keys = client.datasets.get_image_keys("lerobot/pusht")
+print(f"Available keys: {image_keys.image_keys}")
+
+# Start a finetune job
+job = client.finetune.create(
+    project_id=project.project_id,
+    model_id="lerobot/smolvla_base",
+    vla_type="smolvla",
+    dataset_id="lerobot/pusht",
+    hours=2.0,
+    camera_mappings={"cam_1": "observation.images.top"},
+)
+print(f"Started job: {job.job_id}")
+
+# Check job status
+status = client.finetune.get(job.job_id)
+print(f"Status: {status.status.status}")
+print(f"Current phase: {status.status.current_phase}")
+
+# Cancel a job if needed
+result = client.finetune.cancel(job.job_id)
+```
+
+## Resources
+
+### Credits
+
+```python
+# Get your credit balance
+balance = client.credits.get()
+print(f"Available credits: {balance.balance}")
+```
+
+### Datasets
+
+```python
+# Get image keys from a HuggingFace dataset
+image_keys = client.datasets.get_image_keys("lerobot/pusht")
+# Use these keys as values in camera_mappings
+```
+
+### Finetune
+
+```python
+# Create a finetune job
+job = client.finetune.create(
+    project_id="...",
+    model_id="lerobot/smolvla_base",  # HuggingFace model ID
+    vla_type="smolvla",                # smolvla, pi0, or pi0.5
+    dataset_id="lerobot/pusht",        # HuggingFace dataset ID
+    hours=2.0,                         # Training duration (max 168)
+    camera_mappings={                  # Map model slots to dataset keys
+        "cam_1": "observation.images.top",
+    },
+    # Optional parameters:
+    instance_type="gpu_1x_a100",       # From client.instances.list()
+    region="us-east-1",
+    batch_size=32,
+    name="My training run",
+)
+
+# Get job status
+status = client.finetune.get(job.job_id)
+
+# Cancel a job
+result = client.finetune.cancel(job.job_id)
+```
+
+### Instances
+
+```python
+# List available GPU instances
+instances = client.instances.list()
+for inst in instances:
+    print(f"{inst.id}: {inst.gpu_description} - {inst.credits_per_hour} credits/hr")
+    print(f"  Specs: {inst.specs.gpu_count}x GPU, {inst.specs.memory_gib}GB RAM")
+    print(f"  Regions: {[r.name for r in inst.regions]}")
+```
+
+### Models
+
+```python
+# List available VLA model types
+models = client.models.list()
+for model in models:
+    print(f"{model.id}: {model.name}")
+    print(f"  Base model: {model.base_model_id}")
+    print(f"  Camera slots: {model.camera_slots}")
+```
+
+### Projects
+
+```python
+# Create a project
+project = client.projects.create(
+    name="My Project",
+    description="Optional description",
+)
+
+# List all projects
+projects = client.projects.list()
+for p in projects:
+    print(f"{p.name}: {len(p.jobs)} jobs")
+
+# Delete a project (fails if it has active jobs)
+client.projects.delete(project.project_id)
+```
+
+## Configuration
+
+### Environment Variables
+
+- `QUALIA_API_KEY`: Your API key (used if not passed to constructor)
+- `QUALIA_BASE_URL`: Override the API base URL (default: `https://api.qualiastudios.dev`)
+
+### Custom HTTP Client
+
+```python
+import httpx
+
+# Use a custom httpx client for advanced configuration
+custom_client = httpx.Client(
+    timeout=60.0,
+    limits=httpx.Limits(max_connections=10),
+)
+
+client = Qualia(api_key="...", httpx_client=custom_client)
+```
+
+### Context Manager
+
+```python
+# Automatically close the client when done
+with Qualia(api_key="...") as client:
+    models = client.models.list()
+```
+
+## Error Handling
+
+```python
+from qualia import (
+    Qualia,
+    QualiaError,
+    QualiaAPIError,
+    AuthenticationError,
+    NotFoundError,
+    ValidationError,
+    RateLimitError,
+)
+
+try:
+    client = Qualia(api_key="invalid-key")
+    client.models.list()
+except AuthenticationError as e:
+    print(f"Auth failed: {e}")
+except NotFoundError as e:
+    print(f"Not found: {e}")
+except ValidationError as e:
+    print(f"Validation error: {e}")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after: {e.retry_after}s")
+except QualiaAPIError as e:
+    print(f"API error [{e.status_code}]: {e.message}")
+except QualiaError as e:
+    print(f"SDK error: {e}")
+```
+
+## Requirements
+
+- Python 3.10+
+- httpx
+- pydantic
+
+## License
+
+MIT

qualia_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,102 @@
+[project]
+name = "qualia-sdk"
+version = "0.1.0"
+description = "Python SDK for Qualia Studios VLA fine-tuning platform"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Qualia Studios" },
+]
+keywords = ["qualia", "vla", "robotics", "fine-tuning", "machine-learning"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "pydantic>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://qualiastudios.dev"
+Documentation = "https://docs.qualiastudios.dev"
+
+[dependency-groups]
+test = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=4.0.0",
+    "pytest-httpx>=0.30.0",
+    "pytest-timeout>=2.0.0",
+    "python-dotenv>=1.0.0",
+]
+dev = [
+    "ruff>=0.4.0",
+    "mypy>=1.10.0",
+]
+
+[tool.uv]
+default-groups = [
+    "test",
+    "dev",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qualia"]
+
+[tool.ruff]
+line-length = 89
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "I",   # isort
+    "F",   # pyflakes
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "B",   # flake8-bugbear
+    "UP",  # pyupgrade
+    "SIM", # flake8-simplify
+]
+ignore = [
+    "E501", # line too long
+]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+addopts = "-v --tb=short"
+markers = [
+    "integration: marks tests as integration tests (require API key, hit real dev API)",
+    "integration_workflow: marks tests as workflow integration tests (run on merge to master, hit real dev API with real training jobs)",
+]
+
+[tool.coverage.run]
+source = ["src/qualia"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]

qualia_sdk-0.1.0/src/qualia/__init__.py

@@ -0,0 +1,94 @@
+"""
+Qualia SDK
+
+Python SDK for the Qualia Studios VLA fine-tuning platform.
+
+Usage:
+    ```python
+    from qualia import Qualia
+
+    client = Qualia(api_key="your-api-key")
+
+    # List available models
+    models = client.models.list()
+
+    # Create a project
+    project = client.projects.create(name="My Robot Project")
+
+    # Get dataset image keys for camera mapping
+    image_keys = client.datasets.get_image_keys("lerobot/pusht")
+
+    # Start a finetune job
+    job = client.finetune.create(
+        project_id=project.project_id,
+        model_id="lerobot/smolvla_base",
+        vla_type="smolvla",
+        dataset_id="lerobot/pusht",
+        hours=2.0,
+        camera_mappings={"cam_1": "observation.images.top"},
+    )
+
+    # Check status
+    status = client.finetune.get(job.job_id)
+    print(f"Status: {status.status}")
+    ```
+"""
+
+from .client import Qualia
+from .exceptions import (
+    AuthenticationError,
+    NotFoundError,
+    QualiaAPIError,
+    QualiaError,
+    RateLimitError,
+    ValidationError,
+)
+from .models import (
+    CreditBalance,
+    DatasetImageKeys,
+    FinetuneCancelResult,
+    FinetuneJob,
+    FinetuneStatus,
+    Instance,
+    InstanceRegion,
+    InstanceSpecs,
+    Phase,
+    PhaseEvent,
+    Project,
+    ProjectCreateResult,
+    ProjectDeleteResult,
+    ProjectJob,
+    VLAModel,
+    VLAType,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Client
+    "Qualia",
+    # Exceptions
+    "QualiaError",
+    "QualiaAPIError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    # Models
+    "VLAType",
+    "CreditBalance",
+    "DatasetImageKeys",
+    "FinetuneJob",
+    "FinetuneStatus",
+    "Phase",
+    "PhaseEvent",
+    "FinetuneCancelResult",
+    "Instance",
+    "InstanceRegion",
+    "InstanceSpecs",
+    "VLAModel",
+    "Project",
+    "ProjectJob",
+    "ProjectCreateResult",
+    "ProjectDeleteResult",
+]