hive-skills 0.1.0

package/assets/skills/converted/claude-api/composable/mini/52-python-streaming-batches-files.md

@@ -0,0 +1,549 @@
+# Streaming — Python
+
+## Quick Start
+
+```python
+with client.messages.stream(
+    model="claude-opus-4-8",
+    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-4-8",
+    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-4-8",
+    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 / Opus 4.8 / Opus 4.7 / Opus 4.6:** Use `thinking: {type: "adaptive"}`. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead.
+
+```python
+with client.messages.stream(
+    model="claude-opus-4-8",
+    max_tokens=64000,
+    thinking={"type": "adaptive", "display": "summarized"},  # display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 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 currently returns complete messages. Use streaming for individual API calls within a manual loop if you need per-token streaming with tools:
+
+```python
+with client.messages.stream(
+    model="claude-opus-4-8",
+    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-4-8",
+    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-4-8",
+        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.
+
+# Message Batches API — Python
+
+The Batches API (`POST /v1/messages/batches`) processes Messages API requests asynchronously at 50% of standard prices.
+
+## Key Facts
+
+- Up to 100,000 requests or 256 MB per batch
+- Most batches complete within 1 hour; maximum 24 hours
+- Results available for 29 days after creation
+- 50% cost reduction on all token usage
+- All Messages API features supported (vision, tools, caching, etc.)
+
+---
+
+## Create a Batch
+
+```python
+import anthropic
+from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
+from anthropic.types.messages.batch_create_params import Request
+
+client = anthropic.Anthropic()
+
+message_batch = client.messages.batches.create(
+    requests=[
+        Request(
+            custom_id="request-1",
+            params=MessageCreateParamsNonStreaming(
+                model="claude-opus-4-8",
+                max_tokens=16000,
+                messages=[{"role": "user", "content": "Summarize climate change impacts"}]
+            )
+        ),
+        Request(
+            custom_id="request-2",
+            params=MessageCreateParamsNonStreaming(
+                model="claude-opus-4-8",
+                max_tokens=16000,
+                messages=[{"role": "user", "content": "Explain quantum computing basics"}]
+            )
+        ),
+    ]
+)
+
+print(f"Batch ID: {message_batch.id}")
+print(f"Status: {message_batch.processing_status}")
+```
+
+---
+
+## Poll for Completion
+
+```python
+import time
+
+while True:
+    batch = client.messages.batches.retrieve(message_batch.id)
+    if batch.processing_status == "ended":
+        break
+    print(f"Status: {batch.processing_status}, processing: {batch.request_counts.processing}")
+    time.sleep(60)
+
+print("Batch complete!")
+print(f"Succeeded: {batch.request_counts.succeeded}")
+print(f"Errored: {batch.request_counts.errored}")
+```
+
+---
+
+## Retrieve Results
+
+> **Note:** Examples below use `match/case` syntax, requiring Python 3.10+. For earlier versions, use `if/elif` chains instead.
+
+```python
+for result in client.messages.batches.results(message_batch.id):
+    match result.result.type:
+        case "succeeded":
+            msg = result.result.message
+            text = next((b.text for b in msg.content if b.type == "text"), "")
+            print(f"[{result.custom_id}] {text[:100]}")
+        case "errored":
+            if result.result.error.type == "invalid_request":
+                print(f"[{result.custom_id}] Validation error - fix request and retry")
+            else:
+                print(f"[{result.custom_id}] Server error - safe to retry")
+        case "canceled":
+            print(f"[{result.custom_id}] Canceled")
+        case "expired":
+            print(f"[{result.custom_id}] Expired - resubmit")
+```
+
+---
+
+## Cancel a Batch
+
+```python
+cancelled = client.messages.batches.cancel(message_batch.id)
+print(f"Status: {cancelled.processing_status}")  # "canceling"
+```
+
+---
+
+## List Batches (auto-pagination)
+
+Iterating the return value of any `list()` call auto-paginates across all pages — do not index into `.data` if you want the full set:
+
+```python
+for batch in client.messages.batches.list(limit=20):
+    print(batch.id, batch.processing_status)
+```
+
+For manual control, use `first_page.has_next_page()` / `first_page.get_next_page()` / `first_page.next_page_info()`; `first_page.data` holds the current page's items and `first_page.last_id` is the cursor.
+
+---
+
+## Batch with Prompt Caching
+
+```python
+shared_system = [
+    {"type": "text", "text": "You are a literary analyst."},
+    {
+        "type": "text",
+        "text": large_document_text,  # Shared across all requests
+        "cache_control": {"type": "ephemeral"}
+    }
+]
+
+message_batch = client.messages.batches.create(
+    requests=[
+        Request(
+            custom_id=f"analysis-{i}",
+            params=MessageCreateParamsNonStreaming(
+                model="claude-opus-4-8",
+                max_tokens=16000,
+                system=shared_system,
+                messages=[{"role": "user", "content": question}]
+            )
+        )
+        for i, question in enumerate(questions)
+    ]
+)
+```
+
+---
+
+## Full End-to-End Example
+
+```python
+import anthropic
+import time
+from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
+from anthropic.types.messages.batch_create_params import Request
+
+client = anthropic.Anthropic()
+
+# 1. Prepare requests
+items_to_classify = [
+    "The product quality is excellent!",
+    "Terrible customer service, never again.",
+    "It's okay, nothing special.",
+]
+
+requests = [
+    Request(
+        custom_id=f"classify-{i}",
+        params=MessageCreateParamsNonStreaming(
+            model="claude-haiku-4-5",
+            max_tokens=50,
+            messages=[{
+                "role": "user",
+                "content": f"Classify as positive/negative/neutral (one word): {text}"
+            }]
+        )
+    )
+    for i, text in enumerate(items_to_classify)
+]
+
+# 2. Create batch
+batch = client.messages.batches.create(requests=requests)
+print(f"Created batch: {batch.id}")
+
+# 3. Wait for completion
+while True:
+    batch = client.messages.batches.retrieve(batch.id)
+    if batch.processing_status == "ended":
+        break
+    time.sleep(10)
+
+# 4. Collect results
+results = {}
+for result in client.messages.batches.results(batch.id):
+    if result.result.type == "succeeded":
+        msg = result.result.message
+        results[result.custom_id] = next((b.text for b in msg.content if b.type == "text"), "")
+
+for custom_id, classification in sorted(results.items()):
+    print(f"{custom_id}: {classification}")
+```
+
+# Files API — Python
+
+The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls.
+
+**Beta:** Pass `betas=["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically).
+
+## Key Facts
+
+- Maximum file size: 500 MB
+- Total storage: 100 GB per organization
+- Files persist until deleted
+- File operations (upload, list, delete) are free; content used in messages is billed as input tokens
+- Not available on Amazon Bedrock or Google Vertex AI
+
+---
+
+## Upload a File
+
+The `file` argument accepts a `(filename, content, content_type)` tuple, a `pathlib.Path` (or any `PathLike` — read for you, async-safe with `AsyncAnthropic`), or an open binary file object.
+
+```python
+import anthropic
+from pathlib import Path
+
+client = anthropic.Anthropic()
+
+uploaded = client.beta.files.upload(
+    file=("report.pdf", open("report.pdf", "rb"), "application/pdf"),
+)
+# or: client.beta.files.upload(file=Path("report.pdf"))
+print(f"File ID: {uploaded.id}")
+print(f"Size: {uploaded.size_bytes} bytes")
+```
+
+---
+
+## Use a File in Messages
+
+### PDF / Text Document
+
+```python
+response = client.beta.messages.create(
+    model="claude-opus-4-8",
+    max_tokens=16000,
+    messages=[{
+        "role": "user",
+        "content": [
+            {"type": "text", "text": "Summarize the key findings in this report."},
+            {
+                "type": "document",
+                "source": {"type": "file", "file_id": uploaded.id},
+                "title": "Q4 Report",           # optional
+                "citations": {"enabled": True}   # optional, enables citations
+            }
+        ]
+    }],
+    betas=["files-api-2025-04-14"],
+)
+for block in response.content:
+    if block.type == "text":
+        print(block.text)
+```
+
+### Image
+
+```python
+image_file = client.beta.files.upload(
+    file=("photo.png", open("photo.png", "rb"), "image/png"),
+)
+
+response = client.beta.messages.create(
+    model="claude-opus-4-8",
+    max_tokens=16000,
+    messages=[{
+        "role": "user",
+        "content": [
+            {"type": "text", "text": "What's in this image?"},
+            {
+                "type": "image",
+                "source": {"type": "file", "file_id": image_file.id}
+            }
+        ]
+    }],
+    betas=["files-api-2025-04-14"],
+)
+```
+
+---
+
+## Manage Files
+
+### List Files
+
+Iterate the list result directly — the SDK auto-paginates across all pages. Only use `.data` if you want the first page only.
+
+```python
+for f in client.beta.files.list():
+    print(f"{f.id}: {f.filename} ({f.size_bytes} bytes)")
+```
+
+### Get File Metadata
+
+```python
+file_info = client.beta.files.retrieve_metadata("file_011CNha8iCJcU1wXNR6q4V8w")
+print(f"Filename: {file_info.filename}")
+print(f"MIME type: {file_info.mime_type}")
+```
+
+### Delete a File
+
+```python
+client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w")
+```
+
+### Download a File
+
+Only files created by the code execution tool or skills can be downloaded (not user-uploaded files).
+
+```python
+file_content = client.beta.files.download("file_011CNha8iCJcU1wXNR6q4V8w")
+file_content.write_to_file("output.txt")
+```
+
+---
+
+## Full End-to-End Example
+
+Upload a document once, ask multiple questions about it:
+
+```python
+import anthropic
+
+client = anthropic.Anthropic()
+
+# 1. Upload once
+uploaded = client.beta.files.upload(
+    file=("contract.pdf", open("contract.pdf", "rb"), "application/pdf"),
+)
+print(f"Uploaded: {uploaded.id}")
+
+# 2. Ask multiple questions using the same file_id
+questions = [
+    "What are the key terms and conditions?",
+    "What is the termination clause?",
+    "Summarize the payment schedule.",
+]
+
+for question in questions:
+    response = client.beta.messages.create(
+        model="claude-opus-4-8",
+        max_tokens=16000,
+        messages=[{
+            "role": "user",
+            "content": [
+                {"type": "text", "text": question},
+                {
+                    "type": "document",
+                    "source": {"type": "file", "file_id": uploaded.id}
+                }
+            ]
+        }],
+        betas=["files-api-2025-04-14"],
+    )
+    print(f"\nQ: {question}")
+    text = next((b.text for b in response.content if b.type == "text"), "")
+    print(f"A: {text[:200]}")
+
+# 3. Clean up when done
+client.beta.files.delete(uploaded.id)
+```