sference-cli 0.0.2__tar.gz → 0.0.3__tar.gz

{sference_cli-0.0.2 → sference_cli-0.0.3}/.gitignore

@@ -8,3 +8,5 @@ build/
 .venv/
 *.egg
 .pytest_cache/
+cli/.env
+

sference_cli-0.0.2/README.md → sference_cli-0.0.3/PKG-INFO

@@ -1,3 +1,12 @@
+Metadata-Version: 2.4
+Name: sference-cli
+Version: 0.0.3
+Summary: sference command-line interface
+Requires-Python: >=3.12
+Requires-Dist: sference-sdk>=0.0.3
+Requires-Dist: typer>=0.24.1
+Description-Content-Type: text/markdown
+
 # sference CLI
 
 Command-line interface for the sference batch API (`sference`). It uses the Python SDK (`sference-sdk`) and is published on PyPI as `sference-cli`.
@@ -56,7 +65,7 @@ sference stream create --name "my-stream" --window 24h
 sference stream list
 sference stream submit --stream-id <stream_id> --input-file ./lines.jsonl --model Qwen/Qwen2.5-7B-Instruct
 sference stream status --stream-id <stream_id>
-sference stream tail --stream-id <stream_id>
+sference responses tail --stream-id <stream_id>
 ```
 
 ### cURL: OpenAI-compatible `/v1/responses`
@@ -87,7 +96,7 @@ curl -sS "${SFERENCE_BASE_URL:-https://api.sference.com}/v1/responses/${RID}" \
 | `SFERENCE_BASE_URL` | API base URL (default `https://api.sference.com`) |
 | `SFERENCE_CONSOLE_URL` | Console URL for `auth login` browser step (default `https://console.sference.com`) |
 | `SFERENCE_STREAM_CACHE` | Optional path to the stream resumable-cache file (default `~/.sference/stream_cache.json`) |
-| `SFERENCE_STREAM_CHECKPOINTS` | Optional path for **stream event** tail checkpoints (default `~/.sference/stream_checkpoints.json`) |
+| `SFERENCE_STREAM_CHECKPOINTS` | Optional path for **`responses tail`** event checkpoints (default `~/.sference/stream_checkpoints.json`) |
 
 ## Commands
 
@@ -113,9 +122,17 @@ curl -sS "${SFERENCE_BASE_URL:-https://api.sference.com}/v1/responses/${RID}" \
 
 Global options on most batch commands: `--base-url` (default `https://api.sference.com`).
 
+### Responses (`/v1/responses`)
+
+| Command | Description |
+|---------|-------------|
+| `sference responses create` | Create one response (`--model`, `--content`, optional `--wait`, `--poll-ms`, `--timeout-s`) |
+| `sference responses result` | Poll until terminal state (`--id`, `--poll-ms`) |
+| `sference responses tail` | Print completion events as JSONL via `GET /v1/responses/events` (optional `--stream-id` to scope to a stream; omit for non-stream completions). Flags: `--consumer`, `--from-latest`, `--no-checkpoint`, `--poll-ms` |
+
 ### Stream (first-class streams API)
 
-Long-lived **streams** are separate from **batches**: you create a stream, submit **responses** tied to it over time (`POST /v1/responses` with `metadata.stream_id`), and consume **completion events** with cursor-based pagination (`GET /v1/streams/{id}/events`). New API keys include `streams:read` and `streams:write`; older keys keep their existing scopes.
+Long-lived **streams** are separate from **batches**: you create a stream, submit **responses** tied to it over time (`POST /v1/responses` with `metadata.stream_id`), and consume **completion events** with cursor-based pagination on **`GET /v1/responses/events`** (pass **`stream_id`** when scoping to a stream). Authenticate with your **secret API key** like other `/v1` calls.
 
 | Command | Description |
 |---------|-------------|
@@ -125,7 +142,6 @@ Long-lived **streams** are separate from **batches**: you create a stream, submi
 | `sference stream submit` | Create responses from JSONL via `POST /v1/responses` per line (`metadata.stream_id` set automatically; `--stream-id`, `--input-file`, `--model` required for content-only lines) — per line: OpenAI batch-style `{custom_id?, method, url, body}` or content-only `{content}` |
 | `sference stream cancel` | Stop accepting new items and stop enqueueing pending work; does not auto-cancel in-flight requests (`--stream-id`, `--json`) |
 | `sference stream archive` | Finalize the stream (optional after cancel); no new items (`--stream-id`, `--json`) |
-| `sference stream tail` | Print events as JSONL; checkpoints after each event (override with `SFERENCE_STREAM_CHECKPOINTS`). Flags: `--consumer`, `--from-latest`, `--no-checkpoint`, `--poll-ms` |
 
 Example JSONL lines for `stream submit` (both accepted):
 
@@ -211,6 +227,6 @@ For your own code, see **[`../sdk-python/README.md`](../sdk-python/README.md)**
 
 - **Batches (sync):** `submit_batch`, `wait_for_completion`, `get_results`
 - **`/v1/responses` (sync):** `create_response`, `get_response` (standalone or `metadata.stream_id` for streams)
-- **Async:** **`AsyncSferenceClient`** — same surface as sync with `await`, plus `iter_stream_events` / `list_stream_events` for stream tailing
+- **Async:** **`AsyncSferenceClient`** — same surface as sync with `await`, plus `iter_responses_events` / `list_responses_events` for completion tailing (`GET /v1/responses/events`)
 
 That README also documents when to prefer **batches** vs **streams** and includes cURL examples.

sference_cli-0.0.2/PKG-INFO → sference_cli-0.0.3/README.md

@@ -1,12 +1,3 @@
-Metadata-Version: 2.4
-Name: sference-cli
-Version: 0.0.2
-Summary: sference command-line interface
-Requires-Python: >=3.12
-Requires-Dist: sference-sdk>=0.0.1
-Requires-Dist: typer>=0.24.1
-Description-Content-Type: text/markdown
-
 # sference CLI
 
 Command-line interface for the sference batch API (`sference`). It uses the Python SDK (`sference-sdk`) and is published on PyPI as `sference-cli`.
@@ -65,7 +56,7 @@ sference stream create --name "my-stream" --window 24h
 sference stream list
 sference stream submit --stream-id <stream_id> --input-file ./lines.jsonl --model Qwen/Qwen2.5-7B-Instruct
 sference stream status --stream-id <stream_id>
-sference stream tail --stream-id <stream_id>
+sference responses tail --stream-id <stream_id>
 ```
 
 ### cURL: OpenAI-compatible `/v1/responses`
@@ -96,7 +87,7 @@ curl -sS "${SFERENCE_BASE_URL:-https://api.sference.com}/v1/responses/${RID}" \
 | `SFERENCE_BASE_URL` | API base URL (default `https://api.sference.com`) |
 | `SFERENCE_CONSOLE_URL` | Console URL for `auth login` browser step (default `https://console.sference.com`) |
 | `SFERENCE_STREAM_CACHE` | Optional path to the stream resumable-cache file (default `~/.sference/stream_cache.json`) |
-| `SFERENCE_STREAM_CHECKPOINTS` | Optional path for **stream event** tail checkpoints (default `~/.sference/stream_checkpoints.json`) |
+| `SFERENCE_STREAM_CHECKPOINTS` | Optional path for **`responses tail`** event checkpoints (default `~/.sference/stream_checkpoints.json`) |
 
 ## Commands
 
@@ -122,9 +113,17 @@ curl -sS "${SFERENCE_BASE_URL:-https://api.sference.com}/v1/responses/${RID}" \
 
 Global options on most batch commands: `--base-url` (default `https://api.sference.com`).
 
+### Responses (`/v1/responses`)
+
+| Command | Description |
+|---------|-------------|
+| `sference responses create` | Create one response (`--model`, `--content`, optional `--wait`, `--poll-ms`, `--timeout-s`) |
+| `sference responses result` | Poll until terminal state (`--id`, `--poll-ms`) |
+| `sference responses tail` | Print completion events as JSONL via `GET /v1/responses/events` (optional `--stream-id` to scope to a stream; omit for non-stream completions). Flags: `--consumer`, `--from-latest`, `--no-checkpoint`, `--poll-ms` |
+
 ### Stream (first-class streams API)
 
-Long-lived **streams** are separate from **batches**: you create a stream, submit **responses** tied to it over time (`POST /v1/responses` with `metadata.stream_id`), and consume **completion events** with cursor-based pagination (`GET /v1/streams/{id}/events`). New API keys include `streams:read` and `streams:write`; older keys keep their existing scopes.
+Long-lived **streams** are separate from **batches**: you create a stream, submit **responses** tied to it over time (`POST /v1/responses` with `metadata.stream_id`), and consume **completion events** with cursor-based pagination on **`GET /v1/responses/events`** (pass **`stream_id`** when scoping to a stream). Authenticate with your **secret API key** like other `/v1` calls.
 
 | Command | Description |
 |---------|-------------|
@@ -134,7 +133,6 @@ Long-lived **streams** are separate from **batches**: you create a stream, submi
 | `sference stream submit` | Create responses from JSONL via `POST /v1/responses` per line (`metadata.stream_id` set automatically; `--stream-id`, `--input-file`, `--model` required for content-only lines) — per line: OpenAI batch-style `{custom_id?, method, url, body}` or content-only `{content}` |
 | `sference stream cancel` | Stop accepting new items and stop enqueueing pending work; does not auto-cancel in-flight requests (`--stream-id`, `--json`) |
 | `sference stream archive` | Finalize the stream (optional after cancel); no new items (`--stream-id`, `--json`) |
-| `sference stream tail` | Print events as JSONL; checkpoints after each event (override with `SFERENCE_STREAM_CHECKPOINTS`). Flags: `--consumer`, `--from-latest`, `--no-checkpoint`, `--poll-ms` |
 
 Example JSONL lines for `stream submit` (both accepted):
 
@@ -220,6 +218,6 @@ For your own code, see **[`../sdk-python/README.md`](../sdk-python/README.md)**
 
 - **Batches (sync):** `submit_batch`, `wait_for_completion`, `get_results`
 - **`/v1/responses` (sync):** `create_response`, `get_response` (standalone or `metadata.stream_id` for streams)
-- **Async:** **`AsyncSferenceClient`** — same surface as sync with `await`, plus `iter_stream_events` / `list_stream_events` for stream tailing
+- **Async:** **`AsyncSferenceClient`** — same surface as sync with `await`, plus `iter_responses_events` / `list_responses_events` for completion tailing (`GET /v1/responses/events`)
 
 That README also documents when to prefer **batches** vs **streams** and includes cURL examples.

{sference_cli-0.0.2 → sference_cli-0.0.3}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "sference-cli"
-version = "0.0.2"
+version = "0.0.3"
 description = "sference command-line interface"
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
     "typer>=0.24.1",
-    "sference-sdk>=0.0.1",
+    "sference-sdk>=0.0.3",
 ]
 
 [project.scripts]

{sference_cli-0.0.2 → sference_cli-0.0.3}/sference_cli/main.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import logging
 import os
 import sys
 import time
@@ -18,14 +19,18 @@ from . import stream_cache as stream_cache_mod
 
 _T = TypeVar("_T")
 
+_logger = logging.getLogger(__name__)
+
 
 app = typer.Typer(help="sference CLI", invoke_without_command=True)
 auth_app = typer.Typer(help="Auth commands", invoke_without_command=True)
 batch_app = typer.Typer(help="Batch commands", invoke_without_command=True)
 stream_app = typer.Typer(help="Stream commands", invoke_without_command=True)
+responses_app = typer.Typer(help="Responses commands", invoke_without_command=True)
 app.add_typer(auth_app, name="auth")
 app.add_typer(batch_app, name="batch")
 app.add_typer(stream_app, name="stream")
+app.add_typer(responses_app, name="responses")
 
 CREDENTIALS_PATH = Path.home() / ".sference" / "credentials.json"
 
@@ -52,6 +57,12 @@ def _read_token() -> str | None:
 
 
 def _client(base_url: Optional[str] = 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())
 
 
@@ -121,6 +132,26 @@ def _print(value: object, as_json: bool) -> None:
         typer.echo(value)
 
 
+def _wait_for_response(
+    client: SferenceClient, response_id: str, *, poll_ms: int, timeout_s: int
+) -> Any:
+    """Poll GET /v1/responses/{id} until terminal status or timeout."""
+    deadline = time.time() + max(1, timeout_s)
+    last: Any = None
+    while True:
+        last = _call_api(lambda: client.get_response(response_id))
+        if hasattr(last, "model_dump"):
+            d = last.model_dump()
+            status = d.get("status") if isinstance(d, dict) else None
+        else:
+            status = getattr(last, "status", None)
+        if status in ("completed", "failed", "cancelled"):
+            return last
+        if time.time() >= deadline:
+            return last
+        time.sleep(max(10, poll_ms) / 1000.0)
+
+
 def _mvp_batch_window_only(value: str) -> str:
     if value != "24h":
         raise typer.BadParameter('Only "24h" is supported in MVP.', param_hint="--window")
@@ -165,6 +196,14 @@ def _stream_root(ctx: typer.Context) -> None:
         raise typer.Exit(code=0)
 
 
