hammad-python 0.0.14__py3-none-any.whl → 0.0.16__py3-none-any.whl

hammad/mcp/client/client.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 import asyncio
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Callable, Literal
+from typing import Any, Callable, Literal, overload
 import threading
 import concurrent.futures
 import inspect
@@ -20,9 +20,10 @@ try:
     )
     from openai.types.shared import FunctionDefinition as Function
 except ImportError:
-    raise ImportError(
-        "Using mcp requires the `openai` & `mcp` packages. Please install with: pip install 'hammad-python[ai]'"
-    )
+    CallToolResult = Any
+    MCPTool = Any
+    OpenAITool = Any
+    Function = Any
 
 from .client_service import (
     MCPClientService,
@@ -521,3 +522,103 @@ class MCPClient:
     async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
         """Async context manager exit."""
         await self.async_cleanup()
+
+
+# -----------------------------------------------------------------------------
+# Factory Function
+# -----------------------------------------------------------------------------
+
+
+@overload
+def create_mcp_client(
+    type: Literal["stdio"],
+    *,
+    command: str,
+    args: list[str] | None = None,
+    env: dict[str, str] | None = None,
+    cwd: Path | str | None = None,
+    timeout: float = 30.0,
+) -> MCPClient:
+    """Create an MCP client with stdio transport."""
+    ...
+
+
+@overload
+def create_mcp_client(
+    type: Literal["sse"],
+    *,
+    url: str,
+    timeout: float = 30.0,
+) -> MCPClient:
+    """Create an MCP client with SSE transport."""
+    ...
+
+
+@overload
+def create_mcp_client(
+    type: Literal["http"],
+    *,
+    url: str,
+    timeout: float = 30.0,
+) -> MCPClient:
+    """Create an MCP client with HTTP transport."""
+    ...
+
+
+def create_mcp_client(
+    type: Literal["stdio", "sse", "http"],
+    *,
+    command: str | None = None,
+    args: list[str] | None = None,
+    env: dict[str, str] | None = None,
+    cwd: Path | str | None = None,
+    url: str | None = None,
+    timeout: float = 30.0,
+) -> MCPClient:
+    """Create an MCP client with the specified transport type.
+    
+    Args:
+        service_type: The type of transport to use ("stdio", "sse", or "http").
+        command: Command to run for stdio transport.
+        args: Arguments for the command (stdio only).
+        env: Environment variables for the command (stdio only).
+        cwd: Working directory for the command (stdio only).
+        url: URL for SSE or HTTP transport.
+        timeout: Connection timeout in seconds.
+        
+    Returns:
+        A configured MCPClient instance.
+        
+    Raises:
+        ValueError: If required parameters for the transport type are missing.
+    """
+    service_type = type
+
+    if service_type == "stdio":
+        if command is None:
+            raise ValueError("command is required for stdio transport")
+        
+        service = MCPClientServiceStdio(
+            command=command,
+            args=args or [],
+            env=env or {},
+            cwd=Path(cwd) if cwd else None,
+        )
+        
+    elif service_type == "sse":
+        if url is None:
+            raise ValueError("url is required for SSE transport")
+        
+        service = MCPClientServiceSse(url=url)
+        
+    elif service_type == "http":
+        if url is None:
+            raise ValueError("url is required for HTTP transport")
+        
+        service = MCPClientServiceStreamableHttp(url=url)
+        
+    else:
+        raise ValueError(f"Unsupported service_type: {service_type}")
+    
+    settings = MCPClientSettings(timeout=timeout)
+    return MCPClient(service=service, settings=settings)

hammad/mcp/client/client_service.py

@@ -22,9 +22,16 @@ try:
     from mcp.shared.message import SessionMessage
     from mcp.types import CallToolResult, InitializeResult
 except ImportError:
-    raise ImportError(
-        "Using mcp requires the `openai` & `mcp` packages. Please install with: pip install 'hammad-python[ai]'"
-    )
+    MCPTool = Any
+    ClientSession = Any
+    StdioServerParameters = Any
+    stdio_client = Any
+    sse_client = Any
+    GetSessionIdCallback = Any
+    streamablehttp_client = Any
+    SessionMessage = Any
+    CallToolResult = Any
+    InitializeResult = Any
 
 import logging
 

hammad/mcp/servers/__init__.py

@@ -1 +1,25 @@
 """hammad.mcp.servers"""
+
+from typing import TYPE_CHECKING
+from ..._internal import create_getattr_importer
+
+if TYPE_CHECKING:
+    from .launcher import (
+        launch_mcp_servers,
+        MCPServerStdioSettings,
+        MCPServerSseSettings,
+        MCPServerStreamableHttpSettings,
+    )
+
+__all__ = (
+    "launch_mcp_servers",
+    "MCPServerStdioSettings",
+    "MCPServerSseSettings",
+    "MCPServerStreamableHttpSettings",
+)
+
+__getattr__ = create_getattr_importer(__all__)
+
+def __dir__() -> list[str]:
+    """Get the attributes of the servers module."""
+    return list(__all__)

hammad/{performance/runtime → runtime}/__init__.py

@@ -1,7 +1,7 @@
-"""hammad.performance.runtime"""
+"""hammad.lib.runtime"""
 
 from typing import TYPE_CHECKING
-from ..imports import create_getattr_importer
+from ..._internal import create_getattr_importer
 
 
 if TYPE_CHECKING:

hammad/{performance/runtime → runtime}/decorators.py

@@ -1,4 +1,4 @@
-"""hammad.performance.runtime.decorators"""
+"""hammad.runtime.decorators"""
 
 import functools
 from typing import (

hammad/{performance/runtime → runtime}/run.py

@@ -1,4 +1,4 @@
-"""hammad.performance.runtime.run"""
+"""hammad.runtime.run"""
 
 import concurrent.futures
 import itertools

hammad/service/__init__.py

@@ -21,7 +21,7 @@ resources within this submodule. This module contains function/decorators for:
 """
 
 from typing import TYPE_CHECKING
-from ..performance.imports import create_getattr_importer
+from .._internal import create_getattr_importer
 
 if TYPE_CHECKING:
     from .create import (

hammad/service/create.py

@@ -24,7 +24,6 @@ try:
     from fastapi import FastAPI, HTTPException
     from pydantic import BaseModel, create_model
     from uvicorn import Config, Server
-    import uvloop
 except ImportError as e:
     raise ImportError(
         "Service dependencies not installed. Install with: pip install hammad-python[serve]"
@@ -58,7 +57,7 @@ class ServiceConfig:
     timeout_graceful_shutdown: int = 30
     access_log: bool = True
     use_colors: bool = True
-    loop: str = "uvloop"
+    loop: str = "asyncio"
 
 
 class ServiceManager:
@@ -409,10 +408,6 @@ def create_service(
     if not auto_start:
         return app
 
-    # Set up uvloop if available
-    if hasattr(uvloop, "install"):
-        uvloop.install()
-
     # Create and configure server
     config_obj = Config(
         app=app,
@@ -424,7 +419,7 @@ def create_service(
         timeout_keep_alive=timeout_keep_alive,
         access_log=access_log,
         use_colors=use_colors,
-        loop="uvloop" if hasattr(uvloop, "install") else "asyncio",
+        loop="asyncio",
     )
 
     server = Server(config_obj)
@@ -502,7 +497,7 @@ async def async_create_service(
         timeout_keep_alive=timeout_keep_alive,
         access_log=access_log,
         use_colors=use_colors,
-        loop="uvloop" if hasattr(uvloop, "install") else "asyncio",
+        loop="asyncio",
     )
 
     server = Server(config_obj)

hammad/service/decorators.py

@@ -124,7 +124,7 @@ def serve(
 
 
 def serve_mcp(
-    func_or_funcs: Optional[Union[Callable, List[Callable]]] = None,
+    fn: Optional[Union[Callable, List[Callable]]] = None,
     *,
     # MCP Server configuration
     name: Optional[str] = None,
@@ -162,7 +162,7 @@ def serve_mcp(
     4. As a function with multiple functions: serve_mcp([func1, func2])
 
     Args:
-        func_or_funcs: Function or list of functions to serve
+        fn: Function or list of functions to serve
         name: MCP server name
         instructions: Server instructions
         transport: Transport type (stdio, sse, streamable-http)
@@ -270,16 +270,16 @@ def serve_mcp(
         return funcs
 
     # Handle different call patterns
-    if func_or_funcs is None:
+    if fn is None:
         # Called as @serve_mcp(...) - return decorator
         return decorator
-    elif callable(func_or_funcs):
+    elif callable(fn):
         # Called as @serve_mcp (no parentheses) or serve_mcp(single_func)
-        return decorator(func_or_funcs)
-    elif isinstance(func_or_funcs, list):
+        return decorator(fn)
+    elif isinstance(fn, list):
         # Called as serve_mcp([func1, func2, ...])
-        return handle_multiple_functions(func_or_funcs)
+        return handle_multiple_functions(fn)
     else:
         raise TypeError(
-            f"Expected callable or list of callables, got {type(func_or_funcs)}"
+            f"Expected callable or list of callables, got {type(fn)}"
         )

hammad/typing/__init__.py

@@ -6,6 +6,7 @@ core `typing` module, `typing_extensions`, `typing_inspect` and other
 resources."""
 
 from typing import Any, TYPE_CHECKING
+import inspect
 import typing_inspect as inspection
 
 try:
@@ -190,6 +191,7 @@ __all__ = (
     "get_last_origin",
     "get_generic_bases",
     "get_typed_dict_keys",
+    "is_function",
 )
 
 
@@ -202,6 +204,32 @@ class TypingError(Exception):
 # ------------------------------------------------------------------------
 
 
+def is_function(t: "Any") -> bool:
+    """Check if an object is a callable function.
+
+    This function identifies whether the given object is a callable function,
+    including regular functions, built-in functions, and methods, but excluding
+    classes and other callable objects that are not strictly functions.
+
+    Args:
+        t: The object to check. Can be a function, method, or any other type.
+
+    Returns:
+        True if the object is a function or method, False otherwise.
+
+    Example:
+        >>> def my_func():
+        ...     pass
+        >>> is_function(my_func)
+        True
+        >>> is_function(lambda x: x)
+        True
+        >>> is_function(str)
+        False
+    """
+    return inspect.isfunction(t) or inspect.ismethod(t)
+
+
 def is_pydantic_basemodel(t: "Any") -> bool:
     """Check if an object is a Pydantic BaseModel class or instance using duck typing.
 

hammad/web/__init__.py

@@ -1,14 +1,14 @@
 """hammad.web"""
 
 from typing import TYPE_CHECKING
-from ..performance.imports import create_getattr_importer
+from .._internal import create_getattr_importer
 
 if TYPE_CHECKING:
     from .utils import (
         run_web_request,
         read_web_page,
         read_web_pages,
-        search_web,
+        web_search,
         search_news,
         extract_page_links,
     )
@@ -20,7 +20,7 @@ __all__ = (
     "run_web_request",
     "read_web_page",
     "read_web_pages",
-    "search_web",
+    "web_search",
     "search_news",
     "extract_page_links",
     "AsyncHttpClient",

hammad/web/http/client.py

@@ -1,4 +1,4 @@
-"""hammad.web.http.client"""
+"""hammad.http.client"""
 
 from __future__ import annotations
 

hammad/web/models.py

@@ -6,7 +6,8 @@ Output models for web search and parsing functionality.
 from __future__ import annotations
 
 from typing import List, Dict, Any, Optional, Union
-from typing_extensions import TypedDict, NotRequired
+
+from pydantic import BaseModel, Field
 
 
 # -----------------------------------------------------------------------------
@@ -14,7 +15,7 @@ from typing_extensions import TypedDict, NotRequired
 # -----------------------------------------------------------------------------
 
 
-class SearchResult(TypedDict):
+class SearchResult(BaseModel):
     """DuckDuckGo web search result."""
 
     title: str
@@ -27,7 +28,7 @@ class SearchResult(TypedDict):
     """Description/snippet of the search result."""
 
 
-class NewsResult(TypedDict):
+class NewsResult(BaseModel):
     """DuckDuckGo news search result."""
 
     date: str
@@ -54,7 +55,7 @@ class NewsResult(TypedDict):
 # -----------------------------------------------------------------------------
 
 
-class LinkInfo(TypedDict):
+class LinkInfo(BaseModel):
     """Information about a link extracted from a web page."""
 
     href: str
@@ -64,7 +65,7 @@ class LinkInfo(TypedDict):
     """Text content of the link."""
 
 
-class ImageInfo(TypedDict):
+class ImageInfo(BaseModel):
     """Information about an image extracted from a web page."""
 
     src: str
@@ -77,7 +78,7 @@ class ImageInfo(TypedDict):
     """Title attribute of the image."""
 
 
-class SelectedElement(TypedDict):
+class SelectedElement(BaseModel):
     """Information about a selected element from CSS selector."""
 
     tag: str
@@ -93,7 +94,7 @@ class SelectedElement(TypedDict):
     """Attributes of the element."""
 
 
-class WebPageResult(TypedDict):
+class WebPageResult(BaseModel):
     """Result from parsing a single web page."""
 
     url: str
@@ -121,7 +122,7 @@ class WebPageResult(TypedDict):
     """List of elements matching the CSS selector."""
 
 
-class WebPageErrorResult(TypedDict):
+class WebPageErrorResult(BaseModel):
     """Result from a failed web page parsing attempt."""
 
     url: str
@@ -130,7 +131,7 @@ class WebPageErrorResult(TypedDict):
     error: str
     """Error message describing what went wrong."""
 
-    status_code: None
+    status_code: Optional[int]
     """Always None for error results."""
 
     content_type: str
@@ -157,7 +158,7 @@ class WebPageErrorResult(TypedDict):
 # -----------------------------------------------------------------------------
 
 
-class ExtractedLink(TypedDict):
+class ExtractedLink(BaseModel):
     """Information about a link extracted with classification."""
 
     href: str
@@ -181,7 +182,7 @@ class ExtractedLink(TypedDict):
 # -----------------------------------------------------------------------------
 
 
-class HttpResponse(TypedDict):
+class HttpResponse(BaseModel):
     """HTTP response from web requests."""
 
     status_code: int
@@ -199,10 +200,14 @@ class HttpResponse(TypedDict):
     elapsed: float
     """Time elapsed for the request in seconds."""
 
-    json: NotRequired[Optional[Dict[str, Any]]]
+    # NOTE: This is a workaround to avoid the issue with the `json` field
+    # might consider moving to dataclasses
+    json_data: Optional[Dict[str, Any]] = Field(
+        alias="json"
+    )
     """Parsed JSON content if Content-Type is JSON."""
 
-    text: NotRequired[str]
+    text: str
     """Text content if response is text-based."""
 
 
@@ -211,17 +216,44 @@ class HttpResponse(TypedDict):
 # -----------------------------------------------------------------------------
 
 
-WebPageResults = List[Union[WebPageResult, WebPageErrorResult]]
-"""Results from batch web page parsing operations."""
+class WebPageResults(BaseModel):
+    """Results from batch web page parsing operations."""
+
+    urls: List[str]
+    """URLs used for the web page parsing operations."""
+
+    results: List[Union[WebPageResult, WebPageErrorResult]]
+    """List of results from batch web page parsing operations."""
+
+
+class SearchResults(BaseModel):
+    """Results from web search operations."""
+
+    query: str
+    """Query used for the web search operations."""
 
-SearchResults = List[SearchResult]
-"""Results from web search operations."""
+    results: List[SearchResult]
+    """List of results from web search operations."""
 
-NewsResults = List[NewsResult]
-"""Results from news search operations."""
 
-ExtractedLinks = List[ExtractedLink]
-"""Results from link extraction operations."""
+class NewsResults(BaseModel):
+    """Results from news search operations."""
+
+    query: str
+    """Query used for the news search operations."""
+
+    results: List[NewsResult]
+    """List of results from news search operations."""
+
+
+class ExtractedLinks(BaseModel):
+    """Results from link extraction operations."""
+
+    url: str
+    """URL used for the link extraction operations."""
+
+    results: List[ExtractedLink]
+    """List of results from link extraction operations."""
 
 
 __all__ = (