gumloop 0.2.0__tar.gz → 0.3.1__tar.gz

{gumloop-0.2.0 → gumloop-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gumloop
-Version: 0.2.0
+Version: 0.3.1
 Summary: Python client for the Gumloop API
 Project-URL: Homepage, https://github.com/gumloop/gumloop-py
 Project-URL: Bug Tracker, https://github.com/gumloop/gumloop-py/issues
@@ -15,6 +15,7 @@ Requires-Python: >=3.10
 Requires-Dist: httpx-sse>=0.4.0
 Requires-Dist: httpx>=0.24.1
 Requires-Dist: keyring>=24
+Requires-Dist: openrouter==0.9.1
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: questionary>=2.0
 Requires-Dist: rich

{gumloop-0.2.0 → gumloop-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gumloop"
-version = "0.2.0"
+version = "0.3.1"
 description = "Python client for the Gumloop API"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -22,6 +22,9 @@ dependencies = [
     "httpx>=0.24.1",
     "httpx-sse>=0.4.0",
     "keyring>=24",
+    # Spec source of truth — we import only openrouter.components.*.
+    # Exact pin: Speakeasy 0.x can rename fields on any bump.
+    "openrouter==0.9.1",
     "pydantic>=2.0.0",
     "questionary>=2.0",
     "rich",
@@ -40,6 +43,8 @@ dev = [
     "pre-commit>=2.21.0",
     "pyright>=1.1.409",
     "pytest>=7.4.4",
+    "pytest-timeout>=2.4.0",
+    "pytest-xdist>=3.8.0",
     "python-dotenv>=0.21.1",
     "respx>=0.21.1",
     "ruff>=0.15.12",
@@ -52,6 +57,9 @@ build = [
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+markers = [
+    "live: hits the real Gumloop API and upstream providers; opt-in via `-m live`",
+]
 
 [tool.ruff]
 line-length = 120

{gumloop-0.2.0 → gumloop-0.3.1}/src/gumloop/__init__.py

@@ -6,7 +6,7 @@ from gumloop.errors import AuthenticationError
 from gumloop.errors import GumloopError
 from gumloop.oauth import OAuth
 
-__version__ = "0.2.0"
+__version__ = "0.3.1"
 __all__ = [
     "APIStatusError",
     "AsyncGumloop",

{gumloop-0.2.0 → gumloop-0.3.1}/src/gumloop/_client.py

@@ -15,11 +15,13 @@ from gumloop.resources import Agents
 from gumloop.resources import Artifacts
 from gumloop.resources import AsyncAgents
 from gumloop.resources import AsyncArtifacts
+from gumloop.resources import AsyncChat
 from gumloop.resources import AsyncMCP
 from gumloop.resources import AsyncModels
 from gumloop.resources import AsyncSessions
 from gumloop.resources import AsyncSkills
 from gumloop.resources import AsyncTeams
+from gumloop.resources import Chat
 from gumloop.resources import Models
 from gumloop.resources import Sessions
 from gumloop.resources import Skills
@@ -49,7 +51,7 @@ class Gumloop:
         *,
         access_token: str | None = None,
         user_id: str | None = None,
-        base_url: str = DEFAULT_BASE_URL,
+        base_url: str | None = None,
         stream_base_url: str | None = None,
         timeout: float = DEFAULT_TIMEOUT,
         stream_timeout: float | None = DEFAULT_STREAM_TIMEOUT,
@@ -60,7 +62,8 @@ class Gumloop:
         # x-auth-key header to look up the owner's stored secret. OAuth
         # callers omit it because the bearer token already identifies them.
         self.user_id = user_id or os.environ.get("GUMLOOP_USER_ID")
-        self.base_url = base_url.rstrip("/")
+        # Defaults to production; GUMLOOP_BASE_URL is an optional override.
+        self.base_url = (base_url or os.environ.get("GUMLOOP_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
         self.stream_base_url = (stream_base_url or _derive_stream_base_url(self.base_url)).rstrip("/")
         self.timeout = timeout
         self.stream_timeout = stream_timeout
@@ -76,6 +79,7 @@ class Gumloop:
 
         self.agents = Agents(self._http)
         self.sessions = Sessions(self._http)
+        self.chat = Chat(self._http)
         self.models = Models(self._http)
         self.mcp = MCP(self._http)
         self.teams = Teams(self._http)
@@ -102,7 +106,7 @@ class AsyncGumloop:
         *,
         access_token: str | None = None,
         user_id: str | None = None,
-        base_url: str = DEFAULT_BASE_URL,
+        base_url: str | None = None,
         stream_base_url: str | None = None,
         timeout: float = DEFAULT_TIMEOUT,
         stream_timeout: float | None = DEFAULT_STREAM_TIMEOUT,
@@ -110,7 +114,8 @@ class AsyncGumloop:
         self.api_key = api_key
         self.access_token = access_token or api_key or os.environ.get("GUMLOOP_ACCESS_TOKEN")
         self.user_id = user_id or os.environ.get("GUMLOOP_USER_ID")
-        self.base_url = base_url.rstrip("/")
+        # Defaults to production; GUMLOOP_BASE_URL is an optional override.
+        self.base_url = (base_url or os.environ.get("GUMLOOP_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
         self.stream_base_url = (stream_base_url or _derive_stream_base_url(self.base_url)).rstrip("/")
         self.timeout = timeout
         self.stream_timeout = stream_timeout
@@ -126,6 +131,7 @@ class AsyncGumloop:
 
         self.agents = AsyncAgents(self._http)
         self.sessions = AsyncSessions(self._http)
+        self.chat = AsyncChat(self._http)
         self.models = AsyncModels(self._http)
         self.mcp = AsyncMCP(self._http)
         self.teams = AsyncTeams(self._http)

{gumloop-0.2.0 → gumloop-0.3.1}/src/gumloop/_http.py

@@ -1,18 +1,27 @@
 from __future__ import annotations
 
+import logging
 from collections.abc import AsyncIterator
 from collections.abc import Iterator
 from collections.abc import Mapping
 from typing import Any
+from typing import TypeVar
 
 import httpx
 from httpx_sse import EventSource
 from httpx_sse import ServerSentEvent
+from pydantic import BaseModel
+from pydantic import ValidationError
 
 from gumloop.errors import AuthenticationError
 from gumloop.errors import to_api_error
 from gumloop.types import StreamEvent
 
+logger = logging.getLogger(__name__)
+
+_DONE_SENTINEL = "[DONE]"
+_T = TypeVar("_T", bound=BaseModel)
+
 
 def _auth_headers(access_token: str | None, user_id: str | None) -> dict[str, str]:
     if not access_token:
@@ -104,6 +113,22 @@ class HttpClient:
     def delete(self, path: str) -> Any:
         return self._request("DELETE", path)
 
+    def post_to_stream_host(self, path: str, *, json: Any = None) -> Any:
+        # Endpoints whose streaming variant lives on the stream host (e.g. chat
+        # completions) must accept their unary counterparts at the same host —
+        # the api host has no handler for them.
+        headers = _auth_headers(self.access_token, self.user_id)
+        headers["Content-Type"] = "application/json"
+        response = self._client.post(
+            f"{self._stream_base_url}/{path.lstrip('/')}",
+            headers=headers,
+            timeout=self._stream_timeout,
+            json=json,
+        )
+        if response.status_code >= 400:
+            raise to_api_error(response)
+        return response.json() if response.content else None
+
     def stream(
         self,
         method: str,
@@ -127,6 +152,42 @@ class HttpClient:
             for event in EventSource(response).iter_sse():
                 yield _decode_sse(event)
 
+    def stream_typed(
+        self,
+        method: str,
+        path: str,
+        response_model: type[_T],
+        *,
+        json: Any = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> Iterator[_T]:
+        # Skips the StreamEvent envelope and honors OpenRouter's `data: [DONE]`
+        # terminator. Unparseable events (keep-alives, comments) are skipped.
+        headers = {**_auth_headers(self.access_token, self.user_id), "Accept": "text/event-stream"}
+        with self._client.stream(
+            method,
+            f"{self._stream_base_url}/{path.lstrip('/')}",
+            headers=headers,
+            timeout=self._stream_timeout,
+            json=json,
+            params=_omit_none_params(params),
+        ) as response:
+            if response.status_code >= 400:
+                response.read()
+                raise to_api_error(response)
+            for event in EventSource(response).iter_sse():
+                if event.data == _DONE_SENTINEL:
+                    return
+                if not event.data:
+                    continue
+                try:
+                    yield response_model.model_validate_json(event.data)
+                except ValidationError:
+                    # Server-side mid-stream error frames or schema-drift events
+                    # land here. 
+                    logger.debug("dropped non-%s SSE: %s", response_model.__name__, event.data)
+                    continue
+
     def _request(self, method: str, path: str, **kwargs: Any) -> Any:
         # Headers are rebuilt per request so ``access_token`` / ``user_id``
         # can be rotated on a live client without reconstructing it.
@@ -193,6 +254,19 @@ class AsyncHttpClient:
     async def delete(self, path: str) -> Any:
         return await self._request("DELETE", path)
 
+    async def post_to_stream_host(self, path: str, *, json: Any = None) -> Any:
+        headers = _auth_headers(self.access_token, self.user_id)
+        headers["Content-Type"] = "application/json"
+        response = await self._client.post(
+            f"{self._stream_base_url}/{path.lstrip('/')}",
+            headers=headers,
+            timeout=self._stream_timeout,
+            json=json,
+        )
+        if response.status_code >= 400:
+            raise to_api_error(response)
+        return response.json() if response.content else None
+
     async def stream(
         self,
         method: str,
@@ -216,6 +290,40 @@ class AsyncHttpClient:
             async for event in EventSource(response).aiter_sse():
                 yield _decode_sse(event)
 
+    async def stream_typed(
+        self,
+        method: str,
+        path: str,
+        response_model: type[_T],
+        *,
+        json: Any = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> AsyncIterator[_T]:
+        headers = {**_auth_headers(self.access_token, self.user_id), "Accept": "text/event-stream"}
+        async with self._client.stream(
+            method,
+            f"{self._stream_base_url}/{path.lstrip('/')}",
+            headers=headers,
+            timeout=self._stream_timeout,
+            json=json,
+            params=_omit_none_params(params),
+        ) as response:
+            if response.status_code >= 400:
+                await response.aread()
+                raise to_api_error(response)
+            async for event in EventSource(response).aiter_sse():
+                if event.data == _DONE_SENTINEL:
+                    return
+                if not event.data:
+                    continue
+                try:
+                    yield response_model.model_validate_json(event.data)
+                except ValidationError:
+                    # Server-side mid-stream error frames or schema-drift events
+                    # land here. 
+                    logger.debug("dropped non-%s SSE: %s", response_model.__name__, event.data)
+                    continue
+
     async def _request(self, method: str, path: str, **kwargs: Any) -> Any:
         headers = _auth_headers(self.access_token, self.user_id)
         if not kwargs.get("files"):

gumloop-0.3.1/src/gumloop/cli/commands/chat.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Annotated
+from typing import Any
+from typing import Iterator
+
+import typer
+
+from gumloop import GumloopError
+from gumloop.cli.console import console
+from gumloop.cli.console import print_json
+from gumloop.cli.context import CliContext
+from gumloop.cli.errors import exit_with_error
+from gumloop.spec import ChatStreamChunk
+
+chat_app = typer.Typer(
+    help="Chat completions.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+completions_app = typer.Typer(
+    help="Create chat completions.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+chat_app.add_typer(completions_app, name="completions")
+
+
+_EPILOG = (
+    "Examples:\n"
+    '  gumloop chat completions create "ping" -m claude-sonnet-4-5\n'
+    '  echo "summarize" | gumloop chat completions create -m gpt-4o-mini --message-stdin -\n'
+    '  gumloop chat completions create "x" -m claude-haiku-4-5 --json\n'
+    '  gumloop chat completions create "stream me" -m claude-sonnet-4-5 --stream --json    # ndjson\n'
+    '  gumloop chat completions create "image please" -m gemini-2.5-flash-image \\\n'
+    "      --modality image --modality text --json\n"
+    "\n"
+    "This command mirrors the Python SDK call `client.chat.completions.create(...)`\n"
+    "1:1. Every flag maps to the matching SDK kwarg (e.g. --modality -> modalities,\n"
+    "--max-completion-tokens -> max_completion_tokens). Output streams when stdout\n"
+    "is a TTY and the request supports it; pass --stream or --no-stream to be\n"
+    "explicit."
+)
+
+
+@completions_app.command("create", epilog=_EPILOG)
+def create_completion(
+    ctx: typer.Context,
+    prompt: Annotated[
+        str | None,
+        typer.Argument(help="User message. Pass --message-stdin - to read from stdin instead."),
+    ] = None,
+    model: Annotated[
+        str,
+        typer.Option("--model", "-m", help="Model slug, e.g. claude-sonnet-4-5."),
+    ] = "",
+    system: Annotated[
+        list[str] | None,
+        typer.Option("--system", "-s", help="System message prepended to the conversation. Repeatable."),
+    ] = None,
+    message_stdin: Annotated[
+        str | None,
+        typer.Option("--message-stdin", help="Use '-' to read the user message from stdin.", metavar="-"),
+    ] = None,
+    max_completion_tokens: Annotated[
+        int | None,
+        typer.Option(
+            "--max-completion-tokens",
+            help="Cap on completion tokens. SDK-aligned name; maps to max_completion_tokens.",
+        ),
+    ] = None,
+    max_tokens: Annotated[
+        int | None,
+        typer.Option(
+            "--max-tokens",
+            help="Legacy alias for --max-completion-tokens. Same wire field.",
+            hidden=True,
+        ),
+    ] = None,
+    temperature: Annotated[
+        float | None,
+        typer.Option("--temperature", help="Sampling temperature."),
+    ] = None,
+    modality: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--modality",
+            help="Modality to request. Repeatable (e.g. --modality image --modality text). Maps to `modalities`.",
+        ),
+    ] = None,
+    schema_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--schema-file",
+            help="Path to a JSON Schema file. Sent as response_format={type:json_schema,...}.",
+        ),
+    ] = None,
+    schema_name: Annotated[
+        str,
+        typer.Option("--schema-name", help="json_schema.name field (paired with --schema-file)."),
+    ] = "schema",
+    stream: Annotated[
+        bool,
+        typer.Option("--stream", help="Force streaming output (always wins over TTY auto-detect)."),
+    ] = False,
+    no_stream: Annotated[
+        bool,
+        typer.Option("--no-stream", help="Wait for the full response then print. Always wins over TTY auto-detect."),
+    ] = False,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print the response as JSON. Streaming + --json emits ndjson (one chunk per line)."),
+    ] = False,
+) -> None:
+    """Create a chat completion."""
+    cli: CliContext = ctx.obj
+
+    try:
+        if not model:
+            raise GumloopError("Pass --model / -m with a model slug.")
+        if prompt is not None and message_stdin is not None:
+            raise GumloopError("Pass at most one of PROMPT or --message-stdin.")
+        if message_stdin is not None and message_stdin != "-":
+            raise GumloopError("--message-stdin only accepts '-' (reads from stdin).")
+        if stream and no_stream:
+            raise GumloopError("Pass at most one of --stream and --no-stream.")
+        if max_tokens is not None and max_completion_tokens is not None:
+            raise GumloopError("Pass at most one of --max-tokens and --max-completion-tokens.")
+
+        user_message = sys.stdin.read() if message_stdin == "-" else prompt
+        if not user_message:
+            raise GumloopError("Pass a PROMPT or --message-stdin - with text to send.")
+
+        messages: list[dict[str, Any]] = [
+            {"role": "system", "content": s} for s in (system or [])
+        ]
+        messages.append({"role": "user", "content": user_message})
+
+        # Stream resolution: explicit flags always win; --json without --stream
+        # implies unary so machine output is byte-stable; otherwise stream-when-TTY.
+        if stream:
+            should_stream = True
+        elif no_stream or json_output:
+            should_stream = False
+        else:
+            should_stream = _stdout_is_tty()
+
+        kwargs: dict[str, Any] = {"model": model, "messages": messages}
+        token_cap = max_completion_tokens if max_completion_tokens is not None else max_tokens
+        if token_cap is not None:
+            kwargs["max_completion_tokens"] = token_cap
+        if temperature is not None:
+            kwargs["temperature"] = temperature
+        if modality:
+            kwargs["modalities"] = modality
+        if schema_file is not None:
+            schema = json.loads(schema_file.read_text())
+            kwargs["response_format"] = {
+                "type": "json_schema",
+                "json_schema": {"name": schema_name, "strict": True, "schema": schema},
+            }
+
+        if should_stream:
+            kwargs["stream"] = True
+            stream_iter: Iterator[ChatStreamChunk] = cli.call_with_refresh(
+                lambda client: client.chat.completions.create(**kwargs)
+            )
+            for chunk in stream_iter:
+                _emit_stream_chunk(chunk, json_mode=json_output)
+            if not json_output:
+                console.print()  # trailing newline to separate the prompt that follows
+            return
+
+        result = cli.call_with_refresh(
+            lambda client: client.chat.completions.create(**kwargs)
+        )
+    except GumloopError as error:
+        exit_with_error(error, json_output=json_output)
+
+    if json_output:
+        print_json(result)
+        return
+
+    for choice in result.choices:
+        content = choice.message.content
+        if isinstance(content, list):
+            content = "".join(p.get("text", "") for p in content if isinstance(p, dict))
+        if content:
+            console.print(content, markup=False, highlight=False)
+
+
+def _stdout_is_tty() -> bool:
+    # Wrapped so tests can monkeypatch; CliRunner replaces ``sys.stdout`` with
+    # a buffer whose ``isatty()`` always returns False, which would always
+    # collapse the streaming branch.
+    return sys.stdout.isatty()
+
+
+def _emit_stream_chunk(chunk: ChatStreamChunk, *, json_mode: bool = False) -> None:
+    if json_mode:
+        # ndjson: one chunk per line, by_alias so wire field names match the SDK.
+        sys.stdout.write(chunk.model_dump_json(by_alias=True) + "\n")
+        sys.stdout.flush()
+        return
+    for choice in chunk.choices:
+        piece = getattr(choice.delta, "content", None)
+        if piece:
+            # markup=False so output containing [brackets] doesn't trip Rich.
+            console.print(piece, end="", markup=False, highlight=False)