sparki-cli 1.0.0__py3-none-any.whl

sparki/__init__.py

@@ -0,0 +1,5 @@
+"""Sparki — video editor CLI."""
+
+from importlib.metadata import version
+
+__version__ = version("sparki-cli")

sparki/cli.py

@@ -0,0 +1,720 @@
+"""CLI entry point — all sparki subcommands."""
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Annotated, Any, Optional
+
+import httpx
+import typer
+
+from sparki.client import SparkiClient
+from sparki.config import Config, DEFAULT_CONFIG_DIR
+from sparki.constants import (
+    ALLOWED_EXTENSIONS,
+    MAX_FILES_PER_UPLOAD,
+    MAX_UPLOAD_SIZE,
+    EditMode,
+    VALID_DURATION_RANGES,
+    TELEGRAM_FILE_SIZE_LIMIT,
+    validate_style,
+    style_to_payload,
+    DEFAULT_ASSET_POLL_INTERVAL,
+    DEFAULT_ASSET_POLL_TIMEOUT,
+    DEFAULT_PROJECT_POLL_INTERVAL,
+    DEFAULT_PROJECT_POLL_TIMEOUT,
+)
+from sparki.output import log, print_error, print_success
+
+app = typer.Typer(add_completion=False)
+
+
+def get_config_dir() -> Path:
+    """Return the config directory path."""
+    return DEFAULT_CONFIG_DIR
+
+
+def _load_config() -> Config:
+    """Load configuration from the config directory."""
+    return Config(config_dir=get_config_dir())
+
+
+def _require_auth() -> tuple[Config, SparkiClient] | None:
+    """Load config and return (Config, SparkiClient), or print AUTH_FAILED and return None."""
+    cfg = _load_config()
+    if not cfg.api_key:
+        print_error("AUTH_FAILED")
+        return None
+    client = SparkiClient(base_url=cfg.base_url, api_key=cfg.api_key)
+    return cfg, client
+
+
+def _validate_files(files: list[Path]) -> list[Path] | None:
+    """Validate file existence, format, and size. Returns list or None on error."""
+    if len(files) > MAX_FILES_PER_UPLOAD:
+        print_error("UPLOAD_FAILED", f"Too many files: max {MAX_FILES_PER_UPLOAD} allowed, got {len(files)}")
+        return None
+    for f in files:
+        if not f.exists():
+            print_error("UPLOAD_FAILED", f"File not found: {f}")
+            return None
+        ext = f.suffix.lstrip(".").lower()
+        if ext not in ALLOWED_EXTENSIONS:
+            print_error("INVALID_FILE_FORMAT")
+            return None
+        if f.stat().st_size > MAX_UPLOAD_SIZE:
+            print_error("FILE_TOO_LARGE")
+            return None
+    return files
+
+
+def _history_file() -> Path:
+    """Return the path to the local project history file."""
+    return get_config_dir() / "sparki_history.json"
+
+
+def _load_history() -> list[dict]:
+    """Load locally tracked project IDs."""
+    hf = _history_file()
+    if hf.exists():
+        return json.loads(hf.read_text())
+    return []
+
+
+def _lookup_mode(task_id: str) -> str | None:
+    """Look up the edit mode for a task_id from local history."""
+    for entry in _load_history():
+        if entry.get("task_id") == task_id:
+            return entry.get("mode")
+    return None
+
+
+async def _get_status_by_mode(client, task_id: str) -> dict:
+    """Call the correct status endpoint based on the project's mode."""
+    mode = _lookup_mode(task_id)
+    if mode == EditMode.STYLE_CLONE:
+        return await client.get_emulate_project_status(task_id)
+    return await client.get_project_status(task_id)
+
+
+def _save_project(task_id: str, mode: str = "", style: str = "") -> None:
+    """Track a project ID locally for history lookups."""
+    from datetime import datetime, timezone
+    history = _load_history()
+    history.insert(0, {
+        "task_id": task_id,
+        "mode": mode,
+        "style": style,
+        "created_at": datetime.now(timezone.utc).isoformat(),
+    })
+    history = history[:100]
+    hf = _history_file()
+    hf.parent.mkdir(parents=True, exist_ok=True)
+    hf.write_text(json.dumps(history, indent=2))
+
+
+def _extract_result_url(data: dict[str, Any]) -> str | None:
+    """Extract result URL from project status response data."""
+    materials = data.get("materials", data.get("outputResultAssets",
+                data.get("output_result_assets", [])))
+    if not materials:
+        return None
+    item = materials[0]
+    if isinstance(item, dict):
+        return (item.get("url") or item.get("download_url")
+                or item.get("downloadUrl"))
+    if isinstance(item, str):
+        return item
+    return None
+
+
+def _run_async(coro_fn):
+    """Run an async function, catching httpx errors as NETWORK_ERROR."""
+    try:
+        asyncio.run(coro_fn())
+    except (httpx.HTTPError, httpx.StreamError) as e:
+        print_error("NETWORK_ERROR", str(e))
+
+
+async def _upload_and_poll_asset(
+    client: SparkiClient,
+    file_path: Path,
+    label: str = "",
+) -> str | None:
+    """Upload a file and poll until processed. Returns object_key or None on failure."""
+    import time
+
+    display = label or file_path.name
+    log(f"Uploading {display}...")
+    resp = await client.upload_asset(file_path)
+    if resp.get("code") != 200:
+        print_error("UPLOAD_FAILED", resp.get("message"))
+        return None
+    object_key = resp["data"]["object_key"]
+
+    log(f"Waiting for processing: {object_key}")
+    start = time.monotonic()
+    while True:
+        if time.monotonic() - start >= DEFAULT_ASSET_POLL_TIMEOUT:
+            print_error("RENDER_TIMEOUT", "Asset processing timed out")
+            return None
+        try:
+            status_resp = await client.get_asset_status(object_key)
+        except httpx.HTTPError as exc:
+            log(f"Asset status check failed ({exc}), retrying...")
+            await asyncio.sleep(DEFAULT_ASSET_POLL_INTERVAL)
+            continue
+        asset_status = (status_resp.get("data", {}).get("status")
+                        if status_resp.get("data") else None)
+        if asset_status == 1:
+            return object_key
+        if asset_status == -2:
+            print_error("UPLOAD_FAILED", f"Asset processing failed: {object_key}")
+            return None
+        await asyncio.sleep(DEFAULT_ASSET_POLL_INTERVAL)
+
+
+@app.command()
+def setup(
+    api_key: Annotated[str, typer.Option("--api-key", help="Your Sparki API key")],
+    base_url: Annotated[Optional[str], typer.Option("--base-url", help="Override the Sparki API base URL")] = None,
+) -> None:
+    """Save API key and validate it against the Sparki backend."""
+
+    async def _run() -> None:
+        cfg = _load_config()
+        effective_base_url = base_url or cfg.base_url
+        client = SparkiClient(base_url=effective_base_url, api_key=api_key)
+        valid = await client.validate_key()
+        if not valid:
+            print_error("AUTH_FAILED")
+            return
+        cfg.save(api_key=api_key, base_url=base_url)
+        log("Welcome to Sparki! Configuration saved.")
+        print_success({"message": "API key saved successfully",
+                        "config_dir": str(get_config_dir())})
+
+    _run_async(_run)
+
+
+@app.command()
+def upload(
+    file: Annotated[list[Path], typer.Option("--file", help="Video file(s) to upload")],
+) -> None:
+    """Upload one or more video files to Sparki."""
+
+    auth = _require_auth()
+    if auth is None:
+        return
+    _, client = auth
+
+    validated = _validate_files(file)
+    if validated is None:
+        return
+
+    async def _run() -> None:
+        assets = []
+        for f in validated:
+            log(f"Uploading {f.name}...")
+            resp = await client.upload_asset(f)
+            if resp.get("code") != 200:
+                print_error("UPLOAD_FAILED", resp.get("message"))
+                return
+            assets.append(resp["data"])
+        print_success({"assets": assets})
+
+    _run_async(_run)
+
+
+@app.command(name="upload-tg")
+def upload_tg() -> None:
+    """Return the configured Telegram upload link."""
+    auth = _require_auth()
+    if auth is None:
+        return
+    cfg, _ = auth
+    print_success({"upload_tg": cfg.upload_tg})
+
+
+@app.command()
+def assets(
+    limit: Annotated[int, typer.Option("--limit", help="Max number of assets to return")] = 20,
+) -> None:
+    """List uploaded assets."""
+
+    auth = _require_auth()
+    if auth is None:
+        return
+    _, client = auth
+
+    async def _run() -> None:
+        resp = await client.list_assets(page_size=limit)
+        if resp.get("code") != 200:
+            print_error("NETWORK_ERROR", resp.get("message"))
+            return
+        print_success(resp["data"])
+
+    _run_async(_run)
+
+
+@app.command()
+def edit(
+    object_key: Annotated[list[str], typer.Option("--object-key", help="Asset object key(s) to edit")],
+    mode: Annotated[str, typer.Option("--mode", help="Edit mode: style-guided, prompt-driven, style-clone")],
+    style: Annotated[Optional[str], typer.Option("--style", help="Style for style-guided mode (e.g. vlog/daily)")] = None,
+    prompt: Annotated[Optional[str], typer.Option("--prompt", help="Text prompt for prompt-driven or style-clone mode")] = None,
+    aspect_ratio: Annotated[str, typer.Option("--aspect-ratio", help="Output aspect ratio")] = "9:16",
+    duration_range: Annotated[Optional[str], typer.Option("--duration-range", help="Duration range (e.g. 30s~60s)")] = None,
+    reference_url: Annotated[Optional[str], typer.Option("--reference-url", help="Reference video URL (TikTok, Instagram, X, Facebook)")] = None,
+    reference_file: Annotated[Optional[Path], typer.Option("--reference-file", help="Local reference video file")] = None,
+    reference_tg: Annotated[bool, typer.Option("--reference-tg", help="Get Telegram upload link for reference video")] = False,
+) -> None:
+    """Create a new edit project for uploaded assets."""
+
+    auth = _require_auth()
+    if auth is None:
+        return
+    cfg, client = auth
+
+    if duration_range and duration_range not in VALID_DURATION_RANGES:
+        print_error("INVALID_MODE", f"Invalid duration range: {duration_range}")
+        return
+
+    # Cross-mode validation
+    ref_count = sum([bool(reference_url), bool(reference_file), reference_tg])
+    if mode == EditMode.STYLE_CLONE:
+        if ref_count != 1:
+            print_error("INVALID_REFERENCE")
+            return
+        if style:
+            print_error("INVALID_MODE", "--style is not used with style-clone mode")
+            return
+        if duration_range:
+            print_error("INVALID_MODE", "--duration-range is not supported for style-clone mode")
+            return
+    else:
+        if ref_count > 0:
+            print_error("INVALID_MODE", "--reference-* options are only for style-clone mode")
+            return
+
+    if mode == EditMode.STYLE_GUIDED:
+        if not style or not validate_style(style):
+            print_error("INVALID_STYLE")
+            return
+        payload = style_to_payload(style)
+        tags = payload["tags"]
+        agent_type = payload["agent_type"]
+        user_input = prompt or payload.get("default_prompt", "")
+    elif mode == EditMode.PROMPT_DRIVEN:
+        if not prompt:
+            print_error("INVALID_MODE")
+            return
+        tags = []
+        agent_type = None
+        user_input = prompt
+    elif mode == EditMode.STYLE_CLONE:
+        user_input = prompt or ""
+
+        # --reference-tg: return upload link, no project created
+        if reference_tg:
+            print_success({
+                "action": "upload_reference_via_telegram",
+                "upload_tg": cfg.upload_tg,
+                "message": "Please ask the user to upload their reference video via the Telegram Mini App.",
+            })
+            return
+
+        async def _run_clone() -> None:
+            ref_key = None
+            ref_url = None
+
+            if reference_file:
+                validated = _validate_files([reference_file])
+                if validated is None:
+                    return
+                ref_key = await _upload_and_poll_asset(
+                    client, reference_file,
+                    label=f"reference video: {reference_file.name}",
+                )
+                if ref_key is None:
+                    return
+            elif reference_url:
+                ref_url = reference_url
+
+            resp = await client.create_emulate_project(
+                source_object_keys=object_key,
+                reference_object_key=ref_key,
+                reference_url=ref_url,
+                user_input=user_input,
+                aspect_ratio=aspect_ratio,
+            )
+            if resp.get("code") != 200:
+                print_error("NETWORK_ERROR", resp.get("message"))
+                return
+            data = resp["data"]
+            task_id = data.get("task_id", data.get("taskId", ""))
+            _save_project(task_id, mode=mode, style="")
+            print_success(data)
+
+        _run_async(_run_clone)
+        return
+    else:
+        print_error("INVALID_MODE")
+        return
+
+    # Existing style-guided / prompt-driven flow (unchanged)
+    async def _run() -> None:
+        resp = await client.create_project(
+            object_keys=object_key,
+            tags=tags,
+            user_input=user_input,
+            aspect_ratio=aspect_ratio,
+            agent_type=agent_type,
+            duration_range=duration_range,
+        )
+        if resp.get("code") != 200:
+            print_error("NETWORK_ERROR", resp.get("message"))
+            return
+        data = resp["data"]
+        task_id = data.get("task_id", data.get("taskId", ""))
+        _save_project(task_id, mode=mode, style=style or "")
+        print_success(data)
+
+    _run_async(_run)
+
+
+@app.command()
+def status(
+    task_id: Annotated[str, typer.Option("--task-id", help="Project ID to check")],
+) -> None:
+    """Check the status of an edit project."""
+
+    auth = _require_auth()
+    if auth is None:
+        return
+    _, client = auth
+
+    async def _run() -> None:
+        resp = await _get_status_by_mode(client, task_id)
+        if resp.get("code") != 200:
+            print_error("TASK_NOT_FOUND", resp.get("message"))
+            return
+        print_success(resp["data"])
+
+    _run_async(_run)
+
+
+@app.command()
+def download(
+    task_id: Annotated[str, typer.Option("--task-id", help="Project ID to download")],
+    output: Annotated[Optional[Path], typer.Option("--output", help="Output file path")] = None,
+) -> None:
+    """Download the result of a completed edit project."""
+
+    auth = _require_auth()
+    if auth is None:
+        return
+    cfg, client = auth
+
+    async def _run() -> None:
+        resp = await _get_status_by_mode(client, task_id)
+        if resp.get("code") != 200:
+            print_error("TASK_NOT_FOUND", resp.get("message"))
+            return
+        data = resp["data"]
+        task_status = data.get("status", "").upper()
+        if task_status != "COMPLETED":
+            print_error("TASK_NOT_FOUND",
+                        f"Project {task_id} is not completed (status: {data.get('status')})")
+            return
+        result_url = _extract_result_url(data)
+        if not result_url:
+            print_error("NETWORK_ERROR", "No result URL available")
+            return
+        out_path = output or cfg.default_output_dir / f"{task_id}.mp4"
+        file_size = await client.download_result(result_url, out_path)
+        delivery_hint = ("telegram_direct" if file_size <= TELEGRAM_FILE_SIZE_LIMIT
+                         else "link_only")
+        print_success({
+            "task_id": task_id,
+            "file_path": str(out_path),
+            "file_size": file_size,
+            "result_url": result_url,
+            "delivery_hint": delivery_hint,
+        })
+
+    _run_async(_run)
+
+
+@app.command()
+def history(
+    limit: Annotated[int, typer.Option("--limit", help="Number of projects to return")] = 20,
+    status: Annotated[Optional[str], typer.Option("--status", help="Filter by status (or 'all')")] = "all",
+) -> None:
+    """List recent edit projects."""
+
+    auth = _require_auth()
+    if auth is None:
+        return
+    _, client = auth
+
+    async def _run() -> None:
+        local_history = _load_history()
+        if not local_history:
+            print_success({"projects": [], "total": 0})
+            return
+        entries = local_history[:limit]
+        projects = []
+        for entry in entries:
+            tid = entry["task_id"]
+            resp = await _get_status_by_mode(client, tid)
+            if resp.get("code") == 200:
+                projects.append(resp["data"])
+
+        if status and status != "all":
+            projects = [p for p in projects
+                        if p.get("status", "").upper() == status.upper()]
+
+        print_success({"projects": projects, "total": len(projects)})
+
+    _run_async(_run)
+
+
+@app.command()
+def run(
+    file: Annotated[list[Path], typer.Option("--file", help="Video file(s) to upload and edit")],
+    mode: Annotated[str, typer.Option("--mode", help="Edit mode: style-guided, prompt-driven, style-clone")],
+    style: Annotated[Optional[str], typer.Option("--style", help="Style for style-guided mode")] = None,
+    prompt: Annotated[Optional[str], typer.Option("--prompt", help="Text prompt for prompt-driven mode")] = None,
+    aspect_ratio: Annotated[str, typer.Option("--aspect-ratio", help="Output aspect ratio")] = "9:16",
+    duration_range: Annotated[Optional[str], typer.Option("--duration-range", help="Duration range")] = None,
+    output: Annotated[Optional[Path], typer.Option("--output", help="Output file path")] = None,
+    poll_interval: Annotated[int, typer.Option("--poll-interval", help="Seconds between project status polls")] = DEFAULT_PROJECT_POLL_INTERVAL,
+    timeout: Annotated[int, typer.Option("--timeout", help="Max seconds to wait for completion")] = DEFAULT_PROJECT_POLL_TIMEOUT,
+    reference_url: Annotated[Optional[str], typer.Option("--reference-url", help="Reference video URL (TikTok, Instagram, X, Facebook)")] = None,
+    reference_file: Annotated[Optional[Path], typer.Option("--reference-file", help="Local reference video file")] = None,
+    reference_tg: Annotated[bool, typer.Option("--reference-tg", help="Not available in run")] = False,
+) -> None:
+    """End-to-end workflow: upload -> edit -> poll -> download."""
+
+    auth = _require_auth()
+    if auth is None:
+        return
+    cfg, client = auth
+
+    # Cross-mode validation
+    ref_count = sum([bool(reference_url), bool(reference_file), reference_tg])
+    if mode == EditMode.STYLE_CLONE:
+        if reference_tg:
+            print_error("INVALID_MODE", "--reference-tg is not available in run command")
+            return
+        if ref_count != 1:
+            print_error("INVALID_REFERENCE")
+            return
+        if style:
+            print_error("INVALID_MODE", "--style is not used with style-clone mode")
+            return
+        if duration_range:
+            print_error("INVALID_MODE", "--duration-range is not supported for style-clone mode")
+            return
+    else:
+        if ref_count > 0:
+            print_error("INVALID_MODE", "--reference-* options are only for style-clone mode")
+            return
+
+    # Validate duration range
+    if duration_range and duration_range not in VALID_DURATION_RANGES:
+        print_error("INVALID_MODE", f"Invalid duration range: {duration_range}")
+        return
+
+    # Validate mode/style
+    if mode == EditMode.STYLE_GUIDED:
+        if not style or not validate_style(style):
+            print_error("INVALID_STYLE")
+            return
+        payload = style_to_payload(style)
+        tags = payload["tags"]
+        agent_type = payload["agent_type"]
+        user_input = prompt or payload.get("default_prompt", "")
+    elif mode == EditMode.PROMPT_DRIVEN:
+        if not prompt:
+            print_error("INVALID_MODE")
+            return
+        tags = []
+        agent_type = None
+        user_input = prompt
+    elif mode == EditMode.STYLE_CLONE:
+        user_input = prompt or ""
+    else:
+        print_error("INVALID_MODE")
+        return
+
+    validated = _validate_files(file)
+    if validated is None:
+        return
+
+    if reference_file:
+        ref_validated = _validate_files([reference_file])
+        if ref_validated is None:
+            return
+
+    if mode == EditMode.STYLE_CLONE:
+        async def _run_clone() -> None:
+            import time
+
+            # Step 1: Upload source files
+            object_keys = []
+            for f in validated:
+                key = await _upload_and_poll_asset(client, f, label=f"source video: {f.name}")
+                if key is None:
+                    return
+                object_keys.append(key)
+
+            # Step 2: Handle reference video
+            ref_key = None
+            ref_url = None
+            if reference_file:
+                ref_key = await _upload_and_poll_asset(
+                    client, reference_file, label=f"reference video: {reference_file.name}")
+                if ref_key is None:
+                    return
+            elif reference_url:
+                ref_url = reference_url
+
+            # Step 3: Create emulate project
+            log("Creating style-clone project...")
+            proj_resp = await client.create_emulate_project(
+                source_object_keys=object_keys,
+                reference_object_key=ref_key,
+                reference_url=ref_url,
+                user_input=user_input,
+                aspect_ratio=aspect_ratio,
+            )
+            if proj_resp.get("code") != 200:
+                print_error("NETWORK_ERROR", proj_resp.get("message"))
+                return
+            data = proj_resp["data"]
+            task_id = data.get("task_id", data.get("taskId", ""))
+            _save_project(task_id, mode=mode, style="")
+
+            # Step 4: Poll for completion
+            proj_start = time.monotonic()
+            while True:
+                elapsed = time.monotonic() - proj_start
+                if elapsed >= timeout:
+                    print_error("RENDER_TIMEOUT")
+                    return
+                try:
+                    status_resp = await client.get_emulate_project_status(task_id)
+                except httpx.HTTPError as exc:
+                    log(f"Project status check failed ({exc}), retrying...")
+                    await asyncio.sleep(poll_interval)
+                    continue
+                if status_resp.get("code") != 200:
+                    print_error("TASK_NOT_FOUND", status_resp.get("message"))
+                    return
+                proj_data = status_resp["data"]
+                task_status = proj_data.get("status", "")
+                log(f"Project {task_id} status: {task_status}")
+                if task_status.upper() == "COMPLETED":
+                    break
+                if task_status.upper() in ("FAILED", "CANCEL"):
+                    print_error("NETWORK_ERROR", f"Project failed: {task_id}")
+                    return
+                await asyncio.sleep(poll_interval)
+
+            # Step 5: Download result
+            result_url = _extract_result_url(proj_data)
+            if not result_url:
+                print_error("NETWORK_ERROR", "No result URL available")
+                return
+            out_path = output or cfg.default_output_dir / f"{task_id}.mp4"
+            file_size = await client.download_result(result_url, out_path)
+            delivery_hint = ("telegram_direct" if file_size <= TELEGRAM_FILE_SIZE_LIMIT
+                             else "link_only")
+            print_success({
+                "task_id": task_id,
+                "status": task_status,
+                "file_path": str(out_path),
+                "file_size": file_size,
+                "result_url": result_url,
+                "delivery_hint": delivery_hint,
+            })
+
+        _run_async(_run_clone)
+        return
+
+    async def _run() -> None:
+        import time
+
+        # Step 1: Upload all files
+        object_keys = []
+        for f in validated:
+            key = await _upload_and_poll_asset(client, f)
+            if key is None:
+                return
+            object_keys.append(key)
+
+        # Step 2: Create project
+        log("Creating edit project...")
+        proj_resp = await client.create_project(
+            object_keys=object_keys,
+            tags=tags,
+            user_input=user_input,
+            aspect_ratio=aspect_ratio,
+            agent_type=agent_type,
+            duration_range=duration_range,
+        )
+        if proj_resp.get("code") != 200:
+            print_error("NETWORK_ERROR", proj_resp.get("message"))
+            return
+        data = proj_resp["data"]
+        task_id = data.get("task_id", data.get("taskId", ""))
+        _save_project(task_id, mode=mode, style=style or "")
+
+        # Step 3: Poll for project completion
+        proj_start = time.monotonic()
+        while True:
+            elapsed = time.monotonic() - proj_start
+            if elapsed >= timeout:
+                print_error("RENDER_TIMEOUT")
+                return
+            try:
+                status_resp = await client.get_project_status(task_id)
+            except httpx.HTTPError as exc:
+                log(f"Project status check failed ({exc}), retrying...")
+                await asyncio.sleep(poll_interval)
+                continue
+            if status_resp.get("code") != 200:
+                print_error("TASK_NOT_FOUND", status_resp.get("message"))
+                return
+            proj_data = status_resp["data"]
+            task_status = proj_data.get("status", "")
+            log(f"Project {task_id} status: {task_status}")
+            if task_status.upper() in ("COMPLETED",):
+                break
+            if task_status.upper() in ("FAILED", "CANCEL"):
+                print_error("NETWORK_ERROR", f"Project failed: {task_id}")
+                return
+            await asyncio.sleep(poll_interval)
+
+        # Step 4: Download result
+        result_url = _extract_result_url(proj_data)
+        if not result_url:
+            print_error("NETWORK_ERROR", "No result URL available")
+            return
+        out_path = output or cfg.default_output_dir / f"{task_id}.mp4"
+        file_size = await client.download_result(result_url, out_path)
+        delivery_hint = ("telegram_direct" if file_size <= TELEGRAM_FILE_SIZE_LIMIT
+                         else "link_only")
+
+        print_success({
+            "task_id": task_id,
+            "status": task_status,
+            "file_path": str(out_path),
+            "file_size": file_size,
+            "result_url": result_url,
+            "delivery_hint": delivery_hint,
+        })
+
+    _run_async(_run)

