inferenceport-cli 1.0.0__py3-none-any.whl

ipx/commands/mcp.py

@@ -0,0 +1,182 @@
+"""ipx mcp - InferencePort's hosted MCP servers. Today: the Council of LLMs (`ipx mcp council`)."""
+
+from __future__ import annotations
+
+import json
+import shlex
+import sys
+from typing import Any, Dict, List, Optional, Tuple
+
+import click
+from rich.markup import escape
+
+from ipx import ui
+from ipx.app import App, pass_app
+from ipx.clickx import IpxGroup
+from ipx.errors import IpxError
+from ipx.mcp import McpClient, council_url
+
+
+def council_client(app: App) -> McpClient:
+    app.require_login()
+    with ui.status("Connecting to the council…") if not app.json else _null():
+        return McpClient(app, council_url(app.api.base_url)).connect()
+
+
+class _null:
+    def __enter__(self) -> None:
+        return None
+
+    def __exit__(self, *a: Any) -> None:
+        return None
+
+
+def _load(tool_result: Any) -> Any:
+    return tool_result if not isinstance(tool_result, str) else {"text": tool_result}
+
+
+@click.group("mcp", cls=IpxGroup, section="Cloud", short_help="Hosted MCP servers (Council of LLMs)",
+             examples=["ipx mcp council tiers", "ipx mcp council reason \"Is P = NP provable with current methods?\" --tier basic",
+                       "ipx -O acme mcp council reason -f question.md --rounds 2", "ipx mcp council connect claude-code"])
+def group() -> None:
+    """Use InferencePort's hosted Model Context Protocol servers from the terminal."""
+
+
+@group.group("council", cls=IpxGroup, short_help="Council of LLMs: multi-model reasoning")
+def council() -> None:
+    """Send a problem to a council of models that answer, cross-review each other, and have judges synthesize a result.
+
+    Each model call is billed at normal per-token rates plus a flat council surcharge, to your wallet or - with an
+    organization context (`ipx auth context <org>` or --org) - the organization's. Works with a signed-in session
+    or an API key.
+    """
+
+
+@council.command("tiers", short_help="Council tiers and their cost")
+@pass_app
+def tiers(app: App) -> None:
+    """List the council tiers with model counts, judges and the flat surcharge in credits."""
+    c = council_client(app)
+    d = c.call_json("council_list_tiers")
+
+    def render(x: Dict[str, Any]) -> None:
+        ui.console.print(ui.make_table(
+            ["Tier", "Name", "Models", "Judges", "Surcharge", "Description"],
+            [(k, v.get("name"), v.get("model_count"), v.get("judge_count"), f"{ui.fmt_credits(v.get('surcharge_credits'))} cr", v.get("description")) for k, v in x.items()],
+            title="Council tiers", right=["Models", "Judges", "Surcharge"]))
+
+    app.out(d, render)
+
+
+@council.command("models", short_help="Models in a tier")
+@click.option("-t", "--tier", default="basic", show_default=True, help="Tier name (see `ipx mcp council tiers`).")
+@pass_app
+def models(app: App, tier: str) -> None:
+    """The council members, judges and fallbacks of a tier."""
+    d = council_client(app).call_json("council_list_models", {"tier": tier})
+
+    def render(x: Dict[str, Any]) -> None:
+        ui.console.print(ui.make_table(["Role", "Model"], [("member", m) for m in x.get("models") or []] + [("judge", m) for m in x.get("judge_models") or []]
+                                       + [("fallback", m) for m in x.get("fallback_pool") or []], title=f"{x.get('name') or tier} council"))
+
+    app.out(d, render)
+
+
+@council.command("reason", short_help="Ask the council", examples=[
+    "ipx mcp council reason \"Design a rate limiter for 10k rps\"",
+    "ipx mcp council reason -f spec.md --tier pro --rounds 2",
+    "cat bug.txt | ipx mcp council reason --stdin \"What is the root cause?\"",
+    "ipx mcp council reason \"…\" --model openai/gpt-4o --model anthropic/claude-sonnet-4 --judge openai/gpt-4o"])
+@click.argument("problem", required=False)
+@click.option("-f", "--file", "files", multiple=True, type=click.Path(exists=True, dir_okay=False), help="Include a text file's contents (repeatable).")
+@click.option("--stdin", "use_stdin", is_flag=True, help="Append standard input to the problem.")
+@click.option("-t", "--tier", default="basic", show_default=True, help="Council tier; higher tiers use more and better models.")
+@click.option("-r", "--rounds", type=click.IntRange(1, 3), default=1, show_default=True, help="Review rounds (models critique each other).")
+@click.option("--model", "custom_models", multiple=True, help="Override the council members (repeatable).")
+@click.option("--judge", "custom_judges", multiple=True, help="Override the judges (repeatable).")
+@click.option("--log", "show_log", is_flag=True, help="Also print the per-round iteration log.")
+@pass_app
+def reason(app: App, problem: Optional[str], files: Tuple[str, ...], use_stdin: bool, tier: str, rounds: int,
+           custom_models: Tuple[str, ...], custom_judges: Tuple[str, ...], show_log: bool) -> None:
+    """Run PROBLEM through the council and print the synthesized answer (stdout) with a usage summary (stderr)."""
+    app.require_login()
+    parts: List[str] = [problem] if problem and problem != "-" else []
+    for f in files:
+        with open(f, "r", encoding="utf-8", errors="replace") as fh:
+            parts.append(f"--- {f} ---\n{fh.read()}")
+    if use_stdin or problem == "-":
+        parts.append(sys.stdin.read().strip())
+    text = "\n\n".join(p for p in parts if p).strip()
+    if not text:
+        raise IpxError("No problem given.", "Pass it as an argument, with -f FILE, or pipe it in with --stdin.")
+    args: Dict[str, Any] = {"problem": text, "tier": tier, "iteration_rounds": rounds}
+    if custom_models:
+        args["custom_models"] = list(custom_models)
+    if custom_judges:
+        args["custom_judges"] = list(custom_judges)
+    c = council_client(app)
+    if not app.json:
+        ui.err.print(f"[muted]Convening the {tier} council · billed to {'org ' + app.org if app.org else 'your wallet'} · this can take a few minutes…[/muted]")
+    d = c.call_json("council_reason", args)
+    if not isinstance(d, dict):
+        d = {"answer": d}
+    if app.json:
+        if not show_log:
+            d.pop("iteration_log", None)
+        ui.emit_json(d)
+        return
+    sys.stdout.write(str(d.get("answer", "")).rstrip() + "\n")
+    info, bill, use = d.get("council") or {}, d.get("billing") or {}, d.get("usage") or {}
+    if not ui.STATE["quiet"]:
+        failed = info.get("failed_models") or []
+        line = [f"{len(info.get('models_used') or [])} models", f"{info.get('iterations_used', '?')} round(s)"]
+        if bill.get("surcharge_credits"):
+            line.append(f"surcharge {ui.fmt_credits(bill['surcharge_credits'])} cr" + ("" if bill.get("charged") else " (not charged)"))
+        if isinstance(use, dict) and use.get("total_tokens"):
+            line.append(f"{ui.fmt_num(use['total_tokens'])} tokens")
+        ui.err.print("[muted]" + " · ".join(line) + ("" if not failed else f" · {len(failed)} member(s) failed") + "[/muted]")
+    if show_log and d.get("iteration_log"):
+        ui.err.print_json(json.dumps(d["iteration_log"], default=str))
+
+
+@council.command("tools", short_help="Tools the council server exposes")
+@pass_app
+def tools(app: App) -> None:
+    """List the MCP tools offered by the council server."""
+    ts = council_client(app).list_tools()
+    app.out(ts, lambda rows: ui.console.print(ui.make_table(["Tool", "Description"], [(t.get("name"), (t.get("description") or "").strip().split("\n")[0]) for t in rows], title="Council MCP tools")))
+
+
+@council.command("test", short_help="Check the connection")
+@pass_app
+def test(app: App) -> None:
+    """Run the MCP handshake with your sign-in, like an MCP client would."""
+    c = council_client(app)
+    info = {"url": c.url, "server": c.server_info.get("name"), "version": c.server_info.get("version"), "org": app.org}
+    app.out(info, lambda x: ui.ok(f"Connected to [bold]{x['server']}[/bold] at {x['url']}" + (f" as org {x['org']}" if x["org"] else "")))
+
+
+CLIENTS = ["claude-code", "claude-desktop", "cursor", "vscode", "json"]
+
+
+@council.command("connect", short_help="Config snippet for an MCP client")
+@click.argument("client", type=click.Choice(CLIENTS), default="claude-code")
+@pass_app
+def connect(app: App, client: str) -> None:
+    """Print the setup for CLIENT to use the council server. Uses OAuth, or paste an API key (ipa_live_…) as the token."""
+    url = council_url(app.api.base_url)
+    headers = {"X-InferencePort-Org": app.org} if app.org else {}
+    if client == "claude-code":
+        hdr = "".join(f" --header {shlex.quote(f'{k}: {v}')}" for k, v in headers.items())
+        text = f"claude mcp add --transport http council {shlex.quote(url)}{hdr}"
+    elif client == "claude-desktop":
+        text = json.dumps({"mcpServers": {"council": {"command": "npx", "args": ["-y", "mcp-remote", url] + [x for k, v in headers.items() for x in ("--header", f"{k}:{v}")]}}}, indent=2)
+    else:
+        server: Dict[str, Any] = {"type": "http", "url": url} if client == "vscode" else {"url": url}
+        if headers:
+            server["headers"] = headers
+        text = json.dumps({"servers" if client == "vscode" else "mcpServers": {"council": server}}, indent=2)
+    app.out({"client": client, "url": url, "config": text}, lambda _: (ui.err.print(f"[muted]{client} · billed to {'org ' + escape(app.org) if app.org else 'your personal wallet'}[/muted]", markup=True, highlight=False) if not ui.STATE["quiet"] else None, sys.stdout.write(text + "\n")))
+
+
+COMMANDS = [group]

