Metadata-Version: 2.4
Name: adlib-client
Version: 0.1.8
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?"))
```

## Raw response access

When you need ad metadata or success status, use `adify_full()`:

```python
response = adlib.adify_full("My LLM answer text")

if response["success"]:
    print(f"Adified Text: {response['adified']}")
    print(f"Ad Info: {response['ad']}") 
else:
    print(f"Error: {response['error']}")
```

### The Response Format

`adify_full()` returns a dictionary:

```json
{
    "success": true,
    "adified": "...the output with an ad included...",
    "ad": {
        "url": "https://example.com/ad",
        "description": "Check out this product!"
    }
}
```

- `success`: Boolean indicating if the request was processed correctly.
- `adified`: The final string (contains the original text if no ad was added or if an error occurred).
- `ad`: A dictionary containing `url` and `description`. It will be empty `{}` if no ad was inserted.
- `error`: Included only if `success` is `false`.

## 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_full()` sets `success: False` and provides an `error` message, while `adify()` safely returns the original LLM output.

## Notes

- `adlib.adify()` only inserts ads when the text is appropriate.
- You can render the ad metadata separately from the main response text for cleaner UI.
