qbraid-cli 0.13.2__tar.gz → 0.13.3__tar.gz

{qbraid_cli-0.13.2/qbraid_cli.egg-info → qbraid_cli-0.13.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qbraid-cli
-Version: 0.13.2
+Version: 0.13.3
 Summary: Command Line Interface for interacting with all parts of the qBraid platform.
 Author-email: qBraid Development Team <contact@qbraid.com>
 License-Expression: LicenseRef-Proprietary
@@ -30,7 +30,7 @@ Requires-Dist: typer>=0.12.1
 Requires-Dist: rich>=10.11.0
 Requires-Dist: click<=8.3.3
 Requires-Dist: questionary>=2.0.0
-Requires-Dist: qbraid-core>=0.3.3
+Requires-Dist: qbraid-core>=0.3.11
 Provides-Extra: compute
 Requires-Dist: qbraid-core[compute]>=0.3.3; extra == "compute"
 Provides-Extra: envs

{qbraid_cli-0.13.2 → qbraid_cli-0.13.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qbraid-cli"
-version = "0.13.2"
+version = "0.13.3"
 description = "Command Line Interface for interacting with all parts of the qBraid platform."
 readme = "README.md"
 authors = [{ name = "qBraid Development Team", email = "contact@qbraid.com" }]
@@ -32,7 +32,7 @@ dependencies = [
     "rich>=10.11.0",
     "click<=8.3.3",
     "questionary>=2.0.0",
-    "qbraid-core>=0.3.3",
+    "qbraid-core>=0.3.11",
 ]
 requires-python = ">= 3.10"
 
@@ -49,6 +49,9 @@ dev = ["isort", "black", "pytest", "pytest-cov", "pytest-asyncio"]
 
 [project.scripts]
 qbraid = "qbraid_cli.main:app"
+# Separate entry point on purpose: agents re-run this on a timer, and routing it
+# through the full CLI would import every command group to print one string.
+qbraid-ai-token = "qbraid_cli.ai.token:main"
 
 [tool.black]
 line-length = 110

qbraid_cli-0.13.3/qbraid_cli/ai/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) 2026, qBraid Development Team
+# All rights reserved.
+
+"""
+Module for the 'qbraid ai' namespace.
+
+Deliberately empty. ``qbraid_cli.ai.token`` is the console script the agents
+re-run on a timer, and re-exporting the command module here would drag typer
+and rich into the one process whose stdout is a credential — the cost the
+separate entry point exists to avoid. Import ``qbraid_cli.ai.app`` directly.
+"""

qbraid_cli-0.13.3/qbraid_cli/ai/app.py

@@ -0,0 +1,390 @@
+# Copyright (c) 2026, qBraid Development Team
+# All rights reserved.
+
+"""
+Module defining commands in the 'qbraid ai' namespace.
+
+"""
+
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from qbraid_cli.handlers import handle_error
+
+ai_app = typer.Typer(
+    help=(
+        "Use qBraid as your AI provider.\n\n"
+        "Point Claude Code or Codex at the qBraid AI proxy so requests run on "
+        "your qBraid plan instead of a separate vendor subscription, and switch "
+        "back whenever you want.\n\n"
+        "Quick start: qbraid ai connect claude"
+    ),
+    no_args_is_help=True,
+)
+
+console = Console()
+
+_AGENT_LABELS = {"claude": "Claude Code", "codex": "Codex"}
+
+_AUTH_LABELS = {
+    "api_key_helper": "token command (auto-refreshing)",
+    "auth_command": "token command (auto-refreshing)",
+    "api_key": "API key written into the config",
+    "env_key": "API key read from an environment variable",
+}
+
+
+def _warn_if_token_command_missing() -> None:
+    """Warn when the agents won't be able to run the token command.
+
+    They invoke it by bare name, so a `pip install --user` whose bin directory
+    isn't on PATH — or a venv the agent doesn't inherit — means both agents
+    401 forever with nothing in our own output suggesting why.
+    """
+    import shutil
+
+    executable = _ai().token_command()[0]
+    if shutil.which(executable):
+        return
+
+    console.print()
+    console.print(
+        f"[yellow]⚠  '{executable}' is not on PATH.[/yellow] The agents run it to fetch "
+        "a credential, so they will fail to authenticate until it resolves — "
+        "check that the directory pip installed it into is on your PATH."
+    )
+
+
+def _ai():
+    """Import the core AI gateway, or explain why it isn't there.
+
+    The module landed in qbraid-core 0.3.11. An older core is a realistic
+    install state (the pin only takes effect on a fresh resolve), and the bare
+    ImportError surfaces as a full traceback — the convention elsewhere in this
+    CLI is a single actionable line.
+    """
+    try:
+        from qbraid_core.services import ai
+    except ImportError as err:  # pragma: no cover - depends on installed core
+        handle_error(
+            message=(
+                "This command needs qbraid-core>=0.3.11 (the AI gateway module "
+                "is missing from the installed version). Upgrade with: "
+                "pip install -U qbraid-core"
+            ),
+            include_traceback=False,
+        )
+        raise typer.Exit(code=1) from err
+    return ai
+
+
+def _agents_from(agent: str) -> list[str]:
+    """Expand the 'all' shorthand into concrete agent names."""
+    supported = _ai().SUPPORTED_AGENTS
+
+    if agent == "all":
+        return list(supported)
+    if agent not in supported:
+        console.print(
+            f"[red]Unknown agent '{agent}'.[/red] Expected one of: " f"{', '.join(supported)}, or 'all'."
+        )
+        raise typer.Exit(code=2)
+    return [agent]
+
+
+def _print_claude_caveats() -> None:
+    """Consequences of pointing Claude Code at a non-Anthropic host.
+
+    All three are documented Claude Code behaviours, and all three surprise
+    people who weren't told up front.
+    """
+    console.print()
+    console.print("[bold]Worth knowing:[/bold]")
+    console.print("  • This overrides a Claude Pro/Max/Team subscription — requests now bill to qBraid.")
+    console.print(
+        "  • MCP tool search is disabled for non-Anthropic hosts. Set "
+        "ENABLE_TOOL_SEARCH=true if the proxy forwards tool_reference blocks."
+    )
+    console.print("  • Remote Control is disabled while pointed off api.anthropic.com.")
+
+
+@ai_app.command(name="connect")
+def ai_connect(  # pylint: disable=too-many-branches
+    agent: str = typer.Argument("all", help="Agent to configure: claude, codex, or all"),
+    model: Optional[str] = typer.Option(
+        None, "--model", "-m", help="Model id to pin (see `qbraid ai models`)"
+    ),
+    refresh_interval: Optional[int] = typer.Option(
+        None,
+        "--refresh-interval",
+        help="Seconds between credential refreshes (default: 300)",
+    ),
+    api_url: Optional[str] = typer.Option(None, "--api-url", help="Override the qBraid API base URL"),
+    plaintext_key: bool = typer.Option(
+        False,
+        "--plaintext-key",
+        help="Write the API key into the config instead of using a token command",
+    ),
+):
+    """Route an agent through the qBraid AI proxy.
+
+    Writes to the agent's own config — Claude Code's settings.json, Codex's
+    config.toml — and records whatever it replaces so `qbraid ai disconnect`
+    can put it back.
+
+    The credential is not written into either config by default. Both agents
+    are pointed at a command that prints a token, so the key stays in your
+    qBraid config and a rotated token is picked up automatically.
+
+    Example:
+        qbraid ai connect claude
+        qbraid ai connect all --model claude-sonnet-4-6
+    """
+    ai = _ai()
+
+    agents = _agents_from(agent)
+
+    try:
+        _, kind = ai.resolve_credential()
+    except ai.AiGatewayError as err:
+        handle_error(message=str(err), include_traceback=False)
+        return
+
+    api_key = None
+    if plaintext_key:
+        if kind == "access_token":
+            console.print(
+                "[yellow]--plaintext-key is only meaningful for API keys; "
+                "access tokens rotate and must use the token command.[/yellow]"
+            )
+        else:
+            api_key, _ = ai.resolve_credential()
+            if "codex" in agents:
+                console.print(
+                    "[yellow]--plaintext-key applies to Claude Code only; "
+                    "Codex keeps using the token command.[/yellow]"
+                )
+
+    for name in agents:
+        try:
+            result = ai.connect_agent(
+                name,
+                api_url=api_url,
+                api_key=api_key,
+                model=model,
+                refresh_seconds=refresh_interval,
+            )
+        except ai.AiGatewayError as err:
+            handle_error(message=str(err), include_traceback=False)
+            return
+
+        label = _AGENT_LABELS.get(name, name)
+        console.print(f"[green]✓[/green] {label} → [cyan]{result['gateway_url']}[/cyan]")
+        console.print(f"  config: [dim]{result['path']}[/dim]")
+        if result.get("model"):
+            console.print(f"  model:  [dim]{result['model']}[/dim]")
+        cred = "access token" if kind == "access_token" else "API key"
+        how = _AUTH_LABELS.get(result.get("auth_mode"), result.get("auth_mode", "?"))
+        console.print(f"  auth:   [dim]qBraid {cred} via {how}[/dim]")
+
+    if not plaintext_key:
+        _warn_if_token_command_missing()
+
+    if "claude" in agents:
+        _print_claude_caveats()
+
+    console.print()
+    console.print("[dim]Restart the agent to pick up the new configuration.[/dim]")
+    console.print("[dim]Revert any time with: qbraid ai disconnect[/dim]")
+
+
+@ai_app.command(name="disconnect")
+def ai_disconnect(
+    agent: str = typer.Argument("all", help="Agent to restore: claude, codex, or all"),
+):
+    """Restore an agent's previous configuration.
+
+    Puts back exactly what was there before connecting — including removing
+    settings that weren't present to begin with.
+
+    Example:
+        qbraid ai disconnect claude
+    """
+    ai = _ai()
+
+    for name in _agents_from(agent):
+        try:
+            result = ai.disconnect_agent(name)
+        except ai.AiGatewayError as err:
+            handle_error(message=str(err), include_traceback=False)
+            return
+
+        label = _AGENT_LABELS.get(name, name)
+        if result["status"] == "not_configured":
+            console.print(f"[dim]○[/dim] {label} was not configured.")
+        else:
+            restored = "restored previous settings" if result.get("restored") else "cleared"
+            console.print(f"[green]✓[/green] {label} — {restored}")
+
+    console.print()
+    # A running agent keeps its settings in memory and rewrites the file on
+    # exit, which silently puts our config back. Observed with both Claude Code
+    # and Codex, so this is guidance the user genuinely needs, not boilerplate.
+    console.print(
+        "[yellow]If the agent is running, stop it and re-run this command.[/yellow] "
+        "A running agent can rewrite its config from memory and undo the change."
+    )
+    console.print("[dim]Confirm with: qbraid ai status[/dim]")
+
+
+@ai_app.command(name="status")
+def ai_status(
+    check: bool = typer.Option(False, "--check", help="Also verify the credential against the proxy"),
+):
+    """Show which agents are routed through qBraid.
+
+    Pass --check to confirm the credential is actually accepted — useful when
+    a session has started failing and you want to know whether it expired.
+
+    Example:
+        qbraid ai status --check
+    """
+    ai = _ai()
+
+    status = ai.gateway_status()
+
+    table = Table(title="qBraid AI gateway")
+    table.add_column("Agent")
+    table.add_column("Routed")
+    table.add_column("Endpoint")
+    table.add_column("Model")
+
+    for name, info in status.items():
+        table.add_row(
+            _AGENT_LABELS.get(name, name),
+            "[green]yes[/green]" if info.get("connected") else "[dim]no[/dim]",
+            info.get("base_url") or "-",
+            info.get("model") or "-",
+        )
+
+    console.print(table)
+
+    if not check:
+        return
+
+    try:
+        _, kind = ai.resolve_credential()
+    except ai.AiGatewayError as err:
+        console.print(f"[red]✗[/red] {err}")
+        raise typer.Exit(code=1) from err
+
+    console.print()
+    try:
+        ai.list_models()
+    except Exception as err:  # pylint: disable=broad-exception-caught
+        status_code = getattr(err, "status_code", None)
+        if status_code in (401, 403):
+            # The one case where the credential is actually the problem.
+            console.print(f"[red]✗[/red] credential rejected ({status_code})")
+            console.print()
+            console.print(ai.credential_expired_hint(kind))
+        elif status_code is not None:
+            console.print(f"[red]✗[/red] proxy returned {status_code}: {err}")
+            console.print("[dim]Your credential may be fine — this looks server-side.[/dim]")
+        else:
+            console.print(f"[red]✗[/red] could not reach the proxy: {err}")
+            console.print("[dim]Check your connection and `qbraid configure` URL.[/dim]")
+        raise typer.Exit(code=1) from err
+
+    console.print(
+        "[green]✓[/green] credential accepted "
+        f"[dim]({'access token' if kind == 'access_token' else 'API key'})[/dim]"
+    )
+
+
+@ai_app.command(name="models")
+def ai_models():
+    """List models available on the qBraid proxy.
+
+    The proxy matches model ids exactly, so pick one of these when setting
+    `--model` — an id the proxy doesn't know is rejected on the first request.
+
+    Example:
+        qbraid ai models
+    """
+    try:
+        models = _ai().list_models()
+    except Exception as err:  # pylint: disable=broad-exception-caught
+        handle_error(message=f"Could not list models: {err}", include_traceback=False)
+        return
+
+    if not models:
+        console.print("[yellow]No models returned.[/yellow]")
+        return
+
+    table = Table(title="Available models")
+    table.add_column("ID")
+    table.add_column("Name")
+    table.add_column("Backend")
+    table.add_column("Max tokens", justify="right")
+
+    for item in models:
+        if not isinstance(item, dict):
+            table.add_row(str(item), "-", "-", "-")
+            continue
+        # The listing is OpenAI-compatible, so the qBraid metadata (name,
+        # provider, limits) is nested under `_qbraid` rather than top level.
+        meta = item.get("_qbraid") or {}
+        max_tokens = meta.get("maxTokens")
+        table.add_row(
+            item.get("id", "-"),
+            meta.get("name", "-"),
+            meta.get("provider", "-"),
+            f"{max_tokens:,}" if isinstance(max_tokens, int) else "-",
+        )
+
+    console.print(table)
+
+
+@ai_app.command(name="quota")
+def ai_quota():
+    """Show remaining qBraid AI quota.
+
+    Example:
+        qbraid ai quota
+    """
+    try:
+        quota = _ai().get_quota()
+    except Exception as err:  # pylint: disable=broad-exception-caught
+        handle_error(message=f"Could not fetch quota: {err}", include_traceback=False)
+        return
+
+    if not quota:
+        console.print("[yellow]No quota information returned.[/yellow]")
+        return
+
+    for key, value in quota.items():
+        console.print(f"  {key}: [cyan]{value}[/cyan]")
+
+
+@ai_app.command(name="token", hidden=True)
+def ai_token():
+    """Print the qBraid credential for agents.
+
+    Hidden because it exists for Claude Code's `apiKeyHelper` and Codex's
+    `[model_providers.qbraid.auth]` command rather than for people. Prints the
+    credential and nothing else, so the agents can read it from stdout.
+    """
+    ai = _ai()
+
+    try:
+        credential, _ = ai.resolve_credential()
+    except ai.AiGatewayError as err:
+        # stderr, so a failure never looks like a token on stdout.
+        typer.echo(str(err), err=True)
+        raise typer.Exit(code=1) from err
+
+    typer.echo(credential)

qbraid_cli-0.13.3/qbraid_cli/ai/token.py

@@ -0,0 +1,66 @@
+# Copyright (c) 2026, qBraid Development Team
+# All rights reserved.
+
+"""
+Standalone entry point that prints the qBraid credential to stdout.
+
+This exists as its own console script rather than as `qbraid ai token` because
+it is the one command that runs unattended, forever, on every configured agent
+— Claude Code re-invokes it via ``apiKeyHelper`` and Codex via
+``[model_providers.qbraid.auth]``, both on a timer.
+
+Going through ``qbraid_cli.main`` would import every command group in the CLI
+(~0.9s here) to print one string. Importing only what's needed costs ~0.2s, and
+— more to the point — keeps this path from getting slower every time a new
+command group is added.
+
+Deliberately has no argument parsing: it prints the credential and nothing else,
+so an agent reading stdout can never pick up a stray banner or prompt.
+
+The credential is written to the binary stdout buffer rather than via ``print``
+so the bytes are identical on every platform. Text-mode stdout on Windows
+translates ``\n`` into ``\r\n``, which would append a stray carriage return
+to the credential an agent reads.
+"""
+
+import sys
+
+
+def _emit(credential: str) -> None:
+    """Write the credential and exactly one newline, byte-for-byte.
+
+    Goes through ``sys.stdout.buffer`` to bypass the text layer: on Windows
+    that layer turns the newline into ``\r\n``, and an agent that does not
+    strip the carriage return sends it as part of the credential and 401s.
+    Falls back to ``print`` when stdout has been replaced by an object with no
+    binary buffer (pytest's capture, for one).
+    """
+    buffer = getattr(sys.stdout, "buffer", None)
+    if buffer is None:
+        print(credential)
+        return
+    buffer.write(credential.encode("utf-8") + b"\n")
+    buffer.flush()
+
+
+def main() -> int:
+    """Print the credential, or explain on stderr why there isn't one."""
+    try:
+        from qbraid_core.services.ai import AiGatewayError, resolve_credential
+    except ImportError as err:  # pragma: no cover - broken install
+        print(f"qbraid-core is not importable: {err}", file=sys.stderr)
+        return 1
+
+    try:
+        credential, _ = resolve_credential()
+    except AiGatewayError as err:
+        # stderr only — a failure must never look like a token on stdout.
+        print(str(err), file=sys.stderr)
+        return 1
+
+    _emit(credential)
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

{qbraid_cli-0.13.2 → qbraid_cli-0.13.3}/qbraid_cli/main.py

@@ -12,6 +12,7 @@ import typer
 from qbraid_cli.account import account_app
 from qbraid_cli.admin import admin_app
 from qbraid_cli.agents import agents_app
+from qbraid_cli.ai.app import ai_app
 from qbraid_cli.compute import compute_app
 from qbraid_cli.configure import configure_app
 from qbraid_cli.devices import devices_app
@@ -32,7 +33,7 @@ except ImportError:
 
 app = typer.Typer(
     help=(
-        "The qBraid CLI — your unified interface for AI agents, quantum computing,\n"
+        "The qBraid CLI — A unified interface for AI agents, quantum computing,\n"
         "Python environments, and cloud compute.\n\n"
         "Whether you're running AI coding agents locally or on cloud servers,\n"
         "managing quantum experiments across providers, or setting up reproducible\n"
@@ -43,6 +44,7 @@ app = typer.Typer(
 
 app.add_typer(admin_app, name="admin")
 app.add_typer(agents_app, name="agents")
+app.add_typer(ai_app, name="ai")
 app.add_typer(compute_app, name="compute")
 app.add_typer(lab_app, name="lab")
 app.add_typer(configure_app, name="configure")

{qbraid_cli-0.13.2 → qbraid_cli-0.13.3/qbraid_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qbraid-cli
-Version: 0.13.2
+Version: 0.13.3
 Summary: Command Line Interface for interacting with all parts of the qBraid platform.
 Author-email: qBraid Development Team <contact@qbraid.com>
 License-Expression: LicenseRef-Proprietary
@@ -30,7 +30,7 @@ Requires-Dist: typer>=0.12.1
 Requires-Dist: rich>=10.11.0
 Requires-Dist: click<=8.3.3
 Requires-Dist: questionary>=2.0.0
-Requires-Dist: qbraid-core>=0.3.3
+Requires-Dist: qbraid-core>=0.3.11
 Provides-Extra: compute
 Requires-Dist: qbraid-core[compute]>=0.3.3; extra == "compute"
 Provides-Extra: envs

{qbraid_cli-0.13.2 → qbraid_cli-0.13.3}/qbraid_cli.egg-info/SOURCES.txt

@@ -22,6 +22,9 @@ qbraid_cli/admin/headers.py
 qbraid_cli/admin/validation.py
 qbraid_cli/agents/__init__.py
 qbraid_cli/agents/app.py
+qbraid_cli/ai/__init__.py
+qbraid_cli/ai/app.py
+qbraid_cli/ai/token.py
 qbraid_cli/compute/__init__.py
 qbraid_cli/compute/app.py
 qbraid_cli/compute/profiles.py

{qbraid_cli-0.13.2 → qbraid_cli-0.13.3}/qbraid_cli.egg-info/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
 qbraid = qbraid_cli.main:app
+qbraid-ai-token = qbraid_cli.ai.token:main

{qbraid_cli-0.13.2 → qbraid_cli-0.13.3}/qbraid_cli.egg-info/requires.txt

@@ -2,7 +2,7 @@ typer>=0.12.1
 rich>=10.11.0
 click<=8.3.3
 questionary>=2.0.0
-qbraid-core>=0.3.3
+qbraid-core>=0.3.11
 
 [compute]
 qbraid-core[compute]>=0.3.3