sparki/client.py

@@ -0,0 +1,135 @@
+"""HTTP API client wrapping all Sparki C-end API endpoints."""
+
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+
+class SparkiClient:
+    def __init__(self, base_url: str, api_key: str):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self._headers = {"X-API-Key": api_key}
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}{path}"
+
+    async def validate_key(self) -> bool:
+        async with httpx.AsyncClient() as c:
+            resp = await c.get(self._url("/api/v1/account/info"),
+                               headers=self._headers)
+            return resp.status_code == 200
+
+    async def upload_asset(self, file_path: Path) -> dict[str, Any]:
+        async with httpx.AsyncClient(timeout=300) as c:
+            with open(file_path, "rb") as f:
+                files = {"file": (file_path.name, f,
+                                  f"video/{file_path.suffix.lstrip('.').lower()}")}
+                resp = await c.post(self._url("/api/v1/assets/upload"),
+                                    headers=self._headers, files=files)
+            return resp.json()
+
+    async def list_assets(self, page: int = 1, page_size: int = 20) -> dict[str, Any]:
+        params: dict[str, Any] = {"page": page, "page_size": page_size}
+        async with httpx.AsyncClient() as c:
+            resp = await c.get(self._url("/api/v1/assets/user_assets"),
+                               headers=self._headers, params=params)
+            return resp.json()
+
+    async def get_asset_status(self, object_key: str) -> dict[str, Any]:
+        page = 1
+        page_size = 50
+        while True:
+            result = await self.list_assets(page=page, page_size=page_size)
+            data = result.get("data", {})
+            items = data.get("assets", data.get("items", []))
+            for item in items:
+                if item.get("object_key") == object_key or item.get("objectKey") == object_key:
+                    return {"code": result.get("code"), "data": item}
+            if len(items) < page_size:
+                break
+            page += 1
+        return {"code": result.get("code"), "data": None}
+
+    async def create_project(
+        self,
+        object_keys: list[str],
+        tags: list[str],
+        user_input: str = "",
+        aspect_ratio: str = "9:16",
+        agent_type: str | None = None,
+        duration_range: str | None = None,
+    ) -> dict[str, Any]:
+        resources = [{"idx": i, "s3_object_key": key}
+                     for i, key in enumerate(object_keys)]
+        body: dict[str, Any] = {
+            "resources": resources,
+            "user_input": user_input,
+            "generation_preferences": {"aspect_ratio": aspect_ratio},
+            "send_after_create": True,
+        }
+        if tags:
+            body["tags"] = tags
+        if agent_type:
+            body["agent_type"] = agent_type
+        if duration_range:
+            body["generation_preferences"]["duration_range"] = duration_range
+        async with httpx.AsyncClient() as c:
+            resp = await c.post(self._url("/api/v1/projects/"),
+                                headers=self._headers, json=body)
+            return resp.json()
+
+    async def get_project_status(self, task_id: str) -> dict[str, Any]:
+        async with httpx.AsyncClient() as c:
+            resp = await c.get(self._url(f"/api/v1/projects/task/{task_id}"),
+                               headers=self._headers)
+            return resp.json()
+
+    async def create_emulate_project(
+        self,
+        source_object_keys: list[str],
+        reference_object_key: str | None = None,
+        reference_url: str | None = None,
+        user_input: str = "",
+        aspect_ratio: str = "9:16",
+    ) -> dict[str, Any]:
+        ref: dict[str, Any] = {"idx": 0, "media_type": "video"}
+        if reference_object_key:
+            ref["s3_object_key"] = reference_object_key
+        elif reference_url:
+            ref["video_url"] = reference_url
+
+        sources = [{"idx": i, "s3_object_key": key, "media_type": "video"}
+                   for i, key in enumerate(source_object_keys)]
+
+        body: dict[str, Any] = {
+            "reference_resource": [ref],
+            "resources": sources,
+            "user_input": user_input,
+            "send_after_create": True,
+            "generation_preferences": {"aspect_ratio": aspect_ratio},
+        }
+        async with httpx.AsyncClient() as c:
+            resp = await c.post(self._url("/api/v1/emulate/projects/"),
+                                headers=self._headers, json=body)
+            return resp.json()
+
+    async def get_emulate_project_status(self, task_id: str) -> dict[str, Any]:
+        async with httpx.AsyncClient() as c:
+            resp = await c.get(
+                self._url(f"/api/v1/emulate/projects/task/{task_id}"),
+                headers=self._headers)
+            return resp.json()
+
+    async def download_result(self, url: str, output_path: Path) -> int:
+        async with httpx.AsyncClient(timeout=600, follow_redirects=True) as c:
+            async with c.stream("GET", url) as resp:
+                resp.raise_for_status()
+                output_path.parent.mkdir(parents=True, exist_ok=True)
+                total = 0
+                with open(output_path, "wb") as f:
+                    async for chunk in resp.aiter_bytes(chunk_size=1024 * 1024):
+                        f.write(chunk)
+                        total += len(chunk)
+                return total

