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

hammad/ai/completions/settings.py

@@ -0,0 +1,100 @@
+"""hammad.ai.completions.settings"""
+
+from typing import Any, Dict, List, Literal, Optional, Union
+import sys
+from httpx import Timeout
+
+if sys.version_info >= (3, 12):
+    from typing import TypedDict
+else:
+    from typing_extensions import TypedDict
+
+try:
+    from openai.types.chat import (
+        ChatCompletionModality,
+        ChatCompletionPredictionContentParam,
+        ChatCompletionAudioParam,
+    )
+except ImportError:
+    raise ImportError(
+        "Using the `hammad.ai.completions` extension requires the `openai` package to be installed.\n"
+        "Please either install the `openai` package, or install the `hammad.ai` extension with:\n"
+        "`pip install 'hammad-python[ai]'"
+    )
+
+
+__all__ = (
+    "CompletionsModelSettings",
+    "CompletionsSettings",
+)
+
+
+class OpenAIWebSearchUserLocationApproximate(TypedDict):
+    city: str
+    country: str
+    region: str
+    timezone: str
+
+
+class OpenAIWebSearchUserLocation(TypedDict):
+    approximate: OpenAIWebSearchUserLocationApproximate
+    type: Literal["approximate"]
+
+
+class OpenAIWebSearchOptions(TypedDict, total=False):
+    search_context_size: Optional[Literal["low", "medium", "high"]]
+    user_location: Optional[OpenAIWebSearchUserLocation]
+
+
+class AnthropicThinkingParam(TypedDict, total=False):
+    type: Literal["enabled"]
+    budget_tokens: int
+
+
+class CompletionsModelSettings(TypedDict, total=False):
+    """Accepted **MODEL** specific settings for the `litellm` completion function."""
+
+    timeout: Optional[Union[float, str, Timeout]]
+    temperature: Optional[float]
+    top_p: Optional[float]
+    n: Optional[int]
+    stream: Optional[bool]
+    stream_options: Optional[Dict[str, Any]]
+    stop: Optional[str]
+    max_completion_tokens: Optional[int]
+    max_tokens: Optional[int]
+    modalities: Optional[List[ChatCompletionModality]]
+    prediction: Optional[ChatCompletionPredictionContentParam]
+    audio: Optional[ChatCompletionAudioParam]
+    presence_penalty: Optional[float]
+    frequency_penalty: Optional[float]
+    logit_bias: Optional[Dict[str, float]]
+    user: Optional[str]
+    reasoning_effort: Optional[Literal["low", "medium", "high"]]
+    # NOTE: response_format is not used within the `completions` resource
+    # in place of `instructor` and the `type` parameter
+    seed: Optional[int]
+    tools: Optional[List]
+    tool_choice: Optional[Union[str, Dict[str, Any]]]
+    logprobs: Optional[bool]
+    top_logprobs: Optional[int]
+    parallel_tool_calls: Optional[bool]
+    web_search_options: Optional[OpenAIWebSearchOptions]
+    deployment_id: Optional[str]
+    extra_headers: Optional[Dict[str, str]]
+    base_url: Optional[str]
+    functions: Optional[List]
+    function_call: Optional[str]
+    # set api_base, api_version, api_key
+    api_version: Optional[str]
+    api_key: Optional[str]
+    model_list: Optional[list]
+    # Optional liteLLM function params
+    thinking: Optional[AnthropicThinkingParam]
+
+
+class CompletionsSettings(CompletionsModelSettings, total=False):
+    """Accepted settings for the `litellm` completion function."""
+
+    model: str
+    messages: List

hammad/ai/completions/types.py

@@ -37,6 +37,7 @@ __all__ = (
     "Completion",
     "CompletionsInputParam",
     "CompletionsOutputType",
+    "CompletionsInstructorModeParam",
     "CompletionChunk",
     "CompletionStream",
     "AsyncCompletionStream",
@@ -281,6 +282,42 @@ CompletionsModelName: TypeAlias = Literal[
 completions."""
 
 
+CompletionsInstructorModeParam = Literal[
+    "function_call",
+    "parallel_tool_call",
+    "tool_call",
+    "tools_strict",
+    "json_mode",
+    "json_o1",
+    "markdown_json_mode",
+    "json_schema_mode",
+    "anthropic_tools",
+    "anthropic_reasoning_tools",
+    "anthropic_json",
+    "mistral_tools",
+    "mistral_structured_outputs",
+    "vertexai_tools",
+    "vertexai_json",
+    "vertexai_parallel_tools",
+    "gemini_json",
+    "gemini_tools",
+    "genai_tools",
+    "genai_structured_outputs",
+    "cohere_tools",
+    "cohere_json_object",
+    "cerebras_tools",
+    "cerebras_json",
+    "fireworks_tools",
+    "fireworks_json",
+    "writer_tools",
+    "bedrock_tools",
+    "bedrock_json",
+    "perplexity_json",
+    "openrouter_structured_outputs",
+]
+"""Instructor prompt/parsing mode for structured outputs."""
+
+
 class Completion(BaseModel, Generic[CompletionsOutputType]):
     """Extended response object for completions and structured outputs
     generated by language models using the `completions` resource
@@ -299,7 +336,7 @@ class Completion(BaseModel, Generic[CompletionsOutputType]):
     """The actual response content of the completion. This is the string that
     was generated by the model."""
 
-    tool_calls: List[ChatCompletionMessageToolCall] | None = None
+    tool_calls: ChatCompletionMessageToolCall | Any | None = None
     """The tool calls that were made by the model. This is a list of tool calls
     that were made by the model."""
 
@@ -406,6 +443,20 @@ class Completion(BaseModel, Generic[CompletionsOutputType]):
 
             return {"role": "assistant", "content": content or str(self.output)}
 
+    def __str__(self) -> str:
+        """Pretty prints the completion object."""
+        output = "Completion:"
+
+        if self.output or self.content:
+            output += f"\n{self.output if self.output else self.content}"
+        else:
+            output += f"\n{self.completion}"
+
+        output += f"\n\n>>> Model: {self.model}"
+        output += f"\n>>> Tool Calls: {len(self.tool_calls) if self.tool_calls else 0}"
+
+        return output
+
 
 class CompletionChunk(BaseModel, Generic[CompletionsOutputType]):
     """Represents a chunk of data from a completion stream.
@@ -512,11 +563,26 @@ class CompletionStream(Generic[CompletionsOutputType]):
             # For instructor, the final chunk contains the complete object
             # The output is already extracted (.value) in _process_chunk if needed
             final_chunk = self._chunks[-1]
+
+            # Check if stream is from wrapper to get raw content
+            raw_content = None
+            raw_completion = None
+            if hasattr(self._stream, "get_raw_content"):
+                raw_content = self._stream.get_raw_content()
+            if hasattr(self._stream, "get_raw_completion"):
+                raw_completion = self._stream.get_raw_completion()
+
+            # Check for tool calls from wrapper
+            tool_calls = None
+            if hasattr(self._stream, "get_tool_calls"):
+                tool_calls = self._stream.get_tool_calls()
+
             return Completion(
                 output=final_chunk.output,
                 model=final_chunk.model or self._model or "unknown",
-                content=None,
-                completion=None,
+                content=raw_content,
+                tool_calls=tool_calls,
+                completion=raw_completion,
             )
         else:
             # For LiteLLM, combine content from all chunks
@@ -653,11 +719,26 @@ class AsyncCompletionStream(Generic[CompletionsOutputType]):
             # For instructor, the final chunk contains the complete object
             # The output is already extracted (.value) in _process_chunk if needed
             final_chunk = self._chunks[-1]
+
+            # Check if stream is from wrapper to get raw content
+            raw_content = None
+            raw_completion = None
+            if hasattr(self._stream, "get_raw_content"):
+                raw_content = self._stream.get_raw_content()
+            if hasattr(self._stream, "get_raw_completion"):
+                raw_completion = self._stream.get_raw_completion()
+
+            # Check for tool calls from wrapper
+            tool_calls = None
+            if hasattr(self._stream, "get_tool_calls"):
+                tool_calls = self._stream.get_tool_calls()
+
             return Completion(
                 output=final_chunk.output,
                 model=final_chunk.model or self._model or "unknown",
-                content=None,
-                completion=None,
+                content=raw_content,
+                tool_calls=tool_calls,
+                completion=raw_completion,
             )
         else:
             # For LiteLLM, combine content from all chunks

hammad/ai/completions/utils.py

@@ -36,6 +36,8 @@ __all__ = (
     "create_async_completion_stream",
     "format_tool_calls",
     "convert_response_to_completion",
+    "InstructorStreamWrapper",
+    "AsyncInstructorStreamWrapper",
 )
 
 
@@ -372,3 +374,113 @@ def convert_response_to_completion(response: Any) -> Completion[str]:
         refusal=refusal,
         completion=response,
     )
+
+
+class InstructorStreamWrapper:
+    """Wrapper for instructor streaming that captures raw completion content using hooks."""
+
+    def __init__(self, client, response_model, params, output_type, model):
+        self.client = client
+        self.response_model = response_model
+        self.params = params
+        self.output_type = output_type
+        self.model = model
+        self._raw_content_chunks = []
+        self._raw_completion = None
+        self._tool_calls = None
+
+        # Set up hooks to capture raw content
+        self.client.on("completion:response", self._capture_completion)
+
+    def _capture_completion(self, completion):
+        """Capture the raw completion response."""
+        self._raw_completion = completion
+        if hasattr(completion, "choices") and completion.choices:
+            choice = completion.choices[0]
+            # Capture content chunks
+            if hasattr(choice, "delta") and hasattr(choice.delta, "content"):
+                content = choice.delta.content
+                if content:
+                    self._raw_content_chunks.append(content)
+            # Capture tool calls from message (final chunk)
+            if hasattr(choice, "message") and hasattr(choice.message, "tool_calls"):
+                self._tool_calls = choice.message.tool_calls
+
+    def __iter__(self):
+        """Create the stream and yield wrapped chunks."""
+        stream = self.client.chat.completions.create_partial(
+            response_model=self.response_model, **self.params
+        )
+
+        for chunk in stream:
+            yield chunk
+
+        # Clean up hooks
+        self.client.off("completion:response", self._capture_completion)
+
+    def get_raw_content(self):
+        """Get the accumulated raw content."""
+        return "".join(self._raw_content_chunks)
+
+    def get_raw_completion(self):
+        """Get the raw completion object."""
+        return self._raw_completion
+
+    def get_tool_calls(self):
+        """Get the tool calls from the completion."""
+        return self._tool_calls
+
+    def get_tool_calls(self):
+        """Get the tool calls from the completion."""
+        return self._tool_calls
+
+
+class AsyncInstructorStreamWrapper:
+    """Async wrapper for instructor streaming that captures raw completion content using hooks."""
+
+    def __init__(self, client, response_model, params, output_type, model):
+        self.client = client
+        self.response_model = response_model
+        self.params = params
+        self.output_type = output_type
+        self.model = model
+        self._raw_content_chunks = []
+        self._raw_completion = None
+        self._tool_calls = None
+
+        # Set up hooks to capture raw content
+        self.client.on("completion:response", self._capture_completion)
+
+    def _capture_completion(self, completion):
+        """Capture the raw completion response."""
+        self._raw_completion = completion
+        if hasattr(completion, "choices") and completion.choices:
+            choice = completion.choices[0]
+            # Capture content chunks
+            if hasattr(choice, "delta") and hasattr(choice.delta, "content"):
+                content = choice.delta.content
+                if content:
+                    self._raw_content_chunks.append(content)
+            # Capture tool calls from message (final chunk)
+            if hasattr(choice, "message") and hasattr(choice.message, "tool_calls"):
+                self._tool_calls = choice.message.tool_calls
+
+    async def __aiter__(self):
+        """Create the stream and yield wrapped chunks."""
+        stream = await self.client.chat.completions.create_partial(
+            response_model=self.response_model, **self.params
+        )
+
+        async for chunk in stream:
+            yield chunk
+
+        # Clean up hooks
+        self.client.off("completion:response", self._capture_completion)
+
+    def get_raw_content(self):
+        """Get the accumulated raw content."""
+        return "".join(self._raw_content_chunks)
+
+    def get_raw_completion(self):
+        """Get the raw completion object."""
+        return self._raw_completion

hammad/ai/embeddings/__init__.py

@@ -1,7 +1,7 @@
 """hammad.ai.embeddings"""
 
 from typing import TYPE_CHECKING
-from ..._core._utils._import_utils import _auto_create_getattr_loader
+from ...performance.imports import create_getattr_importer
 
 if TYPE_CHECKING:
     from .client.base_embeddings_client import BaseEmbeddingsClient
@@ -28,7 +28,7 @@ __all__ = (
 )
 
 
-__getattr__ = _auto_create_getattr_loader(__all__)
+__getattr__ = create_getattr_importer(__all__)
 
 
 def __dir__() -> list[str]:

hammad/ai/embeddings/client/fastembed_text_embeddings_client.py

@@ -14,7 +14,7 @@ from ..types import (
     EmbeddingUsage,
     EmbeddingResponse,
 )
-from ....text.converters import convert_to_text
+from ....formatting.text.converters import convert_to_text
 from ..._utils import (
     get_fastembed_text_embedding_model,
 )

hammad/ai/embeddings/client/litellm_embeddings_client.py

@@ -15,7 +15,7 @@ from ..types import (
     EmbeddingUsage,
     EmbeddingResponse,
 )
-from ....text.converters import convert_to_text
+from ....formatting.text.converters import convert_to_text
 from ..._utils import get_litellm
 
 __all__ = (

hammad/ai/embeddings/types.py

@@ -2,7 +2,7 @@
 
 from typing import List, Literal
 
-from ...base.model import Model
+from pydantic import BaseModel
 
 __all__ = (
     "Embedding",
@@ -11,7 +11,7 @@ __all__ = (
 )
 
 
-class Embedding(Model):
+class Embedding(BaseModel):
     embedding: List[float]
     """The embedding vector, which is a list of floats.
 
@@ -31,7 +31,7 @@ class Embedding(Model):
         return len(self.embedding)
 
 
-class EmbeddingUsage(Model):
+class EmbeddingUsage(BaseModel):
     """Usage statistics for embedding requests."""
 
     prompt_tokens: int
@@ -41,7 +41,7 @@ class EmbeddingUsage(Model):
     """The total number of tokens used by the request."""
 
 
-class EmbeddingResponse(Model):
+class EmbeddingResponse(BaseModel):
     data: List[Embedding]
     """The list of embeddings generated by the model."""
 

hammad/cache/__init__.py

@@ -1,48 +1,40 @@
-"""hammad.cache
-
-Contains helpful resources for creating simple cache systems, and
-decorators that implement "automatic" hashing & caching of function calls.
-"""
+"""hammad.cache"""
 
 from typing import TYPE_CHECKING
-from .._core._utils._import_utils import _auto_create_getattr_loader
+from ..performance.imports import create_getattr_importer
+
 
 if TYPE_CHECKING:
     from .base_cache import BaseCache, CacheParams, CacheReturn, CacheType
-    from .file_cache import FileCache
+    from .file_cache import FileCache, FileCacheLocation
     from .ttl_cache import TTLCache
     from .cache import Cache, create_cache
-    from .decorators import (
-        cached,
-        auto_cached,
-        get_decorator_cache,
-        clear_decorator_cache,
-    )
+    from .decorators import cached, auto_cached, clear_decorator_cache
 
 
 __all__ = (
-    # hammad.cache.base_cache
+    # hammad.performance.cache.base_cache
     "BaseCache",
     "CacheParams",
     "CacheReturn",
     "CacheType",
-    # hammad.cache.file_cache
+    # hammad.performance.cache.file_cache
     "FileCache",
-    # hammad.cache.ttl_cache
+    "FileCacheLocation",
+    # hammad.performance.cache.ttl_cache
     "TTLCache",
-    # hammad.cache.cache
+    # hammad.performance.cache.cache
     "Cache",
     "create_cache",
-    # hammad.cache.decorators
+    # hammad.performance.cache.decorators
     "cached",
     "auto_cached",
-    "get_decorator_cache",
     "clear_decorator_cache",
 )
 
 
-__getattr__ = _auto_create_getattr_loader(__all__)
+__getattr__ = create_getattr_importer(__all__)
 
 
 def __dir__() -> list[str]:
-    return list(__all__)
+    return sorted(__all__)

hammad/cli/__init__.py

@@ -4,7 +4,7 @@ Contains resources for styling rendered CLI content as well
 as extensions / utilities for creating CLI interfaces."""
 
 from typing import TYPE_CHECKING
-from .._core._utils._import_utils import _auto_create_getattr_loader
+from ..performance.imports import create_getattr_importer
 
 if TYPE_CHECKING:
     from .plugins import print, input, animate
@@ -25,7 +25,7 @@ __all__ = (
 )
 
 
-__getattr__ = _auto_create_getattr_loader(__all__)
+__getattr__ = create_getattr_importer(__all__)
 
 
 def __dir__() -> list[str]:

hammad/cli/animations.py

@@ -7,38 +7,17 @@ import threading
 from dataclasses import dataclass, field
 from typing import Literal, Optional, List, overload, TYPE_CHECKING
 
-if TYPE_CHECKING:
-    from rich import get_console
-    from rich.console import Console, ConsoleOptions, RenderResult, RenderableType
-    from rich.live import Live
-    from rich.text import Text
-    from rich.panel import Panel
+from rich import get_console
+from rich.console import Console, ConsoleOptions, RenderResult, RenderableType
+from rich.live import Live
+from rich.text import Text
+from rich.panel import Panel
 
 from .styles.types import (
     CLIStyleColorName,
 )
 
 
-def _get_rich_animation_classes():
-    """Lazy import for rich classes used in animations"""
-    from rich import get_console
-    from rich.console import Console, ConsoleOptions, RenderResult, RenderableType
-    from rich.live import Live
-    from rich.text import Text
-    from rich.panel import Panel
-
-    return {
-        "get_console": get_console,
-        "Console": Console,
-        "ConsoleOptions": ConsoleOptions,
-        "RenderResult": RenderResult,
-        "RenderableType": RenderableType,
-        "Live": Live,
-        "Text": Text,
-        "Panel": Panel,
-    }
-
-
 __all__ = (
     "CLIAnimation",
     "CLIAnimationState",
@@ -87,8 +66,7 @@ class CLIAnimation:
         self.state = CLIAnimationState(last_update=None)
         """The current state of the animation."""
 
-        rich_classes = _get_rich_animation_classes()
-        self.rich_console = rich_classes["get_console"]()
+        self.rich_console = get_console()
         """The rich console responsible for rendering the animation."""
         self._animation_thread: threading.Thread | None = None
         """The thread responsible for running the animation."""
@@ -141,12 +119,9 @@ class CLIAnimation:
     ) -> None:
         """Animate this effect for the specified duration using Live."""
         animate_duration = duration or self.duration or 3.0
-        rich_classes = _get_rich_animation_classes()
-        Console = rich_classes["Console"]
-        Live = rich_classes["Live"]
 
         # Use provided console or create new one
-        live_console = console or Console()
+        live_console = console or get_console()
 
         with Live(
             self,
@@ -183,9 +158,6 @@ class CLIFlashingAnimation(CLIAnimation):
             self.colors = [on_color, off_color]
 
     def apply(self, console, options):
-        rich_classes = _get_rich_animation_classes()
-        Text = rich_classes["Text"]
-
         # Calculate which color to use based on time
         color_index = int(self.time_elapsed / self.speed) % len(self.colors)
         color = self.colors[color_index]
@@ -303,9 +275,6 @@ class CLITypingAnimation(CLIAnimation):
         self.show_cursor = show_cursor
 
     def apply(self, console: "Console", options: "ConsoleOptions") -> "RenderResult":
-        rich_classes = _get_rich_animation_classes()
-        Text = rich_classes["Text"]
-
         # Calculate how many characters to show
         chars_to_show = int(self.time_elapsed / self.speed)
         chars_to_show = min(chars_to_show, len(self.text))
@@ -404,7 +373,7 @@ class CLIRainbowAnimation(CLIAnimation):
     def apply(self, console: "Console", options: "ConsoleOptions") -> "RenderResult":
         if isinstance(self.renderable, str):
             # Apply rainbow to each character
-            result = _get_rich_animation_classes()["Text"]()
+            result = Text()
             for i, char in enumerate(self.renderable):
                 color_offset = int(
                     (self.time_elapsed / self.speed + i) % len(self.colors)

hammad/cli/styles/__init__.py

@@ -5,7 +5,7 @@ styling rendered content in the CLI. Most resources within this
 submodule are not meant for direct use."""
 
 from typing import TYPE_CHECKING
-from ..._core._utils._import_utils import _auto_create_getattr_loader
+from ...performance.imports import create_getattr_importer
 
 if TYPE_CHECKING:
     from .settings import (
@@ -48,7 +48,7 @@ __all__ = (
 )
 
 
-__getattr__ = _auto_create_getattr_loader(__all__)
+__getattr__ = create_getattr_importer(__all__)
 
 
 def __dir__() -> list[str]:

hammad/data/__init__.py

@@ -1,9 +1,17 @@
 """hammad.data"""
 
 from typing import TYPE_CHECKING
-from .._core._utils._import_utils import _auto_create_getattr_loader
+from ..performance.imports import create_getattr_importer
 
 if TYPE_CHECKING:
+    from .configurations import (
+        Configuration,
+        read_configuration_from_file,
+        read_configuration_from_url,
+        read_configuration_from_os_vars,
+        read_configuration_from_os_prefix,
+        read_configuration_from_dotenv,
+    )
     from .collections import (
         Collection,
         BaseCollection,
@@ -17,6 +25,14 @@ if TYPE_CHECKING:
 
 
 __all__ = (
+    # 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
     "Collection",
     "BaseCollection",
@@ -25,13 +41,14 @@ __all__ = (
     "SearchableCollection",
     "SearchableCollectionSettings",
     "create_collection",
+    
     # hammad.data.databases
     "Database",
     "create_database",
 )
 
 
-__getattr__ = _auto_create_getattr_loader(__all__)
+__getattr__ = create_getattr_importer(__all__)
 
 
 def __dir__() -> list[str]: