qualia-cli 0.1.0__tar.gz

qualia_cli-0.1.0/.gitignore

@@ -0,0 +1,84 @@
+# qualia
+qcore.config.toml
+.qdev/*
+.env
+
+# python-generated
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.coverage
+.coverage.*
+htmlcov/
+
+# virtual envs
+.venv
+
+# ruff stuff:
+.ruff_cache/
+
+# mac
+.DS_Store
+
+# Jupyter Notebook
+.ipynb_checkpoints
+.ipython
+
+# Terraform
+*/*/.terraform/
+*.tfstate
+*.tfstate.backup
+*.tfplan
+
+# supabase
+.temp
+reset.sql
+
+# generated docs
+ui/docs/src/assets/openapi.json
+
+# nix
+.direnv
+result
+
+# playwright-cli
+.playwright-cli/
+
+# Windows
+nul
+lerobot
+
+# Windows
+nul
+
+# qcore runtime files
+qcore.log
+qcore.pid
+
+# Dev credential files (auto-generated by setup workflow)
+dev_project_id.txt
+dev_user_id.txt
+dev_access_token.txt
+.env
+
+# Claude Code sandbox artifacts (https://github.com/anthropics/claude-code/issues/17727)
+.claude/agents
+.claude/commands
+.bash_profile
+.bashrc
+.gitconfig
+.gitmodules
+.idea
+.mcp.json
+.profile
+.ripgreprc
+.zprofile
+.zshrc
+/HEAD
+/config
+/hooks
+/objects
+/refs

qualia_cli-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: qualia-cli
+Version: 0.1.0
+Summary: CLI for the 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: cli,fine-tuning,qualia,robotics,vla
+Classifier: Development Status :: 3 - Alpha
+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: qualia-sdk>=0.2.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.15.0
+Description-Content-Type: text/markdown
+
+# Qualia CLI
+
+Terminal interface for the [Qualia](https://qualiastudios.dev) VLA fine-tuning platform.
+
+## Install
+
+```sh
+pip install qualia-cli
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv tool install qualia-cli
+```
+
+## Quick start
+
+```sh
+# Authenticate (pick one)
+qualia auth login                        # interactive, saves to config
+export QUALIA_API_KEY="your-api-key"     # env var
+qualia --token <KEY> <command>           # inline, for CI/scripts
+
+# List available models
+qualia models list
+
+# List GPU instances
+qualia instances list
+
+# Create a project
+qualia projects create "My Robot"
+
+# Start a fine-tuning job
+qualia finetune create \
+  --project-id <id> \
+  --vla-type smolvla \
+  --model-id lerobot/smolvla_base \
+  --dataset-id lerobot/pusht \
+  --dataset-last-modified "2025-01-15T10:00:00Z" \
+  --model-last-modified "2025-01-15T10:00:00Z" \
+  --hours 2.0 \
+  --camera-mappings '{"cam_1": "observation.images.top"}'
+
+# Check job status
+qualia finetune get <job-id>
+```
+
+## JSON output
+
+All commands support `--json` for machine-readable output:
+
+```sh
+qualia projects list --json
+qualia credits --json
+```

qualia_cli-0.1.0/README.md

@@ -0,0 +1,56 @@
+# Qualia CLI
+
+Terminal interface for the [Qualia](https://qualiastudios.dev) VLA fine-tuning platform.
+
+## Install
+
+```sh
+pip install qualia-cli
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv tool install qualia-cli
+```
+
+## Quick start
+
+```sh
+# Authenticate (pick one)
+qualia auth login                        # interactive, saves to config
+export QUALIA_API_KEY="your-api-key"     # env var
+qualia --token <KEY> <command>           # inline, for CI/scripts
+
+# List available models
+qualia models list
+
+# List GPU instances
+qualia instances list
+
+# Create a project
+qualia projects create "My Robot"
+
+# Start a fine-tuning job
+qualia finetune create \
+  --project-id <id> \
+  --vla-type smolvla \
+  --model-id lerobot/smolvla_base \
+  --dataset-id lerobot/pusht \
+  --dataset-last-modified "2025-01-15T10:00:00Z" \
+  --model-last-modified "2025-01-15T10:00:00Z" \
+  --hours 2.0 \
+  --camera-mappings '{"cam_1": "observation.images.top"}'
+
+# Check job status
+qualia finetune get <job-id>
+```
+
+## JSON output
+
+All commands support `--json` for machine-readable output:
+
+```sh
+qualia projects list --json
+qualia credits --json
+```

qualia_cli-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[project]
+name = "qualia-cli"
+version = "0.1.0"
+description = "CLI for the 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", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "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 = [
+    "qualia-sdk>=0.2.0",
+    "typer>=0.15.0",
+    "rich>=13.0.0",
+]
+
+[project.urls]
+Homepage = "https://qualiastudios.dev"
+Documentation = "https://docs.qualiastudios.dev"
+
+[project.scripts]
+qualia = "qualia_cli.main:cli"
+
+[dependency-groups]
+test = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+dev = [
+    "ruff==0.15.1",
+]
+
+[tool.uv]
+default-groups = [
+    "test",
+    "dev",
+]
+
+[tool.uv.sources]
+qualia-sdk = { path = "../python", editable = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qualia_cli"]
+
+[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.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-v --tb=short"

qualia_cli-0.1.0/src/qualia_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Qualia CLI - Terminal interface for the Qualia VLA fine-tuning platform."""
+
+__version__ = "0.1.0"

qualia_cli-0.1.0/src/qualia_cli/client.py

@@ -0,0 +1,29 @@
+"""Shared client factory."""
+
+from __future__ import annotations
+
+from qualia import AuthenticationError, Qualia
+
+from qualia_cli.config import load_config
+from qualia_cli.output import print_error
+
+
+def get_client() -> Qualia:
+    from qualia_cli.main import _base_url_override, _token_override
+
+    cfg = load_config()
+    kwargs: dict = {}
+    if _token_override:
+        kwargs["api_key"] = _token_override
+    elif cfg.api_key:
+        kwargs["api_key"] = cfg.api_key
+    if _base_url_override:
+        kwargs["base_url"] = _base_url_override
+    elif cfg.base_url:
+        kwargs["base_url"] = cfg.base_url
+    try:
+        return Qualia(**kwargs)
+    except AuthenticationError as e:
+        print_error(str(e))
+        print_error("Set QUALIA_API_KEY or run: qualia auth login --token <KEY>")
+        raise SystemExit(1) from e

qualia_cli-0.1.0/src/qualia_cli/commands/auth.py

@@ -0,0 +1,43 @@
+"""Auth commands."""
+
+from __future__ import annotations
+
+import typer
+
+from qualia_cli.config import load_config, save_config
+from qualia_cli.output import print_error
+
+app = typer.Typer(help="Authentication.")
+
+
+@app.command("login")
+def login(
+    api_key: str = typer.Option(
+        ..., prompt="API key", hide_input=True, help="Your Qualia API key"
+    ),
+    base_url: str | None = typer.Option(
+        None, help="API base URL (e.g. http://localhost:8000)"
+    ),
+) -> None:
+    """Save your API key (and optional base URL) for future use."""
+    try:
+        path = save_config(api_key, base_url)
+        typer.echo(f"Config saved to {path}")
+    except OSError as e:
+        print_error(f"Could not write config: {e}")
+        raise SystemExit(1) from e
+
+
+@app.command("status")
+def status() -> None:
+    """Check current authentication config."""
+    cfg = load_config()
+    if cfg.api_key:
+        typer.echo(f"API key: {cfg.api_key[:8]}...")
+    else:
+        typer.echo("Not authenticated. Run: qualia auth login")
+        raise SystemExit(1)
+    if cfg.base_url:
+        typer.echo(f"Base URL: {cfg.base_url}")
+    else:
+        typer.echo("Base URL: https://api.qualiastudios.dev (default)")

qualia_cli-0.1.0/src/qualia_cli/commands/credits.py

@@ -0,0 +1,21 @@
+"""Credits commands."""
+
+from __future__ import annotations
+
+import typer
+
+from qualia_cli.client import get_client
+from qualia_cli.output import print_json
+
+app = typer.Typer(help="View credit balance.")
+
+
+@app.callback(invoke_without_command=True)
+def credits(json: bool = typer.Option(False, "--json", help="JSON output")) -> None:
+    """Show your current credit balance."""
+    client = get_client()
+    balance = client.credits.get()
+    if json:
+        print_json(balance)
+    else:
+        typer.echo(f"Credits: {balance.balance}")

qualia_cli-0.1.0/src/qualia_cli/commands/datasets.py

@@ -0,0 +1,85 @@
+"""Datasets commands."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+import typer
+
+from qualia_cli.client import get_client
+from qualia_cli.output import print_json, print_table
+
+app = typer.Typer(help="Dataset utilities.")
+
+
+@app.command("list")
+def list_datasets(
+    limit: int = typer.Option(20, "--limit", "-n", help="Page size (1-100)"),
+    cursor: str = typer.Option(None, "--cursor", help="Pagination cursor"),
+    sort: str = typer.Option(
+        "newest", "--sort", "-s", help="newest|oldest|updated|name"
+    ),
+    search: str = typer.Option(None, "--search", "-q", help="Search dataset path"),
+    subtype: str = typer.Option(
+        None, "--dataset-type", help="lerobot_v3 or sarm_progress"
+    ),
+    flow: str = typer.Option(None, "--flow", help="input or output"),
+    project_id: str = typer.Option(None, "--project", help="Filter by project ID"),
+    job_id: str = typer.Option(None, "--job", help="Filter by job ID"),
+    json: bool = typer.Option(False, "--json", help="JSON output"),
+) -> None:
+    """List datasets (paginated)."""
+    client = get_client()
+    page = client.datasets.list(
+        limit=limit,
+        cursor=cursor,
+        sort=sort,
+        search=search,
+        subtype=subtype,
+        flow=flow,
+        project_id=UUID(project_id) if project_id else None,
+        job_id=UUID(job_id) if job_id else None,
+    )
+    if json:
+        print_json(page)
+    else:
+        rows = [
+            {
+                "id": str(d.artifact_id)[:8],
+                "subtype": d.subtype,
+                "path": d.path,
+                "jobs": len(d.jobs),
+                "created": d.created_at.strftime("%Y-%m-%d"),
+            }
+            for d in page.items
+        ]
+        print_table(
+            rows,
+            [
+                ("id", "Dataset ID"),
+                ("subtype", "Subtype"),
+                ("path", "Path"),
+                ("jobs", "Jobs"),
+                ("created", "Created"),
+            ],
+        )
+        if page.page_info.has_next:
+            typer.echo(f"\nNext page: --cursor {page.page_info.end_cursor}")
+
+
+@app.command("get-image-keys")
+def get_image_keys(
+    dataset_id: str = typer.Argument(help="HuggingFace dataset ID"),
+    json: bool = typer.Option(False, "--json", help="JSON output"),
+) -> None:
+    """Get available image keys for camera mapping."""
+    client = get_client()
+    result = client.datasets.get_image_keys(dataset_id)
+    if json:
+        print_json(result)
+    else:
+        print_table(
+            [{"key": k} for k in result.image_keys],
+            [("key", "Image Key")],
+            title=f"Image keys for {result.dataset_id}",
+        )

qualia_cli-0.1.0/src/qualia_cli/commands/finetune.py

@@ -0,0 +1,200 @@
+"""Job commands."""
+
+from __future__ import annotations
+
+import json as json_mod
+
+import typer
+
+from qualia_cli.client import get_client
+from qualia_cli.output import console, print_error, print_json, print_table
+
+app = typer.Typer(help="Manage fine-tuning jobs.")
+
+
+@app.command("list")
+def list_jobs(
+    limit: int = typer.Option(20, "--limit", "-n", help="Page size (1-100)"),
+    cursor: str = typer.Option(None, "--cursor", help="Pagination cursor"),
+    sort: str = typer.Option("newest", "--sort", "-s", help="newest|oldest|updated"),
+    search: str = typer.Option(None, "--search", "-q", help="Search job description"),
+    project_id: str = typer.Option(None, "--project", help="Filter by project ID"),
+    vla_type: str = typer.Option(None, "--vla-type", help="Filter by VLA type"),
+    job_type: str = typer.Option(None, "--job-type", help="vla|reward|vla_w_reward"),
+    use_json: bool = typer.Option(False, "--json", help="JSON output"),
+) -> None:
+    """List fine-tuning jobs (paginated)."""
+    client = get_client()
+    page = client.jobs.list(
+        limit=limit,
+        cursor=cursor,
+        sort=sort,
+        project_id=project_id,
+        vla_type=vla_type,
+        job_type=job_type,
+        search=search,
+    )
+    if use_json:
+        print_json(page)
+    else:
+        rows = [
+            {
+                "job_id": str(j.job_id)[:8],
+                "desc": j.job_desc or "",
+                "phase": j.current_phase or "",
+                "vla": j.vla_type or "",
+                "model": j.model or "",
+                "dataset": j.dataset or "",
+                "created": j.created_at.strftime("%Y-%m-%d") if j.created_at else "",
+            }
+            for j in page.items
+        ]
+        print_table(
+            rows,
+            [
+                ("job_id", "Job ID"),
+                ("desc", "Description"),
+                ("phase", "Phase"),
+                ("vla", "VLA Type"),
+                ("model", "Model"),
+                ("dataset", "Dataset"),
+                ("created", "Created"),
+            ],
+        )
+        if page.page_info.has_next:
+            typer.echo(f"\nNext page: --cursor {page.page_info.end_cursor}")
+
+
+@app.command("launch")
+def launch(
+    project_id: str = typer.Option(..., help="Project ID"),
+    vla_type: str = typer.Option(
+        ..., help="VLA type (act, smolvla, pi0, pi05, gr00t_n1_5)"
+    ),
+    dataset_id: str = typer.Option(..., help="HuggingFace dataset ID"),
+    hours: float = typer.Option(..., help="Training hours"),
+    camera_mappings: str = typer.Option(
+        ...,
+        help='Camera mappings as JSON, e.g. \'{"cam_1": "observation.images.top"}\'',
+    ),
+    model_id: str | None = typer.Option(
+        None, help="HuggingFace model ID (required for smolvla, pi0, pi05)"
+    ),
+    instance_type: str | None = typer.Option(None, help="GPU instance type"),
+    region: str | None = typer.Option(None, help="Cloud region"),
+    batch_size: int = typer.Option(32, help="Training batch size"),
+    name: str | None = typer.Option(None, help="Job name"),
+    hyper_spec: str | None = typer.Option(None, help="Custom hyperparams as JSON"),
+    use_json: bool = typer.Option(False, "--json", help="JSON output"),
+) -> None:
+    """Launch a new fine-tuning job."""
+    try:
+        cam_map = json_mod.loads(camera_mappings)
+    except json_mod.JSONDecodeError as e:
+        print_error("Invalid JSON for --camera-mappings")
+        raise SystemExit(1) from e
+
+    kwargs: dict = {
+        "project_id": project_id,
+        "vla_type": vla_type,
+        "dataset_id": dataset_id,
+        "hours": hours,
+        "camera_mappings": cam_map,
+        "batch_size": batch_size,
+    }
+    if model_id:
+        kwargs["model_id"] = model_id
+    if instance_type:
+        kwargs["instance_type"] = instance_type
+    if region:
+        kwargs["region"] = region
+    if name:
+        kwargs["name"] = name
+    if hyper_spec:
+        try:
+            kwargs["vla_hyper_spec"] = json_mod.loads(hyper_spec)
+        except json_mod.JSONDecodeError as e:
+            print_error("Invalid JSON for --hyper-spec")
+            raise SystemExit(1) from e
+
+    client = get_client()
+    job = client.finetune.create(**kwargs)
+    if use_json:
+        print_json(job)
+    else:
+        typer.echo(f"Job launched: {job.job_id} (status: {job.status})")
+
+
+@app.command("get")
+def get_status(
+    job_id: str = typer.Argument(help="Job ID"),
+    use_json: bool = typer.Option(False, "--json", help="JSON output"),
+) -> None:
+    """Get job status."""
+    client = get_client()
+    status = client.finetune.get(job_id)
+    if use_json:
+        print_json(status)
+    else:
+        console.print(f"[bold]Job:[/bold] {status.job_id}")
+        console.print(f"[bold]Status:[/bold] {status.status}")
+        console.print(f"[bold]Phase:[/bold] {status.current_phase}")
+        if status.instance_type:
+            console.print(f"[bold]Instance:[/bold] {status.instance_type}")
+        if status.region:
+            console.print(f"[bold]Region:[/bold] {status.region}")
+        if status.phases:
+            console.print()
+            rows = [
+                {
+                    "name": p.name,
+                    "status": p.status,
+                    "started": str(p.started_at or "-"),
+                    "completed": str(p.completed_at or "-"),
+                    "error": p.error or "",
+                }
+                for p in status.phases
+            ]
+            print_table(
+                rows,
+                [
+                    ("name", "Phase"),
+                    ("status", "Status"),
+                    ("started", "Started"),
+                    ("completed", "Completed"),
+                    ("error", "Error"),
+                ],
+            )
+
+
+@app.command("cancel")
+def cancel(
+    job_id: str = typer.Argument(help="Job ID to cancel"),
+    use_json: bool = typer.Option(False, "--json", help="JSON output"),
+) -> None:
+    """Cancel a job."""
+    client = get_client()
+    result = client.finetune.cancel(job_id)
+    if use_json:
+        print_json(result)
+    else:
+        if result.cancelled:
+            typer.echo(f"Cancelled job {result.job_id}")
+        else:
+            typer.echo(f"Could not cancel job {result.job_id}: {result.message}")
+
+
+@app.command("hyperparams")
+def hyperparams(
+    vla_type: str = typer.Argument(help="VLA type"),
+    model_id: str | None = typer.Option(
+        None, help="Model ID for type-specific defaults"
+    ),
+) -> None:
+    """Show default hyperparameters for a VLA type."""
+    client = get_client()
+    defaults = client.finetune.get_hyperparams_defaults(
+        vla_type=vla_type,
+        model_id=model_id,
+    )
+    print_json(defaults)