sparki/config.py

@@ -0,0 +1,55 @@
+"""Configuration management — API key, base URL, output directory."""
+
+import json
+import os
+from pathlib import Path
+
+from sparki.constants import DEFAULT_BASE_URL, DEFAULT_UPLOAD_TG_LINK
+
+DEFAULT_CONFIG_DIR = Path.home() / ".openclaw" / "config"
+
+
+class Config:
+    def __init__(self, config_dir: Path | None = None):
+        self.config_dir = config_dir or DEFAULT_CONFIG_DIR
+        self.config_file = self.config_dir / "sparki.json"
+        self._data: dict = {}
+        if self.config_file.exists():
+            self._data = json.loads(self.config_file.read_text())
+
+    @property
+    def api_key(self) -> str | None:
+        env_key = os.environ.get("SPARKI_API_KEY")
+        if env_key:
+            return env_key
+        return self._data.get("api_key")
+
+    @property
+    def base_url(self) -> str:
+        return self._data.get("base_url", DEFAULT_BASE_URL)
+
+    @property
+    def default_output_dir(self) -> Path:
+        configured = self._data.get("default_output_dir")
+        if configured:
+            return Path(configured).expanduser()
+        return Path.home() / ".openclaw" / "workspace" / "sparki" / "videos"
+
+    @property
+    def upload_tg(self) -> str:
+        env = os.environ.get("SPARKI_UPLOAD_TG_LINK")
+        if env:
+            return env
+        return self._data.get("upload_tg", DEFAULT_UPLOAD_TG_LINK)
+
+    def save(self, api_key: str | None = None, base_url: str | None = None, default_output_dir: str | None = None) -> None:
+        self.config_dir.mkdir(parents=True, exist_ok=True)
+        if api_key is not None:
+            self._data["api_key"] = api_key
+        if base_url is not None:
+            self._data["base_url"] = base_url
+        elif "base_url" not in self._data:
+            self._data["base_url"] = DEFAULT_BASE_URL
+        if default_output_dir is not None:
+            self._data["default_output_dir"] = default_output_dir
+        self.config_file.write_text(json.dumps(self._data, indent=2))

