docs: improve SDK guides and examples

examples/README.md

@@ -0,0 +1,25 @@
+# Examples
+
+Run examples from the repository root:
+
+```bash
+uv sync
+export FACTORY_API_KEY="..."
+uv run python examples/query.py
+```
+
+| Example | Purpose |
+| --- | --- |
+| [`query.py`](query.py) | Run one prompt with Auto Router |
+| [`multi_turn_session.py`](multi_turn_session.py) | Preserve context across turns |
+| [`model_discovery.py`](model_discovery.py) | List available model IDs |
+| [`model_selection.py`](model_selection.py) | Select Auto Router or a fixed model |
+| [`resume_session.py`](resume_session.py) | Resume a saved session |
+| [`structured_output.py`](structured_output.py) | Request JSON Schema output |
+| [`permission_handler.py`](permission_handler.py) | Handle tool approval requests |
+| [`attachment.py`](attachment.py) | Send an image, PDF, or text file |
+| [`session_lifecycle.py`](session_lifecycle.py) | Fork and continue a session |
+| [`interactive_session.py`](interactive_session.py) | Run an interactive terminal session |
+
+Each example starts a local `droid exec` subprocess. It uses your current
+directory unless its usage says otherwise.

examples/_helpers.py

@@ -0,0 +1,85 @@
+"""Shared helpers for the runnable examples."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from typing import Any
+
+from droid_sdk import (
+    AssistantTextDelta,
+    DroidClient,
+    ErrorEvent,
+    ThinkingTextDelta,
+    TokenUsageUpdate,
+    ToolProgress,
+    ToolResult,
+    ToolUse,
+    TurnComplete,
+)
+from droid_sdk.schemas import Base64ImageSource, DocumentSource
+
+ImageInput = Base64ImageSource | dict[str, Any]
+DocumentInput = DocumentSource | dict[str, Any]
+
+
+async def run_turn(
+    client: DroidClient,
+    prompt: str,
+    *,
+    images: list[ImageInput] | None = None,
+    files: list[DocumentInput] | None = None,
+    output_format: dict[str, Any] | None = None,
+    show_activity: bool = False,
+    collect_text: bool = False,
+) -> str | None:
+    """Send one prompt, print its stream, and optionally return its text."""
+
+    async def consume() -> str | None:
+        chunks: list[str] = []
+        error_message: str | None = None
+
+        async for event in client.receive_response():
+            if isinstance(event, AssistantTextDelta):
+                print(event.text, end="", flush=True)
+                if collect_text:
+                    chunks.append(event.text)
+            elif show_activity and isinstance(event, ThinkingTextDelta):
+                print(event.text, end="", flush=True)
+            elif show_activity and isinstance(event, ToolUse):
+                print(f"\n[tool] {event.tool_name}")
+            elif show_activity and isinstance(event, ToolProgress):
+                print(f"\n[progress] {event.tool_name}: {event.content}")
+            elif show_activity and isinstance(event, ToolResult):
+                status = "error" if event.is_error else "done"
+                print(f"\n[{status}] {event.tool_name or event.tool_use_id}")
+            elif show_activity and isinstance(event, TokenUsageUpdate):
+                print(
+                    f"\n[tokens] input={event.input_tokens} "
+                    f"output={event.output_tokens}"
+                )
+            elif isinstance(event, ErrorEvent):
+                error_message = event.message
+            elif isinstance(event, TurnComplete):
+                print()
+                if error_message is not None:
+                    raise RuntimeError(error_message)
+                return "".join(chunks) if collect_text else None
+
+        raise RuntimeError("Droid stopped before the turn completed.")
+
+    consumer = asyncio.create_task(consume())
+    await asyncio.sleep(0)
+    try:
+        await client.add_user_message(
+            text=prompt,
+            images=images,
+            files=files,
+            output_format=output_format,
+        )
+        return await consumer
+    finally:
+        if not consumer.done():
+            consumer.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await consumer

examples/attachment.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Send one image, PDF, or text file.
+
+Usage:
+    uv run python examples/attachment.py PATH
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import base64
+from pathlib import Path
+
+from _helpers import DocumentInput, ImageInput, run_turn
+
+from droid_sdk import DroidClient
+
+_IMAGE_TYPES = {
+    ".gif": "image/gif",
+    ".jpeg": "image/jpeg",
+    ".jpg": "image/jpeg",
+    ".png": "image/png",
+    ".webp": "image/webp",
+}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("path", type=Path)
+    return parser.parse_args()
+
+
+def encode(path: Path) -> tuple[list[ImageInput], list[DocumentInput]]:
+    suffix = path.suffix.lower()
+    if suffix in _IMAGE_TYPES:
+        image = {
+            "type": "base64",
+            "data": base64.b64encode(path.read_bytes()).decode("ascii"),
+            "mediaType": _IMAGE_TYPES[suffix],
+        }
+        return [image], []
+
+    if suffix == ".pdf":
+        document = {
+            "type": "base64",
+            "mediaType": "application/pdf",
+            "data": base64.b64encode(path.read_bytes()).decode("ascii"),
+            "name": path.name,
+        }
+        return [], [document]
+
+    document = {
+        "type": "text",
+        "mediaType": "text/plain",
+        "data": path.read_text(),
+        "name": path.name,
+    }
+    return [], [document]
+
+
+async def main(path: Path) -> None:
+    images, files = encode(path)
+    cwd = str(Path.cwd())
+
+    async with DroidClient(exec_path="droid", cwd=cwd) as client:
+        await client.initialize_session(
+            machine_id="python-sdk-example",
+            cwd=cwd,
+        )
+        await run_turn(
+            client,
+            "Describe the attached file.",
+            images=images,
+            files=files,
+        )
+
+
+if __name__ == "__main__":
+    args = parse_args()
+    asyncio.run(main(args.path))