cometapi-cli 0.2.2__tar.gz → 0.3.1__tar.gz

{cometapi_cli-0.2.2 → cometapi_cli-0.3.1}/AGENTS.md

@@ -4,7 +4,7 @@
 
 ## Overview
 
-The CLI is a Typer + Rich command-line tool that proxies all business logic through `cometapi-python`. It must **never** make direct HTTP requests — all network calls go through `CometClient` from the Python SDK.
+The CLI is a Typer + Rich command-line tool with a self-contained `CometClient`. OpenAI-compatible commands should use `CometClient` where practical. Public catalog access and multi-protocol `run` requests may use standard-library HTTP because they call CometAPI-specific catalog endpoints or non-OpenAI wire formats.
 
 ## Project Layout
 
@@ -22,14 +22,18 @@ cometapi-cli/
 │   ├── main.py                         # Backward compat shim → app.py
 │   ├── config.py                       # Config file (~/.config/cometapi/config.toml), get_client()
 │   ├── constants.py                    # Shared constants (QUOTA_PER_UNIT, helpers)
+│   ├── catalog.py                      # Public model catalog fetch/cache/detail helpers
 │   ├── console.py                      # Shared Rich Console instances
 │   ├── errors.py                       # CometCLIError hierarchy, exit codes, handle_errors decorator
 │   ├── formatters.py                   # Multi-format output (table/json/yaml/csv/markdown)
+│   ├── urls.py                         # Base URL normalization helpers
 │   └── commands/
 │       ├── __init__.py
 │       ├── chat.py                     # chat send (streaming + JSON), REPL entry
 │       ├── chat_repl.py               # Multi-turn chat REPL with prompt_toolkit
-│       ├── models.py                   # models list with search/limit
+│       ├── models.py                   # models list with catalog metadata, filters, cache, source selection
+│       ├── model.py                    # model info command group
+│       ├── run.py                      # unified request runner for chat/responses/anthropic/gemini
 │       ├── balance.py                  # account balance
 │       ├── account.py                  # user profile (access_token)
 │       ├── stats.py                    # usage statistics (access_token)
@@ -49,6 +53,9 @@ cometapi-cli/
     ├── test_errors.py                  # Error types and exit codes
     ├── test_formatters.py             # Multi-format output tests
     ├── test_models.py                  # Models command tests
+    ├── test_catalog.py                 # Catalog cache/detail tests
+    ├── test_model_info.py              # Model info command tests
+    ├── test_run.py                     # Unified runner tests
     ├── test_balance.py                 # Balance command tests (incl. --source)
     ├── test_account.py                 # Account command tests
     ├── test_stats.py                   # Stats command tests
@@ -60,7 +67,14 @@ cometapi-cli/
 ## Key Design Decisions
 
 - **Self-contained client.** `cometapi_cli/client.py` contains `CometClient` (inherits `openai.OpenAI`). The CLI has **no dependency** on the `cometapi` Python SDK package.
-- **No direct HTTP for OpenAI-compatible endpoints.** Always use inherited methods via `CometClient`. Only CometAPI-specific endpoints use `self._client.request()` directly.
+- **Prefer `CometClient` for OpenAI-compatible commands.** Use inherited methods via `CometClient` for normal SDK-shaped flows. Standard-library HTTP is acceptable for public catalog endpoints and `run` endpoint formats that intentionally bypass the OpenAI SDK surface.
+
+## Documentation Policy
+
+- **README is the PyPI homepage.** User-facing CLI features must be understandable from `README.md` without access to the private repository.
+- **Every user-visible CLI change must update docs in the same change.** New commands, renamed commands, new options, changed defaults, output-shape changes, or behavior changes must update `README.md`, the relevant file under `docs/`, and the public docs site pages under `docs-cometapi/libraries/cli/`.
+- **Help output is the command contract.** For option or argument changes, run `uv run cometapi -h` and the affected `uv run cometapi <command> -h` commands, then align README and docs with the generated help.
+- **Public links must stay public.** Do not add PyPI metadata or README links that require access to the private GitHub repository. Use PyPI and the public docs site for user-facing navigation.
 
 ## Model ID Policy
 
@@ -184,14 +198,68 @@ These options apply to **every** command via the root Typer callback.
 
 | Parameter | Alias | Type | Default | Description |
 |-----------|-------|------|---------|-------------|
