hammad-python 0.0.23__py3-none-any.whl → 0.0.25__py3-none-any.whl

hammad/genai/models/language/model.py

@@ -100,6 +100,8 @@ class LanguageModel(BaseGenAIModel, Generic[T]):
         base_url: Optional[str] = None,
         api_key: Optional[str] = None,
         instructor_mode: LanguageModelInstructorMode = "tool_call",
+        verbose: bool = False,
+        debug: bool = False,
         **kwargs: Any,
     ):
         """Initialize the language model.
@@ -109,6 +111,8 @@ class LanguageModel(BaseGenAIModel, Generic[T]):
             base_url: Custom base URL for the API
             api_key: API key for authentication
             instructor_mode: Default instructor mode for structured outputs
+            verbose: If True, set logger to INFO level for detailed output
+            debug: If True, set logger to DEBUG level for maximum verbosity
             **kwargs: Additional arguments passed to BaseGenAIModel
         """
         # Initialize BaseGenAIModel via super()
@@ -116,6 +120,14 @@ class LanguageModel(BaseGenAIModel, Generic[T]):
 
         # Initialize LanguageModel-specific attributes
         self._instructor_client = None
+        self.verbose = verbose
+        self.debug = debug
+
+        # Set logger level based on verbose/debug flags
+        if debug:
+            logger.setLevel("DEBUG")
+        elif verbose:
+            logger.setLevel("INFO")
 
         logger.info(f"Initialized LanguageModel w/ model: {self.model}")
         logger.debug(f"LanguageModel settings: {self.settings}")
@@ -337,6 +349,8 @@ class LanguageModel(BaseGenAIModel, Generic[T]):
         messages: LanguageModelMessages,
         instructions: Optional[str] = None,
         mock_response: Optional[str] = None,
+        verbose: Optional[bool] = None,
+        debug: Optional[bool] = None,
         **kwargs: Any,
     ) -> Union[LanguageModelResponse[Any], LanguageModelStream[Any]]:
         """Run a language model request.
@@ -345,11 +359,20 @@ class LanguageModel(BaseGenAIModel, Generic[T]):
             messages: The input messages/content for the request
             instructions: Optional system instructions to prepend
             mock_response: Mock response string for testing (saves API costs)
+            verbose: If True, set logger to INFO level for this request
+            debug: If True, set logger to DEBUG level for this request
             **kwargs: Additional request parameters
 
         Returns:
             LanguageModelResponse or LanguageModelStream depending on parameters
         """
+        # Set logger level for this request if specified
+        original_level = logger.level
+        if debug or (debug is None and self.debug):
+            logger.setLevel("DEBUG")
+        elif verbose or (verbose is None and self.verbose):
+            logger.setLevel("INFO")
+
         logger.info(f"Running LanguageModel request with model: {self.model}")
         logger.debug(f"LanguageModel request kwargs: {kwargs}")
 
@@ -388,6 +411,10 @@ class LanguageModel(BaseGenAIModel, Generic[T]):
 
         except Exception as e:
             raise LanguageModelError(f"Error in language model request: {e}") from e
+        finally:
+            # Restore original logger level
+            if debug is not None or verbose is not None:
+                logger.setLevel(original_level)
 
     # Overloaded async_run methods for different return types
 
@@ -574,6 +601,8 @@ class LanguageModel(BaseGenAIModel, Generic[T]):
         messages: LanguageModelMessages,
         instructions: Optional[str] = None,
         mock_response: Optional[str] = None,
+        verbose: Optional[bool] = None,
+        debug: Optional[bool] = None,
         **kwargs: Any,
     ) -> Union[LanguageModelResponse[Any], LanguageModelStream[Any]]:
         """Run an async language model request.
@@ -582,11 +611,20 @@ class LanguageModel(BaseGenAIModel, Generic[T]):
             messages: The input messages/content for the request
             instructions: Optional system instructions to prepend
             mock_response: Mock response string for testing (saves API costs)
+            verbose: If True, set logger to INFO level for this request
+            debug: If True, set logger to DEBUG level for this request
             **kwargs: Additional request parameters
 
         Returns:
             LanguageModelResponse or LanguageModelAsyncStream depending on parameters
         """
+        # Set logger level for this request if specified
+        original_level = logger.level
+        if debug or (debug is None and self.debug):
+            logger.setLevel("DEBUG")
+        elif verbose or (verbose is None and self.verbose):
+            logger.setLevel("INFO")
+
         logger.info(f"Running async LanguageModel request with model: {self.model}")
         logger.debug(f"LanguageModel request kwargs: {kwargs}")
 
