hammad-python 0.0.19__py3-none-any.whl → 0.0.21__py3-none-any.whl

hammad/genai/{language_models/language_model.py → models/language/model.py}

@@ -1,25 +1,38 @@
 """hammad.genai.language_models.language_model"""
 
 from typing import (
-    Any, 
+    Any,
     Callable,
-    List, 
-    TypeVar, 
-    Generic, 
-    Union, 
-    Optional, 
-    Type, 
-    overload, 
-    Dict, 
+    List,
+    TypeVar,
+    Generic,
+    Union,
+    Optional,
+    Type,
+    overload,
+    Dict,
     TYPE_CHECKING,
 )
+import functools
+import inspect
+import asyncio
 from typing_extensions import Literal
 
 if TYPE_CHECKING:
     from httpx import Timeout
 
-from ._types import LanguageModelName, LanguageModelInstructorMode
-from ._utils import (
+from ....logging.logger import _get_internal_logger
+from ..model_provider import litellm, instructor
+
+from ...types.base import BaseGenAIModel
+from .types.language_model_instructor_mode import LanguageModelInstructorMode
+from .types.language_model_name import LanguageModelName
+from .types.language_model_messages import LanguageModelMessages
+from .types.language_model_response import LanguageModelResponse
+from .types.language_model_settings import LanguageModelSettings
+from .types.language_model_stream import LanguageModelStream
+
+from .utils import (
     parse_messages_input,
     handle_completion_request_params,
     handle_completion_response,
@@ -29,9 +42,6 @@ from ._utils import (
     format_tool_calls,
     LanguageModelRequestBuilder,
 )
-from .language_model_request import LanguageModelRequest, LanguageModelMessagesParam
-from .language_model_response import LanguageModelResponse
-from ._streaming import Stream, AsyncStream
 
 __all__ = [
     "LanguageModel",
@@ -41,9 +51,12 @@ __all__ = [
 T = TypeVar("T")
 
 
+logger = _get_internal_logger(__name__)
+
+
 class LanguageModelError(Exception):
     """Error raised when an error occurs during a language model operation."""
-    
+
     def __init__(self, message: str, *args: Any, **kwargs: Any):
         super().__init__(message, *args, **kwargs)
         self.message = message
@@ -51,117 +64,111 @@ class LanguageModelError(Exception):
         self.kwargs = kwargs
 
 
-class _AIProvider:
-    """Provider for accessing litellm and instructor instances."""
-    
-    _LITELLM = None
-    _INSTRUCTOR = None
-    
-    @staticmethod
-    def get_litellm():
-        """Returns the `litellm` module."""
-        if _AIProvider._LITELLM is None:
-            try:
-                import litellm
-                litellm.drop_params = True
-                litellm.modify_params = True
-                _AIProvider._LITELLM = litellm
-                
-                # Rebuild LanguageModelResponse model now that litellm is available
-                LanguageModelResponse.model_rebuild()
-            except ImportError as e:
-                raise ImportError(
-                    "Using the `hammad.ai.llms` extension requires the `litellm` package to be installed.\n"
-                    "Please either install the `litellm` package, or install the `hammad.ai` extension with:\n"
-                    "`pip install 'hammad-python[ai]'`"
-                ) from e
-        return _AIProvider._LITELLM
-    
-    @staticmethod
-    def get_instructor():
-        """Returns the `instructor` module."""
-        if _AIProvider._INSTRUCTOR is None:
-            try:
-                import instructor
-                _AIProvider._INSTRUCTOR = instructor
-            except ImportError as e:
-                raise ImportError(
-                    "Using the `hammad.ai.llms` extension requires the `instructor` package to be installed.\n"
-                    "Please either install the `instructor` package, or install the `hammad.ai` extension with:\n"
-                    "`pip install 'hammad-python[ai]'`"
-                ) from e
-        return _AIProvider._INSTRUCTOR
-
-
-class LanguageModel(Generic[T]):
-    """A clean language model interface for generating responses with comprehensive
-    parameter handling and type safety."""
-    
+class LanguageModel(BaseGenAIModel, Generic[T]):
+    """
+    A Generative AI model that can be used to generate text, chat completions,
+    structured outputs, call tools and more.
+    """
+
+    model: LanguageModelName | str = "openai/gpt-4o-mini"
+    """The model to use for requests."""
+
+    type: Type[T] = str
+    """The type of the output of the language model."""
+
+    instructions: Optional[str] = None
+    """Instructions for the language model."""
+
+    base_url: Optional[str] = None
+    api_key: Optional[str] = None
+    api_version: Optional[str] = None
+    organization: Optional[str] = None
+    deployment_id: Optional[str] = None
+    model_list: Optional[List[Any]] = None
+    extra_headers: Optional[Dict[str, str]] = None
+
+    settings: LanguageModelSettings = LanguageModelSettings()
+    """Settings for the language model."""
+
+    instructor_mode: LanguageModelInstructorMode = "tool_call"
+    """Default instructor mode for structured outputs."""
+
     def __init__(
         self,
         model: LanguageModelName = "openai/gpt-4o-mini",
         base_url: Optional[str] = None,
         api_key: Optional[str] = None,
         instructor_mode: LanguageModelInstructorMode = "tool_call",
+        **kwargs: Any,
     ):
         """Initialize the language model.
-        
+
         Args:
             model: The model to use for requests
+            base_url: Custom base URL for the API
+            api_key: API key for authentication
             instructor_mode: Default instructor mode for structured outputs
+            **kwargs: Additional arguments passed to BaseGenAIModel
         """
-        self.model = model
-        self.base_url = base_url
-        self.api_key = api_key
-        self.instructor_mode = instructor_mode
+        # Initialize BaseGenAIModel via super()
+        super().__init__(model=model, base_url=base_url, api_key=api_key, **kwargs)
+
+        # Initialize LanguageModel-specific attributes
         self._instructor_client = None
-    
-    def _get_instructor_client(self, mode: Optional[LanguageModelInstructorMode] = None):
+
+        logger.info(f"Initialized LanguageModel w/ model: {self.model}")
+        logger.debug(f"LanguageModel settings: {self.settings}")
+
+    def _get_instructor_client(
+        self, mode: Optional[LanguageModelInstructorMode] = None
+    ):
         """Get or create an instructor client with the specified mode."""
         effective_mode = mode or self.instructor_mode
-        
+
         # Create a new client if mode changed or client doesn't exist
-        if (self._instructor_client is None or 
-            getattr(self._instructor_client, '_mode', None) != effective_mode):
-            
-            instructor = _AIProvider.get_instructor()
+        if (
+            self._instructor_client is None
+            or getattr(self._instructor_client, "_mode", None) != effective_mode
+        ):
+            logger.debug(f"Creating new instructor client for mode: {effective_mode} from old mode: {getattr(self._instructor_client, '_mode', None)}")
+
             self._instructor_client = instructor.from_litellm(
-                completion=_AIProvider.get_litellm().completion,
-                mode=instructor.Mode(effective_mode)
+                completion=litellm.completion, mode=instructor.Mode(effective_mode)
             )
             self._instructor_client._mode = effective_mode
-            
+
         return self._instructor_client
-    
-    def _get_async_instructor_client(self, mode: Optional[LanguageModelInstructorMode] = None):
+
+    def _get_async_instructor_client(
+        self, mode: Optional[LanguageModelInstructorMode] = None
+    ):
         """Get or create an async instructor client with the specified mode."""
         effective_mode = mode or self.instructor_mode
-        
-        instructor = _AIProvider.get_instructor()
+
         return instructor.from_litellm(
-            completion=_AIProvider.get_litellm().acompletion,
-            mode=instructor.Mode(effective_mode)
+            completion=litellm.acompletion, mode=instructor.Mode(effective_mode)
         )
-    
+
     # Overloaded run methods for different return types
-    
+
     @overload
     def run(
         self,
-        messages: LanguageModelMessagesParam,
+        messages: LanguageModelMessages,
         instructions: Optional[str] = None,
         *,
         stream: Literal[False] = False,
         model: Optional[LanguageModelName | str] = None,
         base_url: Optional[str] = None,
         api_key: Optional[str] = None,
+        mock_response: Optional[str] = None,
         **kwargs: Any,
     ) -> LanguageModelResponse[str]: ...
-    
+
     @overload
     def run(
         self,
-        messages: LanguageModelMessagesParam,
+        messages: LanguageModelMessages,
         instructions: Optional[str] = None,
         *,
         stream: Literal[False] = False,
@@ -178,26 +185,28 @@ class LanguageModel(Generic[T]):
         frequency_penalty: Optional[float] = None,
         seed: Optional[int] = None,
         user: Optional[str] = None,
+        mock_response: Optional[str] = None,
         **kwargs: Any,
     ) -> LanguageModelResponse[str]: ...
-    
+
     @overload
     def run(
         self,
-        messages: LanguageModelMessagesParam,
+        messages: LanguageModelMessages,
         instructions: Optional[str] = None,
         *,
         stream: Literal[True],
         model: Optional[LanguageModelName | str] = None,
         base_url: Optional[str] = None,
         api_key: Optional[str] = None,
+        mock_response: Optional[str] = None,
         **kwargs: Any,
-    ) -> Stream[str]: ...
-    
+    ) -> LanguageModelStream[str]: ...
+
     @overload
     def run(
         self,
-        messages: LanguageModelMessagesParam,
+        messages: LanguageModelMessages,
         instructions: Optional[str] = None,
         *,
         stream: Literal[True],
@@ -214,13 +223,14 @@ class LanguageModel(Generic[T]):
         frequency_penalty: Optional[float] = None,
         seed: Optional[int] = None,
         user: Optional[str] = None,
+        mock_response: Optional[str] = None,
         **kwargs: Any,
-    ) -> Stream[str]: ...
-    
+    ) -> LanguageModelStream[str]: ...
+
     @overload
     def run(
         self,
-        messages: LanguageModelMessagesParam,
+        messages: LanguageModelMessages,
         instructions: Optional[str] = None,
         *,
         type: Type[T],
@@ -228,13 +238,14 @@ class LanguageModel(Generic[T]):
         model: Optional[LanguageModelName | str] = None,
         base_url: Optional[str] = None,
         api_key: Optional[str] = None,
+        mock_response: Optional[str] = None,
         **kwargs: Any,
     ) -> LanguageModelResponse[T]: ...
-    
+
     @overload
     def run(
         self,
-        messages: LanguageModelMessagesParam,
+        messages: LanguageModelMessages,
         instructions: Optional[str] = None,
         *,
         type: Type[T],
@@ -263,13 +274,14 @@ class LanguageModel(Generic[T]):
         frequency_penalty: Optional[float] = None,
         seed: Optional[int] = None,
         user: Optional[str] = None,
+        mock_response: Optional[str] = None,
         **kwargs: Any,
     ) -> LanguageModelResponse[T]: ...
-    
+
     @overload
     def run(
         self,
-        messages: LanguageModelMessagesParam,
+        messages: LanguageModelMessages,
         instructions: Optional[str] = None,
         *,
         type: Type[T],
@@ -277,13 +289,14 @@ class LanguageModel(Generic[T]):
         model: Optional[LanguageModelName | str] = None,
         base_url: Optional[str] = None,
         api_key: Optional[str] = None,
+        mock_response: Optional[str] = None,
         **kwargs: Any,
-    ) -> Stream[T]: ...
-    
+    ) -> LanguageModelStream[T]: ...
+
     @overload
     def run(
         self,
-        messages: LanguageModelMessagesParam,
+        messages: LanguageModelMessages,
         instructions: Optional[str] = None,
         *,
         type: Type[T],
@@ -312,77 +325,87 @@ class LanguageModel(Generic[T]):
         frequency_penalty: Optional[float] = None,
         seed: Optional[int] = None,
         user: Optional[str] = None,
+        mock_response: Optional[str] = None,
         **kwargs: Any,
-    ) -> Stream[T]: ...
-    
+    ) -> LanguageModelStream[T]: ...
+
     def run(
         self,
-        messages: LanguageModelMessagesParam,
+        messages: LanguageModelMessages,
         instructions: Optional[str] = None,
+        mock_response: Optional[str] = None,
         **kwargs: Any,
-    ) -> Union[LanguageModelResponse[Any], Stream[Any]]:
+    ) -> Union[LanguageModelResponse[Any], LanguageModelStream[Any]]:
         """Run a language model request.
-        
+
         Args:
             messages: The input messages/content for the request
             instructions: Optional system instructions to prepend
+            mock_response: Mock response string for testing (saves API costs)
             **kwargs: Additional request parameters
-            
+
         Returns:
             LanguageModelResponse or LanguageModelStream depending on parameters
         """
