hammad-python 0.0.24__tar.gz → 0.0.26__tar.gz

{hammad_python-0.0.24 → hammad_python-0.0.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hammad-python
-Version: 0.0.24
+Version: 0.0.26
 Author-email: Hammad Saeed <hammadaidev@gmail.com>
 License: MIT License
         
@@ -26,6 +26,7 @@ License: MIT License
 License-File: LICENSE
 Requires-Python: >=3.11
 Requires-Dist: ddgs>=9.0.0
+Requires-Dist: fasta2a>=0.5.0
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: msgspec>=0.19.0
 Requires-Dist: nest-asyncio>=1.6.0

hammad_python-0.0.26/hammad/__init__.py

@@ -0,0 +1,84 @@
+"""hammad-python
+
+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:
+    from . import types
+
+    # 'builtins'
+    from .cache import cached
+    from .cli import print, input, animate
+    from .genai import (
+        BaseGraph,
+        plugin,
+        action,
+        select,
+        agent_decorator as agent,
+        language_model_decorator as llm,
+        run_embedding_model as embedding,
+        define_tool as tool,
+    )
+    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,
+    )
+
+    from ._main import (
+        to,
+        run,
+        fn,
+        new,
+        read,
+        settings,
+    )
+
+
+__all__ = (
+    # types
+    "types",
+    # -- 'builtins'
+    "cached",
+    "print",
+    "animate",
+    "input",
+    "llm",
+    "agent",
+    "embedding",
+    "tool",
+    "markdown",
+    "launch_mcp_servers",
+    "action",
+    "plugin",
+    "select",
+    "BaseGraph",
+    "collection",
+    "logger",
+    "serve",
+    "serve_mcp",
+    "web_search",
+    "web_request",
+    "to",
+    "run",
+    "fn",
+    "new",
+    "read",
+    "settings",
+)
+
+
+__getattr__ = __hammad_importer__(__all__)
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

hammad_python-0.0.26/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_python-0.0.24 → hammad_python-0.0.26}/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_python-0.0.24 → hammad_python-0.0.26}/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_python-0.0.26/hammad/data/types/__init__.py

@@ -0,0 +1,75 @@
+"""hammad.data.types
+
+Contains functional alias, or model-like objects that are meant to be used
+by users as bases as well as for type hints. These objects define simple
+interfaces for various types of common objects."""
+
+from typing import TYPE_CHECKING
+from ..._internal import create_getattr_importer
+
+
+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 .multimodal import (
+        Audio,
+        Image,
+        read_audio_from_path,
+        read_audio_from_url,
+        read_image_from_path,
+        read_image_from_url,
+    )
+
+
+__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",
+)
+
+
+__getattr__ = create_getattr_importer(__all__)
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

{hammad_python-0.0.24 → hammad_python-0.0.26}/hammad/data/types/file.py

@@ -9,7 +9,13 @@ from urllib.parse import urlparse
 from ..models.model import Model
 from ..models.fields import field
 
-__all__ = ("File", "FileSource")
+__all__ = (
+    "File",
+    "FileSource",
+    "read_file_from_path",
+    "read_file_from_url",
+    "read_file_from_bytes",
+)
 
 
 _FILE_SIGNATURES = {
@@ -356,3 +362,70 @@ class File(Model, kw_only=True, dict=True):
                 path=Path(name) if name else None,
             ),
         )
+
+
+def read_file_from_path(
+    path: str | Path,
+    *,
+    encoding: str | None = None,
+) -> File:
+    """Read a file from a filesystem path.
+
+    Args:
+        path: The path to the file to read.
+        encoding: Optional text encoding to use when reading the file.
+                 If not provided, will attempt to detect automatically.
+
+    Returns:
+        A File instance containing the file data.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        PermissionError: If the file cannot be read due to permissions.
+        IsADirectoryError: If the path points to a directory.
+    """
+    return File.from_path(path, encoding=encoding)
+
+
+def read_file_from_url(
+    url: str,
+    *,
+    encoding: str | None = None,
+    timeout: float = 30.0,
+) -> File:
+    """Read a file from a URL.
+
+    Args:
+        url: The URL to fetch the file from.
+        encoding: Optional text encoding to use when reading the response.
+                 If not provided, will attempt to detect automatically.
+        timeout: Request timeout in seconds. Defaults to 30.0.
+
+    Returns:
+        A File instance containing the downloaded data.
+
+    Raises:
+        httpx.RequestError: If the request fails.
+        httpx.HTTPStatusError: If the response has an error status code.
+    """
+    return File.from_url(url, encoding=encoding, timeout=timeout)
+
+
+def read_file_from_bytes(
+    data: bytes,
+    *,
+    type: str | None = None,
+    name: str | None = None,
+) -> File:
+    """Create a file from raw bytes data.
+
+    Args:
+        data: The bytes data to create the file from.
+        type: Optional MIME type of the data. If not provided,
+              will attempt to detect from content signatures.
+        name: Optional name for the file data.
+
+    Returns:
+        A File instance containing the bytes data.
+    """
+    return File.from_bytes(data, type=type, name=name)

{hammad_python-0.0.24 → hammad_python-0.0.26}/hammad/data/types/multimodal/__init__.py

@@ -7,13 +7,25 @@ from typing import TYPE_CHECKING
 from ...._internal import create_getattr_importer
 
 if TYPE_CHECKING:
-    from .image import Image
-    from .audio import Audio
+    from .image import (
+        Image,
+        read_image_from_path,
+        read_image_from_url,
+    )
+    from .audio import (
+        Audio,
+        read_audio_from_path,
+        read_audio_from_url,
+    )
 
 
 __all__ = (
     "Image",
     "Audio",
+    "read_audio_from_path",
+    "read_audio_from_url",
+    "read_image_from_path",
+    "read_image_from_url",
 )
 
 

{hammad_python-0.0.24 → hammad_python-0.0.26}/hammad/data/types/multimodal/audio.py

@@ -1,12 +1,19 @@
 """hammad.data.types.multimodal.audio"""
 
 import httpx
+import mimetypes
+from pathlib import Path
 from typing import Self
 
-from ...types.file import File, FileSource
+from ...types.file import File, FileSource, _FILE_SIGNATURES
 from ...models.fields import field
 
-__all__ = ("Audio",)
+
+__all__ = (
+    "Audio",
+    "read_audio_from_path",
+    "read_audio_from_url",
+)
 
 
 class Audio(File):
@@ -94,3 +101,100 @@ class Audio(File):
                 size=size,
             ),
         )
+
+    @classmethod
+    def from_path(
+        cls,
+        path: str | Path,
+    ) -> Self:
+        """Create an audio file from a file path.
+
+        Args:
+            path: The path to the audio file.
+
+        Returns:
+            A new Audio instance.
+
+        Raises:
+            FileNotFoundError: If the file does not exist.
+            ValueError: If the file is not a valid audio file.
+        """
+        path_obj = Path(path)
+
+        if not path_obj.exists():
+            raise FileNotFoundError(f"Audio file not found: {path}")
+
+        if not path_obj.is_file():
+            raise ValueError(f"Path is not a file: {path}")
+
+        # Read file data
+        data = path_obj.read_bytes()
+
+        # Determine MIME type
+        type = None
+
+        # Check file signature first
+        for signature, mime_type in _FILE_SIGNATURES.items():
+            if data.startswith(signature) and mime_type.startswith("audio/"):
+                type = mime_type
+                break
+
+        # Fall back to mimetypes module
+        if not type:
+            type, _ = mimetypes.guess_type(str(path))
+
+        # Validate it's an audio file
+        if type and not type.startswith("audio/"):
+            raise ValueError(f"File is not an audio file: {type}")
+
+        return cls(
+            data=data,
+            type=type,
+            source=FileSource(
+                is_file=True,
+                path=path_obj,
+                size=len(data),
+            ),
+        )
+
+
+def read_audio_from_url(
+    url: str,
+    *,
+    lazy: bool = True,
+    timeout: float = 30.0,
+) -> Audio:
+    """Download and create an audio file from a URL.
+
+    Args:
+        url: The URL to download from.
+        lazy: If True, defer loading content until needed.
+        timeout: Request timeout in seconds.
+
+    Returns:
+        A new Audio instance.
+
+    Raises:
+        httpx.RequestError: If the request fails.
+        httpx.HTTPStatusError: If the response has an error status code.
+        ValueError: If the URL does not point to an audio file.
+    """
+    return Audio.from_url(url, lazy=lazy, timeout=timeout)
+
+
+def read_audio_from_path(
+    path: str | Path,
+) -> Audio:
+    """Create an audio file from a file path.
+
+    Args:
+        path: The path to the audio file.
+
+    Returns:
+        A new Audio instance.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        ValueError: If the file is not a valid audio file.
+    """
+    return Audio.from_path(path)