feat: add core module structure and types for call_model API

- Create call_model/ module with __init__.py and py.typed marker
- Add comprehensive exception hierarchy:
  - CallModelError: Base exception with code and context
  - ToolExecutionError: For tool execution failures
  - ToolValidationError: For Pydantic validation errors
  - StreamInterruptedError: For stream interruptions
  - MaxToolRoundsExceededError: For exceeding max rounds
- Add type definitions:
  - ToolType and ResponseState enums
  - ToolContext and CachedData TypedDicts
  - Type aliases for ToolCallId, EventType, StreamEvent
- All exceptions include actionable error messages with suggestions
- Full type hints and comprehensive docstrings
- Follows PEP-8 and Python conventions (snake_case)

This foundation supports the upcoming ResponseWrapper, ReusableStream,
and tool system implementations.

Implements: FR-1.1.1, FR-1.6.1, FR-1.6.2, FR-1.6.3, FR-1.6.4, FR-1.6.5

Author: subtleGradient

src/openrouter/call_model/__init__.py

@@ -0,0 +1,74 @@
+"""High-level API for OpenRouter model interactions with tool orchestration.
+
+This module provides a Pythonic interface for calling OpenRouter models with
+automatic tool execution, streaming support, and multiple consumption patterns.
+
+The call_model API is designed to:
+- Provide a simple, high-level interface similar to TypeScript SDK
+- Support automatic tool orchestration with validation
+- Enable multiple consumption patterns (streaming, complete message, text-only)
+- Allow stream reuse without additional API calls
+- Follow Python conventions (snake_case, async/await, type hints)
+
+Example:
+    Basic usage with tools:
+
+    >>> from openrouter import OpenRouter
+    >>> from openrouter.call_model import call_model
+    >>> from pydantic import BaseModel
+    >>>
+    >>> class WeatherParams(BaseModel):
+    ...     location: str
+    ...     unit: str = "celsius"
+    >>>
+    >>> async def main():
+    ...     client = OpenRouter(api_key="...")
+    ...     response = await call_model(
+    ...         client=client,
+    ...         request={"model": "gpt-4", "messages": [...]},
+    ...         tools=[WeatherParams],
+    ...         max_tool_rounds=5
+    ...     )
+    ...     text = await response.get_text()
+    ...     print(text)
+
+For more examples, see the examples/ directory.
+"""
+
+from .exceptions import (
+    CallModelError,
+    MaxToolRoundsExceededError,
+    StreamInterruptedError,
+    ToolExecutionError,
+    ToolValidationError,
+)
+from .types import (
+    CachedData,
+    EventType,
+    ResponseState,
+    StreamEvent,
+    ToolCallId,
+    ToolContext,
+    ToolType,
+)
+
+__all__ = [
+    # Exception classes
+    "CallModelError",
+    "MaxToolRoundsExceededError",
+    "StreamInterruptedError",
+    "ToolExecutionError",
+    "ToolValidationError",
+    # Type definitions
+    "CachedData",
+    "EventType",
+    "ResponseState",
+    "StreamEvent",
+    "ToolCallId",
+    "ToolContext",
+    "ToolType",
+]
+
+# Module metadata
+__version__ = "0.1.0"
+__author__ = "OpenRouter"

src/openrouter/call_model/exceptions.py

@@ -0,0 +1,162 @@
+"""Custom exception types for the call_model API.
+
+This module defines the exception hierarchy for call_model operations,
+providing actionable error messages with context for debugging.
+"""
+
+from typing import Any, Dict, List, Optional
+
+
+class CallModelError(Exception):
+    """Base exception for all call_model errors.
+
+    This exception includes optional error codes and context to help
+    developers understand and resolve issues.
+
+    Attributes:
+        message: Human-readable error description
+        code: Optional error code for programmatic handling
+        context: Optional dictionary with additional error context
+    """
+
+    def __init__(
+        self,
+        message: str,
+        code: Optional[str] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ):
+        """Initialize the error with message, code, and context.
+
+        Args:
+            message: Human-readable error description
+            code: Optional error code for programmatic handling
+            context: Optional dictionary with additional error context
+        """
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.context = context or {}
+
+    def __str__(self) -> str:
+        """Return the error message."""
+        return self.message
+
+
+class ToolExecutionError(CallModelError):
+    """Raised when tool execution fails.
+
+    This exception includes the tool name, original error, and input context
+    to help developers debug tool implementation issues.
+
+    Example:
+        >>> try:
+        ...     result = await tool.execute(params, context)
+        ... except Exception as e:
+        ...     raise ToolExecutionError(
+        ...         tool_name="weather_tool",
+        ...         error=e,
+        ...         context={"input": params, "tool_call_id": "call_123"}
+        ...     )
+    """
+
+    def __init__(self, tool_name: str, error: Exception, context: Dict[str, Any]):
+        """Initialize the tool execution error.
+
+        Args:
+            tool_name: Name of the tool that failed
+            error: Original exception that was raised
+            context: Context dictionary with input, tool_call_id, etc.
+        """
+        message = f"Tool '{tool_name}' failed: {error}"
+
+        if "input" in context:
+            message += f"\nInput: {context['input']}"
+
+        message += "\nSuggestion: Check tool implementation and input validation"
+
+        super().__init__(message=message, code="TOOL_EXECUTION_ERROR", context=context)
+        self.tool_name = tool_name
+        self.original_error = error
+
+
+class ToolValidationError(CallModelError):
+    """Raised when tool input validation fails.
+
+    This exception includes the validation errors from Pydantic to help
+    developers understand what inputs were invalid.
+
+    Example:
+        >>> raise ToolValidationError(
+        ...     tool_name="weather_tool",
+        ...     validation_errors=["Field 'location' is required"]
+        ... )
+    """
+
+    def __init__(self, tool_name: str, validation_errors: List[str]):
+        """Initialize the tool validation error.
+
+        Args:
+            tool_name: Name of the tool that failed validation
+            validation_errors: List of validation error messages
+        """
+        message = f"Tool '{tool_name}' validation failed:\n"
+        message += "\n".join(f"  - {err}" for err in validation_errors)
+        message += "\nSuggestion: Ensure input matches the tool's Pydantic schema"
+
+        super().__init__(message=message, code="TOOL_VALIDATION_ERROR")
+        self.tool_name = tool_name
+        self.validation_errors = validation_errors
+
+
+class StreamInterruptedError(CallModelError):
+    """Raised when stream is interrupted.
+
+    This exception includes details about the last successful event
+    to help developers understand where the stream failed.
+
+    Example:
+        >>> raise StreamInterruptedError(
+        ...     last_event={"type": "content.delta", "delta": {...}}
+        ... )
+    """
+
+    def __init__(self, last_event: Optional[Dict[str, Any]] = None):
+        """Initialize the stream interrupted error.
+
+        Args:
+            last_event: Optional dictionary with the last successful event
+        """
+        message = "Stream was interrupted"
+
+        if last_event:
+            message += f"\nLast successful event: {last_event.get('type', 'unknown')}"
+
+        message += "\nSuggestion: Check network connection and retry"
+
+        super().__init__(message=message, code="STREAM_INTERRUPTED")
+        self.last_event = last_event
+
+
+class MaxToolRoundsExceededError(CallModelError):
+    """Raised when tool execution rounds exceed limit.
+
+    This exception helps developers identify infinite tool loops
+    or adjust the max_tool_rounds parameter.
+
+    Example:
+        >>> raise MaxToolRoundsExceededError(rounds=10, max_rounds=5)
+    """
+
+    def __init__(self, rounds: int, max_rounds: int):
+        """Initialize the max tool rounds exceeded error.
+
+        Args:
+            rounds: Number of rounds executed
+            max_rounds: Maximum allowed rounds
+        """
+        message = f"Tool execution exceeded maximum rounds ({rounds}/{max_rounds})"
+        message += "\nSuggestion: Increase max_tool_rounds or check for tool loops"
+
+        super().__init__(message=message, code="MAX_ROUNDS_EXCEEDED")
+        self.rounds = rounds
+        self.max_rounds = max_rounds

src/openrouter/call_model/py.typed

@@ -0,0 +1,109 @@
+"""Type definitions for the call_model API.
+
+This module defines the core types, enums, and type aliases used throughout
+the call_model implementation. All types follow Python typing conventions
+with comprehensive docstrings.
+"""
+
+from enum import Enum
+from typing import Any, Dict, List, Optional, TypedDict
+
+
+# Type aliases for clarity and maintainability
+ToolCallId = str
+"""Unique identifier for a tool call."""
+
+EventType = str
+"""Type of SSE event (e.g., 'content.delta', 'tool.call')."""
+
+StreamEvent = Dict[str, Any]
+"""Raw SSE event dictionary from the API."""
+
+
+class ToolType(str, Enum):
+    """Enumeration of supported tool types.
+
+    Currently only function tools are supported. This enum allows for
+    future extension to other tool types.
+
+    Attributes:
+        FUNCTION: Standard function-based tool
+    """
+
+    FUNCTION = "function"
+
+
+class ToolContext(TypedDict, total=False):
+    """Context passed to tool execute methods.
+
+    This context provides tools with information about the current
+    conversation state, enabling context-aware tool execution.
+
+    Attributes:
+        number_of_turns: 1-indexed turn number (first turn = 1)
+        message_history: List of all messages in the conversation
+        model: Primary model being used (if single model)
+        models: List of models (if using model routing)
+        previous_tool_results: Results from previous tool executions
+        request_id: Unique identifier for this request
+
+    Example:
+        >>> context = ToolContext(
+        ...     number_of_turns=2,
+        ...     message_history=[...],
+        ...     model="gpt-4",
+        ...     previous_tool_results=[...]
+        ... )
+    """
+
+    number_of_turns: int
+    message_history: List[Dict[str, Any]]
+    model: Optional[str]
+    models: Optional[List[str]]
+    previous_tool_results: Optional[List[Dict[str, Any]]]
+    request_id: Optional[str]
+
+
+class ResponseState(str, Enum):
+    """State of the ResponseWrapper.
+
+    Tracks the lifecycle of a response from initialization through
+    completion or error.
+
+    Attributes:
+        INITIALIZED: Response created but not yet consumed
+        STREAMING: Currently consuming the stream
+        COMPLETED: Stream fully consumed successfully
+        ERROR: An error occurred during consumption
+    """
+
+    INITIALIZED = "initialized"
+    STREAMING = "streaming"
+    COMPLETED = "completed"
+    ERROR = "error"
+
+
+class CachedData(TypedDict, total=False):
+    """Cached response data for reuse across consumption methods.
+
+    This structure stores parsed data from the response to avoid
+    redundant parsing when multiple consumption methods are called.
+
+    Attributes:
+        message: Complete message object with all content
+        text: Extracted text content only
+        tool_calls: Parsed tool call objects
+        raw_response: Raw API response dictionary
+
+    Example:
+        >>> cache: CachedData = {
+        ...     "message": {"role": "assistant", "content": [...]},
+        ...     "text": "The weather is sunny",
+        ...     "tool_calls": [...]
+        ... }
+    """
+
+    message: Optional[Dict[str, Any]]
+    text: Optional[str]
+    tool_calls: Optional[List[Dict[str, Any]]]
+    raw_response: Optional[Dict[str, Any]]