cometapi-cli 0.2.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

cometapi_cli/__init__.py

@@ -1,3 +1,3 @@
 """CometAPI CLI — professional terminal interface for CometAPI."""
 
-__version__ = "0.2.2"
+__version__ = "0.3.0"

cometapi_cli/app.py

@@ -61,8 +61,10 @@ from cometapi_cli.commands.chat import chat  # noqa: E402
 from cometapi_cli.commands.config_cmd import config_app, init  # noqa: E402
 from cometapi_cli.commands.doctor import doctor  # noqa: E402
 from cometapi_cli.commands.logs import logs  # noqa: E402
+from cometapi_cli.commands.model import model_app  # noqa: E402
 from cometapi_cli.commands.models import models  # noqa: E402
 from cometapi_cli.commands.repl import run_repl  # noqa: E402
+from cometapi_cli.commands.run import run  # noqa: E402
 from cometapi_cli.commands.stats import stats  # noqa: E402
 from cometapi_cli.commands.tasks import tasks  # noqa: E402
 from cometapi_cli.commands.tokens import tokens  # noqa: E402
@@ -75,9 +77,11 @@ app.command()(stats)
 app.command()(tokens)
 app.command()(logs)
 app.command()(tasks)
+app.command()(run)
 app.command()(init)
 app.command()(doctor)
 app.command(name="repl")(run_repl)
+app.add_typer(model_app)
 app.add_typer(config_app)
 
 

cometapi_cli/catalog.py

