sference-cli 0.1.0__tar.gz → 0.1.1__tar.gz

{sference_cli-0.1.0 → sference_cli-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sference-cli
-Version: 0.1.0
+Version: 0.1.1
 Summary: sference command-line interface
 Project-URL: Homepage, https://sference.com
 Project-URL: Repository, https://github.com/s-ference/sference
@@ -21,7 +21,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Utilities
 Requires-Python: >=3.10
-Requires-Dist: sference-sdk>=0.1.0
+Requires-Dist: sference-sdk>=0.1.1
 Requires-Dist: typer>=0.24.1
 Description-Content-Type: text/markdown
 
@@ -109,6 +109,7 @@ sference responses tail --stream-id <stream_id>
 | Variable | Purpose |
 |----------|---------|
 | `SFERENCE_API_KEY` | API key (or JWT); overrides `~/.sference/credentials.json` |
+| `SFERENCE_MODEL` | Default catalog model for `sference launch` (overrides built-in default) |
 | `SFERENCE_STREAM_CACHE` | Optional path to the stream resumable-cache file (default `~/.sference/stream_cache.json`) |
 | `SFERENCE_STREAM_CHECKPOINTS` | Optional path for **`responses tail`** event checkpoints (default `~/.sference/stream_checkpoints.json`) |
 
@@ -121,6 +122,29 @@ sference responses tail --stream-id <stream_id>
 | `sference auth login` | Store an API key (optional `--api-key`, `--no-browser`) |
 | `sference auth me` | Show current user (`--json` for machine-readable output) |
 
+### Launch (hidden from `sference --help`)
+
+These commands are intentionally omitted from the top-level CLI help; see this section for usage.
+
+| Command | Description |
+|---------|-------------|
+| `sference launch claude` | Launch Claude Code with Sference API routing (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`) |
+| `sference launch claude --dry-run` | Print env + command without starting Claude Code |
+| `sference launch claude --model moonshotai/Kimi-K2.6` | Override catalog model |
+| `sference launch claude --enable-tool-search` | Set `ENABLE_TOOL_SEARCH=true` on custom hosts |
+| `sference launch claude --resume` | Forward Claude Code flags/args after `sference launch claude` |
+
+Requires the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) on `PATH`. Uses `~/.sference/credentials.json` or `SFERENCE_API_KEY`. Default model: `moonshotai/Kimi-K2.6` (override with `--model` or `SFERENCE_MODEL`).
+
+| Command | Description |
+|---------|-------------|
+| `sference launch pi` | Launch Pi with Sference API routing (writes `~/.pi/agent/models.json`) |
+| `sference launch pi --dry-run` | Print provider config and command without launching Pi |
+| `sference launch pi --model moonshotai/Kimi-K2.6` | Override catalog model |
+| `sference launch pi -- /path/to/project` | Forward Pi args after `sference launch pi` |
+
+Requires the [Pi CLI](https://pi.dev/docs) on `PATH`. Writes a `sference` provider block to `~/.pi/agent/models.json` with `baseUrl`, `apiKey`, and the chosen `model`, then execs `pi --provider sference --model <id>`. Uses `~/.sference/credentials.json` or `SFERENCE_API_KEY`. Default model: `moonshotai/Kimi-K2.6` (override with `--model` or `SFERENCE_MODEL`).
+
 ### Batch
 
 | Command | Description |

{sference_cli-0.1.0 → sference_cli-0.1.1}/README.md

@@ -82,6 +82,7 @@ sference responses tail --stream-id <stream_id>
 | Variable | Purpose |
 |----------|---------|
 | `SFERENCE_API_KEY` | API key (or JWT); overrides `~/.sference/credentials.json` |
+| `SFERENCE_MODEL` | Default catalog model for `sference launch` (overrides built-in default) |
 | `SFERENCE_STREAM_CACHE` | Optional path to the stream resumable-cache file (default `~/.sference/stream_cache.json`) |
 | `SFERENCE_STREAM_CHECKPOINTS` | Optional path for **`responses tail`** event checkpoints (default `~/.sference/stream_checkpoints.json`) |
 
@@ -94,6 +95,29 @@ sference responses tail --stream-id <stream_id>
 | `sference auth login` | Store an API key (optional `--api-key`, `--no-browser`) |
 | `sference auth me` | Show current user (`--json` for machine-readable output) |
 
+### Launch (hidden from `sference --help`)
+
+These commands are intentionally omitted from the top-level CLI help; see this section for usage.
+
+| Command | Description |
+|---------|-------------|
+| `sference launch claude` | Launch Claude Code with Sference API routing (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`) |
+| `sference launch claude --dry-run` | Print env + command without starting Claude Code |
+| `sference launch claude --model moonshotai/Kimi-K2.6` | Override catalog model |
+| `sference launch claude --enable-tool-search` | Set `ENABLE_TOOL_SEARCH=true` on custom hosts |
+| `sference launch claude --resume` | Forward Claude Code flags/args after `sference launch claude` |
+
+Requires the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) on `PATH`. Uses `~/.sference/credentials.json` or `SFERENCE_API_KEY`. Default model: `moonshotai/Kimi-K2.6` (override with `--model` or `SFERENCE_MODEL`).
+
+| Command | Description |
+|---------|-------------|
+| `sference launch pi` | Launch Pi with Sference API routing (writes `~/.pi/agent/models.json`) |
+| `sference launch pi --dry-run` | Print provider config and command without launching Pi |
+| `sference launch pi --model moonshotai/Kimi-K2.6` | Override catalog model |
+| `sference launch pi -- /path/to/project` | Forward Pi args after `sference launch pi` |
+
+Requires the [Pi CLI](https://pi.dev/docs) on `PATH`. Writes a `sference` provider block to `~/.pi/agent/models.json` with `baseUrl`, `apiKey`, and the chosen `model`, then execs `pi --provider sference --model <id>`. Uses `~/.sference/credentials.json` or `SFERENCE_API_KEY`. Default model: `moonshotai/Kimi-K2.6` (override with `--model` or `SFERENCE_MODEL`).
+
 ### Batch
 
 | Command | Description |

{sference_cli-0.1.0 → sference_cli-0.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sference-cli"
-version = "0.1.0"
+version = "0.1.1"
 description = "sference command-line interface"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -23,7 +23,7 @@ classifiers = [
 ]
 dependencies = [
     "typer>=0.24.1",
-    "sference-sdk>=0.1.0",
+    "sference-sdk>=0.1.1",
 ]
 
 [project.urls]

sference_cli-0.1.1/sference_cli/launch.py

@@ -0,0 +1,305 @@
+"""Launch external agent tools against the Sference API."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+DEFAULT_LAUNCH_MODEL = "moonshotai/Kimi-K2.6"
+DEFAULT_API_BASE_URL = "https://api.sference.com"
+
+
+def resolve_api_base_url(explicit: Optional[str]) -> str:
+    if explicit:
+        return explicit.rstrip("/")
+    env = os.environ.get("SFERENCE_BASE_URL")
+    if env:
+        return env.strip().rstrip("/")
+    return DEFAULT_API_BASE_URL
+
+
+def resolve_launch_model(explicit: Optional[str]) -> str:
+    """Default catalog model for ``launch`` subcommands (--model overrides)."""
+    if explicit:
+        return explicit
+    env = os.environ.get("SFERENCE_MODEL")
+    if env and env.strip():
+        return env.strip()
+    return DEFAULT_LAUNCH_MODEL
+
+
+def resolve_openai_base_url_for_pi(explicit: Optional[str]) -> str:
+    """OpenAI-compatible base URL with ``/v1`` for Pi ``models.json``."""
+    base = resolve_api_base_url(explicit)
+    base = base.rstrip("/")
+    if base.endswith("/v1"):
+        return base
+    return f"{base}/v1"
+
+
+def find_claude_executable() -> str | None:
+    return shutil.which("claude")
+
+
+def find_pi_executable() -> str | None:
+    return shutil.which("pi")
+
+
+def build_claude_env(
+    *,
+    api_key: str,
+    base_url: str,
+    model: str,
+    enable_tool_search: bool,
+) -> dict[str, str]:
+    env = os.environ.copy()
+    env["ANTHROPIC_BASE_URL"] = base_url
+    env["ANTHROPIC_AUTH_TOKEN"] = api_key
+    env["ANTHROPIC_MODEL"] = model
+    # Claude Code prefers AUTH_TOKEN; drop API_KEY to avoid precedence confusion.
+    env.pop("ANTHROPIC_API_KEY", None)
+    if enable_tool_search:
+        env["ENABLE_TOOL_SEARCH"] = "true"
+    else:
+        env.pop("ENABLE_TOOL_SEARCH", None)
+    return env
+
+
+def launch_claude_code(
+    *,
+    api_key: str,
+    base_url: str,
+    model: str,
+    enable_tool_search: bool,
+    claude_args: list[str],
+    dry_run: bool,
+) -> None:
+    claude_bin = find_claude_executable()
+    if claude_bin is None:
+        typer.echo(
+            "Claude Code CLI not found on PATH.\n"
+            "Install from https://docs.anthropic.com/en/docs/claude-code "
+            "and ensure the `claude` command is available.",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    env = build_claude_env(
+        api_key=api_key,
+        base_url=base_url,
+        model=model,
+        enable_tool_search=enable_tool_search,
+    )
+    cmd = [claude_bin, *claude_args]
+
+    if dry_run:
+        typer.echo(f"ANTHROPIC_BASE_URL={env['ANTHROPIC_BASE_URL']}")
+        typer.echo(f"ANTHROPIC_MODEL={env['ANTHROPIC_MODEL']}")
+        typer.echo("ANTHROPIC_AUTH_TOKEN=<redacted>")
+        if enable_tool_search:
+            typer.echo("ENABLE_TOOL_SEARCH=true")
+        typer.echo(f"command: {' '.join(cmd)}")
+        return
+
+    if sys.platform == "win32":
+        raise SystemExit(subprocess.call(cmd, env=env))
+
+    os.execvpe(claude_bin, cmd, env)
+
+
+def _pi_models_json_path() -> Path:
+    return Path.home() / ".pi" / "agent" / "models.json"
+
+
+def _write_pi_models_json(*, base_url: str, api_key: str, model: str) -> Path:
+    """Write or update ``~/.pi/agent/models.json`` with a Sference provider."""
+    path = _pi_models_json_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    provider = {
+        "api": "openai-completions",
+        "baseUrl": base_url,
+        "apiKey": api_key,
+        "models": [{"id": model, "name": model}],
+    }
+
+    if path.exists():
+        with path.open("r", encoding="utf-8") as fh:
+            try:
+                data = json.load(fh)
+            except json.JSONDecodeError:
+                data = {}
+    else:
+        data = {}
+
+    data.setdefault("providers", {})
+    data["providers"]["sference"] = provider
+
+    with path.open("w", encoding="utf-8") as fh:
+        json.dump(data, fh, indent=2)
+        fh.write("\n")
+
+    return path
+
+
+def launch_pi(
+    *,
+    api_key: str,
+    base_url: str,
+    model: str,
+    pi_args: list[str],
+    dry_run: bool,
+) -> None:
+    pi_bin = find_pi_executable()
+    if pi_bin is None:
+        typer.echo(
+            "Pi CLI not found on PATH.\n"
+            "Install from https://pi.dev/docs and ensure the `pi` command is available.",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    models_json = _write_pi_models_json(base_url=base_url, api_key=api_key, model=model)
+    env = os.environ.copy()
+    # Pi reads providers from ~/.pi/agent/models.json; no env vars needed.
+    cmd = [pi_bin, "--provider", "sference", "--model", model, *pi_args]
+
+    if dry_run:
+        typer.echo(f"Wrote provider 'sference' to {models_json}")
+        typer.echo(f"baseUrl: {base_url}")
+        typer.echo(f"model: {model}")
+        typer.echo("apiKey: <redacted>")
+        typer.echo(f"command: {' '.join(cmd)}")
+        return
+
+    if sys.platform == "win32":
+        raise SystemExit(subprocess.call(cmd, env=env))
+
+    os.execvpe(pi_bin, cmd, env)
+
+
+def register_launch_commands(app: typer.Typer) -> None:
+    launch_app = typer.Typer(help="Launch external tools configured for Sference.", invoke_without_command=True)
+
+    @launch_app.callback()
+    def launch_root(ctx: typer.Context) -> None:
+        if ctx.invoked_subcommand is None:
+            typer.echo(ctx.get_help())
+            raise typer.Exit(code=0)
+
+    @launch_app.command(
+        "claude",
+        context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+        help="Launch Claude Code with Sference API routing.",
+    )
+    def claude(
+        ctx: typer.Context,
+        model: Optional[str] = typer.Option(
+            None,
+            "--model",
+            "-m",
+            help=f"Catalog model id (default: {DEFAULT_LAUNCH_MODEL} or SFERENCE_MODEL).",
+        ),
+        base_url: Optional[str] = typer.Option(
+            None,
+            "--base-url",
+            envvar="SFERENCE_BASE_URL",
+            help=f"Sference API base URL (default: {DEFAULT_API_BASE_URL}).",
+        ),
+        enable_tool_search: bool = typer.Option(
+            False,
+            "--enable-tool-search",
+            help="Set ENABLE_TOOL_SEARCH=true for Claude Code on a custom API host.",
+        ),
+        dry_run: bool = typer.Option(
+            False,
+            "--dry-run",
+            help="Print env and command without launching Claude Code.",
+        ),
+    ) -> None:
+        """Run ``claude`` with Sference credentials.
+
+        Uses ``~/.sference/credentials.json`` or ``SFERENCE_API_KEY``. Unknown options
+        and trailing args are forwarded to Claude Code, e.g.
+        ``sference launch claude --resume`` or ``sference launch claude -p "fix the bug"``.
+        """
+        from sference_cli.main import _ensure_api_credential, _read_token
+
+        _ensure_api_credential()
+        api_key = _read_token()
+        if api_key is None:
+            raise typer.Exit(code=1)
+
+        forwarded = list(ctx.args)
+        if forwarded and forwarded[0] == "--":
+            forwarded = forwarded[1:]
+
+        launch_claude_code(
+            api_key=api_key,
+            base_url=resolve_api_base_url(base_url),
+            model=resolve_launch_model(model),
+            enable_tool_search=enable_tool_search,
+            claude_args=forwarded,
+            dry_run=dry_run,
+        )
+
+    @launch_app.command(
+        "pi",
+        context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+        help="Launch Pi with Sference OpenAI-compatible routing.",
+    )
+    def pi(
+        ctx: typer.Context,
+        model: Optional[str] = typer.Option(
+            None,
+            "--model",
+            "-m",
+            help=f"Catalog model id (default: {DEFAULT_LAUNCH_MODEL} or SFERENCE_MODEL).",
+        ),
+        base_url: Optional[str] = typer.Option(
+            None,
+            "--base-url",
+            envvar="SFERENCE_BASE_URL",
+            help=f"Sference API base URL (default: {DEFAULT_API_BASE_URL}).",
+        ),
+        dry_run: bool = typer.Option(
+            False,
+            "--dry-run",
+            help="Print provider config and command without launching Pi.",
+        ),
+    ) -> None:
+        """Run ``pi`` with Sference credentials.
+
+        Writes a ``sference`` provider block to ``~/.pi/agent/models.json`` with
+        ``baseUrl``, ``apiKey``, and the chosen ``model``, then execs
+        ``pi --provider sference --model <id>``. Unknown options and trailing args
+        are forwarded to Pi, e.g. ``sference launch pi -- /path/to/project``.
+        """
+        from sference_cli.main import _ensure_api_credential, _read_token
+
+        _ensure_api_credential()
+        api_key = _read_token()
+        if api_key is None:
+            raise typer.Exit(code=1)
+
+        forwarded = list(ctx.args)
+        if forwarded and forwarded[0] == "--":
+            forwarded = forwarded[1:]
+
+        launch_pi(
+            api_key=api_key,
+            base_url=resolve_openai_base_url_for_pi(base_url),
+            model=resolve_launch_model(model),
+            pi_args=forwarded,
+            dry_run=dry_run,
+        )
+
+    # Hidden from `sference --help`; documented for Claude Code / Pi setup only.
+    app.add_typer(launch_app, name="launch", hidden=True)

{sference_cli-0.1.0 → sference_cli-0.1.1}/sference_cli/main.py

@@ -19,6 +19,7 @@ from sference_cli import __version__ as _CLI_VERSION
 from sference_sdk.checkpoint import clear_checkpoint, load_checkpoint, save_checkpoint
 
 from . import stream_cache as stream_cache_mod
+from .launch import register_launch_commands
 
 _T = TypeVar("_T")
 
@@ -36,6 +37,7 @@ app.add_typer(batch_app, name="batch")
 app.add_typer(stream_app, name="stream")
 app.add_typer(responses_app, name="responses")
 app.add_typer(models_app, name="models")
+register_launch_commands(app)
 
 CREDENTIALS_PATH = Path.home() / ".sference" / "credentials.json"
 
@@ -72,11 +74,8 @@ def _read_token() -> str | None:
 
 
 def _client(base_url: Optional[str] = None, *, timeout: float | None = None) -> SferenceClient:
-    # If the caller didn't explicitly pass --base-url, allow SFERENCE_BASE_URL
-    # to override the default.
     env_base_url = os.environ.get("SFERENCE_BASE_URL")
     if env_base_url and (base_url is None or base_url == "https://api.sference.com"):
-        _logger.info(f"Using SFERENCE_BASE_URL: {env_base_url}")
         base_url = env_base_url
     return SferenceClient(base_url=base_url, api_key=_read_token(), timeout=timeout)