+        logger.info(f"Running LanguageModel request with model: {self.model}")
+        logger.debug(f"LanguageModel request kwargs: {kwargs}")
+
         try:
-            # Extract model, base_url, and api_key from kwargs, using instance defaults
+            # Extract model, base_url, api_key, and mock_response from kwargs, using instance defaults
             model = kwargs.pop("model", None) or self.model
             base_url = kwargs.pop("base_url", None) or self.base_url
             api_key = kwargs.pop("api_key", None) or self.api_key
-            
-            # Add base_url and api_key to kwargs if they are set
+            mock_response_param = kwargs.pop("mock_response", None) or mock_response
+
+            # Add base_url, api_key, and mock_response to kwargs if they are set
             if base_url is not None:
                 kwargs["base_url"] = base_url
             if api_key is not None:
                 kwargs["api_key"] = api_key
-            
+            if mock_response_param is not None:
+                kwargs["mock_response"] = mock_response_param
+
             # Create the request
             request = LanguageModelRequestBuilder(
-                messages=messages,
-                instructions=instructions,
-                model=model,
-                **kwargs
+                messages=messages, instructions=instructions, model=model, **kwargs
             )
-            
+
             # Parse messages
-            parsed_messages = parse_messages_input(request.messages, request.instructions)
-            parsed_messages = format_tool_calls(parsed_messages)
-            
+            parsed_messages = parse_messages_input(
+                request.messages, request.instructions
+            )
+            if request.is_structured_output():
+                parsed_messages = format_tool_calls(parsed_messages)
+
             # Handle different request types
             if request.is_structured_output():
                 return self._handle_structured_output_request(request, parsed_messages)
             else:
                 return self._handle_completion_request(request, parsed_messages)
-                
+
         except Exception as e:
             raise LanguageModelError(f"Error in language model request: {e}") from e
-    
+
     # Overloaded async_run methods for different return types
-    
+
     @overload
     async def async_run(
         self,
-        messages: LanguageModelMessagesParam,
+        messages: LanguageModelMessages,
         instructions: Optional[str] = None,
         *,
         stream: Literal[False] = False,
         model: Optional[LanguageModelName | str] = None,
         base_url: Optional[str] = None,
         api_key: Optional[str] = None,
+        mock_response: Optional[str] = None,
         **kwargs: Any,
     ) -> LanguageModelResponse[str]: ...
-    
+
     @overload
     async def async_run(
         self,
-        messages: LanguageModelMessagesParam,
+        messages: LanguageModelMessages,
         instructions: Optional[str] = None,
         *,
         stream: Literal[False] = False,
@@ -399,26 +422,28 @@ class LanguageModel(Generic[T]):
         frequency_penalty: Optional[float] = None,
         seed: Optional[int] = None,
         user: Optional[str] = None,
+        mock_response: Optional[str] = None,
         **kwargs: Any,
     ) -> LanguageModelResponse[str]: ...
-    
+
     @overload
     async def async_run(
         self,
-        messages: LanguageModelMessagesParam,
+        messages: LanguageModelMessages,
         instructions: Optional[str] = None,
         *,
         stream: Literal[True],
         model: Optional[LanguageModelName | str] = None,
         base_url: Optional[str] = None,
         api_key: Optional[str] = None,
+        mock_response: Optional[str] = None,
         **kwargs: Any,
-    ) -> AsyncStream[str]: ...
-    
+    ) -> LanguageModelStream[str]: ...
+
     @overload
     async def async_run(
         self,
-        messages: LanguageModelMessagesParam,
+        messages: LanguageModelMessages,
         instructions: Optional[str] = None,
         *,
         stream: Literal[True],
@@ -435,13 +460,14 @@ class LanguageModel(Generic[T]):
         frequency_penalty: Optional[float] = None,
         seed: Optional[int] = None,
         user: Optional[str] = None,
+        mock_response: Optional[str] = None,
         **kwargs: Any,
-    ) -> AsyncStream[str]: ...
-    
+    ) -> LanguageModelStream[str]: ...
+
     @overload
     async def async_run(
         self,
-        messages: LanguageModelMessagesParam,
+        messages: LanguageModelMessages,
         instructions: Optional[str] = None,
         *,
         type: Type[T],
@@ -449,13 +475,14 @@ class LanguageModel(Generic[T]):
         model: Optional[LanguageModelName | str] = None,
         base_url: Optional[str] = None,
         api_key: Optional[str] = None,
+        mock_response: Optional[str] = None,
         **kwargs: Any,
     ) -> LanguageModelResponse[T]: ...
-    
+
     @overload
     async def async_run(
         self,
-        messages: LanguageModelMessagesParam,
+        messages: LanguageModelMessages,
         instructions: Optional[str] = None,
         *,
         type: Type[T],
@@ -484,13 +511,14 @@ class LanguageModel(Generic[T]):
         frequency_penalty: Optional[float] = None,
         seed: Optional[int] = None,
         user: Optional[str] = None,
+        mock_response: Optional[str] = None,
         **kwargs: Any,
     ) -> LanguageModelResponse[T]: ...
-    
+
     @overload
     async def async_run(
         self,
-        messages: LanguageModelMessagesParam,
+        messages: LanguageModelMessages,
         instructions: Optional[str] = None,
         *,
         type: Type[T],
@@ -498,13 +526,14 @@ class LanguageModel(Generic[T]):
         model: Optional[LanguageModelName | str] = None,
         base_url: Optional[str] = None,
         api_key: Optional[str] = None,
+        mock_response: Optional[str] = None,
         **kwargs: Any,
-    ) -> AsyncStream[T]: ...
-    
+    ) -> LanguageModelStream[T]: ...
+
     @overload
     async def async_run(
         self,
-        messages: LanguageModelMessagesParam,
+        messages: LanguageModelMessages,
         instructions: Optional[str] = None,
         *,
         type: Type[T],
@@ -533,114 +562,129 @@ class LanguageModel(Generic[T]):
         frequency_penalty: Optional[float] = None,
         seed: Optional[int] = None,
         user: Optional[str] = None,
+        mock_response: Optional[str] = None,
         **kwargs: Any,
-    ) -> AsyncStream[T]: ...
-    
+    ) -> LanguageModelStream[T]: ...
+
     async def async_run(
         self,
-        messages: LanguageModelMessagesParam,
+        messages: LanguageModelMessages,
         instructions: Optional[str] = None,
+        mock_response: Optional[str] = None,
         **kwargs: Any,
-    ) -> Union[LanguageModelResponse[Any], AsyncStream[Any]]:
+    ) -> Union[LanguageModelResponse[Any], LanguageModelStream[Any]]:
         """Run an async language model request.
-        
+
         Args:
             messages: The input messages/content for the request
             instructions: Optional system instructions to prepend
+            mock_response: Mock response string for testing (saves API costs)
             **kwargs: Additional request parameters
-            
+
         Returns:
             LanguageModelResponse or LanguageModelAsyncStream depending on parameters
         """
+        logger.info(f"Running async LanguageModel request with model: {self.model}")
+        logger.debug(f"LanguageModel request kwargs: {kwargs}")
+
         try:
-            # Extract model, base_url, and api_key from kwargs, using instance defaults
+            # Extract model, base_url, api_key, and mock_response from kwargs, using instance defaults
             model = kwargs.pop("model", None) or self.model
             base_url = kwargs.pop("base_url", None) or self.base_url
             api_key = kwargs.pop("api_key", None) or self.api_key
-            
-            # Add base_url and api_key to kwargs if they are set
+            mock_response_param = kwargs.pop("mock_response", None) or mock_response
+
+            # Add base_url, api_key, and mock_response to kwargs if they are set
             if base_url is not None:
                 kwargs["base_url"] = base_url
             if api_key is not None:
                 kwargs["api_key"] = api_key
-            
+            if mock_response_param is not None:
+                kwargs["mock_response"] = mock_response_param
+
             # Create the request
             request = LanguageModelRequestBuilder(
-                messages=messages,
-                instructions=instructions,
-                model=model,
-                **kwargs
+                messages=messages, instructions=instructions, model=model, **kwargs
             )
-            
+
             # Parse messages
-            parsed_messages = parse_messages_input(request.messages, request.instructions)
-            parsed_messages = format_tool_calls(parsed_messages)
-            
+            parsed_messages = parse_messages_input(
+                request.messages, request.instructions
+            )
+            if request.is_structured_output():
+                parsed_messages = format_tool_calls(parsed_messages)
+
             # Handle different request types
             if request.is_structured_output():
-                return await self._handle_async_structured_output_request(request, parsed_messages)
+                return await self._handle_async_structured_output_request(
+                    request, parsed_messages
+                )
             else:
-                return await self._handle_async_completion_request(request, parsed_messages)
-                
+                return await self._handle_async_completion_request(
+                    request, parsed_messages
+                )
+
         except Exception as e:
-            raise LanguageModelError(f"Error in async language model request: {e}") from e
-    
+            raise LanguageModelError(
+                f"Error in async language model request: {e}"
+            ) from e
+
     def _handle_completion_request(
-        self, 
-        request: LanguageModelRequestBuilder, 
-        parsed_messages: List[Any]
-    ) -> Union[LanguageModelResponse[str], Stream[str]]:
+        self, request: LanguageModelRequestBuilder, parsed_messages: List[Any]
+    ) -> Union[LanguageModelResponse[str], LanguageModelStream[str]]:
         """Handle a standard completion request."""
         # Get filtered parameters
         params = handle_completion_request_params(request.get_completion_settings())
         params["messages"] = parsed_messages
-        
-        litellm = _AIProvider.get_litellm()
-        
+
         if request.is_streaming():
             # Handle streaming - stream parameter is already in params
             if "stream_options" not in params and "stream_options" in request.settings:
                 params["stream_options"] = request.settings["stream_options"]
             stream = litellm.completion(**params)
-            return Stream(stream, output_type=str, model=request.model)
+            return LanguageModelStream(
+                model=request.model,
+                stream=stream,
+                output_type=str,
+            )
         else:
             # Handle non-streaming
             response = litellm.completion(**params)
             return handle_completion_response(response, request.model)
-    
+
     async def _handle_async_completion_request(
-        self, 
-        request: LanguageModelRequestBuilder, 
-        parsed_messages: List[Any]
-    ) -> Union[LanguageModelResponse[str], AsyncStream[str]]:
+        self, request: LanguageModelRequestBuilder, parsed_messages: List[Any]
+    ) -> Union[LanguageModelResponse[str], LanguageModelStream[str]]:
         """Handle an async standard completion request."""
         # Get filtered parameters
         params = handle_completion_request_params(request.get_completion_settings())
         params["messages"] = parsed_messages
-        
-        litellm = _AIProvider.get_litellm()
-        
+
         if request.is_streaming():
             # Handle streaming - stream parameter is already in params
             if "stream_options" not in params and "stream_options" in request.settings:
                 params["stream_options"] = request.settings["stream_options"]
             stream = await litellm.acompletion(**params)
-            return AsyncStream(stream, output_type=str, model=request.model)
+            return LanguageModelStream(
+                model=request.model,
+                stream=stream,
+                output_type=str,
+            )
         else:
             # Handle non-streaming
             response = await litellm.acompletion(**params)
             return handle_completion_response(response, request.model)
-    
+
     def _handle_structured_output_request(
-        self, 
-        request: LanguageModelRequestBuilder, 
-        parsed_messages: List[Any]
-    ) -> Union[LanguageModelResponse[Any], Stream[Any]]:
+        self, request: LanguageModelRequestBuilder, parsed_messages: List[Any]
+    ) -> Union[LanguageModelResponse[Any], LanguageModelStream[Any]]:
         """Handle a structured output request."""
         # Get filtered parameters
-        params = handle_structured_output_request_params(request.get_structured_output_settings())
+        params = handle_structured_output_request_params(
+            request.get_structured_output_settings()
+        )
         params["messages"] = parsed_messages
-        
+
         # Prepare response model
         response_model = prepare_response_model(
             request.get_output_type(),
@@ -648,10 +692,10 @@ class LanguageModel(Generic[T]):
             request.get_response_field_instruction(),
             request.get_response_model_name(),
         )
-        
+
         # Get instructor client
         client = self._get_instructor_client(request.get_instructor_mode())
-        
+
         if request.is_streaming():
             if isinstance(request.get_output_type(), list):
                 # Handle streaming - stream parameter is already in params
@@ -669,7 +713,12 @@ class LanguageModel(Generic[T]):
                     strict=request.get_strict_mode(),
                     **params,
                 )
-            return Stream(stream, output_type=request.get_output_type(), model=request.model, response_field_name=request.get_response_field_name())
+            return LanguageModelStream(
+                model=request.model,
+                stream=stream,
+                output_type=request.get_output_type(),
+                response_field_name=request.get_response_field_name(),
+            )
         else:
             # Handle non-streaming
             response, completion = client.chat.completions.create_with_completion(
@@ -679,19 +728,23 @@ class LanguageModel(Generic[T]):
                 **params,
             )
             return handle_structured_output_response(
-                response, completion, request.model, request.get_output_type(), request.get_response_field_name()
+                response,
+                completion,
+                request.model,
+                request.get_output_type(),
+                request.get_response_field_name(),
             )
-    
+
     async def _handle_async_structured_output_request(
-        self, 
-        request: LanguageModelRequestBuilder, 
-        parsed_messages: List[Any]
-    ) -> Union[LanguageModelResponse[Any], AsyncStream[Any]]:
+        self, request: LanguageModelRequestBuilder, parsed_messages: List[Any]
+    ) -> Union[LanguageModelResponse[Any], LanguageModelStream[Any]]:
         """Handle an async structured output request."""
         # Get filtered parameters
-        params = handle_structured_output_request_params(request.get_structured_output_settings())
+        params = handle_structured_output_request_params(
+            request.get_structured_output_settings()
+        )
         params["messages"] = parsed_messages
-        
+
         # Prepare response model
         response_model = prepare_response_model(
             request.get_output_type(),
@@ -699,10 +752,10 @@ class LanguageModel(Generic[T]):
             request.get_response_field_instruction(),
             request.get_response_model_name(),
         )
-        
+
         # Get async instructor client
         client = self._get_async_instructor_client(request.get_instructor_mode())
-        
+
         if request.is_streaming():
             if isinstance(request.get_output_type(), list):
                 # Handle streaming - stream parameter is already in params
@@ -720,7 +773,12 @@ class LanguageModel(Generic[T]):
                     strict=request.get_strict_mode(),
                     **params,
                 )
-            return AsyncStream(stream, output_type=request.get_output_type(), model=request.model, response_field_name=request.get_response_field_name())
+            return LanguageModelStream(
+                model=request.model,
+                stream=stream,
+                output_type=request.get_output_type(),
+                response_field_name=request.get_response_field_name(),
+            )
         else:
             # Handle non-streaming
             response, completion = await client.chat.completions.create_with_completion(
@@ -730,5 +788,239 @@ class LanguageModel(Generic[T]):
                 **params,
             )
             return handle_structured_output_response(
-                response, completion, request.model, request.get_output_type(), request.get_response_field_name()
-            )
+                response,
+                completion,
+                request.model,
+                request.get_output_type(),
+                request.get_response_field_name(),
+            )
+
+    def as_tool(
+        self,
+        func: Optional[Callable] = None,
+        *,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        instructions: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Union[Callable, Any]:
+        """Convert this language model to a tool that can be used by agents.
+
+        Can be used as a decorator or as a function:
+
+        As a decorator:
+        @model.as_tool()
+        def my_function(param1: str, param2: int) -> MyType:
+            '''Function description'''
+            pass
+
+        As a function:
+        tool = model.as_tool(
+            name="my_tool",
+            description="Tool description",
+            instructions="Custom instructions for the LLM"
+        )
+
+        Args:
+            func: The function to wrap (when used as decorator)
+            name: The name of the tool
+            description: Description of what the tool does
+            instructions: Custom instructions for the LLM generation
+            **kwargs: Additional arguments for tool creation
+
+        Returns:
+            BaseTool or decorated function
+        """
+        from ...types.base import BaseTool
+        from ....formatting.text.converters import convert_docstring_to_text
+
+        def create_tool_wrapper(target_func: Optional[Callable] = None) -> Any:
+            """Create a tool wrapper for the language model."""
+
+            if target_func is not None:
+                # Decorator usage - use function signature and docstring
+                sig = inspect.signature(target_func)
+                func_name = name or target_func.__name__
+
+                # Get return type from function signature
+                return_type = (
+                    sig.return_annotation
+                    if sig.return_annotation != inspect.Signature.empty
+                    else str
+                )
+
+                # Extract docstring as system instructions
+                system_instructions = instructions or convert_docstring_to_text(
+                    target_func
+                )
+
+                # Create parameter schema from function signature
+                parameters_schema = {"type": "object", "properties": {}, "required": []}
+
+                for param_name, param in sig.parameters.items():
+                    param_type = (
+                        param.annotation
+                        if param.annotation != inspect.Parameter.empty
+                        else str
+                    )
+
+                    # Convert type to JSON schema type
+                    if param_type == str:
+                        json_type = "string"
+                    elif param_type == int:
+                        json_type = "integer"
+                    elif param_type == float:
+                        json_type = "number"
+                    elif param_type == bool:
+                        json_type = "boolean"
+                    elif param_type == list:
+                        json_type = "array"
+                    elif param_type == dict:
+                        json_type = "object"
+                    else:
+                        json_type = "string"  # Default fallback
+
+                    parameters_schema["properties"][param_name] = {
+                        "type": json_type,
+                        "description": f"Parameter {param_name} of type {param_type.__name__ if hasattr(param_type, '__name__') else str(param_type)}",
+                    }
+
+                    if param.default == inspect.Parameter.empty:
+                        parameters_schema["required"].append(param_name)
+
+                # Create partial function with model settings
+                partial_func = functools.partial(
+                    self._execute_tool_function,
+                    target_func=target_func,
+                    return_type=return_type,
+                    system_instructions=system_instructions,
+                )
+
+                # Handle async functions
+                if asyncio.iscoroutinefunction(target_func):
+
+                    async def async_tool_function(**tool_kwargs: Any) -> Any:
+                        return await partial_func(**tool_kwargs)
+
+                    return BaseTool(
+                        name=func_name,
+                        description=description
+                        or system_instructions
+                        or f"Tool for {func_name}",
+                        function=async_tool_function,
+                        parameters_json_schema=parameters_schema,
+                        **kwargs,
+                    )
+                else:
+
+                    def sync_tool_function(**tool_kwargs: Any) -> Any:
+                        return partial_func(**tool_kwargs)
+
+                    return BaseTool(
+                        name=func_name,
+                        description=description
+                        or system_instructions
+                        or f"Tool for {func_name}",
+                        function=sync_tool_function,
+                        parameters_json_schema=parameters_schema,
+                        **kwargs,
+                    )
+            else:
+                # Function usage - create generic tool
+                tool_name = name or f"language_model_{self.model.replace('/', '_')}"
+                tool_description = (
+                    description or f"Language model tool using {self.model}"
+                )
+
+                # Create partial function with model settings
+                partial_func = functools.partial(
+                    self._execute_generic_tool, system_instructions=instructions
+                )
+
+                def generic_tool_function(
+                    input: str, type: Optional[Type[T]] = None, **tool_kwargs: Any
+                ) -> Any:
+                    """Generic tool function that runs the language model."""
+                    return partial_func(input=input, output_type=type, **tool_kwargs)
+
+                # Generic parameter schema
+                parameters_schema = {
+                    "type": "object",
+                    "properties": {
+                        "input": {
+                            "type": "string",
+                            "description": "The input text for the language model",
+                        },
+                        "type": {
+                            "type": "string",
+                            "description": "Optional output type specification",
+                        },
+                    },
+                    "required": ["input"],
+                }
+
+                return BaseTool(
+                    name=tool_name,
+                    description=tool_description,
+                    function=generic_tool_function,
+                    parameters_json_schema=parameters_schema,
+                    **kwargs,
+                )
+
+        if func is None:
+            # Called as @model.as_tool() or model.as_tool()
+            return create_tool_wrapper
+        else:
+            # Called as @model.as_tool (without parentheses)
+            return create_tool_wrapper(func)
+
+    def _execute_tool_function(
+        self,
+        target_func: Callable,
+        return_type: Type,
+        system_instructions: str,
+        **kwargs: Any,
+    ) -> Any:
+        """Execute a function-based tool using the language model."""
+        # Format the function call parameters
+        param_text = ", ".join([f"{k}={v}" for k, v in kwargs.items()])
+        input_text = f"Function: {target_func.__name__}({param_text})"
+
+        # Use the language model to generate structured output
+        if return_type != str:
+            response = self.run(
+                messages=[{"role": "user", "content": input_text}],
+                instructions=system_instructions,
+                type=return_type,
+            )
+        else:
+            response = self.run(
+                messages=[{"role": "user", "content": input_text}],
+                instructions=system_instructions,
+            )
+
+        return response.output
+
+    def _execute_generic_tool(
+        self,
+        input: str,
+        output_type: Optional[Type] = None,
+        system_instructions: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Execute a generic tool using the language model."""
+        if output_type and output_type != str:
+            response = self.run(
+                messages=[{"role": "user", "content": input}],
+                instructions=system_instructions,
+                type=output_type,
+                **kwargs,
+            )
+        else:
+            response = self.run(
+                messages=[{"role": "user", "content": input}],
+                instructions=system_instructions,
+                **kwargs,
+            )
+
+        return response.output