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

{hammad_python-0.0.14 → 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.14 → hammad_python-0.0.15/deprecated}/hammad/cli/plugins.py

@@ -494,10 +494,6 @@ def _collect_fields_sequentially(schema: Any, console) -> Dict[str, Any]:
     return result
 
 
-@overload
-def input(prompt: str = "") -> str: ...
-
-
 @overload
 def input(
     prompt: str = "",

{hammad_python-0.0.14 → hammad_python-0.0.15/deprecated}/hammad/data/__init__.py

@@ -32,7 +32,6 @@ __all__ = (
     "read_configuration_from_os_vars",
     "read_configuration_from_os_prefix",
     "read_configuration_from_dotenv",
-
     # hammad.data.collections
     "Collection",
     "BaseCollection",
@@ -41,7 +40,6 @@ __all__ = (
     "SearchableCollection",
     "SearchableCollectionSettings",
     "create_collection",
-    
     # hammad.data.databases
     "Database",
     "create_database",

{hammad_python-0.0.14 → hammad_python-0.0.15/deprecated}/hammad/data/collections/base_collection.py

@@ -51,7 +51,7 @@ class BaseCollection(ABC, Generic[Object]):
         self,
         *,
         filters: Optional[Filters] = None,
-        search: Optional[str] = None,
+        query: Optional[str] = None,
         limit: Optional[int] = None,
     ) -> List[Any]:
         """Query items from the collection."""

{hammad_python-0.0.14 → hammad_python-0.0.15/deprecated}/hammad/data/collections/collection.py

@@ -340,7 +340,7 @@ def create_collection(
 
 def create_collection(
     type: Literal["searchable", "vector"],
-    name: str,
+    name: str = "default",
     vector_size: Optional[int] = None,
     *,
     schema: Optional[Any] = None,

{hammad_python-0.0.14 → hammad_python-0.0.15/deprecated}/hammad/data/collections/searchable_collection.py

@@ -287,9 +287,9 @@ class SearchableCollection(BaseCollection, Generic[Object]):
 
     def query(
         self,
+        query: Optional[str] = None,
         *,
         filters: Optional[Filters] = None,
-        search: Optional[str] = None,
         limit: Optional[int] = None,
         offset: int = 0,
         fields: Optional[List[str]] = None,
@@ -310,8 +310,8 @@ class SearchableCollection(BaseCollection, Generic[Object]):
         Query items from the collection using tantivy search.
 
         Args:
+            query: Search query string supporting boolean operators (AND, OR, NOT, +, -)
             filters: Dictionary of filters to apply to results
-            search: Search query string supporting boolean operators (AND, OR, NOT, +, -)
             limit: Maximum number of results to return
             offset: Number of results to skip (for pagination)
             fields: Specific fields to search in (defaults to content field)
@@ -336,7 +336,7 @@ class SearchableCollection(BaseCollection, Generic[Object]):
             return self._storage_backend.query(
                 collection=self.name,
                 filters=filters,
-                search=search,
+                search=query,
                 limit=limit,
                 offset=offset,
                 fields=fields,
@@ -378,16 +378,16 @@ class SearchableCollection(BaseCollection, Generic[Object]):
                 self._tantivy_schema, fields[0] if fields else "content", regex_search
             )
             query_parts.append((tantivy.Occur.Must, search_query))
-        elif search:
+        elif query:
             if phrase:
                 # Phrase query
-                words = search.split()
+                words = query.split()
                 search_query = tantivy.Query.phrase_query(
                     self._tantivy_schema, "content", words, slop=phrase_slop
                 )
             elif fuzzy:
                 # Fuzzy query for each term
-                terms = search.split()
+                terms = query.split()
                 fuzzy_queries = []
                 for term in terms:
                     fuzzy_q = tantivy.Query.fuzzy_term_query(
@@ -405,13 +405,13 @@ class SearchableCollection(BaseCollection, Generic[Object]):
                 # Handle None boost_fields
                 if boost_fields:
                     search_query = self._index.parse_query(
-                        search,
+                        query,
                         default_field_names=fields or ["content", "title"],
                         field_boosts=boost_fields,
                     )
                 else:
                     search_query = self._index.parse_query(
-                        search, default_field_names=fields or ["content", "title"]
+                        query, default_field_names=fields or ["content", "title"]
                     )
 
             query_parts.append((tantivy.Occur.Must, search_query))

{hammad_python-0.0.14 → hammad_python-0.0.15/deprecated}/hammad/data/databases/database.py

@@ -38,9 +38,8 @@ except ImportError:
 from ..collections.base_collection import BaseCollection, Filters, Schema
 from ..collections.collection import create_collection
 
-if TYPE_CHECKING:
-    from ..collections.searchable_collection import SearchableCollection
-    from ..collections.vector_collection import VectorCollection
+from ..collections.searchable_collection import SearchableCollection
+from ..collections.vector_collection import VectorCollection
 
 __all__ = ("Database",)
 
@@ -636,14 +635,22 @@ class Database(Generic[DatabaseEntryType]):
 
     def query(
         self,
+        query: Optional[str] = None,
         *,
         collection: str = "default",
         filters: Optional[Filters] = None,
-        search: Optional[str] = None,
         limit: Optional[int] = None,
         **kwargs,
     ) -> List[DatabaseEntryType]:
-        """Query items from any collection."""
+        """Query items from any collection.
+
+        Args:
+            query: Search query string supporting boolean operators (AND, OR, NOT, +, -)
+            filters: Dictionary of filters to apply to results
+            limit: Maximum number of results to return
+            offset: Number of results to skip (for pagination)
+            fields: List of fields to return
+        """
         # Check modern collections first
         if collection in self._collections:
             coll = self._collections[collection]
@@ -651,13 +658,13 @@ class Database(Generic[DatabaseEntryType]):
             original_backend = coll._storage_backend
             coll._storage_backend = None
             try:
-                return coll.query(filters=filters, search=search, limit=limit, **kwargs)
+                return coll.query(filters=filters, query=query, limit=limit, **kwargs)
             finally:
                 coll._storage_backend = original_backend
 
         # File storage
         if self.location == "file":
-            return self._query_from_file(collection, filters, search, limit)
+            return self._query_from_file(collection, filters, query, limit)
 
         # Traditional in-memory collection logic
         if collection not in self._schemas:
@@ -676,9 +683,9 @@ class Database(Generic[DatabaseEntryType]):
                 continue
 
             # Basic search implementation
-            if search:
+            if query:
                 item_text = str(item["value"]).lower()
-                if search.lower() not in item_text:
+                if query.lower() not in item_text:
                     continue
 
             results.append(item["value"])
@@ -687,6 +694,13 @@ class Database(Generic[DatabaseEntryType]):
 
         return results
 
+    def add_collection(self, collection: BaseCollection) -> None:
+        """Add a collection to the database."""
+        self._collections[collection.name] = collection
+        self._schemas[collection.name] = collection.schema
+        self._collection_ttls[collection.name] = collection.default_ttl
+        self._storage[collection.name] = {}
+
     def __getitem__(self, collection_name: str) -> BaseCollection[DatabaseEntryType]:
         """Get a collection accessor with full IDE typing support."""
         # Return modern collection if it exists
@@ -725,7 +739,7 @@ class Database(Generic[DatabaseEntryType]):
                 limit: Optional[int] = None,
             ) -> List[DatabaseEntryType]:
                 return self._database.query(
-                    collection=self.name, filters=filters, search=search, limit=limit
+                    collection=self.name, filters=filters, query=search, limit=limit
                 )
 
         return DatabaseCollectionAccessor(self, collection_name)
@@ -783,7 +797,7 @@ def create_database(
     schema_builder: Optional[Any] = None,
     writer_memory: Optional[int] = None,
     reload_policy: Optional[str] = None,
-) -> "Database[SearchableCollection]": ...
+) -> Database[SearchableCollection]: ...
 
 
 @overload
@@ -799,7 +813,7 @@ def create_database(
     prefer_grpc: Optional[bool] = None,
     api_key: Optional[str] = None,
     timeout: Optional[float] = None,
-) -> "Database[VectorCollection]": ...
+) -> Database[VectorCollection]: ...
 
 
 def create_database(
@@ -822,7 +836,7 @@ def create_database(
     prefer_grpc: Optional[bool] = None,
     api_key: Optional[str] = None,
     timeout: Optional[float] = None,
-) -> "Database":
+) -> Database:
     """
     Create a database instance optimized for specific collection types.
 

{hammad_python-0.0.14 → hammad_python-0.0.15/deprecated}/hammad/data/models/__init__.py

@@ -8,18 +8,8 @@ from typing import TYPE_CHECKING
 from ...performance.imports import create_getattr_importer
 
 if TYPE_CHECKING:
-    from .base import (
-        Model,
-        field,
-        validator,
-        is_field,
-        is_model,
-        model_settings
-    )
-    from .pydantic import (
-        convert_to_pydantic_model,
-        convert_to_pydantic_field
-    )
+    from .base import Model, field, validator, is_field, is_model, model_settings
+    from .pydantic import convert_to_pydantic_model, convert_to_pydantic_field
 
 
 __all__ = (
@@ -30,7 +20,6 @@ __all__ = (
     "is_field",
     "is_model",
     "model_settings",
-
     # hammad.models.pydantic
     "convert_to_pydantic_model",
     "convert_to_pydantic_field",
@@ -41,4 +30,4 @@ __getattr__ = create_getattr_importer(__all__)
 
 
 def __dir__() -> list[str]:
-    return list(__all__)
+    return list(__all__)

{hammad_python-0.0.14 → hammad_python-0.0.15/deprecated}/hammad/data/types/__init__.py

@@ -24,10 +24,8 @@ __all__ = (
     # hammad.data.types.text
     "BaseText",
     "Text",
-
     # hammad.data.types.file
     "File",
-
     # hammad.data.types.multimodal
     "Audio",
     "Image",

{hammad_python-0.0.14 → hammad_python-0.0.15/deprecated}/hammad/logging/logger.py

@@ -293,7 +293,7 @@ class Logger:
     def __init__(
         self,
         name: Optional[str] = None,
-        level: Optional[Union[str, int]] = None,
+        level: Optional[Union[LoggerLevelName, int]] = None,
         rich: bool = True,
         display_all: bool = False,
         level_styles: Optional[Dict[str, LoggerLevelSettings]] = None,
@@ -899,7 +899,7 @@ def create_logger_level(
 
 def create_logger(
     name: Optional[str] = None,
-    level: Optional[Union[str, int]] = None,
+    level: Optional[Union[LoggerLevelName, int]] = None,
     rich: bool = True,
     display_all: bool = False,
     levels: Optional[Dict[LoggerLevelName, LoggerLevelSettings]] = None,