courier-encode 0.1.0__tar.gz → 0.1.2__tar.gz

courier_encode-0.1.2/.idea/workspace.xml

@@ -0,0 +1,83 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="AutoImportSettings">
+    <option name="autoReloadType" value="ALL" />
+  </component>
+  <component name="ChangeListManager">
+    <list default="true" id="9259bfb5-884c-4336-83fd-f640b45e88c5" name="Changes" comment="">
+      <change beforePath="$PROJECT_DIR$/pyproject.toml" beforeDir="false" afterPath="$PROJECT_DIR$/pyproject.toml" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/encode/_http.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/encode/_http.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/encode/relay.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/encode/relay.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/tests/test_streaming.py" beforeDir="false" afterPath="$PROJECT_DIR$/tests/test_streaming.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/uv.lock" beforeDir="false" afterPath="$PROJECT_DIR$/uv.lock" afterDir="false" />
+    </list>
+    <option name="SHOW_DIALOG" value="false" />
+    <option name="HIGHLIGHT_CONFLICTS" value="true" />
+    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
+    <option name="LAST_RESOLUTION" value="IGNORE" />
+  </component>
+  <component name="EmbeddingIndexingInfo">
+    <option name="cachedIndexableFilesCount" value="3" />
+    <option name="fileBasedEmbeddingIndicesEnabled" value="true" />
+  </component>
+  <component name="Git.Settings">
+    <option name="RECENT_GIT_ROOT_PATH" value="$PROJECT_DIR$" />
+  </component>
+  <component name="McpProjectServerCommands">
+    <commands />
+    <urls />
+  </component>
+  <component name="ProjectColorInfo"><![CDATA[{
+  "associatedIndex": 8,
+  "fromUser": false
+}]]></component>
+  <component name="ProjectId" id="3DRfPMmybWPzhvemSx3K8mYqPeH" />
+  <component name="ProjectViewState">
+    <option name="hideEmptyMiddlePackages" value="true" />
+    <option name="showLibraryContents" value="true" />
+  </component>
+  <component name="PropertiesComponent"><![CDATA[{
+  "keyToString": {
+    "ModuleVcsDetector.initialDetectionPerformed": "true",
+    "RunOnceActivity.MCP Project settings loaded": "true",
+    "RunOnceActivity.ShowReadmeOnStart": "true",
+    "RunOnceActivity.TerminalTabsStorage.copyFrom.TerminalArrangementManager.252": "true",
+    "RunOnceActivity.git.unshallow": "true",
+    "RunOnceActivity.typescript.service.memoryLimit.init": "true",
+    "codeWithMe.voiceChat.enabledByDefault": "false",
+    "com.intellij.ml.llm.matterhorn.ej.ui.settings.DefaultModelSelectionForGA.v1": "true",
+    "git-widget-placeholder": "main",
+    "junie.onboarding.icon.badge.shown": "true",
+    "last_opened_file_path": "/Users/jacksonoaks/Documents/business/recursion_ai/encode",
+    "node.js.detected.package.eslint": "true",
+    "node.js.detected.package.tslint": "true",
+    "node.js.selected.package.eslint": "(autodetect)",
+    "node.js.selected.package.tslint": "(autodetect)",
+    "nodejs_package_manager_path": "npm",
+    "to.speed.mode.migration.done": "true",
+    "vue.rearranger.settings.migration": "true"
+  }
+}]]></component>
+  <component name="SharedIndexes">
+    <attachedChunks>
+      <set>
+        <option value="bundled-js-predefined-d6986cc7102b-3bd3a6803838-JavaScript-PY-261.22158.340" />
+        <option value="bundled-python-sdk-b63d5a1f7c97-b61e75351b1f-com.jetbrains.pycharm.pro.sharedIndexes.bundled-PY-261.22158.340" />
+      </set>
+    </attachedChunks>
+  </component>
+  <component name="TaskManager">
+    <task active="true" id="Default" summary="Default task">
+      <changelist id="9259bfb5-884c-4336-83fd-f640b45e88c5" name="Changes" comment="" />
+      <created>1778249777914</created>
+      <option name="number" value="Default" />
+      <option name="presentableId" value="Default" />
+      <updated>1778249777914</updated>
+      <workItem from="1778249778942" duration="11261000" />
+    </task>
+    <servers />
+  </component>
+  <component name="TypeScriptGeneratedFilesManager">
+    <option name="version" value="3" />
+  </component>
+</project>