@@ -0,0 +1,141 @@
+"""Public CometAPI model catalog helpers."""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from .urls import get_api_root_url
+
+CATALOG_CACHE_FILE = Path.home() / ".cache" / "cometapi" / "models.json"
+CATALOG_TTL_SECONDS = 60 * 60
+
+
+def _request_json(url: str) -> dict[str, Any]:
+    try:
+        with urllib.request.urlopen(url, timeout=30) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        body = e.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"GET {url} failed: HTTP {e.code} {body[:200]}") from e
+    except urllib.error.URLError as e:
+        raise RuntimeError(f"GET {url} failed: {e.reason}") from e
+
+
+def _read_cache(base_url: str) -> list[dict[str, Any]] | None:
+    try:
+        raw = json.loads(CATALOG_CACHE_FILE.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if raw.get("base_url") != base_url:
+        return None
+    if time.time() - float(raw.get("fetched_at", 0)) > CATALOG_TTL_SECONDS:
+        return None
+    data = raw.get("data")
+    return data if isinstance(data, list) else None
+
+
+def _write_cache(base_url: str, data: list[dict[str, Any]]) -> None:
+    try:
+        CATALOG_CACHE_FILE.parent.mkdir(parents=True, exist_ok=True)
+        CATALOG_CACHE_FILE.write_text(
+            json.dumps({"base_url": base_url, "fetched_at": time.time(), "data": data}),
+            encoding="utf-8",
+        )
+    except OSError:
+        pass
+
+
+def fetch_catalog_models(*, refresh: bool = False, no_cache: bool = False) -> list[dict[str, Any]]:
+    """Fetch the public model catalog, using a one-hour local cache by default."""
+    base_url = get_api_root_url()
+    if not refresh and not no_cache:
+        cached = _read_cache(base_url)
+        if cached is not None:
+            return cached
+
+    payload = _request_json(f"{base_url}/api/models")
+    if not payload.get("success", False):
+        raise RuntimeError(payload.get("message") or "GET /api/models returned success=false")
+
+    data = payload.get("data", [])
+    if not isinstance(data, list):
+        raise RuntimeError("GET /api/models returned an unexpected data shape")
+
+    if not no_cache:
+        _write_cache(base_url, data)
+    return data
+
+
+def parse_jsonish(value: Any) -> Any:
+    """Parse JSON-in-string fields from the catalog when possible."""
+    if not isinstance(value, str):
+        return value
+    stripped = value.strip()
+    if not stripped:
+        return value
+    try:
+        return json.loads(stripped)
+    except json.JSONDecodeError:
+        return value
+
+
+def endpoint_terms(model: dict[str, Any]) -> list[str]:
+    endpoints = parse_jsonish(model.get("endpoints"))
+    if isinstance(endpoints, dict):
+        terms: list[str] = []
+        for name, detail in endpoints.items():
+            terms.append(str(name))
+            if isinstance(detail, dict):
+                for key in ("path", "method"):
+                    value = detail.get(key)
+                    if isinstance(value, str):
+                        terms.append(value)
+        return terms
+    if isinstance(endpoints, list):
+        return [str(item) for item in endpoints]
+    if endpoints:
+        return [str(endpoints)]
+    return []
+
+
+def endpoint_labels(model: dict[str, Any]) -> list[str]:
+    """Return compact endpoint labels for display."""
+    endpoints = parse_jsonish(model.get("endpoints"))
+    if isinstance(endpoints, dict):
+        return [str(name) for name in endpoints]
+    if isinstance(endpoints, list):
+        return [str(item) for item in endpoints]
+    if endpoints:
+        return [str(endpoints)]
+    return []
+
+
+def find_catalog_model(model_id: str, models: list[dict[str, Any]]) -> dict[str, Any] | None:
+    normalized = model_id.replace(".", "-")
+    for model in models:
+        if model.get("id") == model_id or model.get("code") == model_id:
+            return model
+        if model.get("code") == normalized:
+            return model
+    return None
+
+
+def fetch_model_detail(model_id: str, *, refresh: bool = False, no_cache: bool = False) -> dict[str, Any]:
+    """Fetch public model detail by model id, resolving catalog code first."""
+    models = fetch_catalog_models(refresh=refresh, no_cache=no_cache)
+    model = find_catalog_model(model_id, models)
+    code = model.get("code") if model else model_id.replace(".", "-")
+    url_code = urllib.parse.quote(str(code), safe="/")
+    payload = _request_json(f"{get_api_root_url()}/api/model/{url_code}")
+    if not payload.get("success", False):
+        raise RuntimeError(payload.get("message") or f"model not found: {model_id}")
+    data = payload.get("data")
+    if not isinstance(data, dict):
+        raise RuntimeError("GET /api/model returned an unexpected data shape")
+    return data

cometapi_cli/commands/account.py

@@ -14,7 +14,10 @@ from ..formatters import OutputFormat, output, resolve_format
 @handle_errors
 def account(
     ctx: typer.Context,
-    output_format: Annotated[OutputFormat | None, typer.Option("--format", "-f", help="Output format (table, json, yaml, csv, markdown).")] = None,
+    output_format: Annotated[
+        OutputFormat | None,
+        typer.Option("--format", "-f", help="Output format (table, json, yaml, csv, markdown)."),
+    ] = None,
     json_output: Annotated[bool, typer.Option("--json", help="Output as JSON.")] = False,
 ) -> None:
     """Show your CometAPI account profile (requires access token)."""

cometapi_cli/commands/chat.py

@@ -17,12 +17,21 @@ from ..formatters import OutputFormat, resolve_format
 def chat(
     ctx: typer.Context,
     message: Annotated[str | None, typer.Argument(help="Message to send. Omit to enter interactive REPL.")] = None,
-    model: Annotated[str | None, typer.Option("--model", "-m", help="Model to use (default: from config or gpt-5.4).")] = None,
+    model: Annotated[
+        str | None,
+        typer.Option("--model", "-m", help="Model to use (default: from config or gpt-5.4)."),
+    ] = None,
     system: Annotated[str | None, typer.Option("--system", "-s", help="System prompt.")] = None,
-    temperature: Annotated[float | None, typer.Option("--temperature", "-t", help="Sampling temperature (0.0–2.0).")] = None,
+    temperature: Annotated[
+        float | None,
+        typer.Option("--temperature", "-t", help="Sampling temperature (0.0-2.0)."),
+    ] = None,
     max_tokens: Annotated[int | None, typer.Option("--max-tokens", help="Max tokens in response.")] = None,
     stream: Annotated[bool, typer.Option("--stream/--no-stream", help="Stream output.")] = True,
-    output_format: Annotated[OutputFormat | None, typer.Option("--format", "-f", help="Output format (table, json, yaml, csv, markdown).")] = None,
+    output_format: Annotated[
+        OutputFormat | None,
+        typer.Option("--format", "-f", help="Output format (table, json, yaml, csv, markdown)."),
+    ] = None,
     json_output: Annotated[bool, typer.Option("--json", help="Output as JSON.")] = False,
 ) -> None:
     """Send a chat message, or start interactive REPL (no args)."""

cometapi_cli/commands/config_cmd.py

@@ -171,7 +171,10 @@ def init(ctx: typer.Context) -> None:
 @handle_errors
 def config_show(
     ctx: typer.Context,
-    output_format: Annotated[OutputFormat | None, typer.Option("--format", "-f", help="Output format (table, json, yaml, csv, markdown).")] = None,
+    output_format: Annotated[
+        OutputFormat | None,
+        typer.Option("--format", "-f", help="Output format (table, json, yaml, csv, markdown)."),
+    ] = None,
     json_output: Annotated[bool, typer.Option("--json", help="Output as JSON.")] = False,
 ) -> None:
     """Display current configuration (secrets are masked)."""
@@ -195,7 +198,10 @@ def config_show(
 @config_app.command("set")
 @handle_errors
 def config_set(
-    key: Annotated[str, typer.Argument(help="Configuration key (api_key, access_token, base_url, default_model, output_format).")],
+    key: Annotated[
+        str,
+        typer.Argument(help="Configuration key (api_key, access_token, base_url, default_model, output_format)."),
+    ],
     value: Annotated[str, typer.Argument(help="Value to set. For output_format: table, json, yaml, csv, markdown.")],
 ) -> None:
     """Set a configuration value.
@@ -221,7 +227,12 @@ def config_set(
 @config_app.command("unset")
 @handle_errors
 def config_unset(
-    key: Annotated[str, typer.Argument(help="Configuration key to remove (api_key, access_token, base_url, default_model, output_format).")],
+    key: Annotated[
+        str,
+        typer.Argument(
+            help="Configuration key to remove (api_key, access_token, base_url, default_model, output_format)."
+        ),
+    ],
 ) -> None:
     """Remove a configuration value."""
     cfg = load_config()

cometapi_cli/commands/doctor.py

@@ -25,7 +25,10 @@ def _warn_mark() -> str:
 @handle_errors
 def doctor(
     ctx: typer.Context,
-    output_format: Annotated[OutputFormat | None, typer.Option("--format", "-f", help="Output format (table, json, yaml, csv, markdown).")] = None,
+    output_format: Annotated[
+        OutputFormat | None,
+        typer.Option("--format", "-f", help="Output format (table, json, yaml, csv, markdown)."),
+    ] = None,
     json_output: Annotated[bool, typer.Option("--json", help="Output as JSON.")] = False,
 ) -> None:
     """Check CLI configuration and API connectivity."""

cometapi_cli/commands/logs.py

@@ -176,7 +176,10 @@ def logs(
     page: Annotated[int, typer.Option("--page", "-p", help="Page number.")] = 1,
     limit: Annotated[int, typer.Option("--limit", "-l", help="Results per page.")] = 20,
     export: Annotated[bool, typer.Option("--export", help="Export logs as CSV to stdout.")] = False,
-    output_format: Annotated[OutputFormat | None, typer.Option("--format", "-f", help="Output format (table, json, yaml, csv, markdown).")] = None,
+    output_format: Annotated[
+        OutputFormat | None,
+        typer.Option("--format", "-f", help="Output format (table, json, yaml, csv, markdown)."),
+    ] = None,
     json_output: Annotated[bool, typer.Option("--json", help="Output as JSON.")] = False,
 ) -> None:
     """Show your usage logs (requires access token)."""

cometapi_cli/commands/model.py

@@ -0,0 +1,70 @@
+"""Model detail commands."""
+
+from __future__ import annotations
+
+import re
+from typing import Annotated, Any
+
+import typer
+
+from ..catalog import endpoint_terms, fetch_model_detail
+from ..errors import handle_errors
+from ..formatters import OutputFormat, output, resolve_format
+from .models import _pricing_label
+
+model_app = typer.Typer(
+    name="model",
+    help="Inspect CometAPI model metadata.",
+    no_args_is_help=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _strip_markdown(text: str | None, *, limit: int = 360) -> str:
+    if not text:
+        return "-"
+    cleaned = re.sub(r"[`#\\*]", "", text)
+    cleaned = re.sub(r"\s+", " ", cleaned).strip()
+    if len(cleaned) > limit:
+        return cleaned[: limit - 3] + "..."
+    return cleaned or "-"
+
+
+def _format_detail(detail: dict[str, Any]) -> dict[str, Any]:
+    pricing = detail.get("pricing") if isinstance(detail.get("pricing"), dict) else {}
+    features = detail.get("features") if isinstance(detail.get("features"), list) else []
+    return {
+        "id": detail.get("id", "") or "-",
+        "code": detail.get("code", "") or "-",
+        "provider": detail.get("provider", "") or "-",
+        "model_type": detail.get("model_type", "") or "-",
+        "features": ", ".join(str(item) for item in features) or "-",
+        "endpoints": ", ".join(endpoint_terms(detail)) or "-",
+        "pricing": _pricing_label(pricing),
+        "context_length": detail.get("context_length") or "-",
+        "max_completion_tokens": detail.get("max_completion_tokens") or "-",
+        "api_doc_url": detail.get("api_doc_url") or "-",
+        "overview": _strip_markdown(detail.get("overview")),
+    }
+
+
+@model_app.command("info")
+@handle_errors
+def model_info(
+    ctx: typer.Context,
+    model_id: Annotated[str, typer.Argument(help="Model ID to inspect.")],
+    refresh: Annotated[bool, typer.Option("--refresh", help="Refresh the public catalog cache.")] = False,
+    no_cache: Annotated[bool, typer.Option("--no-cache", help="Bypass the public catalog cache.")] = False,
+    output_format: Annotated[
+        OutputFormat | None,
+        typer.Option("--format", "-f", help="Output format (table, json, yaml, csv, markdown)."),
+    ] = None,
+    json_output: Annotated[bool, typer.Option("--json", help="Output as JSON.")] = False,
+) -> None:
+    """Show public metadata for one model."""
+    fmt = resolve_format(ctx, json_output, output_format)
+    detail = fetch_model_detail(model_id, refresh=refresh, no_cache=no_cache)
+    if fmt == OutputFormat.JSON:
+        output(detail, fmt)
+        return
+    output(_format_detail(detail), fmt, title="Model Info")

cometapi_cli/commands/models.py

@@ -3,11 +3,13 @@
 from __future__ import annotations
 
 import re
+from enum import Enum
 from functools import cmp_to_key
-from typing import Annotated
+from typing import Annotated, Any
 
 import typer
 
+from ..catalog import endpoint_labels, endpoint_terms, fetch_catalog_models, parse_jsonish
 from ..config import get_client
 from ..errors import handle_errors
 from ..formatters import OutputFormat, output, resolve_format
@@ -60,11 +62,132 @@ def _compare_model_rows(left: dict[str, str], right: dict[str, str]) -> int:
     return _compare_model_ids(left["id"], right["id"])
 
 
+class ModelsSource(str, Enum):
+    """Supported model-list sources."""
+
+    CATALOG = "catalog"
+    OPENAI = "openai"
+
+
+def _csv_terms(raw: str | None) -> list[str]:
+    if raw is None:
+        return []
+    return [item.strip().lower() for item in raw.split(",") if item.strip()]
+
+
+def _contains_any(values: list[str], terms: list[str]) -> bool:
+    lowered = [value.lower() for value in values]
+    return any(term in value for term in terms for value in lowered)
+
+
+def _pricing_label(pricing: dict[str, Any]) -> str:
+    if pricing.get("per_request") is not None:
+        return f"${pricing['per_request']}/request"
+    if pricing.get("per_second") is not None:
+        return f"${pricing['per_second']}/second"
+    parts = []
+    if pricing.get("input") is not None:
+        parts.append(f"in ${pricing['input']}/M")
+    if pricing.get("output") is not None:
+        parts.append(f"out ${pricing['output']}/M")
+    return ", ".join(parts) if parts else "-"
+
+
+def _format_catalog_row(model: dict[str, Any]) -> dict[str, Any]:
+    features = model.get("features") or []
+    if not isinstance(features, list):
+        features = [str(features)]
+    pricing = model.get("pricing") if isinstance(model.get("pricing"), dict) else {}
+    return {
+        "id": model.get("id", ""),
+        "provider": model.get("provider", "") or "-",
+        "model_type": model.get("model_type", "") or "-",
+        "features": ", ".join(str(item) for item in features) or "-",
+        "endpoints": ", ".join(endpoint_labels(model)) or "-",
+        "pricing": _pricing_label(pricing),
+        "context_length": model.get("context_length") or "-",
+        "max_completion_tokens": model.get("max_completion_tokens") or "-",
+    }
+
+
+def _filter_catalog_rows(
+    models: list[dict[str, Any]],
+    *,
+    search: str | None,
+    provider: str | None,
+    model_type: str | None,
+    feature: str | None,
+    endpoint: str | None,
+) -> list[dict[str, Any]]:
+    provider_terms = _csv_terms(provider)
+    feature_terms = _csv_terms(feature)
+    endpoint_filter_terms = _csv_terms(endpoint)
+    search_term = search.lower().strip() if search else ""
+    type_term = model_type.lower().strip() if model_type else ""
+
+    rows: list[dict[str, Any]] = []
+    for model in models:
+        features = [str(item) for item in (model.get("features") or [])]
+        endpoints = endpoint_terms(model)
+        provider_values = [str(model.get("provider", "")), str(model.get("provider_code", ""))]
+        searchable = [
+            str(model.get("id", "")),
+            str(model.get("code", "")),
+            str(model.get("name", "")),
+            str(model.get("description", "")),
+            *provider_values,
+        ]
+
+        if search_term and not _contains_any(searchable, [search_term]):
+            continue
+        if provider_terms and not _contains_any(provider_values, provider_terms):
+            continue
+        if type_term and type_term not in str(model.get("model_type", "")).lower():
+            continue
+        if feature_terms and not _contains_any(features, feature_terms):
+            continue
+        if endpoint_filter_terms and not _contains_any(endpoints, endpoint_filter_terms):
+            continue
+        rows.append(_format_catalog_row({**model, "endpoints": parse_jsonish(model.get("endpoints"))}))
+    return rows
+
+
+def _openai_rows(search: str | None, limit: int | None) -> list[dict[str, str]]:
+    client = get_client()
+    rows = [{"id": m.id} for m in client.models.list()]
+    if search:
+        term = search.lower()
+        rows = [row for row in rows if term in row["id"].lower()]
+    rows = sorted(rows, key=cmp_to_key(_compare_model_rows))
+    if limit and limit > 0:
+        rows = rows[:limit]
+    return rows
+
+
 @handle_errors
 def models(
     ctx: typer.Context,
-    search: Annotated[str | None, typer.Option("--search", "-s", help="Filter models by name.")] = None,
+    search: Annotated[str | None, typer.Option("--search", "-s", help="Filter models by catalog text.")] = None,
+    provider: Annotated[str | None, typer.Option("--provider", help="Filter by provider code or name.")] = None,
+    model_type: Annotated[
+        str | None,
+        typer.Option("--type", "--modality", help="Filter by model type or modality."),
+    ] = None,
+    feature: Annotated[
+        str | None,
+        typer.Option("--feature", "--capability", help="Filter by feature or capability."),
+    ] = None,
+    endpoint: Annotated[
+        str | None,
+        typer.Option("--endpoint", help="Filter by endpoint name, method, or path."),
+    ] = None,
     limit: Annotated[int | None, typer.Option("--limit", "-l", help="Max number of models to show.")] = None,
+    source: Annotated[
+        ModelsSource,
+        typer.Option("--source", help="Model source: catalog (rich public metadata) or openai (/v1/models)."),
+    ] = ModelsSource.CATALOG,
+    refresh: Annotated[bool, typer.Option("--refresh", help="Refresh the public catalog cache.")] = False,
+    no_cache: Annotated[bool, typer.Option("--no-cache", help="Bypass the public catalog cache.")] = False,
     output_format: Annotated[
         OutputFormat | None,
         typer.Option("--format", "-f", help="Output format (table, json, yaml, csv, markdown)."),
@@ -73,23 +196,60 @@ def models(
 ) -> None:
     """List available models."""
     fmt = resolve_format(ctx, json_output, output_format)
-    client = get_client()
-    result = client.models.list()
-
-    rows = [{"id": m.id} for m in result]
-
-    if search:
-        term = search.lower()
-        rows = [r for r in rows if term in r["id"].lower()]
-
-    rows = sorted(rows, key=cmp_to_key(_compare_model_rows))
-
+    if source == ModelsSource.OPENAI:
+        rows = _openai_rows(search, limit)
+        output(rows, fmt, title=f"Available Models ({len(rows)})", columns={"id": "cyan"})
+        return
+
+    catalog_models = fetch_catalog_models(refresh=refresh, no_cache=no_cache)
+    rows = _filter_catalog_rows(
+        catalog_models,
+        search=search,
+        provider=provider,
+        model_type=model_type,
+        feature=feature,
+        endpoint=endpoint,
+    )
     if limit and limit > 0:
         rows = rows[:limit]
 
+    if fmt == OutputFormat.TABLE:
+        table_rows = [
+            {
+                "model": row["id"],
+                "prov": row["provider"],
+                "kind": row["model_type"],
+                "price": row["pricing"],
+                "endpoint": row["endpoints"],
+            }
+            for row in rows
+        ]
+        output(
+            table_rows,
+            fmt,
+            title=f"Available Models ({len(rows)})",
+            columns={
+                "model": "cyan",
+                "prov": "green",
+                "kind": "magenta",
+                "price": "red",
+                "endpoint": "blue",
+            },
+        )
+        return
+
     output(
         rows,
         fmt,
         title=f"Available Models ({len(rows)})",
-        columns={"id": "cyan"},
+        columns={
+            "id": "cyan",
+            "provider": "green",
+            "model_type": "magenta",
+            "features": "yellow",
+            "endpoints": "blue",
+            "pricing": "red",
+            "context_length": "dim",
+            "max_completion_tokens": "dim",
+        },
     )