hammad-python 0.0.13__tar.gz → 0.0.14__tar.gz

{hammad_python-0.0.13 → hammad_python-0.0.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hammad-python
-Version: 0.0.13
+Version: 0.0.14
 Summary: hammad - *Nightly* hyper-fast opinionated resources and modules built for quick development.
 Author-email: Hammad Saeed <hammadaidev@gmail.com>
 License-File: LICENSE
@@ -34,5 +34,37 @@ Requires-Dist: sse-starlette>=1.1.0; extra == 'serve'
 Requires-Dist: uvicorn>=0.34.0; extra == 'serve'
 Description-Content-Type: text/markdown
 
-# hammad-python
-hammadpy - *Nightly* hyper-fast opinionated resources and modules built for quick development.
+## hammad-python
+
+> __Happily Accelerated Micro-Modules (_for_) Application Development__
+
+## Introduction
+
+The `hammad-python` library, is a mix of a love letter and collection of mixed resources for
+developing Python applications. This library is meant to be used for rapid prototyping and
+development, and is focused on providing styled placeholder tools for common patterns, tasks
+and workflows.
+
+The package is currently built into the following structures:
+
+- `hammad-python` : Contains most core functionality and resources.
+- `hammad-python[ai]` : Contains easy to use resources for Generative AI related tasks such as
+   generating completions with language models, or creating embeddings.
+
+## Installation
+
+You can install the package using `pip` or `uv`:
+
+```bash
+pip install hammad-python
+
+# or install the `ai` extension
+# pip install 'hammad-python[ai]'
+```
+
+```bash
+uv pip install hammad-python
+
+# or install the `ai` extension
+# uv pip install 'hammad-python[ai]'
+```

hammad_python-0.0.14/README.md

@@ -0,0 +1,34 @@
+## hammad-python
+
+> __Happily Accelerated Micro-Modules (_for_) Application Development__
+
+## Introduction
+
+The `hammad-python` library, is a mix of a love letter and collection of mixed resources for
+developing Python applications. This library is meant to be used for rapid prototyping and
+development, and is focused on providing styled placeholder tools for common patterns, tasks
+and workflows.
+
+The package is currently built into the following structures:
+
+- `hammad-python` : Contains most core functionality and resources.
+- `hammad-python[ai]` : Contains easy to use resources for Generative AI related tasks such as
+   generating completions with language models, or creating embeddings.
+
+## Installation
+
+You can install the package using `pip` or `uv`:
+
+```bash
+pip install hammad-python
+
+# or install the `ai` extension
+# pip install 'hammad-python[ai]'
+```
+
+```bash
+uv pip install hammad-python
+
+# or install the `ai` extension
+# uv pip install 'hammad-python[ai]'
+```

hammad_python-0.0.14/hammad/__init__.py

@@ -0,0 +1 @@
+"""hammad-python"""

hammad_python-0.0.14/hammad/ai/__init__.py

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

{hammad_python-0.0.13 → hammad_python-0.0.14}/hammad/ai/completions/__init__.py

@@ -4,7 +4,7 @@ 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
+from ...performance.imports import create_getattr_importer
 
 if TYPE_CHECKING:
     from .client import CompletionsClient
@@ -17,6 +17,7 @@ if TYPE_CHECKING:
         CompletionsModelName,
         CompletionsOutputType,
     )
+    from .settings import CompletionsSettings, CompletionsModelSettings
     from .create import create_completion, async_create_completion
 
 
@@ -37,7 +38,7 @@ __all__ = (
 )
 
 
-__getattr__ = _auto_create_getattr_loader(__all__)
+__getattr__ = create_getattr_importer(__all__)
 
 
 def __dir__() -> list[str]:

{hammad_python-0.0.13 → hammad_python-0.0.14}/hammad/ai/completions/client.py

@@ -22,9 +22,8 @@ except ImportError:
         "`pip install 'hammad-python[ai]'"
     )
 
-from ...pydantic.converters import convert_to_pydantic_model
+from ...data.models.pydantic.converters import convert_to_pydantic_model
 from .._utils import get_litellm, get_instructor