{courier_encode-0.1.0 → courier_encode-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: courier-encode
-Version: 0.1.0
+Version: 0.1.2
 Summary: Python SDK for OpenAI-compatible inference endpoints (Courier and friends) with auto tool-call loops, structured outputs, and Whisper.
 Project-URL: Homepage, https://getcourier.ai
 Project-URL: Documentation, https://getcourier.ai/docs
@@ -211,7 +211,7 @@ License-File: LICENSE
 Keywords: agents,courier,llm,openai,sdk,tool-calling,whisper
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
+Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11

{courier_encode-0.1.0 → courier_encode-0.1.2}/docs.md

@@ -232,7 +232,7 @@ print(out.tool_calls[0].name)  # "get_weather"
 print(out.tool_calls[0].result)  # {"city": "Denver", "temp_f": 72}
 ```
 
-The loop runs until the model stops calling tools (or hits `max_tool_iterations`, default `8`).
+The loop runs until the model stops calling tools. There is no cap by default — pass `max_tool_iterations=N` if you want to bail on a runaway model. See [Capping iterations](#capping-iterations-optional) below.
 
 ### What the SDK does for you
 
@@ -406,7 +406,7 @@ The tool loop and intercept work identically across both endpoints — `function
 
 ## Streaming
 
-Set `stream=True` and iterate the handle:
+Set `stream=True` and iterate the handle. The handle yields `StreamEvent` objects — parsed Python values, not raw SSE bytes. The upstream HTTP connection is held open with `httpx.stream()`, so backpressure works end-to-end.
 
 ```python
 handle = encode.relay(
@@ -419,14 +419,82 @@ for event in handle:
         print(event.data, end="", flush=True)
 ```
 
-For `/v1/responses`, events use the typed names from the spec (`response.output_text.delta`, `response.completed`, etc.):
+### `StreamEvent`
+
+Every event carries three fields:
+
+| field   | type             | meaning                                                                 |
+| ------- | ---------------- | ----------------------------------------------------------------------- |
+| `type`  | `str`            | event kind (see tables below)                                           |
+| `data`  | `Any`            | the parsed payload — a `str` for text deltas, `dict`/`list` otherwise   |
+| `raw`   | `dict` \| `None` | the full upstream chunk as parsed JSON (re-serialize this if proxying)  |
+
+### Event types — `/v1/chat/completions`
+
+| `event.type`         | `event.data`                                                          |
+| -------------------- | --------------------------------------------------------------------- |
+| `content.delta`      | `str` — the next token of assistant text                              |
+| `tool_calls.delta`   | `list[dict]` — partial tool-call fragments (raw upstream deltas)      |
+| `tool_call.start`    | `{id, name, arguments: dict, iteration}` — fully assembled tool call about to run |
+| `tool_call.result`   | `{id, result, result_serialized, duration_ms, iteration}` — tool returned successfully |
+| `tool_call.error`    | `{id, error, iteration}` — tool raised; loop continues                |
+| `iteration.end`      | `{iteration, had_tool_calls}` — one tool-loop iteration completed     |
+| `finish`             | `str` — final finish reason (`"stop"`, `"length"`, `"tool_calls"`, …) |
+
+The new `tool_call.*` events fire **only when `tools=` is set**. Without tools, you only see `content.delta` / `finish`. The raw `tool_calls.delta` events still fire when the model emits tool-call fragments — most chat-UI consumers can ignore them and key off `tool_call.start` / `tool_call.result` instead.
+
+### Event types — `/v1/responses`
+
+For the responses endpoint, upstream events are passed through with their `type` field intact (`response.output_text.delta`, `response.completed`, …) and `event.data` set to the entire parsed event dict. When `tools=` is set, encode also synthesizes `content.delta` (mapped from `response.output_text.delta`) and the same `tool_call.start` / `tool_call.result` / `tool_call.error` / `iteration.end` events as chat, so a single consumer can handle both endpoints uniformly.
 
 ```python
 for event in encode.relay(model="m", input="hi", stream=True):
     print(event.type, event.data)
 ```
 
-> Streaming with auto-tool-loop is not supported in v0.1.0 — you can only iterate streams when `tools=None`. Use `stream=False` with tools, then re-issue a streaming call yourself if you want to stream the final answer.
+### Streaming with tools (auto-loop)
+
+Pass `tools=` and `stream=True` together. The SDK runs the same auto-tool-loop as `stream=False` but yields events as the iteration proceeds — content tokens forward to the consumer in real time, and each tool dispatch fires `tool_call.start` / `tool_call.result` (or `.error`) events the consumer can render in a chat UI.
+
+```python
+def get_weather(city: str) -> dict:
+    """Get current weather by city."""
+    return {"city": city, "temp_f": 72}
+
+for ev in encode.relay(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "What's the weather in Denver?"}],
+    tools=[get_weather],
+    stream=True,
+):
+    if ev.type == "content.delta":
+        print(ev.data, end="", flush=True)
+    elif ev.type == "tool_call.start":
+        print(f"\n[calling {ev.data['name']}({ev.data['arguments']})]")
+    elif ev.type == "tool_call.result":
+        print(f"[result: {ev.data['result']}]")
+    elif ev.type == "tool_call.error":
+        print(f"[tool error: {ev.data['error']}]")
+```
+
+`max_tool_iterations` still works — passing a cap raises `MaxToolIterationsError` (with `.partial` carrying the streamed-so-far state) the moment the cap is exceeded.
+
+`Messages` containers passed as `messages=` are mutated when the stream finishes, just like the non-stream path. If the consumer abandons the iterator early (breaks out of the loop), the container is **not** updated — drain the iterator if you want the absorption.
+
+### Async streaming
+
+Use `relay_async` with `async for`:
+
+```python
+handle = encode.relay_async(model="m", messages=[...], tools=[get_weather], stream=True)
+async for event in handle:
+    if event.type == "content.delta":
+        print(event.data, end="", flush=True)
+```
+
+### Restrictions
+
+- **`response_format` is not supported when streaming.** Combining the two raises `ValueError` immediately — structured output isn't meaningful mid-stream.
 
 ---
 
@@ -691,7 +759,7 @@ async for event in AsyncRelayHandle: ...
 # Models
 encode.Message, Messages, Conversation, TextContent, ImageContent, AudioContent
 encode.RelayResponse, WhisperResponse, ToolCallRecord, AssistantTurn, Usage
-encode.InterceptEvent
+encode.InterceptEvent, StreamEvent
 
 # Errors (all inherit CourierError)
 encode.AuthError, InvalidRequestError, InvalidToolCallError, InvalidToolChoiceError,

{courier_encode-0.1.0 → courier_encode-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "courier-encode"
-version = "0.1.0"
+version = "0.1.2"
 description = "Python SDK for OpenAI-compatible inference endpoints (Courier and friends) with auto tool-call loops, structured outputs, and Whisper."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -14,7 +14,7 @@ keywords = ["openai", "courier", "llm", "sdk", "agents", "tool-calling", "whispe
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
+    "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",

{courier_encode-0.1.0 → courier_encode-0.1.2}/src/encode/__init__.py

@@ -22,6 +22,7 @@ from . import _config
 # Auto-load .env once on import (opt-out via ENCODE_DISABLE_DOTENV=1).
 _config.load_dotenv_once()
 
+from ._streaming import StreamEvent
 from ._version import __version__
 from .client import AsyncClient, Client
 from .errors import (
@@ -77,6 +78,7 @@ __all__ = [
     "RelayHandle",
     "AsyncRelayHandle",
     "InterceptEvent",
+    "StreamEvent",
     "whisper",
     "whisper_async",
     "Message",

{courier_encode-0.1.0 → courier_encode-0.1.2}/src/encode/_http.py

@@ -47,6 +47,17 @@ def parse_body(resp: httpx.Response) -> Any:
 def raise_for_status(resp: httpx.Response) -> None:
     if resp.is_success:
         return
+    # Idempotent for already-buffered responses; required for sync streaming.
+    resp.read()
+    body = parse_body(resp)
+    raise errors.from_envelope(body, status=resp.status_code)
+
+
+async def araise_for_status(resp: httpx.Response) -> None:
+    if resp.is_success:
+        return
+    # Required for responses obtained via async_client.stream(...).
+    await resp.aread()
     body = parse_body(resp)
     raise errors.from_envelope(body, status=resp.status_code)
 

{courier_encode-0.1.0 → courier_encode-0.1.2}/src/encode/_streaming.py

@@ -95,3 +95,46 @@ async def aiter_responses(resp: httpx.Response) -> AsyncIterator[StreamEvent]:
             continue
         etype = event.get("type", "unknown")
         yield StreamEvent(type=etype, data=event, raw=event)
+
+
+# ---------------------------------------------------------------------------
+# Chat tool-call delta accumulator
+#
+# Chat completions emits tool calls as a sequence of partial deltas keyed by
+# `index`. Each chunk may contribute id/type/function.name on first arrival
+# and append more bytes to function.arguments on subsequent chunks. The relay
+# tool-loop needs the assembled list at end-of-stream to dispatch tools.
+# ---------------------------------------------------------------------------
+
+
+def accumulate_chat_tool_calls(
+    buf: dict[int, dict[str, Any]],
+    deltas: list[dict[str, Any]] | None,
+) -> None:
+    """Merge a chunk's `tool_calls` delta list into ``buf`` keyed by index.
+
+    Mutates ``buf`` in place. Safe to call with a ``None`` or empty deltas list.
+    """
+    if not deltas:
+        return
+    for d in deltas:
+        idx = d.get("index", 0)
+        slot = buf.setdefault(
+            idx, {"id": "", "type": "function", "function": {"name": "", "arguments": ""}}
+        )
+        if d.get("id"):
+            slot["id"] = d["id"]
+        if d.get("type"):
+            slot["type"] = d["type"]
+        fn = d.get("function") or {}
+        if fn.get("name"):
+            slot["function"]["name"] = fn["name"]
+        if fn.get("arguments"):
+            slot["function"]["arguments"] += fn["arguments"]
+
+
+def finalize_chat_tool_calls(
+    buf: dict[int, dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """Return the buffered tool calls sorted by index, in /v1/chat shape."""
+    return [buf[k] for k in sorted(buf)]

{courier_encode-0.1.0 → courier_encode-0.1.2}/src/encode/messages.py

@@ -14,7 +14,7 @@ import mimetypes
 from collections.abc import Iterable, Iterator, Sequence
 from os import PathLike
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Literal
+from typing import TYPE_CHECKING, Any, Literal, overload
 
 from pydantic import BaseModel, ConfigDict
 
@@ -193,15 +193,16 @@ def _coerce_content(content: Any) -> Any:
     return content
 
 
-class Messages:
+class Messages(Sequence[dict[str, Any]]):
     """Mutable conversation container.
 
     Pass to ``relay()`` / ``relay_async()`` as ``messages=`` and the SDK will
     append the new turns in place after the loop completes. Plain lists work
     too — they are not mutated.
 
-    Quacks like a list (``__len__``, ``__iter__``, ``__getitem__``, ``__bool__``)
-    and exposes chainable adders for ergonomic construction.
+    Implements :class:`collections.abc.Sequence`, so it satisfies
+    ``Sequence[Any]`` parameter types and supports ``len()``, iteration,
+    indexing, slicing, ``in``, ``index()``, ``count()``, etc.
 
     Example:
         m = (
@@ -282,7 +283,13 @@ class Messages:
     def __iter__(self) -> Iterator[dict[str, Any]]:
         return iter(self._items)
 
-    def __getitem__(self, idx: int) -> dict[str, Any]:
+    @overload
+    def __getitem__(self, idx: int) -> dict[str, Any]: ...
+    @overload
+    def __getitem__(self, idx: slice) -> list[dict[str, Any]]: ...
+    def __getitem__(
+        self, idx: int | slice
+    ) -> dict[str, Any] | list[dict[str, Any]]:
         return self._items[idx]
 
     def __bool__(self) -> bool: