tokenroute 0.1.0__tar.gz

tokenroute-0.1.0/.gitignore

@@ -0,0 +1,69 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+env/
+*.egg-info/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+
+# Node / Next.js (storefront, P3)
+node_modules/
+.next/
+.turbo/
+*.tsbuildinfo
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Env / secrets
+.env
+.env.local
+.env.*.local
+!.env.example
+
+# Local DBs / logs
+*.db
+*.sqlite
+*.sqlite3
+*.log
+logs/
+
+# Alembic
+gateway/migrations/versions/*.pyc
+
+# pytest
+.pytest_cache/
+
+# Docker
+infra/volumes/
+
+# Local-only scratch (CI keypairs, throwaway artifacts)
+.tmp/
+.dev-logs/
+
+# Claude Code session state
+.claude/
+
+# Stripe API debug dumps（手动 curl 后 saved，绝不入库）
+gateway/*.json
+!gateway/package.json
+!gateway/tsconfig.json

tokenroute-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: tokenroute
+Version: 0.1.0
+Summary: Agent-first CLI for tokenroute — OpenAI-compatible LLM gateway with smart routing and transparent billing
+Project-URL: Homepage, https://tokenroute.io
+Project-URL: Documentation, https://docs.tokenroute.io
+Project-URL: Repository, https://github.com/jiangjin11/tokenroute
+Author: Paradigx Pte Ltd
+License: MIT
+Keywords: agent,ai,anthropic,cli,gateway,llm,openai
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28
+Requires-Dist: rich>=13.0
+Requires-Dist: typer<1.0,>=0.15
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.14; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tokenroute (Python CLI)
+
+Agent-first CLI for [tokenroute](https://tokenroute.io) — the OpenAI-compatible LLM API gateway with smart routing and transparent token billing.
+
+## Install
+
+```bash
+pip install tokenroute
+# or, run once without installing:
+uvx tokenroute --help
+pipx run tokenroute --help
+```
+
+## Quickstart
+
+```bash
+tokenroute login                                 # OAuth device-flow, opens browser
+tokenroute whoami                                # current user + balance
+tokenroute keys create --name my-app             # create new sk-tr-* key
+tokenroute balance                               # current credit
+```
+
+All commands accept `--json` (or env `TOKENROUTE_JSON=1`) for machine-parseable output that's friendly to agents and CI.
+
+## Agent / sub-agent usage (no interactive login)
+
+For automation, skip `tokenroute login` and call the OpenAI-compatible API directly with a pre-issued key:
+
+```bash
+export TOKENROUTE_API_KEY=sk-tr-...
+curl https://api.tokenroute.io/v1/chat/completions \
+  -H "Authorization: Bearer $TOKENROUTE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'
+```
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `TOKENROUTE_API_URL` | `https://api.tokenroute.io` | Override gateway base URL |
+| `TOKENROUTE_API_KEY` | _(unset)_ | sk-tr-* key for LLM calls — skips `login` |
+| `TOKENROUTE_JSON` | _(unset)_ | Set to `1` to force JSON output globally |
+
+Credentials from `tokenroute login` are stored at `~/.tokenroute/credentials.json` (owner-readable only on POSIX).
+
+## License
+
+MIT

tokenroute-0.1.0/README.md

@@ -0,0 +1,49 @@
+# tokenroute (Python CLI)
+
+Agent-first CLI for [tokenroute](https://tokenroute.io) — the OpenAI-compatible LLM API gateway with smart routing and transparent token billing.
+
+## Install
+
+```bash
+pip install tokenroute
+# or, run once without installing:
+uvx tokenroute --help
+pipx run tokenroute --help
+```
+
+## Quickstart
+
+```bash
+tokenroute login                                 # OAuth device-flow, opens browser
+tokenroute whoami                                # current user + balance
+tokenroute keys create --name my-app             # create new sk-tr-* key
+tokenroute balance                               # current credit
+```
+
+All commands accept `--json` (or env `TOKENROUTE_JSON=1`) for machine-parseable output that's friendly to agents and CI.
+
+## Agent / sub-agent usage (no interactive login)
+
+For automation, skip `tokenroute login` and call the OpenAI-compatible API directly with a pre-issued key:
+
+```bash
+export TOKENROUTE_API_KEY=sk-tr-...
+curl https://api.tokenroute.io/v1/chat/completions \
+  -H "Authorization: Bearer $TOKENROUTE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'
+```
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `TOKENROUTE_API_URL` | `https://api.tokenroute.io` | Override gateway base URL |
+| `TOKENROUTE_API_KEY` | _(unset)_ | sk-tr-* key for LLM calls — skips `login` |
+| `TOKENROUTE_JSON` | _(unset)_ | Set to `1` to force JSON output globally |
+
+Credentials from `tokenroute login` are stored at `~/.tokenroute/credentials.json` (owner-readable only on POSIX).
+
+## License
+
+MIT

tokenroute-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "tokenroute"
+version = "0.1.0"
+description = "Agent-first CLI for tokenroute — OpenAI-compatible LLM gateway with smart routing and transparent billing"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Paradigx Pte Ltd" }]
+keywords = ["llm", "openai", "anthropic", "gateway", "agent", "cli", "ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+    "typer>=0.15,<1.0",
+    "httpx>=0.28",
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3",
+    "pytest-mock>=3.14",
+]
+
+[project.urls]
+Homepage = "https://tokenroute.io"
+Documentation = "https://docs.tokenroute.io"
+Repository = "https://github.com/jiangjin11/tokenroute"
+
+[project.scripts]
+tokenroute = "tokenroute_cli.__main__:app"
+
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tokenroute_cli"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tokenroute-0.1.0/src/tokenroute_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

tokenroute-0.1.0/src/tokenroute_cli/__main__.py

@@ -0,0 +1,334 @@
+"""tokenroute CLI entry point.
+
+  tokenroute login                          # OAuth device-flow
+  tokenroute logout
+  tokenroute whoami                         # user + balance
+  tokenroute balance
+  tokenroute keys create --name <n>
+  tokenroute keys list
+  tokenroute keys revoke <id>
+
+All commands accept `--json` (or env TOKENROUTE_JSON=1) for agent-friendly
+machine-parseable output. Authentication: `tokenroute login` writes
+~/.tokenroute/credentials.json; subsequent commands re-use it.
+"""
+from __future__ import annotations
+
+import os
+import time
+
+import typer
+
+from . import __version__
+from .client import ApiError, request
+from .config import (
+    Credentials,
+    api_url,
+    clear_credentials,
+    resolve_api_key,
+    save_credentials,
+    save_last_key,
+)
+from .device_flow import fetch_discovery, open_browser, poll_for_token, request_device_code
+from .output import emit, error, info, success
+
+app = typer.Typer(
+    name="tokenroute",
+    help="Agent-first CLI for tokenroute LLM gateway.",
+    add_completion=False,
+    no_args_is_help=True,
+)
+keys_app = typer.Typer(name="keys", help="Manage your tokenroute API keys.", no_args_is_help=True)
+app.add_typer(keys_app, name="keys")
+
+
+def _global_callback(
+    json_output: bool = typer.Option(
+        False, "--json", help="Machine-parseable JSON output (for agents / scripts)."
+    ),
+) -> None:
+    if json_output or os.environ.get("TOKENROUTE_JSON") == "1":
+        os.environ["_TOKENROUTE_OUTPUT_JSON"] = "1"
+
+
+app.callback()(_global_callback)
+
+
+# ─── login / logout / whoami ─────────────────────────────────────────
+
+
+@app.command()
+def login() -> None:
+    """Log in via OAuth device-flow (opens browser)."""
+    try:
+        disc = fetch_discovery()
+    except Exception as e:
+        error(f"could not reach tokenroute API: {e}", code=2)
+
+    try:
+        code = request_device_code(disc)
+    except Exception as e:
+        error(f"device-flow init failed: {e}", code=3)
+
+    info(f"\nVisit: [bold cyan]{code.verification_uri}[/bold cyan]")
+    info(f"And enter code: [bold yellow]{code.user_code}[/bold yellow]\n")
+    info("(opening browser automatically — if it doesn't, use the URL above)")
+    open_browser(code.verification_uri_complete)
+
+    info("Waiting for authorization...")
+    try:
+        token = poll_for_token(disc, code)
+    except RuntimeError as e:
+        error(str(e), code=3)
+
+    expires_at = int(time.time()) + int(token.get("expires_in", 3600))
+    save_credentials(
+        Credentials(
+            access_token=token["access_token"],
+            refresh_token=token.get("refresh_token"),
+            expires_at=expires_at,
+            issuer=disc.issuer,
+            client_id=disc.client_id,
+        )
+    )
+    success("logged in")
+
+
+@app.command()
+def logout() -> None:
+    """Forget locally stored credentials."""
+    if clear_credentials():
+        success("logged out")
+    else:
+        info("(no stored credentials)")
+
+
+@app.command()
+def whoami() -> None:
+    """Show current user + balance."""
+    try:
+        me = request("GET", "/api/v1/me")
+    except ApiError as e:
+        error(e.message, code=1 if e.status < 500 else 3)
+    emit(me)
+
+
+@app.command()
+def balance() -> None:
+    """Show available credit balance."""
+    try:
+        body = request("GET", "/api/v1/balance")
+    except ApiError as e:
+        error(e.message, code=1 if e.status < 500 else 3)
+    emit(body)
+
+
+# ─── keys subcommands ────────────────────────────────────────────────
+
+
+@keys_app.command("create")
+def keys_create(
+    name: str = typer.Option(..., "--name", "-n", help="Human-friendly key label."),
+    no_cache: bool = typer.Option(
+        False, "--no-cache", help="Don't save raw key to ~/.tokenroute/last_key.txt"
+    ),
+) -> None:
+    """Create a new sk-tr-* API key. The raw key is shown ONCE."""
+    try:
+        out = request("POST", "/api/v1/me/keys", json_body={"name": name})
+    except ApiError as e:
+        error(e.message, code=1 if e.status < 500 else 3)
+    raw = out.get("raw")
+    if raw and not no_cache:
+        save_last_key(raw)
+    emit(out)
+    if not os.environ.get("_TOKENROUTE_OUTPUT_JSON"):
+        info("\n[yellow]Save the `raw` key — it won't be shown again.[/yellow]")
+        if raw and not no_cache:
+            info(
+                "[dim]Cached at ~/.tokenroute/last_key.txt for `env` / `test` / `models`. "
+                "Pass --no-cache to skip.[/dim]"
+            )
+
+
+# ─── topup / test / env / usage / models ─────────────────────────────
+
+
+@app.command()
+def topup(
+    amount: float = typer.Option(
+        ..., "--amount", "-a", help="USD amount to top up (>= 1).", min=1.0
+    ),
+    open_url: bool = typer.Option(
+        True, "--open/--no-open", help="Open the Stripe Checkout page in browser."
+    ),
+) -> None:
+    """Get a Stripe Checkout URL to add credit. Agents must NOT auto-pay."""
+    try:
+        out = request("POST", "/api/v1/topup", json_body={"amount_usd": str(amount)})
+    except ApiError as e:
+        error(e.message, code=1 if e.status < 500 else 3)
+    emit(out)
+    url = out.get("checkout_url")
+    if url and open_url and not os.environ.get("_TOKENROUTE_OUTPUT_JSON"):
+        info(f"\nOpening browser: {url}")
+        open_browser(url)
+
+
+@app.command()
+def usage(
+    days: int = typer.Option(30, "--days", "-d", help="Look-back window in days.", min=1, max=365),
+) -> None:
+    """Summary spend over the last N days."""
+    try:
+        body = request("GET", f"/api/v1/me/usage?days={days}")
+    except ApiError as e:
+        error(e.message, code=1 if e.status < 500 else 3)
+    emit(body)
+
+
+@app.command(name="env")
+def env_cmd(
+    key: str = typer.Option(
+        None,
+        "--key",
+        "-k",
+        help="Override API key (default: env TOKENROUTE_API_KEY or last cached).",
+    ),
+) -> None:
+    """Print OPENAI_API_KEY + OPENAI_BASE_URL for shell sourcing.
+
+    Usage:  tokenroute env >> .env
+    """
+    raw = key or resolve_api_key()
+    if not raw:
+        error(
+            "no API key available — run `tokenroute keys create --name <name>` first, "
+            "or set TOKENROUTE_API_KEY env var",
+            code=1,
+        )
+    base = f"{api_url()}/v1"
+    if os.environ.get("_TOKENROUTE_OUTPUT_JSON"):
+        emit({"OPENAI_API_KEY": raw, "OPENAI_BASE_URL": base})
+        return
+    # Plain printf — must work in `>> .env` redirection. No rich formatting.
+    print(f"OPENAI_API_KEY={raw}")
+    print(f"OPENAI_BASE_URL={base}")
+
+
+@app.command()
+def test(
+    model: str = typer.Option(
+        "openai/gpt-4o-mini", "--model", "-m", help="Model id to test against."
+    ),
+    key: str = typer.Option(
+        None, "--key", "-k", help="Override API key (default: cached / env)."
+    ),
+) -> None:
+    """Send a tiny chat completion to verify the gateway + your key work."""
+    import httpx
+
+    raw = key or resolve_api_key()
+    if not raw:
+        error(
+            "no API key available — run `tokenroute keys create --name <name>` first",
+            code=1,
+        )
+    url = f"{api_url()}/v1/chat/completions"
+    body = {
+        "model": model,
+        "messages": [{"role": "user", "content": "Reply with the single word 'OK'."}],
+        "max_tokens": 8,
+    }
+    try:
+        with httpx.Client(timeout=30.0) as c:
+            r = c.post(url, json=body, headers={"Authorization": f"Bearer {raw}"})
+        if not r.is_success:
+            error(f"chat failed ({r.status_code}): {r.text}", code=1 if r.status_code < 500 else 3)
+        data = r.json()
+    except httpx.RequestError as e:
+        error(f"network error: {e}", code=2)
+    reply = data["choices"][0]["message"]["content"]
+    if os.environ.get("_TOKENROUTE_OUTPUT_JSON"):
+        emit({"ok": True, "model": data.get("model", model), "reply": reply})
+    else:
+        success(f"connected ({data.get('model', model)})")
+        info(f"  reply: [italic]{reply}[/italic]")
+
+
+@app.command(name="models")
+def models_cmd(
+    list_models: bool = typer.Option(
+        True, "--list/--no-list", help="(reserved — only `list` is implemented in Phase A)"
+    ),
+    key: str = typer.Option(
+        None, "--key", "-k", help="Override API key (default: cached / env)."
+    ),
+) -> None:
+    """List available models with pricing."""
+    import httpx
+
+    raw = key or resolve_api_key()
+    if not raw:
+        error(
+            "no API key available — run `tokenroute keys create --name <name>` first",
+            code=1,
+        )
+    try:
+        with httpx.Client(timeout=15.0) as c:
+            r = c.get(f"{api_url()}/v1/models", headers={"Authorization": f"Bearer {raw}"})
+        if not r.is_success:
+            error(f"models lookup failed ({r.status_code}): {r.text}", code=3)
+        items = r.json().get("data", [])
+    except httpx.RequestError as e:
+        error(f"network error: {e}", code=2)
+    emit(
+        items,
+        table_columns=[
+            ("ID", "id"),
+            ("Provider", "owned_by"),
+            ("Tier", "complexity_tier"),
+            ("$/1k in", "input_usd_per_1k"),
+            ("$/1k out", "output_usd_per_1k"),
+        ],
+    )
+
+
+@keys_app.command("list")
+def keys_list() -> None:
+    """List your API keys (raw values never shown)."""
+    try:
+        items = request("GET", "/api/v1/me/keys")
+    except ApiError as e:
+        error(e.message, code=1 if e.status < 500 else 3)
+    emit(
+        items,
+        table_columns=[
+            ("ID", "id"),
+            ("Name", "name"),
+            ("Prefix", "key_prefix"),
+            ("Status", "status"),
+            ("Balance USD", "balance_usd"),
+            ("Created", "created_at"),
+        ],
+    )
+
+
+@keys_app.command("revoke")
+def keys_revoke(key_id: str = typer.Argument(..., help="Key id (uuid).")) -> None:
+    """Revoke an API key. Future calls with it return 401."""
+    try:
+        out = request("DELETE", f"/api/v1/me/keys/{key_id}")
+    except ApiError as e:
+        error(e.message, code=1 if e.status < 500 else 3)
+    emit(out)
+
+
+@app.command()
+def version() -> None:
+    """Print CLI version."""
+    emit({"version": __version__})
+
+
+if __name__ == "__main__":
+    app()

tokenroute-0.1.0/src/tokenroute_cli/client.py

@@ -0,0 +1,74 @@
+"""Thin httpx wrapper for hitting the tokenroute gateway API.
+
+For /api/v1/me* and /api/v1/topup we send the saved Logto JWT as Bearer.
+For /v1/* (OpenAI-compatible chat etc.) we send the sk-tr-* API key instead.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from . import __version__
+from .config import Credentials, api_url, load_credentials
+
+
+class ApiError(RuntimeError):
+    def __init__(self, status: int, message: str, body: Any = None):
+        super().__init__(f"HTTP {status}: {message}")
+        self.status = status
+        self.message = message
+        self.body = body
+
+
+def _default_headers() -> dict[str, str]:
+    return {
+        "User-Agent": f"tokenroute-cli/{__version__}",
+        "Accept": "application/json",
+    }
+
+
+def _require_login() -> Credentials:
+    creds = load_credentials()
+    if creds is None or not creds.access_token:
+        raise ApiError(401, "not logged in — run `tokenroute login` first")
+    return creds
+
+
+def _raise(resp: httpx.Response) -> None:
+    if resp.is_success:
+        return
+    try:
+        body = resp.json()
+    except (ValueError, httpx.DecodingError):
+        body = resp.text
+    if isinstance(body, dict):
+        msg = (
+            body.get("error", {}).get("message")
+            if isinstance(body.get("error"), dict)
+            else body.get("detail") or body.get("error") or resp.reason_phrase
+        )
+    else:
+        msg = resp.reason_phrase
+    raise ApiError(resp.status_code, str(msg), body)
+
+
+def request(
+    method: str,
+    path: str,
+    *,
+    json_body: Any | None = None,
+    auth_jwt: bool = True,
+    timeout: float = 30.0,
+) -> Any:
+    headers = _default_headers()
+    if auth_jwt:
+        creds = _require_login()
+        headers["Authorization"] = f"Bearer {creds.access_token}"
+    url = f"{api_url()}{path}"
+    with httpx.Client(timeout=timeout) as client:
+        resp = client.request(method, url, json=json_body, headers=headers)
+    _raise(resp)
+    if resp.status_code == 204 or not resp.content:
+        return None
+    return resp.json()