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

hammad/__init__.py

@@ -1,50 +1,303 @@
-"""hammad-python"""
+"""hammad-python
 
-from __future__ import annotations
+A vast ecosystem of ('nightly', dont trust literally any interface to stay the same
+for more than a few days) resources, utilities and components for building applications
+in Python."""
 
 from typing import TYPE_CHECKING
 from ._internal import create_getattr_importer as __hammad_importer__
 
+
 if TYPE_CHECKING:
-    # hammad.cache
-    from .cache import cached, Cache
+    # BUILTINS | hammad.cli
+    from .cli import print, input, animate
 
-    # hammad.cli
-    from .cli import print, animate, input
+    # hammad.cache
+    from .cache import Cache, create_cache, cached, auto_cached
 
     # hammad.formatting
     from .formatting.json import convert_to_json_schema
-    from .formatting.text import convert_to_text, convert_type_to_text
+    from .formatting.text import (
+        convert_to_text,
+        convert_type_to_text,
+        convert_docstring_to_text,
+    )
+
+    # hammad.data
+    from .data.configurations import (
+        Configuration,
+        read_configuration_from_os_vars,
+        read_configuration_from_file,
+        read_configuration_from_url,
+    )
+    from .data.collections import Collection, create_collection
+    from .data.sql import (
+        Database as SQLDatabase,
+        create_database as create_sql_database,
+    )
+    from .data.models import (
+        Model,
+        field,
+        validator,
+        convert_to_pydantic_field,
+        convert_to_pydantic_model,
+        is_pydantic_model_class,
+    )
+    from .data.types import Text, BaseText, Audio, Image, File
+
+    # hammad.genai
+    from .genai.graphs import (
+        BaseGraph,
+        GraphResponse,
+        GraphStream,
+        GraphResponseChunk,
+        GraphBuilder,
+        action,
+        plugin,
+    )
+    from .genai.agents import (
+        Agent,
+        AgentResponse,
+        AgentResponseChunk,
+        AgentStream,
+        create_agent,
+        run_agent,
+        run_agent_iter,
+        async_run_agent,
+        async_run_agent_iter,
+    )
+    from .genai.models.embeddings import (
+        Embedding,
+        EmbeddingModel,
+        EmbeddingModelResponse,
+        EmbeddingModelSettings,
+        create_embedding_model,
+        run_embedding_model,
+        async_run_embedding_model,
+    )
+    from .genai.models.language import (
+        LanguageModel,
+        LanguageModelRequest,
+        LanguageModelResponse,
+        LanguageModelResponseChunk,
+        LanguageModelStream,
+        LanguageModelSettings,
+        create_language_model,
+        run_language_model,
+        async_run_language_model,
+    )
+    from .genai.models.multimodal import (
+        run_image_edit_model,
+        run_image_generation_model,
+        run_image_variation_model,
+        run_transcription_model,
+        run_tts_model,
+        async_run_image_edit_model,
+        async_run_image_generation_model,
+        async_run_image_variation_model,
+        async_run_transcription_model,
+        async_run_tts_model,
+    )
+    from .genai.models.reranking import run_reranking_model, async_run_reranking_model
+    from .genai.types.tools import define_tool, Tool
+    from .genai.types.history import History
 
     # hammad.logging
-    from .logging.logger import Logger, create_logger
-    from .logging.decorators import trace, trace_cls, trace_function, trace_http
+    from .logging import (
+        Logger,
+        create_logger,
+        create_logger_level,
+        trace,
+        trace_cls,
+        trace_function,
+        trace_http,
+    )
 
+    # hammad.mcp
+    from .mcp import (
+        MCPClient,
+        MCPClientSseSettings,
+        MCPClientStdioSettings,
+        MCPClientStreamableHttpSettings,
+        MCPServerSseSettings,
+        MCPServerStdioSettings,
+        MCPServerStreamableHttpSettings,
+        launch_mcp_servers,
+        convert_mcp_tool_to_openai_tool,
+    )
 
