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

hammad/__init__.py

@@ -1,180 +1 @@
-"""hammad-python
-
-```markdown
-## Happliy Accelerated Micro Modules (for) Application Development
-```
-"""
-
-from typing import TYPE_CHECKING
-from ._core._utils._import_utils import _auto_create_getattr_loader
-
-
-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.base
-    from .base import Model, field, create_model, is_field, is_model, validator
-
-    # hammad.cache
-    from .cache import Cache, cached, auto_cached, create_cache
-
-    # hammad.cli
-    from .cli import print, animate, input
-
-    # 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.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-python"""

hammad/ai/__init__.py

@@ -1,59 +1 @@
 """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/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/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/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,