muapi-cli 0.2.5__py3-none-any.whl

muapi/config.py

@@ -0,0 +1,110 @@
+"""Config management — stores API key in OS keychain, with ~/.muapi/config.json fallback."""
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+_CONFIG_DIR = Path.home() / ".muapi"
+_CONFIG_FILE = _CONFIG_DIR / "config.json"
+_KEYRING_SERVICE = "muapi-cli"
+_KEYRING_USER = "api-key"
+
+BASE_URL = os.environ.get("MUAPI_BASE_URL", "https://api.muapi.ai/api/v1")
+
+
+def _try_keyring() -> tuple[bool, Optional[str]]:
+    try:
+        import keyring
+        val = keyring.get_password(_KEYRING_SERVICE, _KEYRING_USER)
+        return True, val
+    except Exception:
+        return False, None
+
+
+def get_api_key() -> Optional[str]:
+    # 1. Environment variable always wins
+    if key := os.environ.get("MUAPI_API_KEY"):
+        return key
+    # 2. OS keychain
+    ok, val = _try_keyring()
+    if ok and val:
+        return val
+    # 3. Config file fallback
+    if _CONFIG_FILE.exists():
+        try:
+            data = json.loads(_CONFIG_FILE.read_text())
+            return data.get("api_key")
+        except Exception:
+            pass
+    return None
+
+
+def save_api_key(api_key: str) -> str:
+    """Save API key; returns where it was saved ('keychain' or 'file')."""
+    ok, _ = _try_keyring()
+    if ok:
+        import keyring
+        keyring.set_password(_KEYRING_SERVICE, _KEYRING_USER, api_key)
+        return "keychain"
+    # Fallback: write to file
+    _CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    existing: dict = {}
+    if _CONFIG_FILE.exists():
+        try:
+            existing = json.loads(_CONFIG_FILE.read_text())
+        except Exception:
+            pass
+    existing["api_key"] = api_key
+    _CONFIG_FILE.write_text(json.dumps(existing, indent=2))
+    _CONFIG_FILE.chmod(0o600)
+    return "file"
+
+
+def get_setting(key: str) -> Optional[str]:
+    """Read a value from the settings section of the config file."""
+    if _CONFIG_FILE.exists():
+        try:
+            data = json.loads(_CONFIG_FILE.read_text())
+            return data.get("settings", {}).get(key)
+        except Exception:
+            pass
+    return None
+
+
+def set_setting(key: str, value: str) -> None:
+    """Write a value to the settings section of the config file."""
+    _CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    existing: dict = {}
+    if _CONFIG_FILE.exists():
+        try:
+            existing = json.loads(_CONFIG_FILE.read_text())
+        except Exception:
+            pass
+    existing.setdefault("settings", {})[key] = value
+    _CONFIG_FILE.write_text(json.dumps(existing, indent=2))
+    _CONFIG_FILE.chmod(0o600)
+
+
+def get_all_settings() -> dict:
+    """Return all settings as a dict."""
+    if _CONFIG_FILE.exists():
+        try:
+            data = json.loads(_CONFIG_FILE.read_text())
+            return data.get("settings", {})
+        except Exception:
+            pass
+    return {}
+
+
+def delete_api_key() -> None:
+    ok, _ = _try_keyring()
+    if ok:
+        try:
+            import keyring
+            keyring.delete_password(_KEYRING_SERVICE, _KEYRING_USER)
+        except Exception:
+            pass
+    if _CONFIG_FILE.exists():
+        data = json.loads(_CONFIG_FILE.read_text())
+        data.pop("api_key", None)
+        _CONFIG_FILE.write_text(json.dumps(data, indent=2))

muapi/dynamic_help.py

@@ -0,0 +1,144 @@
+"""Dynamic per-model `--help` for `muapi run <model>`.
+
+Typer's static help only knows about flags that are *declared* on a command,
+so it can't show per-model inputs. We sniff argv before Typer runs, and if
+the user is asking for help on `muapi run <model>`, we fetch the model's
+OpenAPI schema and print its real properties.
+
+If anything goes wrong (network, unknown model, malformed spec), we return
+False so the caller falls through to Typer's normal static help.
+"""
+from __future__ import annotations
+
+import sys
+from typing import Optional
+
+from rich.console import Console
+from rich.table import Table
+
+from . import schema_introspect
+
+
+_HELP_FLAGS = {"-h", "--help"}
+
+
+def detect_run_help(argv: list[str]) -> Optional[str]:
+    """Return the model token if argv looks like `muapi run <model> -h`.
+
+    The check is intentionally permissive — extra flags between `run`
+    and `-h` don't disqualify (e.g. `run flux-dev -p foo -h`).
+    """
+    try:
+        run_idx = argv.index("run")
+    except ValueError:
+        return None
+    rest = argv[run_idx + 1:]
+    if not rest:
+        return None
+    if not any(flag in rest for flag in _HELP_FLAGS):
+        return None
+    # First non-flag token after `run` is the model.
+    for token in rest:
+        if token in _HELP_FLAGS:
+            return None  # asked for help with no model
+        if not token.startswith("-"):
+            return token
+    return None
+
+
+def print_dynamic_help(model: str) -> bool:
+    """Print schema-driven help for `model`. Returns True on success."""
+    # Resolve aliases the same way the run command does.
+    try:
+        from .commands.run import resolve_model
+        endpoint = resolve_model(model)
+    except Exception:
+        endpoint = model
+
+    try:
+        described = schema_introspect.lookup(endpoint)
+    except Exception:
+        return False
+    if not described:
+        return False
+
+    console = Console(stderr=False)
+    console.print()
+    console.print(f"[bold magenta]muapi run {model}[/bold magenta]")
+    if endpoint != model:
+        console.print(f"  [dim]endpoint:[/dim] {endpoint}")
+    if described["title"] and described["title"] != endpoint:
+        console.print(f"  [dim]schema:  [/dim] {described['title']}")
+    console.print()
+    console.print("[bold]Usage:[/bold] muapi run "
+                  f"{model} [-p PROMPT] [-i KEY=VALUE ...] [--input-file FILE] [global opts]")
+    console.print()
+
+    props = described["properties"]
+    if not props:
+        console.print("[dim]No input properties documented for this endpoint.[/dim]")
+        console.print()
+    else:
+        table = Table(show_header=True, header_style="bold cyan", title="Inputs (from live OpenAPI schema)")
+        table.add_column("name")
+        table.add_column("type")
+        table.add_column("required")
+        table.add_column("default")
+        table.add_column("description / enum")
+        for p in props:
+            default = "" if p["default"] is None else _short(p["default"])
+            desc = p["description"]
+            if p["enum"]:
+                desc = (desc + "  " if desc else "") + f"[dim]enum:[/dim] {', '.join(map(str, p['enum']))}"
+            table.add_row(
+                p["name"],
+                p["type"],
+                "[red]✓[/red]" if p["required"] else "",
+                default,
+                desc,
+            )
+        console.print(table)
+        console.print()
+
+    console.print("[bold]Global options:[/bold]")
+    console.print("  -p, --prompt TEXT        Prompt (also pass via -i prompt=...). Use '-' for stdin.")
+    console.print("  -i, --input KEY=VALUE    Repeatable. Values are parsed as JSON when valid.")
+    console.print("  --input-file FILE        JSON file of inputs (merged before -i flags).")
+    console.print("  --wait / --no-wait       Poll until done (default: --wait).")
+    console.print("  --dry-run                Print the request that would be sent and exit.")
+    console.print("  --download DIR, -d       Save outputs to DIR.")
+    console.print("  --output-json, -j        Print raw JSON to stdout.")
+    console.print("  --jq EXPR                jq-style filter on JSON output.")
+    console.print()
+    console.print("[dim]Example:[/dim] muapi run "
+                  f"{model} -p \"...\" {_example_inputs(props)}--output-json")
+    console.print()
+    return True
+
+
+def _short(val: object) -> str:
+    s = repr(val) if isinstance(val, str) else str(val)
+    return s if len(s) <= 32 else s[:29] + "..."
+
+
+def _example_inputs(props: list[dict]) -> str:
+    """Suggest a couple of `-i` flags from the schema as an example."""
+    bits = []
+    for p in props:
+        if p["name"] == "prompt":
+            continue
+        if p["default"] is not None and not isinstance(p["default"], (list, dict)):
+            bits.append(f"-i {p['name']}={p['default']}")
+        elif p["enum"]:
+            bits.append(f"-i {p['name']}={p['enum'][0]}")
+        if len(bits) >= 2:
+            break
+    return (" ".join(bits) + " ") if bits else ""
+
+
+def maybe_handle_run_help(argv: Optional[list[str]] = None) -> bool:
+    """Top-level entry: if argv asks for `run <model> -h`, print + return True."""
+    model = detect_run_help(list(argv) if argv is not None else sys.argv)
+    if not model:
+        return False
+    return print_dynamic_help(model)

muapi/exitcodes.py

@@ -0,0 +1,14 @@
+"""Semantic exit codes for agent-friendly scripting.
+
+Exit codes match the convention established by modelslab-cli and common
+Unix tool practices so agents can branch on specific failure types.
+"""
+
+OK            = 0   # Success
+ERROR         = 1   # Generic / unclassified error
+AUTH_ERROR    = 3   # Missing or invalid API key
+RATE_LIMITED  = 4   # 429 Too Many Requests
+NOT_FOUND     = 5   # 404 — resource or model not found
+BILLING_ERROR = 6   # Insufficient credits / payment required
+TIMEOUT       = 7   # Generation timed out
+VALIDATION    = 8   # Bad input / schema validation failure

muapi/main.py

@@ -0,0 +1,98 @@
+"""muapi CLI — official command-line interface for muapi.ai"""
+from typing import Optional
+
+import typer
+from rich import print as rprint
+
+from . import __version__
+from .commands import auth, account, audio, config_cmd, docs, edit, enhance, image, keys, models, predict, run, upload, video, workflow
+from .commands import mcp_server
+from .dynamic_help import maybe_handle_run_help
+
+app = typer.Typer(
+    name="muapi",
+    help="muapi.ai CLI — generate images, videos, and audio from the terminal.",
+    add_completion=True,
+    rich_markup_mode="rich",
+    no_args_is_help=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+# ── Subcommand groups ──────────────────────────────────────────────────────────
+
+app.add_typer(auth.app,        name="auth",    help="Log in, register, or configure API key.")
+app.add_typer(account.app,     name="account", help="Check balance and top up credits.")
+app.add_typer(keys.app,        name="keys",    help="List, create, and delete API keys.")
+app.add_typer(image.app,       name="image",   help="Generate or edit images.")
+app.add_typer(video.app,       name="video",   help="Generate videos from text or images.")
+app.add_typer(audio.app,       name="audio",   help="Create or remix music and audio.")
+app.add_typer(enhance.app,     name="enhance", help="Enhance images (upscale, bg-remove, face-swap…).")
+app.add_typer(edit.app,        name="edit",    help="Edit videos (effects, lipsync, dance, dress…).")
+app.add_typer(predict.app,     name="predict", help="Check or wait for async prediction results.")
+
+# `run` is a single top-level command, not a group, so its positional MODEL
+# argument doesn't collide with subcommand routing.
+app.command(
+    "run",
+    help="Run any model by endpoint name (schema-driven; try `muapi run <model> -h`).",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)(run.run)
+app.add_typer(upload.app,      name="upload",  help="Upload local files to get a hosted URL.")
+app.add_typer(models.app,      name="models",  help="Discover all available models.")
+app.add_typer(workflow.app,    name="workflow", help="Build, run, and visualize multi-step AI workflows.")
+app.add_typer(config_cmd.app,  name="config",  help="Get and set persistent CLI configuration.")
+app.add_typer(docs.app,        name="docs",    help="Access the muapi.ai API documentation.")
+app.add_typer(mcp_server.app,  name="mcp",     help="Run as an MCP server for AI agent integration.")
+
+
+@app.command("version")
+def version(
+    output_json: bool = typer.Option(False, "--output-json", "-j"),
+):
+    """Show the muapi CLI version."""
+    if output_json:
+        import json
+        from .utils import out
+        out.print_json(json.dumps({"version": __version__, "name": "muapi-cli"}))
+    else:
+        rprint(f"muapi CLI [bold]{__version__}[/bold]")
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    no_color: bool = typer.Option(
+        False, "--no-color",
+        help="Disable colored output (also respects NO_COLOR env var)",
+        is_eager=True,
+    ),
+    version_flag: bool = typer.Option(
+        False, "--version", "-V",
+        help="Show version and exit",
+        is_eager=True,
+    ),
+):
+    if no_color:
+        from .utils import disable_color
+        disable_color()
+
+    if version_flag:
+        rprint(f"muapi CLI [bold]{__version__}[/bold]")
+        raise typer.Exit()
+
+    if ctx.invoked_subcommand is None:
+        rprint(ctx.get_help())
+
+
+def _entrypoint() -> None:
+    # Intercept `muapi run <model> -h` so we can print model-specific
+    # input help from the live OpenAPI schema. Falls through to Typer
+    # on any failure (network down, unknown model, missing schema).
+    import sys
+    if maybe_handle_run_help(sys.argv[1:]):
+        return
+    app()
+
+
+if __name__ == "__main__":
+    _entrypoint()

