Metadata-Version: 2.4
Name: adlib-client
Version: 0.1.9
Summary: Python Package for Monetizing your LLM using AdLib
Author: Daniel
License: MIT
Project-URL: Homepage, https://adlib-site.onrender.com/
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: python-dotenv
Requires-Dist: requests

# adlib-client

A Python wrapper for monetizing LLM output with AdLib.

## Install

Install from PyPI:

```bash
pip install adlib-client
```

## Required API keys

`AdLib` requires two keys:

```env
ADLIB_API_KEY=your_adlib_api_key_here
ADLIB_CHATBOT_PUBLIC_KEY=your_chatbot_public_key_here
```

You can provide them using environment variables (in a `.env` file) or directly when creating `AdLib()`:

```python
from adlib_client import AdLib

adlib = AdLib(
    adlib_api_key="your_adlib_api_key_here",
    adlib_chatbot_api_key="your_chatbot_public_key_here",
)
```

### Authorization on Initialization

When you create an instance of `AdLib()`, it automatically attempts to validate your credentials against the AdLib service. 

- **Success**: The object is initialized and ready for use.
- **Missing Keys**: If either key is missing (and not found in environment variables), an `Exception` is raised immediately.
- **Invalid Keys**: If the keys are provided but rejected by the server, a `ValueError` is raised with the specific error message from the service.

## Basic usage

```python
from adlib_client import AdLib

# Automatically loads keys from environment or .env
adlib = AdLib()

llm_output = "Here is the answer from your model."
adified_output = adlib.adify(llm_output)

print(adified_output)
```

`adlib.adify()` sends text to AdLib and returns the final transformed output string. If an ad is inserted, it's included in the string; otherwise, the original text is returned.

## Use `AdLib` as a decorator

You can wrap your generation functions directly:

```python
from adlib_client import AdLib

adlib = AdLib()

@adlib.adify
def generate_answer(prompt: str) -> str:
    # Your LLM logic here
    answer = ...
    return answer

# The returned value is now automatically adified
print(generate_answer("What is the weather?"))
```

## Error Handling

- **Initialization**: `Exception` for missing keys, `ValueError` for invalid keys.
- **Network Errors**: Failed HTTP requests raise standard `requests` exceptions (e.g., connection issues).
- **Service Errors**: If the adify service fails during a call, `adify()` safely returns the original LLM output.

## Notes

- `adlib.adify()` returns the transformed text string directly.
- Use `adify` when you want to wrap LLM outputs or decorate generation functions.
