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

{hammad_python-0.0.13 → hammad_python-0.0.15}/.gitignore

@@ -28,7 +28,6 @@ dist/
 downloads/
 eggs/
 .eggs/
-lib/
 lib64/
 parts/
 sdist/

hammad_python-0.0.15/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: hammad-python
+Version: 0.0.15
+Author-email: Hammad Saeed <hammadaidev@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Hammad Saeed
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: ddgs>=9.0.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: msgspec>=0.19.0
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: rich>=14.0.0
+Requires-Dist: selectolax>=0.3.31
+Requires-Dist: sqlalchemy>=2.0.41
+Requires-Dist: tantivy>=0.24.0
+Requires-Dist: tenacity>=9.1.2
+Requires-Dist: typing-inspect>=0.9.0
+Provides-Extra: ai
+Requires-Dist: instructor>=1.9.0; extra == 'ai'
+Requires-Dist: litellm>=1.73.6; extra == 'ai'
+Requires-Dist: qdrant-client>=1.14.3; extra == 'ai'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.10.1; extra == 'mcp'
+Provides-Extra: serve
+Requires-Dist: fastapi>=0.115.6; extra == 'serve'
+Requires-Dist: uvicorn>=0.34.0; extra == 'serve'
+Description-Content-Type: text/markdown
+
+## 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.
+- `hammad-python[serve]` : Contains FastAPI / Uvicorn based resources for serving and running applications.
+
+## 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]'
+
+# or install the `serve` extension
+# pip install 'hammad-python[serve]'
+```
+
+```bash
+uv pip install hammad-python
+
+# or install the `ai` extension
+# uv pip install 'hammad-python[ai]'
+
+# or install the `serve` extension
+# uv pip install 'hammad-python[serve]'
+```
+
+## Basic Usage
+
+### Data Structures, Databases and Other Data Related Resources
+
+#### Collections
+
+Using `hammad.data.collections` is a simple way to create searchable collections of
+data using both `bm25` and `vector` based search.
+
+```python
+from hammad.data.collections import create_collection
+
+# Create either a `vector` or `searchable` collection
+col = create_collection(type = "searchable")
+
+# add anything to the collection
+col.add("This is some text")
+col.add(5)
+col.add({'text' : "this is a dictionary"})
+
+# search the collection
+print(col.query("text"))
+```
+
+#### Databases
+
+Any collection can be either used as a standalone database, or can be added as one
+of the collections within a database. Databases provide a unified interface for handling
+both `Searchable` and `Vector` based collections.
+
+```python
+from hammad.data.collections import create_collection
+from hammad.data.databases import Database
+
+# Create either a `vector` or `searchable` collection
+col = create_collection(type = "searchable")
+
+col.add("This is some text")
+
+# Databases can either be created on memory or using a path
+db = Database(location = "memory")
+
+db.add_collection(col)
+
+# search globally or within a single collection
+print(db.query("text"))
+```
+
+### Styling / Introspection Resources
+
+The `hammad-python` package contains a variety of components that can be used
+to easily style, or run introspection (logging) on your code.
+
+```python
+from hammad.cli import print, input, animate
+
+# Use extended `rich` styling easily
+print("Hello, World", bg_settings = {"title" : "This is a title"})
+
+# Easily collect various forms of input in a single function
+class User(BaseModel):
+    name : str
+    age : int
+
+# TIP:
+# you can style this the same way with `print`
+user = input("Enter some information about yourself: ", schema = User)
+
+# easily run a collection of prebuilt animations
+animate("This is a rainbow!", type = "rainbow", duration = 2, refresh_rate = 20)
+```
+
+Using the various `hammad.logging` resources, you can both create custom & styled
+loggers, as well as easily inspect various aspects of your code during runtime.
+
+```python
+from hammad.logging import Logger
+
+# create standard / file based loggers easily
+logger = Logger("hammad", level = "info", rich = Trues)
+
+file_logger = Logger("hammad-file", level = "info", file = "hammad.log")
+
+# log to the console
+logger.info("This is an info message")
+
+# Use the various `trace_` methods to run various introspection tasks
+from hammad.logging import (
+   trace,
+   trace_cls,
+   trace_function,
+   trace_http
+)
+```

hammad_python-0.0.15/README.md

@@ -0,0 +1,136 @@
+## 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.
+- `hammad-python[serve]` : Contains FastAPI / Uvicorn based resources for serving and running applications.
+
+## 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]'
+
+# or install the `serve` extension
+# pip install 'hammad-python[serve]'
+```
+
+```bash
+uv pip install hammad-python
+
+# or install the `ai` extension
+# uv pip install 'hammad-python[ai]'
+
+# or install the `serve` extension
+# uv pip install 'hammad-python[serve]'
+```
+
+## Basic Usage
+
+### Data Structures, Databases and Other Data Related Resources
+
+#### Collections
+
+Using `hammad.data.collections` is a simple way to create searchable collections of
+data using both `bm25` and `vector` based search.
+
+```python
+from hammad.data.collections import create_collection
+
+# Create either a `vector` or `searchable` collection
+col = create_collection(type = "searchable")
+
+# add anything to the collection
+col.add("This is some text")
+col.add(5)
+col.add({'text' : "this is a dictionary"})
+
+# search the collection
+print(col.query("text"))
+```
+
+#### Databases
+
+Any collection can be either used as a standalone database, or can be added as one
+of the collections within a database. Databases provide a unified interface for handling
+both `Searchable` and `Vector` based collections.
+
+```python
+from hammad.data.collections import create_collection
+from hammad.data.databases import Database
+
+# Create either a `vector` or `searchable` collection
+col = create_collection(type = "searchable")
+
+col.add("This is some text")
+
+# Databases can either be created on memory or using a path
+db = Database(location = "memory")
+
+db.add_collection(col)
+
+# search globally or within a single collection
+print(db.query("text"))
+```
+
+### Styling / Introspection Resources
+
+The `hammad-python` package contains a variety of components that can be used
+to easily style, or run introspection (logging) on your code.
+
+```python
+from hammad.cli import print, input, animate
+
+# Use extended `rich` styling easily
+print("Hello, World", bg_settings = {"title" : "This is a title"})
+
+# Easily collect various forms of input in a single function
+class User(BaseModel):
+    name : str
+    age : int
+
+# TIP:
+# you can style this the same way with `print`
+user = input("Enter some information about yourself: ", schema = User)
+
+# easily run a collection of prebuilt animations
+animate("This is a rainbow!", type = "rainbow", duration = 2, refresh_rate = 20)
+```
+
+Using the various `hammad.logging` resources, you can both create custom & styled
+loggers, as well as easily inspect various aspects of your code during runtime.
+
+```python
+from hammad.logging import Logger
+
+# create standard / file based loggers easily
+logger = Logger("hammad", level = "info", rich = Trues)
+
+file_logger = Logger("hammad-file", level = "info", file = "hammad.log")
+
+# log to the console
+logger.info("This is an info message")
+
+# Use the various `trace_` methods to run various introspection tasks
+from hammad.logging import (
+   trace,
+   trace_cls,
+   trace_function,
+   trace_http
+)
+```

hammad_python-0.0.15/deprecated/hammad/__init__.py

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

hammad_python-0.0.15/deprecated/hammad/ai/__init__.py

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

{hammad_python-0.0.13 → hammad_python-0.0.15/deprecated}/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.15/deprecated}/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,
             )