-from ...base.model import Model
 from ...typing import is_pydantic_basemodel
 from .utils import (
     format_tool_calls,
@@ -32,117 +31,23 @@ from .utils import (
     convert_response_to_completion,
     create_async_completion_stream,
     create_completion_stream,
+    InstructorStreamWrapper,
+    AsyncInstructorStreamWrapper,
+)
+from .settings import (
+    CompletionsSettings,
+    OpenAIWebSearchOptions,
+    AnthropicThinkingParam,
 )
 from .types import (
+    CompletionsInstructorModeParam,
     CompletionsInputParam,
     CompletionsOutputType,
     Completion,
-    CompletionChunk,
-    CompletionStream,
-    AsyncCompletionStream,
 )
 
 
-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
-
-
-InstructorModeParam = 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 CompletionsSettings(TypedDict):
-    """Accepted settings for the `litellm` completion function."""
-
-    model: str
-    messages: List
-    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]
+__all__ = "CompletionsClient"
 
 
 class CompletionsError(Exception):
@@ -372,7 +277,9 @@ class CompletionsClient(Generic[CompletionsOutputType]):
         instructions: Optional[str] = None,
         model: str = "openai/gpt-4o-mini",
         type: CompletionsOutputType = str,
-        instructor_mode: InstructorModeParam = "tool_call",
+        response_field_name: str = "content",
+        response_field_instruction: str = "A response in the correct type as requested by the user, or relevant content.",
+        instructor_mode: CompletionsInstructorModeParam = "tool_call",
         max_retries: int = 3,
         strict: bool = True,
         *,
@@ -515,22 +422,30 @@ class CompletionsClient(Generic[CompletionsOutputType]):
             response_model = convert_to_pydantic_model(
                 target=type,
                 name="Response",
-                field_name="value",
-                description="A single field response in the correct type.",
+                field_name=response_field_name,
+                description=response_field_instruction,
             )
         else:
             response_model = type
 
         if stream:
