@prismer/runtime 2.0.7 → 2.2.55

package/built-in-skills/claude-api/python/claude-api/files-api.md

@@ -0,0 +1,165 @@
+# 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
+
+```python
+import anthropic
+
+client = anthropic.Anthropic()
+
+uploaded = client.beta.files.upload(
+    file=("report.pdf", open("report.pdf", "rb"), "application/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-7",
+    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-7",
+    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
+
+```python
+files = client.beta.files.list()
+for f in files.data:
+    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-7",
+        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)
+```

package/built-in-skills/claude-api/python/claude-api/streaming.md

@@ -0,0 +1,162 @@
+# Streaming — Python
+
+## Quick Start
+
+```python
+with client.messages.stream(
+    model="claude-opus-4-7",
+    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-7",
+    max_tokens=64000,
+    messages=[{"role": "user", "content": "Write a story"}]
+) as stream:
+    async for text in stream.text_stream:
+        print(text, end="", flush=True)
+```
+
+---
+
+## Handling Different Content Types
+
+Claude may return text, thinking blocks, or tool use. Handle each appropriately:
+
+> **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-7",
+    max_tokens=64000,
+    thinking={"type": "adaptive"},
+    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-7",
+    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-7",
+    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-7",
+        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