hammad-python 0.0.11__py3-none-any.whl → 0.0.13__py3-none-any.whl

hammad/__init__.py

@@ -1,67 +1,180 @@
 """hammad-python
 
-A collection of rapid, opinionated, cookie-cutter like resources for
-Python applications and development."""
-
-# NOTE:
-# all resources imported to the top level are lazy loaded within their
-# respective modules.
-
-# `hammad.based`
-from .based import (
-    BasedModel,
-    basedfield,
-    based_validator,
-    create_basedmodel,
-)
-from .based.utils import install, is_basedfield, is_basedmodel
+```markdown
+## Happliy Accelerated Micro Modules (for) Application Development
+```
+"""
 
-# `hammad.cache`
-from .cache import cached, auto_cached, create_cache
+from typing import TYPE_CHECKING
+from ._core._utils._import_utils import _auto_create_getattr_loader
 
-# `hammad.cli`
-from .cli import input, print, animate
 
-# `hammad.data`
-from .data import create_collection, create_database
+if TYPE_CHECKING:
+    # hammad.ai
+    # NOTE:
+    # TO USE MODULES FROM THE `hammad.ai` EXTENSION,
+    # REQUIRES INSTALLATION OF THE `hammad-python[ai]` PACKAGE.
+    from .ai import (
+        create_completion,
+        async_create_completion,
+        create_embeddings,
+        async_create_embeddings,
+    )
 
-# `hammad.json`
-from .json import convert_to_json_schema
+    # hammad.base
+    from .base import Model, field, create_model, is_field, is_model, validator
 
-# `hammad.logging`
-from .logging import (
-    create_logger,
-    create_logger_level,
-    # NOTE: decorators
-    trace,
-    trace_cls,
-    trace_function,
-)
+    # hammad.cache
+    from .cache import Cache, cached, auto_cached, create_cache
 
-# `hammad.pydantic`
-from .pydantic import (
-    convert_to_pydantic_model,
-    convert_to_pydantic_field,
-    create_confirmation_pydantic_model,
-    create_selection_pydantic_model,
-)
+    # hammad.cli
+    from .cli import print, animate, input
 
-# `hammad.text`
-from .text import (
-    convert_docstring_to_text,
-    convert_to_text,
-    convert_type_to_text,
-)
+    # hammad.configuration
+    from .configuration import (
+        Configuration,
+        read_configuration_from_os_vars,
+        read_configuration_from_dotenv,
+        read_configuration_from_file,
+        read_configuration_from_url,
+        read_configuration_from_os_prefix,
+    )
+
+    # hammad.data
+    from .data import Collection, Database, create_collection, create_database
+
+    # hammad.json
+    from .json import encode_json, decode_json, convert_to_json_schema
+
+    # hammad.logging
+    from .logging import (
+        Logger,
+        create_logger,
+        trace,
+        trace_cls,
+        trace_function,
+        trace_http,
+        install_trace_http,
+    )
+
+    # hammad.multithreading
+    from .multithreading import (
+        run_parallel,
+        run_sequentially,
+        run_with_retry,
+        retry,
+    )
+
+    # hammad.pydantic
+    from .pydantic import (
+        convert_to_pydantic_field,
+        convert_to_pydantic_model,
+    )
 
-# `hammad.web`
-from .web import (
-    create_http_client,
-    create_openapi_client,
-    create_search_client,
-    read_web_page,
-    read_web_pages,
-    run_web_request,
-    search_news,
-    search_web,
-    extract_page_links,
+    # hammad.text
+    from .text import (
+        Text,
+        OutputText,
+        SimpleText,
+        convert_to_text,
+        convert_type_to_text,
+        convert_docstring_to_text,
+    )
+
+    # hammad.web
+    from .web import (
+        create_http_client,
+        create_openapi_client,
+        create_search_client,
+        search_news,
+        search_web,
+        run_web_request,
+        read_web_page,
+        read_web_pages,
+        extract_page_links,
+    )
+
+    # hammad.yaml
+    from .yaml import encode_yaml, decode_yaml, read_yaml_file
+
+
+__all__ = (
+    # hammad.ai
+    "create_completion",
+    "async_create_completion",
+    "create_embeddings",
+    "async_create_embeddings",
+    # hammad.base
+    "Model",
+    "field",
+    "create_model",
+    # hammad.cache
+    "Cache",
+    "cached",
+    "auto_cached",
+    "create_cache",
+    # hammad.cli
+    "print",
+    "animate",
+    "input",
+    # hammad.configuration
+    "Configuration",
+    "read_configuration_from_os_vars",
+    "read_configuration_from_dotenv",
+    "read_configuration_from_file",
+    "read_configuration_from_url",
+    "read_configuration_from_os_prefix",
+    # hammad.data
+    "Collection",
+    "Database",
+    "create_collection",
+    "create_database",
+    # hammad.json
+    "encode_json",
+    "decode_json",
+    "convert_to_json_schema",
+    # hammad.logging
+    "Logger",
+    "create_logger",
+    "trace",
+    "trace_cls",
+    "trace_function",
+    "trace_http",
+    "install_trace_http",
+    # hammad.multithreading
+    "run_parallel",
+    "run_sequentially",
+    "run_with_retry",
+    "retry",
+    # hammad.pydantic
+    "convert_to_pydantic_field",
+    "convert_to_pydantic_model",
+    # hammad.text
+    "Text",
+    "OutputText",
+    "SimpleText",
+    "convert_to_text",
+    "convert_type_to_text",
+    "convert_docstring_to_text",
+    # hammad.web
+    "create_http_client",
+    "create_openapi_client",
+    "create_search_client",
+    "search_news",
+    "search_web",
+    "run_web_request",
+    "read_web_page",
+    "read_web_pages",
+    "extract_page_links",
+    # hammad.yaml
+    "encode_yaml",
+    "decode_yaml",
+    "read_yaml_file",
 )
+
+
+__getattr__ = _auto_create_getattr_loader(__all__)
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

hammad/_core/__init__.py

@@ -0,0 +1 @@
+"""hammad._core"""

hammad/_core/_utils/__init__.py

@@ -0,0 +1,4 @@
+"""hammad._core._utils
+
+Contains internal utility functions use at a low level for various cases
+throughout the `hammad` package."""

hammad/_core/_utils/_import_utils.py

@@ -0,0 +1,182 @@
+"""hammad._core._utils._import_utils"""
+
+from typing import Any, Callable
+import inspect
+import ast
+import hashlib
+
+__all__ = ("_auto_create_getattr_loader",)
+
+
+class _ModuleCache:
+    """Minimal cache implementation for internal use only."""
+
+    def __init__(self, maxsize: int = 128):
+        self.maxsize = maxsize
+        self._cache: dict[str, Any] = {}
+
+    def _make_key(self, data: str) -> str:
+        """Create a simple hash key from string data."""
+        return hashlib.sha256(data.encode("utf-8")).hexdigest()[:16]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get value from cache."""
+        return self._cache.get(key, default)
+
+    def set(self, key: str, value: Any) -> None:
+        """Set value in cache with basic LRU eviction."""
+        if len(self._cache) >= self.maxsize and key not in self._cache:
+            # Simple eviction: remove oldest (first) item
+            oldest_key = next(iter(self._cache))
+            del self._cache[oldest_key]
+        self._cache[key] = value
+
+    def cached_call(self, func: Callable[[str], Any]) -> Callable[[str], Any]:
+        """Decorator to cache function calls."""
+
+        def wrapper(arg: str) -> Any:
+            key = self._make_key(arg)
+            result = self.get(key)
+            if result is None:
+                result = func(arg)
+                self.set(key, result)
+            return result
+
+        return wrapper
+
+
+# Global cache instance for parse function
+_parse_cache = _ModuleCache(maxsize=64)
+
+
+def _create_getattr_loader(
+    imports_dict: dict[str, tuple[str, str]], package: str
+) -> Callable[[str], Any]:
+    """Create a lazy loader function for __getattr__.
+
+    Args:
+        imports_dict: Dictionary mapping attribute names to (module_path, original_name) tuples
+        package: The package name for import_module
+
+    Returns:
+        A __getattr__ function that lazily imports modules
+    """
+    from importlib import import_module
+
+    _cache = {}
+
+    def __getattr__(name: str) -> Any:
+        if name in _cache:
+            return _cache[name]
+
+        if name in imports_dict:
+            module_path, original_name = imports_dict[name]
+            module = import_module(module_path, package)
+            result = getattr(module, original_name)
+            _cache[name] = result
+            return result
+        raise AttributeError(f"module '{package}' has no attribute '{name}'")
+
+    return __getattr__
+
+
+_type_checking_cache = {}
+
+
+def _auto_create_getattr_loader(all_exports: tuple[str, ...]) -> Callable[[str], Any]:
+    """Automatically create a lazy loader by inspecting the calling module.
+
+    This function inspects the calling module's source code to extract
+    TYPE_CHECKING imports and automatically builds the import map.
+
+    Args:
+        all_exports: The __all__ tuple from the calling module
+
+    Returns:
+        A __getattr__ function that lazily imports modules
+    """
+    # Get the calling module's frame
+    frame = inspect.currentframe()
+    if frame is None or frame.f_back is None:
+        raise RuntimeError("Cannot determine calling module")
+
+    calling_frame = frame.f_back
+    module_name = calling_frame.f_globals.get("__name__", "")
+    package = calling_frame.f_globals.get("__package__", "")
+    filename = calling_frame.f_globals.get("__file__", "")
+
+    # Check cache first
+    cache_key = (filename, tuple(all_exports))
+    if cache_key in _type_checking_cache:
+        return _type_checking_cache[cache_key]
+
+    # Read the source file
+    try:
+        with open(filename, "r") as f:
+            source_code = f.read()
+    except (IOError, OSError):
+        # Fallback: try to get source from the module
+        import sys
+
+        module = sys.modules.get(module_name)
+        if module:
+            source_code = inspect.getsource(module)
+        else:
+            raise RuntimeError(f"Cannot read source for module {module_name}")
+
+    # Parse the source to extract TYPE_CHECKING imports
+    imports_map = _parse_type_checking_imports(source_code)
+
+    # Filter to only include exports that are in __all__
+    filtered_map = {
+        name: path for name, path in imports_map.items() if name in all_exports
+    }
+
+    loader = _create_getattr_loader(filtered_map, package)
+    _type_checking_cache[cache_key] = loader
+    return loader
+
+
+def _parse_type_checking_imports(source_code: str) -> dict[str, tuple[str, str]]:
+    """Parse TYPE_CHECKING imports from source code to build import map.
+
+    Args:
+        source_code: The source code containing TYPE_CHECKING imports
+
+    Returns:
+        Dictionary mapping local names to (module_path, original_name) tuples
+    """
+
+    @_parse_cache.cached_call
+    def _exec(source_code: str) -> dict[str, tuple[str, str]]:
+        tree = ast.parse(source_code)
+        imports = {}
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.If):
+                # Check if this is a TYPE_CHECKING block
+                is_type_checking = False
+
+                if isinstance(node.test, ast.Name) and node.test.id == "TYPE_CHECKING":
+                    is_type_checking = True
+                elif isinstance(node.test, ast.Attribute):
+                    if (
+                        isinstance(node.test.value, ast.Name)
+                        and node.test.value.id == "typing"
+                        and node.test.attr == "TYPE_CHECKING"
+                    ):
+                        is_type_checking = True
+
+                if is_type_checking:
+                    # Process imports in this block
+                    for stmt in node.body:
+                        if isinstance(stmt, ast.ImportFrom) and stmt.module:
+                            module_path = f".{stmt.module}"
+                            for alias in stmt.names:
+                                original_name = alias.name
+                                local_name = alias.asname or original_name
+                                imports[local_name] = (module_path, original_name)
+
+        return imports
+
+    return _exec(source_code)

hammad/ai/__init__.py

@@ -0,0 +1,59 @@
+"""hammad.ai"""
+
+from typing import TYPE_CHECKING
+from .._core._utils._import_utils import _auto_create_getattr_loader
+
+if TYPE_CHECKING:
+    from .completions import (
+        CompletionsClient,
+        Completion,
+        CompletionChunk,
+        CompletionsInputParam,
+        CompletionsModelName,
+        CompletionsOutputType,
+        CompletionStream,
+        AsyncCompletionStream,
+        async_create_completion,
+        create_completion,
+    )
+    from .embeddings import (
+        Embedding,
+        EmbeddingResponse,
+        EmbeddingUsage,
+        BaseEmbeddingsClient,
+        FastEmbedTextEmbeddingsClient,
+        LiteLlmEmbeddingsClient,
+        create_embeddings,
+        async_create_embeddings,
+    )
+
+
+__all__ = (
+    # hammad.ai.completions
+    "CompletionsClient",
+    "Completion",
+    "CompletionChunk",
+    "CompletionsInputParam",
+    "CompletionsModelName",
+    "CompletionsOutputType",
+    "CompletionStream",
+    "AsyncCompletionStream",
+    "async_create_completion",
+    "create_completion",
+    # hammad.ai.embeddings
+    "Embedding",
+    "EmbeddingResponse",
+    "EmbeddingUsage",
+    "BaseEmbeddingsClient",
+    "FastEmbedTextEmbeddingsClient",
+    "LiteLlmEmbeddingsClient",
+    "create_embeddings",
+    "async_create_embeddings",
+)
+
+
+__getattr__ = _auto_create_getattr_loader(__all__)
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