@@ -631,6 +669,10 @@ class LanguageModel(BaseGenAIModel, Generic[T]):
             raise LanguageModelError(
                 f"Error in async language model request: {e}"
             ) from e
+        finally:
+            # Restore original logger level
+            if debug is not None or verbose is not None:
+                logger.setLevel(original_level)
 
     def _handle_completion_request(
         self, request: LanguageModelRequestBuilder, parsed_messages: List[Any]
@@ -1038,6 +1080,8 @@ def create_language_model(
     deployment_id: Optional[str] = None,
     model_list: Optional[List[Any]] = None,
     extra_headers: Optional[Dict[str, str]] = None,
+    verbose: bool = False,
+    debug: bool = False,
 ) -> LanguageModel:
     """Create a language model instance."""
     return LanguageModel(
@@ -1049,4 +1093,6 @@ def create_language_model(
         deployment_id=deployment_id,
         model_list=model_list,
         extra_headers=extra_headers,
+        verbose=verbose,
+        debug=debug,
     )

hammad/genai/models/language/run.py

@@ -3,6 +3,8 @@
 Standalone functions for running language models with full parameter typing.
 """
 
+import inspect
+import functools
 from typing import (
     Any,
     List,
@@ -39,6 +41,7 @@ from .model import LanguageModel
 __all__ = [
     "run_language_model",
     "async_run_language_model",
+    "language_model_decorator",
 ]
 
 
@@ -275,6 +278,8 @@ def run_language_model(
     messages: "LanguageModelMessages",
     instructions: Optional[str] = None,
     mock_response: Optional[bool] = None,
+    verbose: bool = False,
+    debug: bool = False,
     **kwargs: Any,
 ) -> Union["LanguageModelResponse[Any]", "LanguageModelStream[Any]"]:
     """Run a language model request with full parameter support.
@@ -282,6 +287,8 @@ def run_language_model(
     Args:
         messages: The input messages/content for the request
         instructions: Optional system instructions to prepend
+        verbose: If True, set logger to INFO level for detailed output
+        debug: If True, set logger to DEBUG level for maximum verbosity
         **kwargs: All request parameters from LanguageModelRequest
 
     Returns:
@@ -291,11 +298,16 @@ def run_language_model(
     model = kwargs.pop("model", "openai/gpt-4o-mini")
 
     # Create language model instance
-    language_model = LanguageModel(model=model)
+    language_model = LanguageModel(model=model, verbose=verbose, debug=debug)
 
     # Forward to the instance method
     return language_model.run(
-        messages, instructions, mock_response=mock_response, **kwargs
+        messages,
+        instructions,
+        mock_response=mock_response,
+        verbose=verbose,
+        debug=debug,
+        **kwargs,
     )
 
 
@@ -528,6 +540,8 @@ async def async_run_language_model(
     messages: "LanguageModelMessages",
     instructions: Optional[str] = None,
     mock_response: Optional[bool] = None,
+    verbose: bool = False,
+    debug: bool = False,
     **kwargs: Any,
 ) -> Union["LanguageModelResponse[Any]", "LanguageModelStream[Any]"]:
     """Run an async language model request with full parameter support.
@@ -535,6 +549,8 @@ async def async_run_language_model(
     Args:
         messages: The input messages/content for the request
         instructions: Optional system instructions to prepend
+        verbose: If True, set logger to INFO level for detailed output
+        debug: If True, set logger to DEBUG level for maximum verbosity
         **kwargs: All request parameters from LanguageModelRequest
 
     Returns:
@@ -544,9 +560,319 @@ async def async_run_language_model(
     model = kwargs.pop("model", "openai/gpt-4o-mini")
 
     # Create language model instance
-    language_model = LanguageModel(model=model)
+    language_model = LanguageModel(model=model, verbose=verbose, debug=debug)
 
     # Forward to the instance method
     return await language_model.async_run(
-        messages, instructions, mock_response=mock_response, **kwargs
+        messages,
+        instructions,
+        mock_response=mock_response,
+        verbose=verbose,
+        debug=debug,
+        **kwargs,
     )
+
+
+def language_model_decorator(
+    fn: Union[str, Callable, None] = None,
+    *,
+    # Model settings
+    model: Optional[Union["LanguageModel", "LanguageModelName"]] = None,
+    instructions: Optional[str] = None,
+    mock_response: Optional[bool] = None,
+    # Request settings
+    output_type: Optional[Type] = None,
+    stream: Optional[bool] = None,
+    instructor_mode: Optional["LanguageModelInstructorMode"] = None,
+    return_output: bool = True,
+    # LM settings
+    timeout: Optional[Union[float, str, "Timeout"]] = None,
+    temperature: Optional[float] = None,
+    top_p: Optional[float] = None,
+    max_tokens: Optional[int] = None,
+    presence_penalty: Optional[float] = None,
+    frequency_penalty: Optional[float] = None,
+    seed: Optional[int] = None,
+    user: Optional[str] = None,
+    # Advanced settings
+    response_format: Optional[Dict[str, Any]] = None,
+    stop: Optional[Union[str, List[str]]] = None,
+    logit_bias: Optional[Dict[int, float]] = None,
+    logprobs: Optional[bool] = None,
+    top_logprobs: Optional[int] = None,
+    thinking: Optional[Dict[str, Any]] = None,
+    web_search_options: Optional[Dict[str, Any]] = None,
+    # Tools settings
+    tools: Optional[List[Any]] = None,
+    tool_choice: Optional[Union[str, Dict[str, Any]]] = None,
+    parallel_tool_calls: Optional[bool] = None,
+    functions: Optional[List[Any]] = None,
+    function_call: Optional[str] = None,
+    verbose: bool = False,
+    debug: bool = False,
+):
+    """Decorator that converts a function into a language model call.
+
+    The function's parameters become the input to the LLM (converted to a string),
+    the function's return type annotation becomes the language model's output type,
+    and the function's docstring becomes the language model's instructions.
+
+    Works with both sync and async functions.
+
+    Can be used in multiple ways:
+
+    1. As a decorator with parameters:
+       @language_model_decorator(model="gpt-4", temperature=0.7)
+       def my_lm():
+           pass
+
+    2. As a decorator without parameters:
+       @language_model_decorator
+       def my_lm():
+           pass
+
+    3. As an inline function with model as first argument:
+       lm = language_model_decorator("gpt-4")
+       # Then use: decorated_func = lm(my_function)
+
+    4. As an inline function with all parameters:
+       lm = language_model_decorator(model="gpt-4", temperature=0.7)
+       # Then use: decorated_func = lm(my_function)
+    """
+    # Handle different calling patterns
+    if callable(fn):
+        # Case: @language_model_decorator (no parentheses)
+        func = fn
+        actual_model = model or "openai/gpt-4o-mini"
+        return _create_language_model_wrapper(
+            func,
+            actual_model,
+            instructions,
+            mock_response,
+            output_type,
+            stream,
+            instructor_mode,
+            return_output,
+            timeout,
+            temperature,
+            top_p,
+            max_tokens,
+            presence_penalty,
+            frequency_penalty,
+            seed,
+            user,
+            response_format,
+            stop,
+            logit_bias,
+            logprobs,
+            top_logprobs,
+            thinking,
+            web_search_options,
+            tools,
+            tool_choice,
+            parallel_tool_calls,
+            functions,
+            function_call,
+            verbose,
+            debug,
+        )
+    elif isinstance(fn, str):
+        # Case: language_model_decorator("gpt-4") - first arg is model
+        actual_model = fn
+    else:
+        # Case: language_model_decorator() or language_model_decorator(model="gpt-4")
+        actual_model = model or "openai/gpt-4o-mini"
+
+    def decorator(func: Callable) -> Callable:
+        return _create_language_model_wrapper(
+            func,
+            actual_model,
+            instructions,
+            mock_response,
+            output_type,
+            stream,
+            instructor_mode,
+            return_output,
+            timeout,
+            temperature,
+            top_p,
+            max_tokens,
+            presence_penalty,
+            frequency_penalty,
+            seed,
+            user,
+            response_format,
+            stop,
+            logit_bias,
+            logprobs,
+            top_logprobs,
+            thinking,
+            web_search_options,
+            tools,
+            tool_choice,
+            parallel_tool_calls,
+            functions,
+            function_call,
+            verbose,
+            debug,
+        )
+
+    return decorator
+
+
+def _create_language_model_wrapper(
+    func: Callable,
+    model: Union["LanguageModel", "LanguageModelName"],
+    instructions: Optional[str],
+    mock_response: Optional[bool],
+    output_type: Optional[Type],
+    stream: Optional[bool],
+    instructor_mode: Optional["LanguageModelInstructorMode"],
+    return_output: bool,
+    timeout: Optional[Union[float, str, "Timeout"]],
+    temperature: Optional[float],
+    top_p: Optional[float],
+    max_tokens: Optional[int],
+    presence_penalty: Optional[float],
+    frequency_penalty: Optional[float],
+    seed: Optional[int],
+    user: Optional[str],
+    response_format: Optional[Dict[str, Any]],
+    stop: Optional[Union[str, List[str]]],
+    logit_bias: Optional[Dict[int, float]],
+    logprobs: Optional[bool],
+    top_logprobs: Optional[int],
+    thinking: Optional[Dict[str, Any]],
+    web_search_options: Optional[Dict[str, Any]],
+    tools: Optional[List[Any]],
+    tool_choice: Optional[Union[str, Dict[str, Any]]],
+    parallel_tool_calls: Optional[bool],
+    functions: Optional[List[Any]],
+    function_call: Optional[str],
+    verbose: bool,
+    debug: bool,
+) -> Callable:
+    """Helper function to create the actual language model wrapper."""
+    import inspect
+    import asyncio
+    from typing import get_type_hints
+
+    # Get function metadata
+    sig = inspect.signature(func)
+    type_hints = get_type_hints(func)
+    return_type = output_type or type_hints.get("return", str)
+    func_instructions = instructions or func.__doc__ or ""
+
+    # Check if function is async
+    is_async = asyncio.iscoroutinefunction(func)
+
+    if is_async:
+
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            # Convert function parameters to message string
+            bound_args = sig.bind(*args, **kwargs)
+            bound_args.apply_defaults()
+
+            # Create message from parameters
+            param_parts = []
+            for param_name, param_value in bound_args.arguments.items():
+                param_parts.append(f"{param_name}: {param_value}")
+            message = "\n".join(param_parts)
+
+            # Prepare parameters for language model call
+            lm_kwargs = {
+                "messages": message,
+                "instructions": func_instructions,
+                "model": model,
+                "mock_response": mock_response,
+                "stream": stream,
+                "instructor_mode": instructor_mode,
+                "timeout": timeout,
+                "temperature": temperature,
+                "top_p": top_p,
+                "max_tokens": max_tokens,
+                "presence_penalty": presence_penalty,
+                "frequency_penalty": frequency_penalty,
+                "seed": seed,
+                "user": user,
+                "response_format": response_format,
+                "stop": stop,
+                "logit_bias": logit_bias,
+                "logprobs": logprobs,
+                "top_logprobs": top_logprobs,
+                "thinking": thinking,
+                "web_search_options": web_search_options,
+                "tools": tools,
+                "tool_choice": tool_choice,
+                "parallel_tool_calls": parallel_tool_calls,
+                "functions": functions,
+                "function_call": function_call,
+            }
+
+            # Only add type parameter if it's not str (for structured output)
+            if return_type is not str:
+                lm_kwargs["type"] = return_type
+
+            # Run language model with extracted parameters
+            return await async_run_language_model(**lm_kwargs)
+
+        return async_wrapper
+    else:
+
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            # Convert function parameters to message string
+            bound_args = sig.bind(*args, **kwargs)
+            bound_args.apply_defaults()
+
+            # Create message from parameters
+            param_parts = []
+            for param_name, param_value in bound_args.arguments.items():
+                param_parts.append(f"{param_name}: {param_value}")
+            message = "\n".join(param_parts)
+
+            # Prepare parameters for language model call
+            lm_kwargs = {
+                "messages": message,
+                "instructions": func_instructions,
+                "model": model,
+                "mock_response": mock_response,
+                "stream": stream,
+                "instructor_mode": instructor_mode,
+                "timeout": timeout,
+                "temperature": temperature,
+                "top_p": top_p,
+                "max_tokens": max_tokens,
+                "presence_penalty": presence_penalty,
+                "frequency_penalty": frequency_penalty,
+                "seed": seed,
+                "user": user,
+                "response_format": response_format,
+                "stop": stop,
+                "logit_bias": logit_bias,
+                "logprobs": logprobs,
+                "top_logprobs": top_logprobs,
+                "thinking": thinking,
+                "web_search_options": web_search_options,
+                "tools": tools,
+                "tool_choice": tool_choice,
+                "parallel_tool_calls": parallel_tool_calls,
+                "functions": functions,
+                "function_call": function_call,
+            }
+
+            # Only add type parameter if it's not str (for structured output)
+            if return_type is not str:
+                lm_kwargs["type"] = return_type
+
+            # Run language model with extracted parameters
+            response = run_language_model(**lm_kwargs)
+
+            # Return just the output if return_output is True (default behavior)
+            if return_output:
+                return response.output
+            else:
+                return response
+
+        return sync_wrapper

hammad/genai/models/language/types/language_model_response.py

@@ -47,7 +47,7 @@ class LanguageModelResponse(BaseGenAIModelResponse[T]):
     In many cases with tool calling, message content is not present, in these cases
     this field will **NOT** represent tool calls, and will be returned as `None`."""
 
-    completion: "litellm.ModelResponse"
+    completion: Any
     """The raw Chat Completion (`litellm.ModelResponse`) object returned by the
     language model."""
 

hammad/genai/types/tools.py

@@ -75,7 +75,7 @@ def extract_tool_calls_from_response(
 ) -> List[Any]:
     """Extract tool calls from various response types."""
     # ensure type is of agent or language model
-    if response.type not in ["language_model", "agent"]:
+    if response.type not in ["language_model", "agent", "graph"]:
         raise ValueError(f"Response type {response.type} is not supported")
 
     # Handle LanguageModelResponse

hammad/logging/logger.py

@@ -534,6 +534,47 @@ class Logger:
 
         return JSONFormatter()
 
+    def setLevel(
+        self,
+        level: Union[LoggerLevelName, int],
+    ) -> None:
+        """Set the logging level."""
+        # Handle integer levels by converting to string names
+        if isinstance(level, int):
+            # Map standard logging levels to their names
+            int_to_name = {
+                _logging.DEBUG: "debug",
+                _logging.INFO: "info",
+                _logging.WARNING: "warning",
+                _logging.ERROR: "error",
+                _logging.CRITICAL: "critical",
+            }
+            level_str = int_to_name.get(level, "warning")
+        else:
+            level_str = level
+
+        self._user_level = level_str
+
+        # Standard level mapping
+        level_map = {
+            "debug": _logging.DEBUG,
+            "info": _logging.INFO,
+            "warning": _logging.WARNING,
+            "error": _logging.ERROR,
+            "critical": _logging.CRITICAL,
+        }
+
+        # Check custom levels first
+        if level_str.lower() in self._custom_levels:
+            log_level = self._custom_levels[level_str.lower()]
+        else:
+            log_level = level_map.get(level_str.lower(), _logging.WARNING)
+
+        # Set the integer level on the logger and handlers
+        self._logger.setLevel(log_level)
+        for handler in self._logger.handlers:
+            handler.setLevel(log_level)
+
     def add_level(
         self, name: str, value: int, style: Optional[LoggerLevelSettings] = None
     ) -> None:
@@ -570,9 +611,23 @@ class Logger:
         return self._user_level
 
     @level.setter
-    def level(self, value: str) -> None:
+    def level(self, value: Union[str, int]) -> None:
         """Set the logging level."""
-        self._user_level = value
+        # Handle integer levels by converting to string names
+        if isinstance(value, int):
+            # Map standard logging levels to their names
+            int_to_name = {
+                _logging.DEBUG: "debug",
+                _logging.INFO: "info",
+                _logging.WARNING: "warning",
+                _logging.ERROR: "error",
+                _logging.CRITICAL: "critical",
+            }
+            value_str = int_to_name.get(value, "warning")
+        else:
+            value_str = value
+
+        self._user_level = value_str
 
         # Standard level mapping
         level_map = {
@@ -584,10 +639,10 @@ class Logger:
         }
 
         # Check custom levels
-        if value.lower() in self._custom_levels:
-            log_level = self._custom_levels[value.lower()]
+        if value_str.lower() in self._custom_levels:
+            log_level = self._custom_levels[value_str.lower()]
         else:
-            log_level = level_map.get(value.lower(), _logging.WARNING)
+            log_level = level_map.get(value_str.lower(), _logging.WARNING)
 
         # Update logger level
         self._logger.setLevel(log_level)

hammad/mcp/__init__.py

@@ -6,6 +6,7 @@ from typing import TYPE_CHECKING
 from .._internal import create_getattr_importer
 
 if TYPE_CHECKING:
+    from mcp.server.fastmcp import FastMCP
     from .client.client import (
         convert_mcp_tool_to_openai_tool,
         MCPClient,
@@ -26,6 +27,8 @@ if TYPE_CHECKING:
 
 
 __all__ = (
+    # fastmcp
+    "FastMCP",
     # hammad.mcp.client
     "MCPClient",
     "MCPClientService",