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

hammad/__init__.py

@@ -9,290 +9,71 @@ from ._internal import create_getattr_importer as __hammad_importer__
 
 
 if TYPE_CHECKING:
-    # BUILTINS | hammad.cli
-    from .cli import print, input, animate
-
-    # 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,
-        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
+    from . import types
 
-    # hammad.genai
-    from .genai.graphs import (
+    # 'builtins'
+    from .cache import cached
+    from .cli import print, input, animate
+    from .genai import (
         BaseGraph,
-        GraphResponse,
-        GraphStream,
-        GraphResponseChunk,
-        GraphBuilder,
-        action,
         plugin,
+        action,
+        select,
+        agent_decorator as agent,
+        language_model_decorator as llm,
+        run_embedding_model as embedding,
+        define_tool as tool,
     )
-    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 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,
-    )
-
-    # hammad.runtime
-    from .runtime import (
-        run_parallel,
-        run_sequentially,
-        run_with_retry,
-        parallelize_function,
-        sequentialize_function,
+    from .data.collections import create_collection as collection
+    from .formatting.text import convert_to_text as markdown
+    from .mcp import launch_mcp_servers
+    from .logging import create_logger as logger
+    from .service import serve, serve_mcp
+    from .web import (
+        run_web_search as web_search,
+        run_web_request as web_request,
     )
 
-    # 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,
+    from ._main import (
+        to,
+        run,
+        fn,
+        new,
+        read,
+        settings,
     )
 
 
 __all__ = (
-    # hammad.cli
+    # types
+    "types",
+    # -- 'builtins'
+    "cached",
     "print",
-    "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",
+    "input",
+    "llm",
+    "agent",
+    "embedding",
+    "tool",
+    "markdown",
+    "launch_mcp_servers",
     "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",
+    "select",
+    "BaseGraph",
+    "collection",
+    "logger",
     "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",
+    "web_search",
+    "web_request",
+    "to",
+    "run",
+    "fn",
+    "new",
+    "read",
+    "settings",
 )
 
 

hammad/_main.py

@@ -0,0 +1,226 @@
+"""hammad._main"""
+
+
+class to:
+    """Namespace for converters that can be used to convert objects to various formats.
+
+    The `to` class provides a collection of converters that can be used to convert objects
+    to various formats, such as pydantic models, text, markdown, json, and more.
+    """
+
+    # ! CONVERTERS
+    from .data import (
+        convert_to_pydantic_field as pydantic_field,
+        convert_to_pydantic_model as pydantic_model,
+    )
+    from .data.types import (
+        convert_to_base_text as text,
+        convert_to_simple_text as simple_text,
+        convert_to_code_section as code_section,
+        convert_to_schema_section as schema_section,
+        convert_to_output_instructions as output_instructions,
+    )
+    from .formatting.json import (
+        convert_to_json_schema as json_schema,
+    )
+    from .formatting.text import (
+        convert_to_text as markdown,
+    )
+
+
+class fn:
+    """Namespace for decorators that can be used to modify functions, methods, and classes.
+
+    The `fn` class provides a collection of decorators that can be used to modify functions,
+    methods, and classes in various ways, such as caching results, tracing function calls,
+    and validating input parameters.
+    """
+
+    # ! DECORATORS
+    from .cache import cached, auto_cached
+    from .logging import trace, trace_cls, trace_function, trace_http
+    from .data.models import validator
+    from .runtime import (
+        sequentialize_function as sequentialize,
+        parallelize_function as parallelize,
+        run_with_retry as retry,
+    )
+    from .service import serve, serve_mcp
+
+
+class new:
+    """Namespace for factory functions that create new objects, models, services, and clients.
+
+    The `new` class provides convenient access to a variety of factory functions for creating
+    commonly used objects in the hammad ecosystem, such as caches, collections, databases,
+    models, loggers, agents, services, and web clients.
+
+    Example usage:
+        cache = new.cache(...)
+        collection = new.collection(...)
+        model = new.model(...)
+        logger = new.logger(...)
+        agent = new.agent(...)
+        service = new.service(...)
+        http_client = new.http_client(...)
+    """
+
+    # ! FACTORIES
+    from .cache import (
+        create_cache as cache,
+    )
+    from .data import (
+        create_collection as collection,
+        create_database as database,
+        create_model as model,
+    )
+    from .logging import create_logger as logger
+    from .genai import (
+        create_agent as agent,
+        create_embedding_model as embedding_model,
+        create_language_model as language_model,
+    )
+    from .service import (
+        create_service as service,
+        async_create_service as async_service,
+    )
+    from .mcp import (
+        MCPClient as mcp_client,
+    )
+    from .web import (
+        create_http_client as http_client,
+        create_openapi_client as openapi_client,
+        create_search_client as search_client,
+    )
+
+
+class run:
+    """Centeral namespace for 'one-off' runners, or functions that can be
+    executed directly, and standalone."""
+
+    # ! RUNNERS
+    from .genai import (
+        run_agent as agent,
+        run_agent_iter as agent_iter,
+        run_embedding_model as embedding_model,
+        run_image_edit_model as image_edit_model,
+        run_image_generation_model as image_generation_model,
+        run_image_variation_model as image_variation_model,
+        run_language_model as language_model,
+        run_reranking_model as reranking_model,
+        run_transcription_model as transcription_model,
+        run_tts_model as text_to_speech_model,
+    )
+    from .mcp import (
+        launch_mcp_servers as mcp_servers,
+    )
+    from .web import (
+        run_news_search as news_search,
+        run_web_search as web_search,
+        run_web_request as web_request,
+    )
+
+
+class read:
+    """Namespace for various resource, URL or other file-type readers."""
+
+    from .data.configurations import (
+        read_configuration_from_dotenv as configuration_from_dotenv,
+        read_configuration_from_file as configuration_from_file,
+        read_configuration_from_url as configuration_from_url,
+        read_configuration_from_os_prefix as configuration_from_os_prefix,
+        read_configuration_from_os_vars as configuration_from_os_vars,
+    )
+    from .data.types import (
+        read_file_from_bytes as file_from_bytes,
+        read_file_from_path as file_from_path,
+        read_file_from_url as file_from_url,
+        read_audio_from_path as audio_from_path,
+        read_audio_from_url as audio_from_url,
+        read_image_from_path as image_from_path,
+        read_image_from_url as image_from_url,
+    )
+    from .web import (
+        read_web_page as web_page,
+        read_web_pages as web_pages,
+        extract_web_page_links as extract_links,
+    )
+
+
+class settings:
+    """Namespace class for all settings definitions within the ecosystem. This is an
+    easy way to find the configuration settings for the component you are intending
+    to use."""
+
+    # NOTE:
+    # these are attached to the 'core/builtin' extensions imported at the very top
+    # hence the weird very very literal names
+    from .cli import (
+        CLIStyleLiveSettings as live,
+        CLIStyleBackgroundSettings as bg,
+        CLIStyleRenderableSettings as style,
+    )
+
+    from .data import (
+        QdrantCollectionIndexSettings as qdrant,
+        QdrantCollectionIndexQuerySettings as qdrant_query,
+        TantivyCollectionIndexSettings as tantivy,
+        TantivyCollectionIndexQuerySettings as tantivy_query,
+    )
+    from .logging.logger import LoggerLevelSettings as logger_level
+    from .genai import (
+        AgentSettings as agent,
+        LanguageModelSettings as language_model,
+        EmbeddingModelSettings as embedding_model,
+    )
+    from .mcp import (
+        MCPClientSseSettings as mcp_client_sse,
+        MCPClientStdioSettings as mcp_client_stdio,
+        MCPClientStreamableHttpSettings as mcp_client_streamable_http,
+        MCPServerSseSettings as mcp_server_sse,
+        MCPServerStdioSettings as mcp_server_stdio,
+        MCPServerStreamableHttpSettings as mcp_server_streamable_http,
+    )
+
+
+__all__ = (
+    # hammad.cache
+    "cached",
+    # hammad.cli
+    "print",
+    "input",
+    "animate",
+    # hammad.logging
+    "logger",
+    # hammad.genai
+    "BaseGraph",
+    "plugin",
+    "action",
+    "agent",
+    "llm",
+    "tool",
+    # hammad.data.collections
+    "collection",
+    # hammad.formatting.text
+    "markdown",
+    # hammad.mcp
+    "launch_mcp_servers",
+    # hammad.service
+    "serve",
+    "serve_mcp",
+    # hammad.web
+    "web_search",
+    "web_request",
+    # hammad.to
+    "to",
+    # hammad.fn
+    "fn",
+    # hammad.new
+    "new",
+    # hammad.run
+    "run",
+    # hammad.read
+    "read",
+    # hammad.settings
+    "settings",
+)

hammad/cli/__init__.py

@@ -8,7 +8,6 @@ from .._internal import create_getattr_importer
 
 if TYPE_CHECKING:
     from .plugins import print, input, animate
-    from ._runner import CLIRunner
     from .styles.settings import (
         CLIStyleRenderableSettings,
         CLIStyleBackgroundSettings,
@@ -20,7 +19,6 @@ __all__ = (
     "print",
     "input",
     "animate",
-    "CLIRunner",
     "CLIStyleRenderableSettings",
     "CLIStyleBackgroundSettings",
     "CLIStyleLiveSettings",

hammad/data/__init__.py

@@ -19,6 +19,7 @@ if TYPE_CHECKING:
         convert_to_pydantic_field,
         is_pydantic_model_class,
     )
+    from .models.utils import create_model
     from .collections import (
         Collection,
         create_collection,
@@ -29,11 +30,7 @@ if TYPE_CHECKING:
         QdrantCollectionIndexSettings,
         QdrantCollectionIndexQuerySettings,
     )
-    from .sql import (
-        DatabaseItemType,
-        DatabaseItem,
-        Database,
-    )
+    from .sql import DatabaseItemType, DatabaseItem, Database, create_database
     from .configurations import (
         Configuration,
         read_configuration_from_file,
@@ -58,6 +55,7 @@ __all__ = (
     "convert_to_pydantic_model",
     "convert_to_pydantic_field",
     "is_pydantic_model_class",
+    "create_model",
     # hammad.data.collections
     "Collection",
     "create_collection",
@@ -71,6 +69,7 @@ __all__ = (
     "DatabaseItemType",
     "DatabaseItem",
     "Database",
+    "create_database",
     # hammad.data.configurations
     "Configuration",
     "read_configuration_from_file",

hammad/data/types/__init__.py

@@ -12,11 +12,30 @@ if TYPE_CHECKING:
     from .text import (
         BaseText,
         Text,
+        SimpleText,
+        CodeSection,
+        SchemaSection,
+        OutputText,
+        convert_to_simple_text,
+        convert_to_output_text,
+        convert_to_output_instructions,
+        convert_to_code_section,
+        convert_to_schema_section,
+        convert_to_base_text,
+    )
+    from .file import (
+        File,
+        read_file_from_bytes,
+        read_file_from_path,
+        read_file_from_url,
     )
-    from .file import File
     from .multimodal import (
         Audio,
         Image,
+        read_audio_from_path,
+        read_audio_from_url,
+        read_image_from_path,
+        read_image_from_url,
     )
 
 
@@ -24,11 +43,28 @@ __all__ = (
     # hammad.data.types.text
     "BaseText",
     "Text",
+    "SimpleText",
+    "CodeSection",
+    "SchemaSection",
+    "OutputText",
+    "convert_to_simple_text",
+    "convert_to_output_text",
+    "convert_to_output_instructions",
+    "convert_to_code_section",
+    "convert_to_schema_section",
+    "convert_to_base_text",
     # hammad.data.types.file
     "File",
+    "read_file_from_bytes",
+    "read_file_from_path",
+    "read_file_from_url",
     # hammad.data.types.multimodal
     "Audio",
     "Image",
+    "read_audio_from_path",
+    "read_audio_from_url",
+    "read_image_from_path",
+    "read_image_from_url",
 )