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

hammad_python-0.0.15.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,4 @@
+hammad_python-0.0.15.dist-info/METADATA,sha256=76e_P5ZnWxhhfnyhA0B91cnlFtAxepwavtFancGsUuw,5907
+hammad_python-0.0.15.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+hammad_python-0.0.15.dist-info/licenses/LICENSE,sha256=h74yFUWjbBaodcWG5wNmm30npjl8obVcxD-1nQfUp2I,1069
+hammad_python-0.0.15.dist-info/RECORD,,

hammad/__init__.py

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

hammad/ai/__init__.py

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

hammad/ai/_utils.py

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

hammad/ai/completions/__init__.py

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