-            stream = await client.chat.completions.create_partial(
+            # Create wrapper to capture raw content via hooks
+            wrapper = AsyncInstructorStreamWrapper(
+                client=client,
                 response_model=response_model,
-                max_retries=max_retries,
-                strict=strict,
-                **{k: v for k, v in params.items() if v is not None},
+                params={
+                    "max_retries": max_retries,
+                    "strict": strict,
+                    **{k: v for k, v in params.items() if v is not None},
+                },
+                output_type=type,
+                model=model,
+            )
+            return create_async_completion_stream(
+                wrapper, output_type=type, model=model
             )
-            return create_async_completion_stream(stream, output_type=type, model=model)
         else:
-            response = await client.chat.completions.create(
+            response, completion = await client.chat.completions.create_with_completion(
                 response_model=response_model,
                 max_retries=max_retries,
                 strict=strict,
@@ -538,13 +453,29 @@ class CompletionsClient(Generic[CompletionsOutputType]):
             )
 
             # Extract the actual value if using converted pydantic model
-            if not is_pydantic_basemodel(type) and hasattr(response, "value"):
-                actual_output = response.value
+            if not is_pydantic_basemodel(type) and hasattr(
+                response, response_field_name
+            ):
+                actual_output = getattr(response, response_field_name)
             else:
                 actual_output = response
 
+            # Extract content and tool calls from the completion
+            content = None
+            tool_calls = None
+            if hasattr(completion, "choices") and completion.choices:
+                choice = completion.choices[0]
+                if hasattr(choice, "message"):
+                    message = choice.message
+                    content = getattr(message, "content", None)
+                    tool_calls = getattr(message, "tool_calls", None)
+
             return Completion(
-                output=actual_output, model=model, content=None, completion=None
+                output=actual_output,
+                model=model,
+                content=content,
+                tool_calls=tool_calls,
+                completion=completion,
             )
 
     @staticmethod
@@ -553,7 +484,9 @@ class CompletionsClient(Generic[CompletionsOutputType]):
         instructions: Optional[str] = None,
         model: str = "openai/gpt-4o-mini",
         type: CompletionsOutputType = str,
-        instructor_mode: InstructorModeParam = "tool_call",
+        response_field_name: str = "content",
+        response_field_instruction: str = "A response in the correct type as requested by the user, or relevant content.",
+        instructor_mode: CompletionsInstructorModeParam = "tool_call",
         max_retries: int = 3,
         strict: bool = True,
         *,
@@ -696,22 +629,28 @@ class CompletionsClient(Generic[CompletionsOutputType]):
             response_model = convert_to_pydantic_model(
                 target=type,
                 name="Response",
-                field_name="value",
-                description="A single field response in the correct type.",
+                field_name=response_field_name,
+                description=response_field_instruction,
             )
         else:
             response_model = type
 
         if stream:
-            stream = client.chat.completions.create_partial(
+            # Create wrapper to capture raw content via hooks
+            wrapper = InstructorStreamWrapper(
+                client=client,
                 response_model=response_model,
-                max_retries=max_retries,
-                strict=strict,
-                **{k: v for k, v in params.items() if v is not None},
+                params={
+                    "max_retries": max_retries,
+                    "strict": strict,
+                    **{k: v for k, v in params.items() if v is not None},
+                },
+                output_type=type,
+                model=model,
             )
-            return create_completion_stream(stream, output_type=type, model=model)
+            return create_completion_stream(wrapper, output_type=type, model=model)
         else:
-            response = client.chat.completions.create(
+            response, completion = client.chat.completions.create_with_completion(
                 response_model=response_model,
                 max_retries=max_retries,
                 strict=strict,
@@ -719,11 +658,27 @@ class CompletionsClient(Generic[CompletionsOutputType]):
             )
 
             # Extract the actual value if using converted pydantic model
-            if not is_pydantic_basemodel(type) and hasattr(response, "value"):
-                actual_output = response.value
+            if not is_pydantic_basemodel(type) and hasattr(
+                response, response_field_name
+            ):
+                actual_output = getattr(response, response_field_name)
             else:
                 actual_output = response
 
+            # Extract content and tool calls from the completion
+            content = None
+            tool_calls = None
+            if hasattr(completion, "choices") and completion.choices:
+                choice = completion.choices[0]
+                if hasattr(choice, "message"):
+                    message = choice.message
+                    content = getattr(message, "content", None)
+                    tool_calls = getattr(message, "tool_calls", None)
+
             return Completion(
-                output=actual_output, model=model, content=None, completion=None
+                output=actual_output,
+                model=model,
+                content=content,
+                tool_calls=tool_calls,
+                completion=completion,
             )

{hammad_python-0.0.13 → hammad_python-0.0.14}/hammad/ai/completions/create.py

@@ -24,7 +24,7 @@ from .types import (
     CompletionStream,
 )
 from .client import (
-    InstructorModeParam,
+    CompletionsInstructorModeParam,
     AnthropicThinkingParam,
     OpenAIWebSearchOptions,
     CompletionsClient,
@@ -41,7 +41,9 @@ async def async_create_completion(
     instructions: Optional[str] = None,
     model: str | CompletionsModelName = "openai/gpt-4o-mini",
     type: CompletionsOutputType = str,
-    instructor_mode: InstructorModeParam = "tool_call",
+    response_field_name: str = "content",
+    response_field_instruction: str = "A response in the correct type as requested by the user, or relevant content.",
+    instructor_mode: CompletionsInstructorModeParam = "tool_call",
     max_retries: int = 3,
     strict: bool = True,
     *,
@@ -91,7 +93,9 @@ async def async_create_completion(
     instructions: Optional[str] = None,
     model: str | CompletionsModelName = "openai/gpt-4o-mini",
     type: CompletionsOutputType = str,
-    instructor_mode: InstructorModeParam = "tool_call",
+    response_field_name: str = "content",
+    response_field_instruction: str = "A response in the correct type as requested by the user, or relevant content.",
+    instructor_mode: CompletionsInstructorModeParam = "tool_call",
     max_retries: int = 3,
     strict: bool = True,
     *,
@@ -140,7 +144,9 @@ async def async_create_completion(
     instructions: Optional[str] = None,
     model: str | CompletionsModelName = "openai/gpt-4o-mini",
     type: CompletionsOutputType = str,
-    instructor_mode: InstructorModeParam = "tool_call",
+    response_field_name: str = "content",
+    response_field_instruction: str = "A response in the correct type as requested by the user, or relevant content.",
+    instructor_mode: CompletionsInstructorModeParam = "tool_call",
     max_retries: int = 3,
     strict: bool = True,
     *,
@@ -206,7 +212,11 @@ async def async_create_completion(
             - A Pydantic BaseModel class for structured output
             - Basic Python types (int, float, bool, list, dict)
             Defaults to str.
-        instructor_mode (InstructorModeParam, optional): The instructor mode for
+        response_field_name (str, optional): The name of the field in the response to return.
+            Defaults to "content".
+        response_field_instruction (str, optional): The instruction for the response field.
+            Defaults to "A response in the correct type as requested by the user, or relevant content."
+        instructor_mode (CompletionsInstructorModeParam, optional): The instructor mode for
             structured outputs ("tool_call", "json", "json_schema", "markdown_json_schema",
             "function_call"). Defaults to "tool_call".
         max_retries (int, optional): Maximum number of retries for structured output
@@ -321,6 +331,8 @@ async def async_create_completion(
         instructions=instructions,
         model=model,
         type=type,
+        response_field_name=response_field_name,
+        response_field_instruction=response_field_instruction,
         instructor_mode=instructor_mode,
         max_retries=max_retries,
         strict=strict,
@@ -367,7 +379,9 @@ def create_completion(
     instructions: Optional[str] = None,
     model: str | CompletionsModelName = "openai/gpt-4o-mini",
     type: CompletionsOutputType = str,
-    instructor_mode: InstructorModeParam = "tool_call",
+    response_field_name: str = "content",
+    response_field_instruction: str = "A response in the correct type as requested by the user, or relevant content.",
+    instructor_mode: CompletionsInstructorModeParam = "tool_call",
     max_retries: int = 3,
     strict: bool = True,
     *,
@@ -417,7 +431,9 @@ def create_completion(
     instructions: Optional[str] = None,
     model: str | CompletionsModelName = "openai/gpt-4o-mini",
     type: CompletionsOutputType = str,
-    instructor_mode: InstructorModeParam = "tool_call",
+    response_field_name: str = "content",
+    response_field_instruction: str = "A response in the correct type as requested by the user, or relevant content.",
+    instructor_mode: CompletionsInstructorModeParam = "tool_call",
     max_retries: int = 3,
     strict: bool = True,
     *,
@@ -466,7 +482,9 @@ def create_completion(
     instructions: Optional[str] = None,
     model: str | CompletionsModelName = "openai/gpt-4o-mini",
     type: CompletionsOutputType = str,
-    instructor_mode: InstructorModeParam = "tool_call",
+    response_field_name: str = "content",
+    response_field_instruction: str = "A response in the correct type as requested by the user, or relevant content.",
+    instructor_mode: CompletionsInstructorModeParam = "tool_call",
     max_retries: int = 3,
     strict: bool = True,
     *,
@@ -532,7 +550,11 @@ def create_completion(
             - A Pydantic BaseModel class for structured output
             - Basic Python types (int, float, bool, list, dict)
             Defaults to str.
-        instructor_mode (InstructorModeParam, optional): The instructor mode for
+        response_field_name (str, optional): The name of the field in the response to return.
+            Defaults to "content".
+        response_field_instruction (str, optional): The instruction for the response field.
+            Defaults to "A response in the correct type as requested by the user, or relevant content."
+        instructor_mode (CompletionsInstructorModeParam, optional): The instructor mode for
             structured outputs ("tool_call", "json", "json_schema", "markdown_json_schema",
             "function_call"). Defaults to "tool_call".
         max_retries (int, optional): Maximum number of retries for structured output
@@ -647,6 +669,8 @@ def create_completion(
         instructions=instructions,
         model=model,
         type=type,
+        response_field_name=response_field_name,
+        response_field_instruction=response_field_instruction,
         instructor_mode=instructor_mode,
         max_retries=max_retries,
         strict=strict,

hammad_python-0.0.14/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