+@responses_app.callback()
+def _responses_root(ctx: typer.Context) -> None:
+    """Print help when invoked without a command."""
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit(code=0)
+
+
 @auth_app.command("login")
 def auth_login(
     api_key: Optional[str] = typer.Option(
@@ -172,6 +211,12 @@ def auth_login(
         "--api-key",
         help="API key (sk_...) or JWT. Non-interactive: saves immediately (e.g. CI).",
     ),
+    as_json: bool = typer.Option(False, "--json", help="Print authenticated user as JSON after validation."),
+    validate: bool = typer.Option(
+        True,
+        "--validate/--no-validate",
+        help="Validate the credential by calling GET /v1/auth/me and print the authenticated user.",
+    ),
     console_url: Optional[str] = typer.Option(
         None,
         "--console-url",
@@ -188,6 +233,16 @@ def auth_login(
             raise typer.Exit(code=1)
         _write_token(key)
         typer.echo(f"Credentials saved to {CREDENTIALS_PATH}")
+        if validate:
+            client = _client(None)
+            me = _call_api(client.get_me)
+            if as_json:
+                _print(me, True)
+            else:
+                if isinstance(me, dict) and "username" in me and "role" in me:
+                    typer.echo(f"Authenticated as {me['username']} ({me['role']}).")
+                else:
+                    typer.echo(f"Authenticated. {me}")
         return
 
     base = (console_url or DEFAULT_CONSOLE_URL).rstrip("/")
@@ -213,6 +268,16 @@ def auth_login(
         raise typer.Exit(code=1)
     _write_token(token.strip())
     typer.echo(f"Credentials saved to {CREDENTIALS_PATH}")
+    if validate:
+        client = _client(None)
+        me = _call_api(client.get_me)
+        if as_json:
+            _print(me, True)
+        else:
+            if isinstance(me, dict) and "username" in me and "role" in me:
+                typer.echo(f"Authenticated as {me['username']} ({me['role']}).")
+            else:
+                typer.echo(f"Authenticated. {me}")
 
 
 @auth_app.command("me")
@@ -226,6 +291,113 @@ def auth_me(
     _print(me, as_json)
 
 
+@responses_app.command("create")
+def responses_create(
+    model: str = typer.Option(..., "--model"),
+    content: str = typer.Option(..., "--content"),
+    wait: bool = typer.Option(False, "--wait/--no-wait"),
+    poll_ms: int = typer.Option(500, "--poll-ms", help="Polling interval when --wait is enabled."),
+    timeout_s: int = typer.Option(60, "--timeout-s", help="Timeout in seconds when --wait is enabled."),
+    base_url: str = typer.Option("https://api.sference.com"),
+) -> None:
+    _ensure_api_credential()
+    client = _client(base_url)
+    resp = _call_api(
+        lambda: client.create_response(model=model, input=[{"role": "user", "content": content}])
+    )
+    if wait:
+        final = _wait_for_response(client, resp.id, poll_ms=poll_ms, timeout_s=timeout_s)
+        if getattr(final, "status", None) not in ("completed", "failed", "cancelled"):
+            _print(final.model_dump(), True)
+            raise typer.Exit(code=1)
+        resp = final
+    _print(resp.model_dump(), True)
+
+
+@responses_app.command("result")
+def responses_result(
+    id: str = typer.Option(..., "--id"),
+    poll_ms: int = typer.Option(500, "--poll-ms", help="Polling interval while waiting for completion."),
+    base_url: str = typer.Option("https://api.sference.com"),
+) -> None:
+    """Wait for a response to reach a terminal status and print the final JSON.
+
+    Use Ctrl-C to stop waiting.
+    """
+    _ensure_api_credential()
+    client = _client(base_url)
+    try:
+        while True:
+            resp = _call_api(lambda: client.get_response(id))
+            d = resp.model_dump()
+            status = d.get("status") if isinstance(d, dict) else None
+            if status in ("completed", "failed", "cancelled"):
+                _print(d, True)
+                return
+            time.sleep(max(10, poll_ms) / 1000.0)
+    except KeyboardInterrupt:
+        raise typer.Exit(code=130) from None
+
+
+@responses_app.command("tail")
+def responses_tail(
+    stream_id: Optional[str] = typer.Option(
+        None,
+        "--stream-id",
+        help="Optional stream UUID; omit to tail non-stream completion events only.",
+    ),
+    consumer: str = typer.Option("default", "--consumer", help="Checkpoint namespace for resume."),
+    from_latest: bool = typer.Option(
+        False,
+        "--from-latest",
+        help="Ignore saved checkpoint and start from the latest events page.",
+    ),
+    no_checkpoint: bool = typer.Option(False, "--no-checkpoint", help="Do not read or write checkpoints."),
+    poll_ms: int = typer.Option(5000, "--poll-ms", help="Long-poll wait_ms when catching up (max 30000)."),
+    base_url: str = typer.Option("https://api.sference.com"),
+    as_json: bool = typer.Option(False, "--json"),
+) -> None:
+    """Print completion events as JSONL (GET /v1/responses/events). Ctrl-C to stop.
+
+    Omit --stream-id for standalone/batch completions; pass --stream-id to scope to a stream.
+    """
+    _ = as_json
+    _ensure_api_credential()
+    client = _client(base_url)
+    bu = base_url.rstrip("/")
+    ck = stream_id if stream_id else "__responses_events__"
+
+    if from_latest and not no_checkpoint:
+        clear_checkpoint(bu, ck, consumer)
+
+    last: str | None = None
+    if not no_checkpoint and not from_latest:
+        last = load_checkpoint(bu, ck, consumer)
+
+    try:
+        while True:
+
+            def fetch() -> Any:
+                return client.list_responses_events(
+                    stream_id=stream_id,
+                    limit=50,
+                    starting_after=last,
+                    wait_ms=min(poll_ms, 30000),
+                )
+
+            page = _call_api(fetch)
+            if not page.data:
+                time.sleep(max(1, poll_ms) / 1000.0)
+                continue
+            for ev in page.data:
+                typer.echo(json.dumps(ev.model_dump(), default=str))
+                last = ev.completion_id
+                if not no_checkpoint:
+                    save_checkpoint(bu, ck, consumer, ev.completion_id)
+    except KeyboardInterrupt:
+        typer.echo("Interrupted.", err=True)
+        raise typer.Exit(code=130) from None
+
 @batch_app.command("list")
 def batch_list(
     base_url: str = typer.Option("https://api.sference.com"),
@@ -519,7 +691,8 @@ def stream_submit(
             typer.echo(f"Unrecognized line format: {line[:100]}", err=True)
             raise typer.Exit(code=1)
 
-        resp = _call_api(lambda: client.create_response(body))
+        # SDK signature is keyword-only; pass the payload as kwargs.
+        resp = _call_api(lambda: client.create_response(**body))
         created_responses.append(resp)
 
     # Return stream detail-like response for compatibility
@@ -556,58 +729,6 @@ def stream_cancel(
     _print(st.model_dump(), as_json)
 
 
-@stream_app.command("tail")
-def stream_tail(
-    stream_id: str = typer.Option(..., "--stream-id"),
-    consumer: str = typer.Option("default", "--consumer", help="Checkpoint namespace for resume."),
-    from_latest: bool = typer.Option(
-        False,
-        "--from-latest",
-        help="Ignore saved checkpoint and start from the latest events page.",
-    ),
-    no_checkpoint: bool = typer.Option(False, "--no-checkpoint", help="Do not read or write checkpoints."),
-    poll_ms: int = typer.Option(5000, "--poll-ms", help="Long-poll wait_ms when catching up (max 30000)."),
-    base_url: str = typer.Option("https://api.sference.com"),
-    as_json: bool = typer.Option(False, "--json"),
-) -> None:
-    """Print stream result events as JSONL (stdout). Checkpoints after each event unless --no-checkpoint."""
-    _ = as_json
-    _ensure_api_credential()
-    client = _client(base_url)
-    bu = base_url.rstrip("/")
-
-    if from_latest and not no_checkpoint:
-        clear_checkpoint(bu, stream_id, consumer)
-
-    last: str | None = None
-    if not no_checkpoint and not from_latest:
-        last = load_checkpoint(bu, stream_id, consumer)
-
-    try:
-        while True:
-
-            def fetch() -> Any:
-                return client.list_stream_events(
-                    stream_id,
-                    limit=50,
-                    starting_after=last,
-                    wait_ms=min(poll_ms, 30000),
-                )
-
-            page = _call_api(fetch)
-            if not page.data:
-                time.sleep(max(1, poll_ms) / 1000.0)
-                continue
-            for ev in page.data:
-                typer.echo(json.dumps(ev.model_dump(), default=str))
-                last = ev.completion_id
-                if not no_checkpoint:
-                    save_checkpoint(bu, stream_id, consumer, ev.completion_id)
-    except KeyboardInterrupt:
-        typer.echo("Interrupted.", err=True)
-        raise typer.Exit(code=130) from None
-
-
 @batch_app.command("download-results")
 def batch_download_results(
     batch_id: str = typer.Option(..., "--batch-id"),