cometapi-cli 0.2.2__py3-none-any.whl → 0.3.1__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.1"

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

@@ -9,7 +9,14 @@ from typing import Annotated
 import typer
 
 from ..config import get_client
-from ..constants import extract_items, format_ts, parse_date, quota_to_usd
+from ..constants import (
+    QUOTA_PER_UNIT,
+    extract_items,
+    format_iso,
+    format_ts,
+    parse_date,
+    quota_to_usd,
+)
 from ..errors import handle_errors
 from ..formatters import OutputFormat, output, resolve_format
 
@@ -70,61 +77,111 @@ def _find_log_by_id(
     return None
 
 
-def _format_log_detail(log: dict) -> dict:
-    """Build a rich key-value detail card from a single log entry."""
+def _build_log_record(log: dict) -> dict:
+    """Build the canonical, machine-friendly record for a single log entry.
+
+    Returns a stable schema with raw, typed values (numbers, booleans, ISO 8601
+    time). The same field set drives every output format; human-facing formats
+    layer display formatting on top via :func:`_record_to_detail_display`.
+    Missing values are ``None`` so the schema stays consistent across entries.
+    """
     other = _parse_other(log.get("other"))
-    prompt_tokens = log.get("prompt_tokens", 0)
-    completion_tokens = log.get("completion_tokens", 0)
-    quota = log.get("quota", 0)
+    quota = log.get("quota", 0) or 0
+
+    # model_price == -1 is the backend sentinel for "use ratio-based pricing"
+    # (i.e. no fixed per-call price); expose it as null in the canonical record.
+    raw_model_price = other.get("model_price")
+    model_price = None if raw_model_price == -1 else raw_model_price
+
+    # Prefer total_ms (true end-to-end latency) over use_time, which the backend
+    # records in seconds and is too coarse to be useful as a duration.
+    total_ms = other.get("total_ms")
+    use_time = log.get("use_time", 0) or 0
+    duration_ms = total_ms if total_ms else (use_time or None)
+
+    frt = other.get("frt")
+    user_id = log.get("user_id")
+
+    return {
+        "request_id": log.get("request_id") or None,
+        "response_id": log.get("response_id") or None,
+        "time": format_iso(log.get("created_at", 0)),
+        "type": _LOG_TYPE_NAMES.get(log.get("type", 0), "unknown"),
+        "model": log.get("model_name") or None,
+        "token_name": log.get("token_name") or None,
+        "username": log.get("username") or None,
+        "user_id": user_id if user_id else None,
+        "ip": log.get("ip") or None,
+        "stream": bool(log.get("is_stream")),
+        "prompt_tokens": log.get("prompt_tokens", 0) or 0,
+        "completion_tokens": log.get("completion_tokens", 0) or 0,
+        "cache_tokens": other.get("cache_tokens", 0) or 0,
+        "cost_usd": round(quota / QUOTA_PER_UNIT, 6),
+        "quota": quota,
+        "model_ratio": other.get("model_ratio"),
+        "completion_ratio": other.get("completion_ratio"),
+        "group_ratio": other.get("group_ratio"),
+        "model_price": model_price,
+        "cache_ratio": other.get("cache_ratio"),
+        "duration_ms": duration_ms,
+        "first_token_ms": frt if frt and frt > 0 else None,
+        "endpoint": other.get("request_path") or None,
+    }
+
 
+def _record_to_detail_display(rec: dict) -> dict:
+    """Render a canonical log record as a formatted key-value detail card.
+
+    Mirrors the field set of :func:`_build_log_record` but uses human-friendly
+    labels and formatted strings (USD, ``Yes``/``No``, ``ms``). Optional fields
+    are omitted when absent to keep the card readable.
+    """
+    em_dash = "—"
     info: dict[str, str | int | float] = {}
-    info["Request ID"] = log.get("request_id", "") or "—"
-    info["Response ID"] = log.get("response_id", "") or "—"
-    info["Time"] = format_ts(log.get("created_at", 0))
-    info["Model"] = log.get("model_name", "") or "—"
-    info["Token Name"] = log.get("token_name", "") or "—"
-    info["Group"] = log.get("group", "") or "—"
-    info["Stream"] = "Yes" if log.get("is_stream") else "No"
+    info["Request ID"] = rec["request_id"] or em_dash
+    info["Response ID"] = rec["response_id"] or em_dash
+    iso = rec["time"]
+    info["Time"] = iso[:19].replace("T", " ") if iso else em_dash
+    info["Model"] = rec["model"] or em_dash
+    info["Token Name"] = rec["token_name"] or em_dash
+    if rec["username"]:
+        info["Username"] = rec["username"]
+    if rec["user_id"] is not None:
+        info["User ID"] = rec["user_id"]
+    if rec["ip"]:
+        info["IP"] = rec["ip"]
+    info["Type"] = rec["type"]
+    info["Stream"] = "Yes" if rec["stream"] else "No"
 
     # Tokens
-    info["Prompt Tokens"] = f"{prompt_tokens:,}"
-    info["Completion Tokens"] = f"{completion_tokens:,}"
-    cache_tokens = other.get("cache_tokens", 0)
-    if cache_tokens:
-        info["Cache Tokens"] = f"{cache_tokens:,}"
-
-    # Cost
-    info["Cost (USD)"] = quota_to_usd(quota)
-    info["Quota (raw)"] = f"{quota:,}"
-
-    # Pricing breakdown from 'other'
-    model_ratio = other.get("model_ratio")
-    if model_ratio is not None:
-        info["Model Ratio"] = model_ratio
-    completion_ratio = other.get("completion_ratio")
-    if completion_ratio is not None:
-        info["Completion Ratio"] = f"{completion_ratio}x"
-    group_ratio = other.get("group_ratio")
-    if group_ratio is not None:
-        info["Group Ratio"] = group_ratio
-    model_price = other.get("model_price")
-    if model_price is not None:
-        info["Model Price"] = "default" if model_price == -1 else model_price
-    cache_ratio = other.get("cache_ratio")
-    if cache_ratio is not None:
-        info["Cache Ratio"] = cache_ratio
+    info["Prompt Tokens"] = f"{rec['prompt_tokens']:,}"
+    info["Completion Tokens"] = f"{rec['completion_tokens']:,}"
+    if rec["cache_tokens"]:
+        info["Cache Tokens"] = f"{rec['cache_tokens']:,}"
+
+    # Cost (6 decimals so sub-cent calls are not rounded away)
+    info["Cost (USD)"] = f"${rec['cost_usd']:,.6f}"
+    info["Quota (raw)"] = f"{rec['quota']:,}"
+
+    # Pricing breakdown
+    if rec["model_ratio"] is not None:
+        info["Model Ratio"] = rec["model_ratio"]
+    if rec["completion_ratio"] is not None:
+        info["Completion Ratio"] = f"{rec['completion_ratio']}x"
+    if rec["group_ratio"] is not None:
+        info["Group Ratio"] = rec["group_ratio"]
+    info["Model Price"] = "default" if rec["model_price"] is None else rec["model_price"]
+    if rec["cache_ratio"] is not None:
+        info["Cache Ratio"] = rec["cache_ratio"]
 
     # Timing
-    use_time = log.get("use_time", 0)
-    info["Duration"] = f"{use_time:,} ms" if use_time else "—"
-    frt = other.get("frt")
-    if frt and frt > 0:
-        info["First Token"] = f"{frt:,} ms"
+    info["Duration"] = f"{rec['duration_ms']:,} ms" if rec["duration_ms"] else em_dash
+    if rec["first_token_ms"]:
+        info["First Token"] = f"{rec['first_token_ms']:,} ms"
 
     # Path
-    request_path = other.get("request_path")
-    if request_path:
-        info["Endpoint"] = request_path
+    if rec["endpoint"]:
+        info["Endpoint"] = rec["endpoint"]
 
     return info
 
@@ -176,7 +233,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)."""
@@ -218,12 +278,13 @@ def logs(
             )
             raise typer.Exit(code=1)
 
-        if fmt == OutputFormat.JSON:
-            output(log_entry, fmt)
+        record = _build_log_record(log_entry)
+        # Machine formats get raw typed values; human formats get the formatted card.
+        if fmt in (OutputFormat.JSON, OutputFormat.YAML, OutputFormat.CSV):
+            output(record, fmt)
             return
 
-        info = _format_log_detail(log_entry)
-        output(info, fmt, title="Request Detail")
+        output(_record_to_detail_display(record), fmt, title="Request Detail")
         return
 
     # Server-side CSV export — write raw bytes to stdout and return early
@@ -267,8 +328,10 @@ def logs(
 
     data = extract_items(resp)
 
-    if fmt == OutputFormat.JSON:
-        output(data, fmt)
+    # Machine formats emit the full canonical record per entry (typed values,
+    # incl. cost_usd); table/markdown/csv keep the compact summary rows.
+    if fmt in (OutputFormat.JSON, OutputFormat.YAML):
+        output([_build_log_record(log) for log in data], fmt)
         return
 
     if not data:

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")