hammad/ai/_utils.py

@@ -0,0 +1,142 @@
+"""hammad.ai._utils
+
+Shared internal utilities for the `hammad.ai` extension."""
+
+from typing import Any, Optional, Sequence
+
+__all__ = (
+    "get_instructor",
+    "get_litellm",
+    "get_fastembed",
+    "get_fastembed_text_embedding_model",
+)
+
+
+# ------------------------------------------------------------
+# INSTRUCTOR
+# ------------------------------------------------------------
+
+
+INSTRUCTOR_MODULE = None
+"""Library level singleton for the `instructor` module."""
+
+
+def get_instructor():
+    """Get the instructor module."""
+    global INSTRUCTOR_MODULE
+
+    if INSTRUCTOR_MODULE is None:
+        try:
+            import instructor
+
+            INSTRUCTOR_MODULE = instructor
+        except ImportError:
+            raise ImportError(
+                "instructor is not installed. Please install it with `pip install hammad-python[ai]`"
+            )
+
+    return INSTRUCTOR_MODULE
+
+
+# ------------------------------------------------------------
+# LITELLM
+# ------------------------------------------------------------
+
+
+LITELLM_MODULE = None
+"""Library level singleton for the `litellm` module."""
+
+
+def get_litellm():
+    """Get the litellm module."""
+    global LITELLM_MODULE
+    if LITELLM_MODULE is None:
+        try:
+            import litellm
+
+            litellm.drop_params = True
+            litellm.modify_params = True
+            LITELLM_MODULE = litellm
+        except ImportError:
+            raise ImportError(
+                "litellm is not installed. Please install it with `pip install hammad-python[ai]`"
+            )
+
+    return LITELLM_MODULE
+
+
+# ------------------------------------------------------------
+# FASTEMBED
+# ------------------------------------------------------------
+
+
+FASTEMBED_MODULE = None
+"""Library level singleton for the `fastembed` module."""
+
+
+def get_fastembed():
+    """Get the fastembed module."""
+    global FASTEMBED_MODULE
+    if FASTEMBED_MODULE is None:
+        try:
+            import fastembed
+
+            FASTEMBED_MODULE = fastembed
+        except ImportError:
+            raise ImportError(
+                "fastembed is not installed. Please install it with `pip install hammad-python[ai]`"
+            )
+
+    return FASTEMBED_MODULE
+
+
+FASTEMBED_LOADED_TEXT_EMBEDDING_MODELS: dict = {}
+
+
+def get_fastembed_text_embedding_model(
+    model: str,
+    cache_dir: Optional[str] = None,
+    threads: Optional[int] = None,
+    providers: Optional[Sequence[Any]] = None,
+    cuda: bool = False,
+    device_ids: Optional[list[int]] = None,
+    lazy_load: bool = False,
+):
+    """Initializes a fastembed model instance for a given
+    model name using a global library level singleton.
+
+    NOTE: Custom models are not supported yet.
+
+    Args:
+        model (str) : The model name to load.
+        cache_dir (Optional[str]) : The directory to cache the model in.
+        threads (Optional[int]) : The number of threads to use for the model.
+        providers (Optional[Sequence[Any]]) : The ONNX providers to use for the model.
+        cuda (bool) : Whether to use CUDA for the model.
+        device_ids (Optional[list[int]]) : The device IDs to use for the model.
+        lazy_load (bool) : Whether to lazy load the model.
+
+    Returns:
+        fastembed.TextEmbedding : The loaded fastembed model instance.
+    """
+    global FASTEMBED_LOADED_TEXT_EMBEDDING_MODELS
+
+    if model not in FASTEMBED_LOADED_TEXT_EMBEDDING_MODELS:
+        fastembed_module = get_fastembed()
+
+        try:
+            embedding_model = fastembed_module.TextEmbedding(
+                model_name=model,
+                cache_dir=cache_dir,
+                threads=threads,
+                providers=providers,
+                cuda=cuda,
+                device_ids=device_ids,
+                lazy_load=lazy_load,
+            )
+        except Exception as e:
+            raise e
+
+        FASTEMBED_LOADED_TEXT_EMBEDDING_MODELS[model] = embedding_model
+
+    return FASTEMBED_LOADED_TEXT_EMBEDDING_MODELS[model]

hammad/ai/completions/__init__.py

@@ -0,0 +1,44 @@
+"""hammad.ai.completions
+
+Contains types and model like objects for working with language model
+completions."""
+
+from typing import TYPE_CHECKING
+from ..._core._utils._import_utils import _auto_create_getattr_loader
+
+if TYPE_CHECKING:
+    from .client import CompletionsClient
+    from .types import (
+        Completion,
+        CompletionChunk,
+        CompletionStream,
+        AsyncCompletionStream,
+        CompletionsInputParam,
+        CompletionsModelName,
+        CompletionsOutputType,
+    )
+    from .create import create_completion, async_create_completion
+
+
+__all__ = (
+    # hammad.ai.completions.client
+    "CompletionsClient",
+    # hammad.ai.completions.types
+    "Completion",
+    "CompletionChunk",
+    "CompletionStream",
+    "AsyncCompletionStream",
+    "CompletionsInputParam",
+    "CompletionsModelName",
+    "CompletionsOutputType",
+    # hammad.ai.completions.create
+    "create_completion",
+    "async_create_completion",
+)
+
+
+__getattr__ = _auto_create_getattr_loader(__all__)
+
+
+def __dir__() -> list[str]:
+    return list(__all__)