hammad-python 0.0.24__py3-none-any.whl → 0.0.26__py3-none-any.whl

hammad/genai/graphs/types.py

@@ -29,7 +29,7 @@ from ..types.history import History
 from ..types.base import BaseGenAIModelStream
 
 if TYPE_CHECKING:
-    from .base import BaseGraph
+    from .base import BaseGraph, SelectionStrategy
 
 __all__ = [
     "GraphState",
@@ -68,7 +68,7 @@ class ActionSettings:
     start: bool = False
     terminates: bool = False
     xml: Optional[str] = None
-    next: Optional[Union[str, List[str]]] = None
+    next: Optional[Union[str, List[str], "SelectionStrategy"]] = None
     read_history: bool = False
     persist_history: bool = False
     condition: Optional[str] = None

hammad/genai/models/language/__init__.py

@@ -9,7 +9,11 @@ if TYPE_CHECKING:
         LanguageModel,
         create_language_model,
     )
-    from .run import run_language_model, async_run_language_model
+    from .run import (
+        run_language_model,
+        async_run_language_model,
+        language_model_decorator,
+    )
     from .types.language_model_instructor_mode import LanguageModelInstructorMode
     from .types.language_model_messages import LanguageModelMessages
     from .types.language_model_name import LanguageModelName
@@ -26,6 +30,7 @@ __all__ = [
     # hammad.genai.models.language.run
     "run_language_model",
     "async_run_language_model",
+    "language_model_decorator",
     # hammad.genai.models.language.types.language_model_instructor_mode
     "LanguageModelInstructorMode",
     # hammad.genai.models.language.types.language_model_messages

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",
 ]
 
 
@@ -568,3 +571,308 @@ async def async_run_language_model(
         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

@@ -13,6 +13,7 @@ from typing import (
 )
 
 from .....cache import cached
+from .....typing import get_type_description
 
 from ...model_provider import litellm
 from ....types.base import BaseGenAIModelResponse
@@ -210,6 +211,7 @@ class LanguageModelResponse(BaseGenAIModelResponse[T]):
             output += f"\n{self.completion}"
 
         output += f"\n\n>>> Model: {self.model}"
+        output += f"\n>>> Type: {get_type_description(type(self.output))}"
         output += f"\n>>> Tool Calls: {len(self.tool_calls) if self.tool_calls else 0}"
 
         return output

hammad/logging/logger.py

@@ -539,10 +539,41 @@ class Logger:
         level: Union[LoggerLevelName, int],
     ) -> None:
         """Set the logging level."""
-        self._user_level = level
-        self._logger.setLevel(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(level)
+            handler.setLevel(log_level)
 
     def add_level(
         self, name: str, value: int, style: Optional[LoggerLevelSettings] = None
@@ -580,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 = {
@@ -594,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",