Metadata-Version: 2.4
Name: hammad-python
Version: 0.0.20
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: nest-asyncio>=1.6.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>=8.2.3
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: all
Requires-Dist: fastapi>=0.115.6; extra == 'all'
Requires-Dist: instructor>=1.9.0; extra == 'all'
Requires-Dist: litellm>=1.73.6; extra == 'all'
Requires-Dist: mcp>=1.10.1; extra == 'all'
Requires-Dist: qdrant-client>=1.14.3; extra == 'all'
Requires-Dist: uvicorn>=0.34.0; extra == 'all'
Provides-Extra: genai
Requires-Dist: fastapi>=0.115.6; extra == 'genai'
Requires-Dist: instructor>=1.9.0; extra == 'genai'
Requires-Dist: litellm>=1.73.6; extra == 'genai'
Requires-Dist: mcp>=1.10.1; extra == 'genai'
Requires-Dist: qdrant-client>=1.14.3; extra == 'genai'
Requires-Dist: uvicorn>=0.34.0; extra == 'genai'
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
)
```
