fix(types): make ChatCompletionMessageToolCallParam instantiable

[ryx2]

Summary

Fixes issue where ChatCompletionMessageToolCallParam could not be instantiated after version 1.99.2, causing TypeError: Cannot instantiate typing.Union.

This addresses:

• GitHub issue ChatCompletionMessageToolCallParam "cannot instantiate typing.Union" error in 1.99.4 #2541
• Related pydantic-ai issue Make API docs available via MCP or similar #2476

Problem

In version 1.99.2, ChatCompletionMessageToolCallParam was changed from a concrete TypedDict class to a Union type alias to support custom tool calls. This broke backward compatibility for users who were directly instantiating the type.

Before (v1.99.1):

# This worked
tool_call = ChatCompletionMessageToolCallParam(
    id="test_id", 
    function={"name": "func", "arguments": "{}"}
)

After (v1.99.2+):

# This failed with "TypeError: Cannot instantiate typing.Union"
tool_call = ChatCompletionMessageToolCallParam(
    id="test_id", 
    function={"name": "func", "arguments": "{}"}
)

Solution

This change introduces a constructor class that can be instantiated while preserving the Union type behavior for type checking:

• ✅ Instantiable: ChatCompletionMessageToolCallParam() now works again
• ✅ Backward compatible: Pre-1.99.2 usage patterns continue to work
• ✅ Type safe: Proper type hints with overloads for function and custom tools
• ✅ Forward compatible: Supports both function and custom tool call types
• ✅ Error handling: Clear error messages for invalid parameters

Changes Made

1. Constructor class: _ChatCompletionMessageToolCallParamConstructor with proper overloads
2. Type alias preservation: ChatCompletionMessageToolCallParamType for explicit typing
3. Backward compatibility: Automatic type="function" inference for pre-1.99.2 patterns
4. Export updates: Added new type alias to __init__.py

Test Plan

• Reproduces the original error in GitHub issue ChatCompletionMessageToolCallParam "cannot instantiate typing.Union" error in 1.99.4 #2541
• Verifies fix allows instantiation without errors
• Tests backward compatibility with pre-1.99.2 usage patterns
• Tests both function and custom tool call types
• Verifies proper error handling for invalid parameters
• Passes mypy type checking
• All existing functionality preserved

🤖 Generated with Claude Code