muapi/schema_introspect.py

@@ -0,0 +1,175 @@
+"""Fetch the muapi OpenAPI spec and resolve per-endpoint request schemas.
+
+The CLI's static verb commands wrap a curated subset of models. `muapi run`
+needs to reach *any* endpoint exposed by the API and discover its input
+schema at call time — so we read the live OpenAPI spec and look up the
+request body for the endpoint the user named.
+
+The spec is cached on disk (~/.muapi/openapi-cache.json, 1h TTL) so repeated
+`muapi run ... -h` calls don't hit the network.
+"""
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+import httpx
+
+from .config import BASE_URL
+
+_HOST = BASE_URL.replace("/api/v1", "")
+_OPENAPI_URL = f"{_HOST}/openapi.json"
+
+_CACHE_DIR = Path.home() / ".muapi"
+_CACHE_FILE = _CACHE_DIR / "openapi-cache.json"
+_CACHE_TTL = 3600  # 1 hour, matches WaveSpeed's `models.json` cache
+
+_API_PREFIX = "/api/v1/"
+
+
+def _load_cache() -> Optional[dict]:
+    if not _CACHE_FILE.exists():
+        return None
+    try:
+        wrapper = json.loads(_CACHE_FILE.read_text())
+        if time.time() - wrapper.get("fetched_at", 0) > _CACHE_TTL:
+            return None
+        if wrapper.get("base_url") != BASE_URL:
+            return None
+        return wrapper.get("spec")
+    except Exception:
+        return None
+
+
+def _save_cache(spec: dict) -> None:
+    _CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    payload = {"base_url": BASE_URL, "fetched_at": time.time(), "spec": spec}
+    try:
+        _CACHE_FILE.write_text(json.dumps(payload))
+    except Exception:
+        pass  # cache failure shouldn't break the call
+
+
+def fetch_spec(force_refresh: bool = False, timeout: float = 15.0) -> dict:
+    """Return the OpenAPI spec, served from cache when fresh."""
+    if not force_refresh:
+        cached = _load_cache()
+        if cached:
+            return cached
+    resp = httpx.get(_OPENAPI_URL, timeout=timeout)
+    resp.raise_for_status()
+    spec = resp.json()
+    _save_cache(spec)
+    return spec
+
+
+# ── Lookup ────────────────────────────────────────────────────────────────────
+
+def _resolve_ref(spec: dict, ref: str) -> dict:
+    # "#/components/schemas/ImageRequest" → dict
+    if not ref.startswith("#/"):
+        return {}
+    node: Any = spec
+    for part in ref[2:].split("/"):
+        if not isinstance(node, dict) or part not in node:
+            return {}
+        node = node[part]
+    return node if isinstance(node, dict) else {}
+
+
+def find_endpoint(spec: dict, endpoint: str) -> Optional[dict]:
+    """Locate the POST operation for an endpoint name (with or without /api/v1/ prefix)."""
+    paths = spec.get("paths", {})
+    # Try a few common forms — users pass the endpoint slug, not the full path.
+    candidates = [endpoint]
+    if not endpoint.startswith("/"):
+        candidates.append(f"{_API_PREFIX}{endpoint}")
+        candidates.append(f"/{endpoint}")
+    for candidate in candidates:
+        node = paths.get(candidate)
+        if node and "post" in node:
+            return node["post"]
+    return None
+
+
+def get_request_schema(spec: dict, endpoint: str) -> Optional[dict]:
+    """Return the resolved JSON schema for the endpoint's request body, or None."""
+    op = find_endpoint(spec, endpoint)
+    if not op:
+        return None
+    body = op.get("requestBody", {})
+    content = body.get("content", {}).get("application/json", {})
+    schema = content.get("schema", {})
+    # Follow a single $ref hop — that's all muapi's spec uses today.
+    if "$ref" in schema:
+        return _resolve_ref(spec, schema["$ref"])
+    return schema or None
+
+
+def _format_type(prop: dict) -> str:
+    """Best-effort one-line type label for a JSON schema property."""
+    if "enum" in prop:
+        return "enum"
+    if "anyOf" in prop:
+        types = []
+        for sub in prop["anyOf"]:
+            t = sub.get("type")
+            if t and t != "null":
+                types.append(t)
+        return " | ".join(types) if types else "any"
+    if "type" in prop:
+        t = prop["type"]
+        if t == "array":
+            item_type = prop.get("items", {}).get("type", "any")
+            return f"array<{item_type}>"
+        return t
+    if "$ref" in prop:
+        ref = prop["$ref"].rsplit("/", 1)[-1]
+        return f"object<{ref}>"
+    return "any"
+
+
+def describe_schema(schema: dict) -> dict:
+    """Normalize a JSON schema for display.
+
+    Returns: {title, properties: [(name, type, required, default, enum, description)]}
+    """
+    title = schema.get("title", "")
+    required = set(schema.get("required", []))
+    rows = []
+    for name, prop in schema.get("properties", {}).items():
+        if not isinstance(prop, dict):
+            continue
+        rows.append({
+            "name": name,
+            "type": _format_type(prop),
+            "required": name in required,
+            "default": prop.get("default", None),
+            "enum": prop.get("enum"),
+            "description": prop.get("description") or prop.get("title") or "",
+        })
+    # Sort: required first, then alphabetical.
+    rows.sort(key=lambda r: (not r["required"], r["name"]))
+    return {"title": title, "properties": rows}
+
+
+# ── Public convenience ───────────────────────────────────────────────────────
+
+def lookup(endpoint: str, *, force_refresh: bool = False) -> Optional[dict]:
+    """Fetch + extract + describe in one call. Returns None if not found."""
+    spec = fetch_spec(force_refresh=force_refresh)
+    schema = get_request_schema(spec, endpoint)
+    if not schema:
+        return None
+    return describe_schema(schema)
+
+
+def list_endpoint_slugs(spec: dict) -> list[str]:
+    """Return every POST endpoint slug under /api/v1/."""
+    slugs = []
+    for path in spec.get("paths", {}):
+        if path.startswith(_API_PREFIX) and "post" in spec["paths"][path]:
+            slugs.append(path[len(_API_PREFIX):])
+    return slugs