-__all__ = [
-    # hammad.cache
-    "cached",
-    "Cache",
+    # hammad.runtime
+    from .runtime import (
+        run_parallel,
+        run_sequentially,
+        run_with_retry,
+        parallelize_function,
+        sequentialize_function,
+    )
+
+    # hammad.service
+    from .service import create_service, async_create_service, serve, serve_mcp
+
+    # hammad.web
+    from .web import (
+        HttpClient,
+        AsyncHttpClient,
+        OpenAPIClient,
+        AsyncOpenAPIClient,
+        SearchClient,
+        AsyncSearchClient,
+        create_http_client,
+        create_openapi_client,
+        create_search_client,
+        run_web_search,
+        run_news_search,
+        run_web_request,
+        read_web_page,
+        read_web_pages,
+        extract_web_page_links,
+    )
+
+
+__all__ = (
     # hammad.cli
     "print",
-    "animate",
     "input",
+    "animate",
+    # hammad.cache
+    "Cache",
+    "create_cache",
+    "cached",
+    "auto_cached",
     # hammad.formatting
     "convert_to_json_schema",
     "convert_to_text",
     "convert_type_to_text",
+    "convert_docstring_to_text",
+    # hammad.data
+    "Configuration",
+    "read_configuration_from_os_vars",
+    "read_configuration_from_file",
+    "read_configuration_from_url",
+    "Collection",
+    "create_collection",
+    "SQLDatabase",
+    "create_sql_database",
+    "Model",
+    "field",
+    "validator",
+    "convert_to_pydantic_field",
+    "convert_to_pydantic_model",
+    "is_pydantic_model_class",
+    "Text",
+    "BaseText",
+    "Audio",
+    "Image",
+    "File",
+    # hammad.genai
+    "BaseGraph",
+    "GraphResponse",
+    "GraphStream",
+    "GraphResponseChunk",
+    "GraphBuilder",
+    "action",
+    "plugin",
+    # hammad.genai.agents
+    "Agent",
+    "AgentResponse",
+    "AgentResponseChunk",
+    "AgentStream",
+    "create_agent",
+    "run_agent",
+    "run_agent_iter",
+    "async_run_agent",
+    "async_run_agent_iter",
+    # hammad.genai.models.embeddings
+    "Embedding",
+    "EmbeddingModel",
+    "EmbeddingModelResponse",
+    "EmbeddingModelSettings",
+    "create_embedding_model",
+    "run_embedding_model",
+    "async_run_embedding_model",
+    # hammad.genai.models.language
+    "LanguageModel",
+    "LanguageModelRequest",
+    "LanguageModelResponse",
+    "LanguageModelResponseChunk",
+    "LanguageModelStream",
+    "LanguageModelSettings",
+    "create_language_model",
+    "run_language_model",
+    "async_run_language_model",
+    # hammad.genai.models.multimodal
+    "run_image_edit_model",
+    "run_image_generation_model",
+    "run_image_variation_model",
+    "run_transcription_model",
+    "run_tts_model",
+    "async_run_image_edit_model",
+    "async_run_image_generation_model",
+    "async_run_image_variation_model",
+    "async_run_transcription_model",
+    "async_run_tts_model",
+    # hammad.genai.models.reranking
+    "run_reranking_model",
+    "async_run_reranking_model",
+    # hammad.genai.types.tools
+    "define_tool",
+    "Tool",
+    # hammad.genai.types.history
+    "History",
     # hammad.logging
     "Logger",
     "create_logger",
+    "create_logger_level",
     "trace",
     "trace_cls",
     "trace_function",
     "trace_http",
-]
+    # hammad.mcp
+    "MCPClient",
+    "MCPClientSseSettings",
+    "MCPClientStdioSettings",
+    "MCPClientStreamableHttpSettings",
+    "MCPServerSseSettings",
+    "MCPServerStdioSettings",
+    "MCPServerStreamableHttpSettings",
+    "launch_mcp_servers",
+    "convert_mcp_tool_to_openai_tool",
+    # hammad.runtime
+    "run_parallel",
+    "run_sequentially",
+    "run_with_retry",
+    "parallelize_function",
+    "sequentialize_function",
+    # hammad.service
+    "create_service",
+    "async_create_service",
+    "serve",
+    "serve_mcp",
+    # hammad.web
+    "HttpClient",
+    "AsyncHttpClient",
+    "OpenAPIClient",
+    "AsyncOpenAPIClient",
+    "SearchClient",
+    "AsyncSearchClient",
+    "create_http_client",
+    "create_openapi_client",
+    "create_search_client",
+    "run_web_search",
+    "run_news_search",
+    "run_web_request",
+    "read_web_page",
+    "read_web_pages",
+    "extract_web_page_links",
+)
 
 
 __getattr__ = __hammad_importer__(__all__)
 
 
 def __dir__() -> list[str]:
-    return __all__
+    return list(__all__)

hammad/_internal.py

@@ -108,7 +108,25 @@ def _parse_type_checking_imports(source_code: str) -> dict[str, tuple[str, str]]
                     # Process imports in this block
                     for stmt in node.body:
                         if isinstance(stmt, ast.ImportFrom) and stmt.module:
-                            module_path = f".{stmt.module}"
+                            # Only add '.' prefix for relative imports
+                            # If stmt.level > 0, it's already a relative import
+                            # If stmt.level == 0 and module doesn't start with '.', it's absolute
+                            if stmt.level > 0:
+                                # Already relative import
+                                module_path = "." * stmt.level + (stmt.module or "")
+                            elif stmt.module.startswith("."):
+                                # Explicit relative import
+                                module_path = stmt.module
+                            elif any(
+                                stmt.module.startswith(name)
+                                for name in ["litellm", "openai", "instructor", "httpx"]
+                            ):
+                                # Known absolute third-party imports
+                                module_path = stmt.module
+                            else:
+                                # Default to relative import for internal modules
+                                module_path = f".{stmt.module}"
+
                             for alias in stmt.names:
                                 original_name = alias.name
                                 local_name = alias.asname or original_name

hammad/cli/plugins.py

@@ -734,7 +734,9 @@ def input(
 
 def animate(
     renderable: "RenderableType | str",
-    type: Literal["flashing", "pulsing", "shaking", "typing", "spinning", "rainbow"],
+    type: Literal[
+        "flashing", "pulsing", "shaking", "typing", "spinning", "rainbow"
+    ] = "pulsing",
     duration: Optional[float] = None,
     # Animation parameters (defaults are handled by the specific animation classes)
     speed: Optional[float] = None,

hammad/data/__init__.py

@@ -21,6 +21,7 @@ if TYPE_CHECKING:
     )
     from .collections import (
         Collection,
+        create_collection,
         TantivyCollectionIndex,
         QdrantCollectionIndex,
         TantivyCollectionIndexSettings,
@@ -54,8 +55,12 @@ __all__ = (
     "validator",
     "is_field",
     "is_model",
+    "convert_to_pydantic_model",
+    "convert_to_pydantic_field",
+    "is_pydantic_model_class",
     # hammad.data.collections
     "Collection",
+    "create_collection",
     "TantivyCollectionIndex",
     "QdrantCollectionIndex",
     "TantivyCollectionIndexSettings",
@@ -68,6 +73,11 @@ __all__ = (
     "Database",
     # hammad.data.configurations
     "Configuration",
+    "read_configuration_from_file",
+    "read_configuration_from_url",
+    "read_configuration_from_os_vars",
+    "read_configuration_from_os_prefix",
+    "read_configuration_from_dotenv",
 )
 
 

hammad/data/collections/__init__.py

@@ -4,7 +4,10 @@ from typing import TYPE_CHECKING
 from ..._internal import create_getattr_importer
 
 if TYPE_CHECKING:
-    from .collection import Collection
+    from .collection import (
+        Collection,
+        create_collection,
+    )
 
     from .indexes import (
         TantivyCollectionIndex,
@@ -25,6 +28,7 @@ if TYPE_CHECKING:
 __all__ = (
     # hammad.data.collections.collection
     "Collection",
+    "create_collection",
     # hammad.data.collections.indexes
     "TantivyCollectionIndex",
     "QdrantCollectionIndex",

hammad/data/sql/__init__.py

@@ -5,13 +5,14 @@ from ..._internal import create_getattr_importer
 
 if TYPE_CHECKING:
     from .types import DatabaseItemType, DatabaseItem
-    from .database import Database
+    from .database import Database, create_database
 
 
 __all__ = (
     "DatabaseItemType",
     "DatabaseItem",
     "Database",
+    "create_database",
 )
 
 

hammad/genai/__init__.py

@@ -13,6 +13,7 @@ if TYPE_CHECKING:
         AgentContext,
         AgentMessages,
         AgentResponseChunk,
+        create_agent,
     )
     from .agents.run import (
         run_agent,
@@ -20,6 +21,32 @@ if TYPE_CHECKING:
         async_run_agent,
         async_run_agent_iter,
     )
+    from .graphs import (
+        GraphBuilder,
+        GraphContext,
+        GraphEnd,
+        GraphEvent,
+        GraphHistoryEntry,
+        GraphNode,
+        GraphState,
+        GraphResponse,
+        GraphStream,
+        GraphResponseChunk,
+        BaseGraph,
+        BasePlugin,
+        PluginDecorator,
+        PydanticGraphContext,
+        AudioPlugin,
+        ServePlugin,
+        MemoryPlugin,
+        HistoryPlugin,
+        SettingsPlugin,
+        ActionNode,
+        ActionInfo,
+        ActionSettings,
+        action,
+        plugin,
+    )
     from .models.embeddings import (
         Embedding,
         EmbeddingModel,
@@ -27,6 +54,7 @@ if TYPE_CHECKING:
         EmbeddingModelSettings,
         run_embedding_model,
         async_run_embedding_model,
+        create_embedding_model,
     )
     from .models.language import (
         LanguageModel,
@@ -40,6 +68,7 @@ if TYPE_CHECKING:
         LanguageModelStream,
         run_language_model,
         async_run_language_model,
+        create_language_model,
     )
     from .models.reranking import run_reranking_model, async_run_reranking_model
     from .models.multimodal import (
@@ -78,11 +107,37 @@ __all__ = [
     "AgentContext",
     "AgentMessages",
     "AgentResponseChunk",
+    "create_agent",
     # hammad.genai.agents.run
     "run_agent",
     "run_agent_iter",
     "async_run_agent",
     "async_run_agent_iter",
+    # hammad.genai.graphs
+    "GraphBuilder",
+    "GraphContext",
+    "GraphEnd",
+    "GraphEvent",
+    "GraphHistoryEntry",
+    "GraphNode",
+    "GraphState",
+    "GraphResponse",
+    "GraphStream",
+    "GraphResponseChunk",
+    "BaseGraph",
+    "BasePlugin",
+    "PluginDecorator",
+    "PydanticGraphContext",
+    "AudioPlugin",
+    "ServePlugin",
+    "MemoryPlugin",
+    "HistoryPlugin",
+    "SettingsPlugin",
+    "ActionNode",
+    "ActionInfo",
+    "ActionSettings",
+    "action",
+    "plugin",
     # hammad.genai.models.embeddings
     "Embedding",
     "EmbeddingModel",
@@ -90,6 +145,7 @@ __all__ = [
     "EmbeddingModelSettings",
     "run_embedding_model",
     "async_run_embedding_model",
+    "create_embedding_model",
     # hammad.genai.models.language
     "LanguageModel",
     "LanguageModelInstructorMode",
@@ -102,6 +158,7 @@ __all__ = [
     "LanguageModelStream",
     "run_language_model",
     "async_run_language_model",
+    "create_language_model",
     # hammad.genai.models.reranking
     "run_reranking_model",
     "async_run_reranking_model",

hammad/genai/agents/__init__.py

@@ -5,7 +5,11 @@ from ..._internal import create_getattr_importer
 
 
 if TYPE_CHECKING:
-    from .agent import Agent
+    from .agent import (
+        Agent,
+        create_agent,
+    )
+    from .run import run_agent, run_agent_iter, async_run_agent, async_run_agent_iter
 
     # Types
     from .types.agent_context import AgentContext
@@ -22,6 +26,12 @@ if TYPE_CHECKING:
 __all__ = [
     # hammad.genai.agents.agent
     "Agent",
+    "create_agent",
+    # hammad.genai.agents.run
+    "run_agent",
+    "run_agent_iter",
+    "async_run_agent",
+    "async_run_agent_iter",
     # hammad.genai.agents.types.agent_context
     "AgentContext",
     # hammad.genai.agents.types.agent_event