sparki/constants.py

@@ -0,0 +1,144 @@
+"""Edit modes, style catalog, error codes, and limit constants."""
+
+from enum import StrEnum
+
+
+class EditMode(StrEnum):
+    STYLE_GUIDED = "style-guided"
+    PROMPT_DRIVEN = "prompt-driven"
+    STYLE_CLONE = "style-clone"
+
+
+STYLE_CATALOG: dict[str, dict[str | None, dict]] = {
+    "vlog": {
+        "energetic-sports":   {"tags": ["19"], "agent_type": None},
+        "funny-commentary":   {"tags": ["20"], "agent_type": None},
+        "daily":              {"tags": ["21"], "agent_type": "vlog"},
+        "upbeat-energy":      {"tags": ["22"], "agent_type": None},
+        "chill-vibe":         {"tags": ["23"], "agent_type": "vlog"},
+    },
+    "montage": {
+        "highlight-reel":         {"tags": ["28"], "agent_type": None},
+        "hype-beatsync":          {"tags": ["29"], "agent_type": None},
+        "creative-splitscreen":   {"tags": ["30"], "agent_type": None},
+        "meme-moments":           {"tags": ["31"], "agent_type": None},
+    },
+    "commentary": {
+        "tiktok-trending-recap":  {"tags": ["24"], "agent_type": None},
+        "funny-commentary":       {"tags": ["25"], "agent_type": None},
+        "master-storyteller":     {"tags": ["26"], "agent_type": None},
+        "first-person-narration": {"tags": ["27"], "agent_type": None},
+    },
+    "talking-head": {
+        "tutorial":               {"tags": ["32"], "agent_type": None},
+        "podcast-interview":      {"tags": ["33"], "agent_type": None},
+        "product-review":         {"tags": ["34"], "agent_type": None},
+        "reaction-commentary":    {"tags": ["35"], "agent_type": None},
+    },
+    "long-to-short": {
+        None: {"tags": [], "agent_type": None,
+               "default_prompt": "Find hooks, highlights, and turn the video into viral shorts"},
+    },
+    "ai-caption": {
+        None: {"tags": [], "agent_type": None,
+               "default_prompt": "Add captions to the video"},
+    },
+    "video-resizer": {
+        None: {"tags": [], "agent_type": None,
+               "default_prompt": "Reframe the video for the target aspect ratio"},
+    },
+}
+
+VALID_DURATION_RANGES = {"<30s", "30s~60s", "60s~90s", ">90s", "custom"}
+
+TELEGRAM_FILE_SIZE_LIMIT = 100 * 1024 * 1024
+MAX_UPLOAD_SIZE = 3 * 1024 * 1024 * 1024
+ALLOWED_EXTENSIONS = {"mp4", "mov"}
+MAX_FILES_PER_UPLOAD = 10
+DEFAULT_ASSET_POLL_INTERVAL = 10
+DEFAULT_ASSET_POLL_TIMEOUT = 1200
+DEFAULT_PROJECT_POLL_INTERVAL = 30
+DEFAULT_PROJECT_POLL_TIMEOUT = 3600
+DEFAULT_BASE_URL = "https://agent-api.sparki.io"
+DEFAULT_UPLOAD_TG_LINK = "https://t.me/Sparki_AI_bot/upload"
+
+
+def validate_style(style: str) -> bool:
+    if not style:
+        return False
+    if "/" in style:
+        category, sub = style.split("/", 1)
+        return category in STYLE_CATALOG and sub in STYLE_CATALOG[category]
+    else:
+        return style in STYLE_CATALOG and None in STYLE_CATALOG[style]
+
+
+def style_to_payload(style: str) -> dict:
+    if "/" in style:
+        category, sub = style.split("/", 1)
+        return STYLE_CATALOG[category][sub]
+    else:
+        return STYLE_CATALOG[style][None]
+
+
+def all_styles_list() -> list[str]:
+    styles = []
+    for category, subs in STYLE_CATALOG.items():
+        for sub in subs:
+            if sub is None:
+                styles.append(category)
+            else:
+                styles.append(f"{category}/{sub}")
+    return styles
+
+
+ERROR_CODES: dict[str, dict[str, str]] = {
+    "AUTH_FAILED": {
+        "message": "Invalid or missing API key",
+        "action": "Run `sparki setup --api-key <key>` or get a key from @sparki_bot on Telegram",
+    },
+    "QUOTA_EXCEEDED": {
+        "message": "API quota exhausted",
+        "action": "Visit https://sparki.io/pricing to upgrade",
+    },
+    "FILE_TOO_LARGE": {
+        "message": "File exceeds 3GB limit",
+        "action": "Compress or trim the video before uploading",
+    },
+    "CONCURRENT_LIMIT": {
+        "message": "Too many projects running",
+        "action": "Wait for a running project to complete",
+    },
+    "INVALID_FILE_FORMAT": {
+        "message": "Unsupported file format",
+        "action": "Only mp4 and mov files are supported",
+    },
+    "INVALID_STYLE": {
+        "message": "Unknown style",
+        "action": "See available styles with `sparki edit --help`",
+    },
+    "INVALID_MODE": {
+        "message": "Unknown edit mode",
+        "action": "Choose from: style-guided, prompt-driven, style-clone",
+    },
+    "INVALID_REFERENCE": {
+        "message": "Reference video required for style-clone mode",
+        "action": "Provide --reference-url, --reference-file, or --reference-tg",
+    },
+    "UPLOAD_FAILED": {
+        "message": "Upload failed",
+        "action": "Check your network connection and try again",
+    },
+    "RENDER_TIMEOUT": {
+        "message": "Video processing timed out",
+        "action": "Try a shorter clip or increase --timeout",
+    },
+    "TASK_NOT_FOUND": {
+        "message": "Task not found",
+        "action": "Run `sparki history` to see your recent tasks",
+    },
+    "NETWORK_ERROR": {
+        "message": "Cannot reach Sparki servers",
+        "action": "Check your internet connection and try again",
+    },
+}

sparki/models.py

@@ -0,0 +1,59 @@
+"""Pydantic models for API responses and CLI output."""
+
+from pydantic import BaseModel, computed_field
+
+from sparki.constants import TELEGRAM_FILE_SIZE_LIMIT
+
+
+class AssetInfo(BaseModel):
+    object_key: str
+    file_name: str
+    status: int
+    file_size: int
+    is_duplicate: bool = False
+    duration: float | None = None
+    resolution: str | None = None
+
+
+class UploadResponse(BaseModel):
+    object_key: str
+    file_name: str
+    file_size: int
+    status: int
+    is_duplicate: bool = False
+
+
+class ProjectInfo(BaseModel):
+    task_id: str
+    status: str
+    created_at: str | None = None
+    result_url: str | None = None
+    thumbnail_url: str | None = None
+    duration: float | None = None
+    resolution: str | None = None
+    filesize: int | None = None
+
+
+class DownloadResult(BaseModel):
+    task_id: str
+    file_path: str
+    file_size: int
+    result_url: str
+
+    @computed_field
+    @property
+    def delivery_hint(self) -> str:
+        return "telegram_direct" if self.file_size <= TELEGRAM_FILE_SIZE_LIMIT else "link_only"
+
+
+class RunResult(BaseModel):
+    task_id: str
+    status: str
+    file_path: str
+    file_size: int
+    result_url: str
+
+    @computed_field
+    @property
+    def delivery_hint(self) -> str:
+        return "telegram_direct" if self.file_size <= TELEGRAM_FILE_SIZE_LIMIT else "link_only"

sparki/output.py

@@ -0,0 +1,42 @@
+"""Unified JSON output formatter for all CLI commands."""
+
+import json
+import sys
+from typing import Any
+
+from sparki.constants import ERROR_CODES
+
+
+def success(data: dict[str, Any]) -> str:
+    return json.dumps({"ok": True, "data": data, "error": None}, ensure_ascii=False)
+
+
+def format_error(code: str, message: str | None = None) -> dict[str, str]:
+    defaults = ERROR_CODES.get(code, {
+        "message": "An unexpected error occurred",
+        "action": "Please try again or contact support",
+    })
+    return {
+        "code": code,
+        "message": message or defaults["message"],
+        "action": defaults["action"],
+    }
+
+
+def error(code: str, message: str | None = None) -> str:
+    return json.dumps(
+        {"ok": False, "data": None, "error": format_error(code, message)},
+        ensure_ascii=False,
+    )
+
+
+def print_success(data: dict[str, Any]) -> None:
+    print(success(data))
+
+
+def print_error(code: str, message: str | None = None) -> None:
+    print(error(code, message))
+
+
+def log(msg: str) -> None:
+    print(msg, file=sys.stderr)

sparki_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: sparki-cli
+Version: 1.0.0
+Summary: Sparki video editor CLI
+Author: Sparki AI
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typer>=0.9.0
+Description-Content-Type: text/markdown
+
+# Sparki
+
+AI-powered video editing from the command line.
+
+## Installation
+
+```
+pip install sparki-cli
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```
+uv tool install sparki-cli
+```
+
+## Quick Start
+
+```bash
+# Save your API key
+sparki setup --api-key YOUR_KEY
+
+# Upload, edit, and download in one step
+sparki run --file video.mp4 --mode style-guided --style vlog/daily
+
+# Or step by step
+sparki upload --file video.mp4
+sparki edit --object-key KEY --mode prompt-driven --prompt "Make a highlight reel"
+sparki status --task-id TASK_ID
+sparki download --task-id TASK_ID
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `setup` | Save and validate your API key |
+| `upload` | Upload video files |
+| `assets` | List uploaded assets |
+| `edit` | Create an edit project |
+| `status` | Check project status |
+| `download` | Download completed result |
+| `run` | End-to-end: upload → edit → download |
+| `history` | List recent projects |
+
+## Edit Modes
+
+- **style-guided** — Choose from preset styles (e.g. `vlog/daily`, `montage/highlight-reel`)
+- **prompt-driven** — Describe what you want in natural language
+- **style-clone** — Clone the style of a reference video
+
+## Links
+
+- Website: https://sparki.io
+- Telegram: https://t.me/Sparki_AI_bot

sparki_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+sparki/__init__.py,sha256=ma_MWG7nIP75DiC8DoydG1CQPoQdRofU7uRTDyLAzMA,112
+sparki/cli.py,sha256=mq3-6xwwbTEq4sK9D2rZlEHzacw22LfaQqnHvQHWO_0,25968
+sparki/client.py,sha256=nZnrFd16ZWNxsRIc9p9k7kEREdUfmS7vt-RRmDdwCAk,5493
+sparki/config.py,sha256=-uDZUFA3W9uCijBsRGcVybZt2-suaFIS4BdoU1TQu88,1957
+sparki/constants.py,sha256=kNViOaP4VqwSEoFWh7QFBosjVuqyiVPqM7XUdKl2LRU,5119
+sparki/models.py,sha256=zY3yak-Gl3y25-80Ah1LFWcJRgruu_6IiUo93qdT1LE,1337
+sparki/output.py,sha256=lGTom-RhDr2PV-UAE_q0anf9nCYv4p5B-FiAIF-QUTQ,1063
+sparki_cli-1.0.0.dist-info/METADATA,sha256=KMyRYLRSqiUN0R-5228SCR_TzZZrBNA3xbx3Q9BBK4M,1820
+sparki_cli-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sparki_cli-1.0.0.dist-info/entry_points.txt,sha256=cB61gHZ_-lbfAbOvk_g9Xx_DA4ikReQmDD_n4kX8sEI,42
+sparki_cli-1.0.0.dist-info/licenses/LICENSE,sha256=VBTuXUpmn-mx-nb_NI2o2SsxjA27gDC90UdPIvKWYvM,1066
+sparki_cli-1.0.0.dist-info/RECORD,,

sparki_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sparki_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sparki = sparki.cli:app

sparki_cli-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sparki AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.