feat: add structured outputs support with Pydantic integration

Add support for Anthropic's structured outputs beta feature using the
anthropic-beta: structured-outputs-2025-11-13 header. Enables type-safe
JSON responses through Pydantic models or raw JSON schemas.

Features:
- Pydantic v1/v2 automatic detection and schema conversion
- Per-query output_format parameter for flexibility
- Deep copy schema validation to prevent mutations
- Comprehensive examples demonstrating advanced Pydantic features
- Full test coverage (34 new tests, 151 total passing)

Implementation:
- Added schema_utils.py for Pydantic → JSON schema conversion
- Modified query() and ClaudeSDKClient.query() to accept output_format
- Created examples/structured_outputs.py with 4 production scenarios
- Updated README.md with usage examples and documentation

Note: Actual functionality blocked pending CLI support for --json-schema
flag (see anthropics/claude-code#9058). Infrastructure complete and ready.

Author: trevorprater

README.md

@@ -76,6 +76,58 @@ options = ClaudeAgentOptions(
 )
 ```
 
+### Structured Outputs
+
+Structured outputs allow you to get responses from Claude in a specific JSON schema format, ensuring type-safe and predictable responses.
+
+**Note:** This feature requires Claude Code CLI support for passing schemas (see [anthropics/claude-code#9058](https://github.com/anthropics/claude-code/issues/9058)). The SDK provides the public API and schema conversion utilities, ready for when CLI support is added.
+
+#### Using Raw JSON Schema
+
+```python
+from claude_agent_sdk import query
+
+# Define your expected output schema
+schema = {
+    "type": "object",
+    "properties": {
+        "name": {"type": "string"},
+        "email": {"type": "string"},
+        "plan_interest": {"type": "string"},
+        "demo_requested": {"type": "boolean"}
+    },
+    "required": ["name", "email", "plan_interest", "demo_requested"]
+}
+
+async for message in query(
+    prompt="Extract info: John Smith ([email protected]) wants Enterprise plan demo",
+    output_format=schema
+):
+    print(message)
+```
+
+#### Using Pydantic Models (Recommended)
+
+```python
+from pydantic import BaseModel, Field
+from claude_agent_sdk import query
+
+class EmailExtraction(BaseModel):
+    """Structured data from an email."""
+    name: str = Field(description="Full name")
+    email: str = Field(description="Email address")
+    plan_interest: str = Field(description="Plan they're interested in")
+    demo_requested: bool = Field(description="Whether they requested a demo")
+
+async for message in query(
+    prompt="Extract info: Sarah ([email protected]) wants Professional plan demo",
+    output_format=EmailExtraction  # Pass the Pydantic model class
+):
+    print(message)
+```
+
+For more examples, see [examples/structured_outputs.py](examples/structured_outputs.py).
+
 ## ClaudeSDKClient
 
 `ClaudeSDKClient` supports bidirectional, interactive conversations with Claude
@@ -271,6 +323,8 @@ See [examples/quick_start.py](examples/quick_start.py) for a complete working ex
 
 See [examples/streaming_mode.py](examples/streaming_mode.py) for comprehensive examples involving `ClaudeSDKClient`. You can even run interactive examples in IPython from [examples/streaming_mode_ipython.py](examples/streaming_mode_ipython.py).
 
+See [examples/structured_outputs.py](examples/structured_outputs.py) for structured outputs examples using both Pydantic models and raw JSON schemas.
+
 ## Migrating from Claude Code SDK
 
 If you're upgrading from the Claude Code SDK (versions < 0.1.0), please see the [CHANGELOG.md](CHANGELOG.md#010) for details on breaking changes and new features, including: