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

If either key is missing, `AdLib()` raises an exception immediately.

## Basic usage

```python
from adlib_client import AdLib

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.

## Use `AdLib` as a decorator

```python
from adlib_client import AdLib

adlib = AdLib()

@adlib.adify
def generate_answer(prompt: str) -> str:
    return f"Answer for: {prompt}"

print(generate_answer("What is the weather?"))
```

The decorator wraps your function and automatically adifies its returned text.

## Raw response access

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

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

- `adify_full()` returns the full JSON payload.
- `adify()` returns only the `adified` string.

The response format is:

```json
{
    "adified": "...the output with an ad included...",
    "ad": {
        "url": "url of the ad",
        "description": "description of the ad"
    }
}
```

If no ad is inserted, `ad` is an empty object.
Your app should check `response["ad"]` before rendering ad-specific UI.

Use the `ad` metadata to build stronger interfaces: banners, cards, buttons, or other visual treatments—rather than relying only on the raw `adified` text.

## What to expect

- `AdLib()` only initializes successfully with both keys.
- Missing keys cause an immediate exception.
- Failed HTTP requests raise a requests exception via `response.raise_for_status()`.
- `adify()` returns the final output string.
- `adify_full()` returns the dict with ad metadata.

When `adlib.adify()` succeeds:

- If an ad was inserted, the returned output includes the ad content.
- If no ad was inserted, the returned output is still valid text and `response["ad"]` will be empty.

## 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.