-| `--search` | `-s` | `str` | `None` | Filter models by name (case-insensitive substring match) |
+| `--search` | `-s` | `str` | `None` | Filter models by ID, code, name, description, or provider |
+| `--provider` | — | `str` | `None` | Filter by provider code or name |
+| `--type` | `--modality` | `str` | `None` | Filter by model type or modality |
+| `--feature` | `--capability` | `str` | `None` | Filter by feature or capability |
+| `--endpoint` | — | `str` | `None` | Filter by endpoint name, method, or path |
 | `--limit` | `-l` | `int` | `None` (show all) | Maximum number of models to display |
+| `--source` | — | `catalog\|openai` | `catalog` | Source: public catalog metadata or OpenAI-compatible `/v1/models` |
+| `--refresh` | — | flag | `false` | Refresh the public catalog cache |
+| `--no-cache` | — | flag | `false` | Bypass the public catalog cache |
 | `--format` | `-f` | `OutputFormat` | inherits global | Per-command output format override |
 | `--json` | — | flag | `false` | Output as JSON |
 
-**Behavior:** Fetches all models via `client.models.list()`, applies `--search`, sorts model IDs in descending natural/version-aware order so newer variants surface first, then applies `--limit`.
+**Behavior:**
+- Default source calls public `GET /api/models` and caches results for one hour at `~/.cache/cometapi/models.json`.
+- Catalog source supports `--provider`, `--type/--modality`, `--feature/--capability`, `--endpoint`, `--search`, `--limit`, `--refresh`, and `--no-cache`.
+- `--source openai` calls `client.models.list()` for `/v1/models` compatibility and supports `--search` plus `--limit`.
+
+**Catalog output fields:** `id`, `provider`, `model_type`, `features`, `endpoints`, `pricing`, `context_length`, `max_completion_tokens`.
+
+---
+
+### `model info` — Show one model's public metadata
+
+**Auth:** `COMETAPI_KEY`
+
+| Parameter | Alias | Type | Default | Description |
+|-----------|-------|------|---------|-------------|
+| `MODEL_ID` | — | argument | required | Model ID to inspect |
+| `--refresh` | — | flag | `false` | Refresh the public catalog cache before lookup |
+| `--no-cache` | — | flag | `false` | Bypass the public catalog cache |
+| `--format` | `-f` | `OutputFormat` | inherits global | Per-command output format override |
+| `--json` | — | flag | `false` | Output raw detail JSON |
+
+**Behavior:** Resolves `MODEL_ID` against the public catalog, uses the catalog `code` to request `GET /api/model/{code}`, then displays detail metadata. Supports slash-style and dotted model IDs.
+
+**Table fields:** `id`, `code`, `provider`, `model_type`, `features`, `endpoints`, `pricing`, `context_length`, `max_completion_tokens`, `api_doc_url`, `overview`.
+
+---
+
+### `run` — Send one request through a selected endpoint format
+
+**Auth:** `COMETAPI_KEY`
+
+| Parameter | Alias | Type | Default | Description |
+|-----------|-------|------|---------|-------------|
+| `MODEL` | — | argument, optional | `body.model` or config default | Model ID; overrides `body.model` |
+| `--endpoint` | `-e` | `chat\|responses\|anthropic\|gemini` | `chat` | Endpoint format |
+| `--input-file` | — | path | `None` | JSON object request body |
+| `--input` | `-i` | `key=value` | repeatable | Merge inline request fields into the body |
+| `--prompt` | `-p` | `str` | `None` | Prompt shortcut |
+| `--json` | — | flag | `false` | Output raw JSON response |
+
+**Endpoint mapping:**
+
+| Endpoint | Method and path | Auth header |
+|----------|-----------------|-------------|
+| `chat` | `POST /v1/chat/completions` | `Authorization: Bearer $COMETAPI_KEY` |
+| `responses` | `POST /v1/responses` | `Authorization: Bearer $COMETAPI_KEY` |
+| `anthropic` | `POST /v1/messages` | `x-api-key: $COMETAPI_KEY`, plus `anthropic-version: 2023-06-01` |
+| `gemini` | `POST /v1beta/models/{model}:generateContent` | `x-goog-api-key: $COMETAPI_KEY` |
 
-**Table columns:** `id` (cyan).
+**Body merge order:** `--input-file` JSON object → repeated `-i key=value` values → `-p/--prompt` shortcut → positional `MODEL` override. Inline values parse JSON when possible and dotted keys create nested objects.
 
 ---
 
@@ -460,11 +528,11 @@ When `cometapi chat` is started without a message, these slash commands are avai
 ## Build & Test
 
 ```bash
-uv sync                         # Install deps (links local cometapi-python)
+uv sync                         # Install dependencies
 uv run cometapi --version        # Verify CLI version
 uv run cometapi -h               # List all commands
 uv run cometapi doctor           # Check configuration health
-uv run pytest -v                 # Run tests (98 tests)
+uv run pytest -v                 # Run tests
 uv run ruff check src/ tests/    # Lint
 ```
 
@@ -489,7 +557,7 @@ uv run ruff check src/ tests/    # Lint
 
 ## Dependencies
 
-- `cometapi` — CometAPI Python SDK (local editable in dev)
+- `openai>=1.0.0` — OpenAI-compatible client base
 - `typer>=0.12` — CLI framework
 - `rich>=13.0` — Terminal UI
 - `tomli>=2.0` — TOML reading (Python 3.10 only; 3.11+ uses stdlib `tomllib`)

{cometapi_cli-0.2.2 → cometapi_cli-0.3.1}/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] — 2026-05-29
+
+### Fixed
+
+- `logs` now emits a consistent field set across all output formats. Previously `--json` dumped the raw API response (no computed `cost`, `other` left as a stringified blob, internal junk fields), while `table`/`yaml`/`markdown` showed a curated card.
+- `logs --request-id` detail duration now reflects true end-to-end latency (`other.total_ms`) instead of the coarse `use_time` seconds value.
+- `logs --request-id` cost now shows 6 decimal places (e.g. `$0.000384`) so sub-cent calls are no longer rounded to `$0.0004`.
+
+### Changed
+
+- `logs` JSON/YAML output is now a canonical, typed record (raw numbers, booleans, ISO 8601 time, computed `cost_usd`, exploded `other` fields, normalized `model_price`) with a stable schema; `table`/`markdown` render the same fields as formatted strings.
+
+## [0.3.0] — 2026-05-26
+
+### Added
+
+- `models` now reads the public model catalog by default, with OpenAI-compatible `/v1/models` kept as `--source openai`.
+- `models` includes provider, type, features, endpoints, pricing, context length, and completion token metadata when catalog data is available.
+- `models` supports catalog filtering by provider, modality/type, feature/capability, endpoint, text search, limit, cache refresh, and cache bypass.
+- `model info <id>` shows detailed catalog metadata for a model and supports raw JSON output.
+- `run` provides a unified execution entrypoint for chat completions, responses, Anthropic messages, and Gemini generateContent.
+- `run` supports JSON input files, repeated `-i key=value` body overrides, prompt shortcuts, and raw JSON response output.
+
+### Changed
+
+- README and command docs now position PyPI as the public package homepage and document the enhanced model catalog and unified run workflow.
+- Package metadata now points to the PyPI homepage and public CLI documentation instead of private GitHub links.
+- Agent instructions now require user-visible CLI changes to update README, local docs, and public docs together.
+
 ## [0.2.2] — 2026-04-14
 
 ### Changed

cometapi_cli-0.3.1/PKG-INFO

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: cometapi-cli
+Version: 0.3.1
+Summary: CometAPI CLI — official command-line interface for the CometAPI AI gateway
+Project-URL: Homepage, https://pypi.org/project/cometapi-cli/
+Project-URL: Documentation, https://apidoc.cometapi.com/libraries/cli/overview
+Author-email: CometAPI <support@cometapi.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,api-gateway,chat,cli,cometapi,llm,openai,streaming
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: openai>=1.0.0
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CometAPI CLI
+
+[![PyPI](https://img.shields.io/pypi/v/cometapi-cli)](https://pypi.org/project/cometapi-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/cometapi-cli)](https://pypi.org/project/cometapi-cli/)
+
+Official command-line interface for [CometAPI](https://www.cometapi.com/?utm_source=cometapi-cli&utm_medium=readme&utm_campaign=pypi&utm_content=homepage), a multi-model AI gateway for GPT, Claude, Gemini, image, audio, and video models.
+
+The [PyPI package page](https://pypi.org/project/cometapi-cli/) is the public homepage for installation and release metadata. The public documentation is available at [CometAPI CLI docs](https://apidoc.cometapi.com/libraries/cli/overview).
+
+## Features
+
+- Chat with CometAPI models from the terminal, with streaming and an interactive REPL
+- Browse the public model catalog with provider, modality, endpoint, capability, context, and pricing metadata
+- Inspect one model with `cometapi model info <id>`
+- Send one request through OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, or Gemini Generate Content with `cometapi run`
+- Check balance, account data, usage stats, API keys, logs, and async task history
+- Output tables, JSON, YAML, CSV, or Markdown for terminal use and automation
+- Store local configuration in `~/.config/cometapi/config.toml`
+
+## Installation
+
+The CLI requires Python 3.10 or later.
+
+```bash
+pip install cometapi-cli
+```
+
+You can also install it in an isolated tool environment:
+
+```bash
+pipx install cometapi-cli
+uv tool install cometapi-cli
+```
+
+Create an API key in the [CometAPI console](https://www.cometapi.com/console/token?utm_source=cometapi-cli&utm_medium=readme&utm_campaign=pypi&utm_content=api-key). Account-management commands can also use an optional [access token](https://www.cometapi.com/console/personal?utm_source=cometapi-cli&utm_medium=readme&utm_campaign=pypi&utm_content=access-token).
+
+## Quick start
+
+Run the setup wizard:
+
+```bash
+cometapi init
+```
+
+Or configure credentials with environment variables:
+
+```bash
+export COMETAPI_KEY="your-api-key"
+export COMETAPI_ACCESS_TOKEN="your-access-token"  # optional, for account/log/task commands
+```
+
+Verify the installation and available commands:
+
+```bash
+cometapi --version
+cometapi -h
+cometapi doctor
+```
+
+Send a chat message:
+
+```bash
+cometapi chat "Explain quantum computing in one sentence"
+```
+
+Search the model catalog:
+
+```bash
+cometapi models --search gpt --limit 10
+```
+
+Inspect one model:
+
+```bash
+cometapi model info your-model-id
+```
+
+Run a one-off request through the default chat endpoint:
+
+```bash
+cometapi run your-model-id -p "Reply with OK only."
+```
+
+## Command reference
+
+Use `-h` on the root command or any subcommand to see the exact options for the installed version:
+
+```bash
+cometapi -h
+cometapi models -h
+cometapi model info -h
+cometapi run -h
+```
+
+| Command | Description | Credential |
+|---------|-------------|------------|
+| `chat [MESSAGE]` | Send a chat message or start the chat REPL | API key |
+| `models` | List and filter public model catalog metadata | API key |
+| `model info <id>` | Show provider, endpoint, capability, context, pricing, and docs metadata for one model | API key |
+| `run [MODEL]` | Send one request through chat, responses, anthropic, or gemini endpoint formats | API key |
+| `balance` | Show account or current API key balance | API key or access token |
+| `account` | Show account profile | Access token |
+| `stats` | Show usage statistics | Access token |
+| `tokens` | List and search API keys | Access token |
+| `logs` | Browse usage logs and export CSV | Access token |
+| `tasks` | Browse async task logs | Access token |
+| `init` | Run the interactive setup wizard | None |
+| `doctor` | Check configuration and connectivity | API key |
+| `repl` | Start an interactive command shell | Depends on command used |
+| `config` | Show, set, unset, or locate local configuration | None |
+
+## Models
+
+`cometapi models` uses the public model catalog by default and displays richer metadata than `/v1/models`.
+
+```bash
+# Search by keyword
+cometapi models --search gpt --limit 10
+
+# Filter by provider, modality, capability, or endpoint
+cometapi models --provider openai --type chat --limit 10
+cometapi models --feature image --endpoint responses --json
+
+# Refresh the one-hour local cache
+cometapi models --refresh
+
+# Use the OpenAI-compatible /v1/models source
+cometapi models --source openai --search gpt
+```
+
+Catalog rows include:
+
+- `id`
+- `provider`
+- `model_type`
+- `features`
+- `endpoints`
+- `pricing`
+- `context_length`
+- `max_completion_tokens`
+
+The catalog cache is stored at `~/.cache/cometapi/models.json`. Use `--refresh` to replace stale cache data or `--no-cache` to bypass the cache for one command.
+
+## Model info
+
+Use `cometapi model info <id>` when you need the detail page metadata for one model.
+
+```bash
+# Human-readable table
+cometapi model info your-model-id
+
+# Raw model detail JSON
+cometapi model info your-model-id --json
+
+# Refresh catalog metadata before resolving the model
+cometapi model info your-model-id --refresh
+```
+
+The command resolves the public catalog entry first, then loads detail metadata from the model detail API. It supports slash-style model IDs and dotted IDs.
+
+## Run
+
+`cometapi run` is a unified request entrypoint for CometAPI's multi-protocol gateway. It accepts an optional positional model, a JSON request body, repeated inline inputs, and a prompt shortcut.
+
+```bash
+# OpenAI Chat Completions format (default)
+cometapi run your-model-id -p "Write one sentence about CometAPI."
+
+# OpenAI Responses format
+cometapi run your-model-id --endpoint responses -p "Reply with OK only." -i max_output_tokens=32 --json
+
+# Anthropic Messages format
+cometapi run your-model-id --endpoint anthropic -p "Reply with OK only." -i max_tokens=32
+
+# Gemini Generate Content format
+cometapi run your-model-id --endpoint gemini -p "Reply with OK only." -i generationConfig.maxOutputTokens=32
+```
+
+Build a request from a JSON file and override fields inline:
+
+```bash
+cometapi run your-model-id \
+  --endpoint responses \
+  --input-file body.json \
+  -i temperature=0.2 \
+  -i metadata.source='"cli"' \
+  --json
+```
+
+Input precedence is:
+
+1. `--input-file` JSON object
+2. Repeated `-i key=value` values
+3. `-p/--prompt` convenience body
+4. Positional `MODEL`, which overrides `body.model`
+
+`-i key=value` parses JSON values when possible, so numbers, booleans, `null`, objects, and arrays can be passed without string coercion. Dotted keys create nested JSON objects.
+
+## Output formats
+
+Most data commands support `--json` or `--format`:
+
+```bash
+cometapi models --json
+cometapi models --format yaml
+cometapi stats --format csv
+cometapi account --format markdown
+```
+
+Set a persistent default format:
+
+```bash
+cometapi config set output_format json
+```
+
+## Configuration
+
+Config file: `~/.config/cometapi/config.toml`
+
+```bash
+cometapi config show
+cometapi config set api_key "$COMETAPI_KEY"
+cometapi config set default_model your-model-id
+cometapi config unset api_key
+cometapi config path
+```
+
+| Key | Env variable | Description |
+|-----|--------------|-------------|
+| `api_key` | `COMETAPI_KEY` | API key for model and balance commands |
+| `access_token` | `COMETAPI_ACCESS_TOKEN` | Access token for account, stats, token, log, and task commands |
+| `base_url` | `COMETAPI_BASE_URL` | API base URL |
+| `default_model` | `COMETAPI_DEFAULT_MODEL` | Default model for `chat` and `run` |
+| `output_format` | - | Default output format |
+
+Configuration priority: CLI flags > config file > environment variables > defaults.
+
+## Chat REPL
+
+Run `cometapi chat` without a message to start a multi-turn chat session.
+
+```bash
+cometapi chat
+```
+
+Available slash commands:
+
+| Command | Description |
+|---------|-------------|
+| `/model <name>` | Switch model mid-conversation |
+| `/system <prompt>` | Set the system prompt |
+| `/clear` | Clear conversation history |
+| `/history` | Show conversation history |
+| `/save <file.json|file.md>` | Save the session |
+| `/tokens` | Show approximate token count |
+| `/help` | Show REPL help |
+| `/exit` | Exit the REPL |
+
+## Security
+
+- API keys and access tokens are never displayed in full by CLI diagnostics.
+- Config files are stored with restrictive permissions (`0600`).
+- Keep credentials out of source control and shell history.
+- You are responsible for usage and charges incurred with your API keys.
+
+## Troubleshooting
+
+| Error | Fix |
+|-------|-----|
+| `API key not configured` | Run `cometapi init` or set `COMETAPI_KEY` |
+| `Connection failed` | Run `cometapi doctor` |
+| `Access token not configured` | Set `COMETAPI_ACCESS_TOKEN` only when using account, stats, tokens, logs, or tasks |
+
+## License
+
+MIT