ipx/commands/misc.py

@@ -0,0 +1,168 @@
+"""Top-level utility commands: status, doctor, api, rewards, completion."""
+
+from __future__ import annotations
+
+import json
+import socket
+import sys
+from typing import Any, Dict, List, Optional
+
+import click
+from rich.text import Text
+
+from ipx import __version__, ui
+from ipx.app import App, pass_app
+from ipx.clickx import IpxCommand, IpxGroup
+from ipx.config import DEFAULT_SERVER_PORT, desktop_data_dir
+from ipx.errors import IpxError
+
+_STATE_STYLE = {"operational": "ok", "up": "ok", "ok": "ok", "degraded": "warn", "partial": "warn", "down": "bad", "outage": "bad"}
+
+
+def _dot(state: Any) -> Text:
+    s = str(state).lower()
+    style = _STATE_STYLE.get(s, "muted")
+    return Text(f"● {state}", style=style)
+
+
+@click.command("status", cls=IpxCommand, section="Tools", short_help="InferencePort service health")
+@pass_app
+def status(app: App) -> None:
+    """Show the health of the Lightning API and each generation service (no sign-in needed)."""
+    data = app.api.get("/status", auth=False, org=False) or {}
+
+    def render(d: Dict[str, Any]) -> None:
+        rows: List[Any] = [("Overall", _dot(d.get("state", "unknown")))]
+        for name, val in (d.get("services") or {}).items():
+            state = val.get("state") or val.get("status") if isinstance(val, dict) else val
+            rows.append((name, _dot(state)))
+        ui.console.print(ui.kv_panel("InferencePort status", rows, subtitle=app.cfg.base_url))
+        for n in d.get("notifications") or []:
+            ui.warn(n if isinstance(n, str) else n.get("message") or json.dumps(n))
+
+    app.out(data, render)
+
+
+@click.command("doctor", cls=IpxCommand, section="Tools", short_help="Diagnose your setup")
+@pass_app
+def doctor(app: App) -> None:
+    """Check connectivity, sign-in, organization context, local Ollama and the host-server port."""
+    from ipx.local import ollama_version
+
+    checks: List[Dict[str, Any]] = []
+
+    def add(name: str, ok_: Optional[bool], detail: str) -> None:
+        checks.append({"check": name, "ok": ok_, "detail": detail})
+
+    add("ipx version", True, __version__)
+    try:
+        st = app.api.get("/status", auth=False, org=False) or {}
+        add("API reachable", True, f"{app.cfg.base_url} · {st.get('state', 'ok')}")
+    except IpxError as e:
+        add("API reachable", False, e.message)
+    if app.creds.signed_in:
+        try:
+            sub = app.api.get("/subscription", org=False) or {}
+            add("Signed in", True, f"{sub.get('email') or app.creds.email} · {sub.get('plan_name', 'plan unknown')}")
+        except IpxError as e:
+            add("Signed in", False, e.message)
+    else:
+        add("Signed in", None, "not signed in — run `ipx auth login`")
+    add("Organization context", None if not app.cfg.org else True, app.cfg.org or "personal account")
+    v = ollama_version(app.cfg.ollama_url)
+    add("Local Ollama", bool(v), f"{app.cfg.ollama_url} · v{v}" if v else "not running — install from https://ollama.com and run `ollama serve`")
+    with socket.socket() as s:
+        s.settimeout(0.3)
+        busy = s.connect_ex(("127.0.0.1", DEFAULT_SERVER_PORT)) == 0
+    add("Host server port", None, f"{DEFAULT_SERVER_PORT} in use (server may be running)" if busy else f"{DEFAULT_SERVER_PORT} is free")
+    dd = desktop_data_dir()
+    add("Desktop app data", True if dd.exists() else None, str(dd) if dd.exists() else "desktop app not found (imports will create the folder)")
+
+    def render(rows: List[Dict[str, Any]]) -> None:
+        for r in rows:
+            mark = {True: "[ok]✔[/ok]", False: "[bad]✖[/bad]", None: "[warn]•[/warn]"}[r["ok"]]
+            ui.console.print(f" {mark} [bold]{r['check']:<22}[/bold] [muted]{r['detail']}[/muted]")
+
+    app.out(checks, render)
+    if any(r["ok"] is False for r in checks):
+        sys.exit(1)
+
+
+@click.command("api", cls=IpxCommand, section="Tools", short_help="Make a raw authenticated API request",
+               examples=["ipx api GET /v1/me", "ipx api POST /v1/chat/completions -d '{\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}]}'"])
+@click.argument("method")
+@click.argument("path")
+@click.option("-d", "--data", help="JSON request body (or @file.json).")
+@click.option("-q", "--query", "queries", multiple=True, help="Query parameter key=value (repeatable).")
+@click.option("--no-auth", is_flag=True, help="Do not send credentials.")
+@pass_app
+def api(app: App, method: str, path: str, data: Optional[str], queries, no_auth: bool) -> None:
+    """Call any endpoint with your credentials and print the response. Escape hatch for scripting."""
+    body: Any = None
+    if data:
+        raw = open(data[1:], "r", encoding="utf-8").read() if data.startswith("@") else data
+        try:
+            body = json.loads(raw)
+        except ValueError as e:
+            raise IpxError(f"--data is not valid JSON: {e}")
+    params = dict(q.split("=", 1) for q in queries if "=" in q)
+    r = app.api.request(method.upper(), path, json=body, params=params, auth=not no_auth)
+    if r.content_type.startswith(("application/json",)) or r.body[:1] in (b"{", b"["):
+        try:
+            ui.console.print_json(r.text) if ui.console.is_terminal and not app.json else click.echo(r.text)
+            return
+        except Exception:
+            pass
+    sys.stdout.buffer.write(r.body)
+
+
+@click.group("rewards", cls=IpxGroup, section="Tools", short_help="Rewards and discounts")
+def rewards() -> None:
+    """Earn and claim InferencePort rewards."""
+
+
+@rewards.command("list")
+@pass_app
+def rewards_list(app: App) -> None:
+    """List available rewards."""
+    data = app.api.get("/v1/rewards", org=False) or {}
+    items = data.get("rewards") or data.get("items") or (data if isinstance(data, list) else [])
+
+    def render(_: Any) -> None:
+        rows = [(r.get("id"), r.get("title") or r.get("name"), r.get("description") or "") for r in items if isinstance(r, dict)]
+        ui.console.print(ui.make_table(["ID", "Reward", "Description"], rows, title="Rewards"))
+
+    app.out(data, render)
+
+
+@rewards.command("summary")
+@pass_app
+def rewards_summary(app: App) -> None:
+    """Your reward progress at a glance."""
+    data = app.api.get("/v1/rewards/summary", org=False) or {}
+    app.out(data, lambda d: ui.console.print(ui.kv_panel("Rewards", [(k, v) for k, v in d.items() if not isinstance(v, (dict, list))])))
+
+
+@rewards.command("claim")
+@click.argument("reward_id")
+@pass_app
+def rewards_claim(app: App, reward_id: str) -> None:
+    """Claim an earned reward."""
+    data = app.api.post(f"/v1/rewards/claim/{reward_id}", {}, org=False)
+    app.out(data, lambda _: ui.ok(f"Claimed reward [bold]{reward_id}[/bold]"))
+
+
+@click.command("completion", cls=IpxCommand, section="Tools", short_help="Print a shell completion script",
+               examples=["ipx completion bash >> ~/.bashrc", "ipx completion zsh > ~/.zfunc/_ipx", "ipx completion fish > ~/.config/fish/completions/ipx.fish"])
+@click.argument("shell", type=click.Choice(["bash", "zsh", "fish"]))
+def completion(shell: str) -> None:
+    """Print a completion script for your shell."""
+    from click.shell_completion import get_completion_class
+
+    from ipx.cli import root
+
+    cls = get_completion_class(shell)
+    click.echo(cls(root, {}, "ipx", "_IPX_COMPLETE").source())
+
+
+COMMANDS = [status, doctor, api, rewards, completion]

ipx/commands/model.py

@@ -0,0 +1,234 @@
+"""ipx model - manage models on this machine (the Ollama runtime used by the desktop app)."""
+
+from __future__ import annotations
+
+import copy as _copy
+import os
+import re
+from typing import Any, Dict, Optional
+
+import click
+from rich.text import Text
+
+from ipx import policy, ui
+from ipx.app import App, pass_app
+from ipx.clickx import IpxGroup
+from ipx.local import Ollama
+
+
+def _clip(s: str, n: int) -> str:
+    s = " ".join(s.split())
+    return s if len(s) <= n else s[: n - 1].rsplit(" ", 1)[0] + "…"
+
+
+def client(app: App) -> Ollama:
+    return Ollama(app.cfg.ollama_url)
+
+
+@click.group("model", cls=IpxGroup, section="Local", short_help="Pull, list, inspect and remove local models",
+             examples=["ipx model list", "ipx model pull llama3.2", "ipx model search coder", "ipx model rm llama3.2:1b",
+                       "ipx model import gguf ./my-model.gguf --name mine", "ipx model import hf bartowski/Llama-3.2-3B-Instruct-GGUF"])
+def group() -> None:
+    """Manage local models on your machine.
+
+    Uses the same Ollama runtime as the InferencePort desktop app, so models you pull here appear there (and vice
+    versa). Organization controls on pulling and importing apply when an org context is active.
+    """
+
+
+group_alias_name = "models"
+
+
+@group.command("list", short_help="Installed models")
+@pass_app
+def list_(app: App) -> None:
+    """List models installed locally."""
+    models = client(app).list()
+
+    def render(_: Any) -> None:
+        if not models:
+            ui.info("No local models yet. Try `ipx model pull llama3.2`.")
+            return
+        rows = []
+        for m in sorted(models, key=lambda x: x.get("name", "")):
+            d = m.get("details") or {}
+            rows.append((m.get("name"), ui.fmt_bytes(m.get("size", 0)), d.get("parameter_size"), d.get("quantization_level"),
+                         d.get("family"), (m.get("modified_at") or "")[:10]))
+        ui.console.print(ui.make_table(["Model", "Size", "Params", "Quant", "Family", "Modified"], rows,
+                                       title=f"Local models ({len(rows)})", right=["Size"]))
+
+    app.out(models, render)
+
+
+@group.command("pull", examples=["ipx model pull llama3.2", "ipx model pull qwen2.5-coder:7b"])
+@click.argument("names", nargs=-1, required=True)
+@pass_app
+def pull(app: App, names) -> None:
+    """Download one or more models with a live progress bar."""
+    oll = client(app)
+    for name in names:
+        policy.assert_pull(app, name)
+        _pull_one(app, oll, name)
+
+
+def _pull_one(app: App, oll: Ollama, name: str) -> None:
+    last: Dict[str, Any] = {}
+    if app.json:
+        for ev in oll.pull(name):
+            last = ev
+        ui.emit_json({"model": name, "status": last.get("status")})
+        return
+    tasks: Dict[str, int] = {}
+    with ui.download_progress() as prog:
+        status_task = prog.add_task(f"Pulling {name}", total=None)
+        for ev in oll.pull(name):
+            last = ev
+            st = str(ev.get("status", ""))
+            digest = ev.get("digest")
+            if digest and ev.get("total"):
+                tid = tasks.get(digest)
+                if tid is None:
+                    tid = prog.add_task(f"layer {digest.split(':')[-1][:10]}", total=ev["total"])
+                    tasks[digest] = tid
+                prog.update(tid, completed=ev.get("completed", 0), total=ev["total"])
+            else:
+                prog.update(status_task, description=f"{name} · {st}")
+        prog.update(status_task, total=1, completed=1, description=f"{name} · done")
+    if last.get("status") == "success" or last:
+        ui.ok(f"Pulled [bold]{name}[/bold]")
+
+
+@group.command("rm", short_help="Remove models")
+@click.argument("names", nargs=-1, required=True)
+@pass_app
+def rm(app: App, names) -> None:
+    """Delete local models and free the disk space."""
+    oll = client(app)
+    if not ui.confirm(f"Delete {', '.join(names)}?"):
+        return
+    for n in names:
+        oll.delete(n)
+        ui.ok(f"Removed [bold]{n}[/bold]")
+
+
+@group.command("show", short_help="Details about a model")
+@click.argument("name")
+@pass_app
+def show_(app: App, name: str) -> None:
+    """Show a model's parameters, template and capabilities."""
+    d = client(app).show(name)
+
+    def render(d: Dict[str, Any]) -> None:
+        det = d.get("details") or {}
+        info = d.get("model_info") or {}
+        rows = [("Family", det.get("family")), ("Parameters", det.get("parameter_size")), ("Quantization", det.get("quantization_level")),
+                ("Format", det.get("format")), ("Capabilities", ", ".join(d.get("capabilities") or []) or None),
+                ("Context length", next((v for k, v in info.items() if k.endswith("context_length")), None))]
+        ui.console.print(ui.kv_panel(name, rows))
+        if d.get("system"):
+            ui.console.print(Text("System prompt", style="key"))
+            ui.console.print(Text(d["system"].strip(), style="muted"))
+        if d.get("modelfile") and not app.json:
+            ui.dim("Use `--json` for the full Modelfile and template.")
+
+    app.out(d, render)
+
+
+@group.command("ps", short_help="Models loaded in memory")
+@pass_app
+def ps(app: App) -> None:
+    """Show which models are currently loaded."""
+    run = client(app).running()
+    rows = [(m.get("name"), ui.fmt_bytes(m.get("size", 0)), ui.fmt_bytes(m.get("size_vram", 0)), (m.get("expires_at") or "")[:19].replace("T", " ")) for m in run]
+    app.out(run, lambda _: ui.console.print(ui.make_table(["Model", "Size", "VRAM", "Unloads at"], rows, title="Running models", right=["Size", "VRAM"])) if rows else ui.info("No models are loaded right now."))
+
+
+@group.command("copy", short_help="Copy a model to a new name")
+@click.argument("source")
+@click.argument("destination")
+@pass_app
+def copy(app: App, source: str, destination: str) -> None:
+    """Duplicate a model under another name."""
+    client(app).copy(source, destination)
+    ui.ok(f"Copied [bold]{source}[/bold] → [bold]{destination}[/bold]")
+
+
+@group.command("create", examples=["ipx model create my-assistant -f Modelfile"])
+@click.argument("name")
+@click.option("-f", "--file", "modelfile", required=True, type=click.Path(exists=True, dir_okay=False), help="Path to a Modelfile.")
+@pass_app
+def create(app: App, name: str, modelfile: str) -> None:
+    """Create a model from a Modelfile."""
+    policy.assert_import(app)
+    content = open(modelfile, "r", encoding="utf-8").read()
+    _create(app, name, modelfile=content)
+
+
+def _create(app: App, name: str, **body: Any) -> None:
+    last = ""
+    with ui.status("Creating model…") as st:
+        for ev in client(app).create(name, **body):
+            last = str(ev.get("status", ""))
+            if st:
+                st.update(f"[accent]{last}[/accent]")
+    ui.ok(f"Created [bold]{name}[/bold] [muted]({last})[/muted]")
+
+
+@group.command("search", examples=["ipx model search vision", "ipx model search llama --limit 5"])
+@click.argument("query", required=False)
+@click.option("--limit", type=int, default=15, show_default=True)
+@pass_app
+def search(app: App, query: Optional[str], limit: int) -> None:
+    """Search the public model catalog (no sign-in needed)."""
+    with ui.status("Searching the catalog…"):
+        cat = app.api.get("/models", auth=False, org=False) or []
+    q = (query or "").lower()
+    hits = [m for m in cat if isinstance(m, dict) and (not q or q in str(m.get("name", "")).lower() or q in str(m.get("description", "")).lower()
+                                                        or any(q in str(t).lower() for t in m.get("tags") or []))]
+    hits = hits[:limit]
+
+    def render(_: Any) -> None:
+        rows = [(m.get("name"), ", ".join(m.get("sizes") or []), m.get("pulls"), ", ".join(t for t in m.get("tags") or [] if not re.fullmatch(r"[\d.]+[bm]", str(t).lower())), _clip(m.get("description") or "", 64)) for m in hits]
+        ui.console.print(ui.make_table(["Model", "Sizes", "Pulls", "Tags", "About"], rows, title=f"Catalog results ({len(hits)})"))
+        ui.dim("Install with `ipx model pull <name>`")
+
+    app.out(hits, render)
+
+
+@group.group("import", cls=IpxGroup, short_help="Import GGUF files or Hugging Face models")
+def import_() -> None:
+    """Bring your own models: a local GGUF file or a Hugging Face repository."""
+
+
+@import_.command("gguf", examples=["ipx model import gguf ./model.Q4_K_M.gguf --name my-model --system \"You are concise.\""])
+@click.argument("path", type=click.Path(exists=True, dir_okay=False))
+@click.option("--name", required=True, help="Name for the imported model.")
+@click.option("--system", help="Optional system prompt baked into the model.")
+@click.option("--template", help="Optional chat template.")
+@pass_app
+def import_gguf(app: App, path: str, name: str, system: Optional[str], template: Optional[str]) -> None:
+    """Import a local .gguf file as a model."""
+    policy.assert_import(app)
+    lines = [f'FROM {os.path.abspath(path)}']
+    if template:
+        lines.append(f'TEMPLATE """{template}"""')
+    if system:
+        lines.append(f'SYSTEM """{system}"""')
+    _create(app, name, modelfile="\n".join(lines))
+
+
+@import_.command("hf", examples=["ipx model import hf bartowski/Llama-3.2-3B-Instruct-GGUF:Q4_K_M"])
+@click.argument("repo")
+@pass_app
+def import_hf(app: App, repo: str) -> None:
+    """Pull a GGUF model straight from Hugging Face (user/repo[:quant])."""
+    policy.assert_import(app)
+    ref = repo if repo.startswith("hf.co/") else f"hf.co/{repo}"
+    _pull_one(app, client(app), ref)
+
+
+_alias = _copy.copy(group)
+_alias.name = "models"
+_alias.hidden = True
+
+COMMANDS = [group, _alias]