@hcu-lab.me/mcp-device 1.0.9 → 1.0.12

package/control-plane/scripts/skills/claude-api/python/claude-api/streaming.md

@@ -0,0 +1,179 @@
+# Streaming - Python
+
+## Quick Start
+
+```python
+with client.messages.stream(
+    model="claude-opus-5",
+    max_tokens=64000,
+    messages=[{"role": "user", "content": "Write a story"}]
+) as stream:
+    for text in stream.text_stream:
+        print(text, end="", flush=True)
+```
+
+### Async
+
+```python
+async with async_client.messages.stream(
+    model="claude-opus-5",
+    max_tokens=64000,
+    messages=[{"role": "user", "content": "Write a story"}]
+) as stream:
+    async for text in stream.text_stream:
+        print(text, end="", flush=True)
+```
+
+### Low-level: `stream=True`
+
+`messages.stream()` (above) is the recommended helper - it accumulates state and exposes `text_stream` / `get_final_message()`. If you only need the raw event iterator and want lower memory use, pass `stream=True` to `messages.create()` instead:
+
+```python
+for event in client.messages.create(
+    model="claude-opus-5",
+    max_tokens=64000,
+    messages=[{"role": "user", "content": "Write a story"}],
+    stream=True,
+):
+    print(event.type)
+```
+
+No final-message accumulation is done for you in this form.
+
+---
+
+## Handling Different Content Types
+
+Claude may return text, thinking blocks, or tool use. Handle each appropriately:
+
+> **Fable 5 / Claude Opus 5 / Opus 4.8 / Opus 4.7 / Opus 4.6:** Use `thinking: {type: "adaptive"}`. On Claude Opus 5 adaptive is also what you get by omitting `thinking` entirely. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead.
+
+```python
+with client.messages.stream(
+    model="claude-opus-5",
+    max_tokens=64000,
+    thinking={"type": "adaptive", "display": "summarized"},  # display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Claude Opus 5 / Opus 4.8 / 4.7
+    messages=[{"role": "user", "content": "Analyze this problem"}]
+) as stream:
+    for event in stream:
+        if event.type == "content_block_start":
+            if event.content_block.type == "thinking":
+                print("\n[Thinking...]")
+            elif event.content_block.type == "text":
+                print("\n[Response:]")
+
+        elif event.type == "content_block_delta":
+            if event.delta.type == "thinking_delta":
+                print(event.delta.thinking, end="", flush=True)
+            elif event.delta.type == "text_delta":
+                print(event.delta.text, end="", flush=True)
+```
+
+---
+
+## Streaming with Tool Use
+
+The Python tool runner supports streaming: pass `stream=True` to `client.beta.messages.tool_runner(...)` and each iteration yields a stream you consume event-by-event, with `get_final_message()` for the accumulated message per turn (see `shared/tool-use-concepts.md` -> Tool Runner vs Manual Loop). Use the manual-loop pattern below only when you're not using the tool runner and need per-token streaming with tools:
+
+```python
+with client.messages.stream(
+    model="claude-opus-5",
+    max_tokens=64000,
+    tools=tools,
+    messages=messages
+) as stream:
+    for text in stream.text_stream:
+        print(text, end="", flush=True)
+
+    response = stream.get_final_message()
+    # Continue with tool execution if response.stop_reason == "tool_use"
+```
+
+---
+
+## Getting the Final Message
+
+```python
+with client.messages.stream(
+    model="claude-opus-5",
+    max_tokens=64000,
+    messages=[{"role": "user", "content": "Hello"}]
+) as stream:
+    for text in stream.text_stream:
+        print(text, end="", flush=True)
+
+    # Get full message after streaming
+    final_message = stream.get_final_message()
+    print(f"\n\nTokens used: {final_message.usage.output_tokens}")
+```
+
+---
+
+## Streaming with Progress Updates
+
+```python
+def stream_with_progress(client, **kwargs):
+    """Stream a response with progress updates."""
+    total_tokens = 0
+    content_parts = []
+
+    with client.messages.stream(**kwargs) as stream:
+        for event in stream:
+            if event.type == "content_block_delta":
+                if event.delta.type == "text_delta":
+                    text = event.delta.text
+                    content_parts.append(text)
+                    print(text, end="", flush=True)
+
+            elif event.type == "message_delta":
+                if event.usage and event.usage.output_tokens is not None:
+                    total_tokens = event.usage.output_tokens
+
+        final_message = stream.get_final_message()
+
+    print(f"\n\n[Tokens used: {total_tokens}]")
+    return "".join(content_parts)
+```
+
+---
+
+## Error Handling in Streams
+
+```python
+try:
+    with client.messages.stream(
+        model="claude-opus-5",
+        max_tokens=64000,
+        messages=[{"role": "user", "content": "Write a story"}]
+    ) as stream:
+        for text in stream.text_stream:
+            print(text, end="", flush=True)
+except anthropic.APIConnectionError:
+    print("\nConnection lost. Please retry.")
+except anthropic.RateLimitError:
+    print("\nRate limited. Please wait and retry.")
+except anthropic.APIStatusError as e:
+    print(f"\nAPI error: {e.status_code}")
+```
+
+---
+
+## Stream Event Types
+
+| Event Type            | Description                 | When it fires                     |
+| --------------------- | --------------------------- | --------------------------------- |
+| `message_start`       | Contains message metadata   | Once at the beginning             |
+| `content_block_start` | New content block beginning | When a text/tool_use block starts |
+| `content_block_delta` | Incremental content update  | For each token/chunk              |
+| `content_block_stop`  | Content block complete      | When a block finishes             |
+| `message_delta`       | Message-level updates       | Contains `stop_reason`, usage     |
+| `message_stop`        | Message complete            | Once at the end                   |
+
+## Best Practices
+
+1. **Always flush output** - Use `flush=True` to show tokens immediately
+2. **Handle partial responses** - If the stream is interrupted, you may have incomplete content
+3. **Track token usage** - The `message_delta` event contains usage information
+4. **Use timeouts** - Set appropriate timeouts for your application
+5. **Default to streaming** - Use `.get_final_message()` to get the complete response even when streaming, giving you timeout protection without needing to handle individual events
+6. **Large `max_tokens` without streaming raises `ValueError`** - The SDK refuses non-streaming requests it estimates will exceed ~10 minutes (idle connections drop). Pass `stream=True` / use `messages.stream()`, or explicitly override `timeout`, to suppress the guard.