Metadata-Version: 2.4
Name: notpixel
Version: 0.2.0
Summary: NotPixel Python SDK — Privacy-first contextual ads for LLM applications (FastAPI, Django, LangChain, CrewAI)
Project-URL: Homepage, https://notpixel.ai
Project-URL: Documentation, https://docs.notpixel.ai/http-api
Project-URL: Repository, https://github.com/Cocco-Enterprises/notpixel
Author-email: NotPixel <dev@notpixel.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: Contextual-ads,ads,ai,fastapi,langchain,llm,monetization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: fastembed<1,>=0.7.0
Requires-Dist: httpx>=0.25.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# NotPixel Python SDK (`notpixel`)

Official Python SDK for **NotPixel** — privacy-first contextual monetization for LLM applications, agents, and backends (**FastAPI, Django, Flask, LangChain, LlamaIndex, CrewAI**).

## Installation

```bash
pip install notpixel
```

## Quick Start (Async — FastAPI / LangChain)

```python
from notpixel import AsyncAds

# Ad matching uses local embeddings automatically.
# Prompt text is not sent to the NotPixel API.
ads = AsyncAds(publisher_id="pub_10565")

# 1. Fetch a contextual ad + run your LLM in parallel (best-effort)
result = await ads.respond(
    input="How do I optimize PostgreSQL queries with indexes?",
    llm=lambda: call_my_llm("How do I optimize PostgreSQL queries with indexes?"),
)
print(result.text)  # LLM response + sponsored ad block (if matched)

# 2. Track events
if result.ad:
    await ads.impression(result.ad)
    await ads.track_click(result.ad, metadata={"source": "fastapi_chat"})
    await ads.track_conversion(
        result.ad,
        type="signup",
        value_cents=2900,
        external_id="order_12345",
    )
```

## Synchronous Usage (Django WSGI / Scripts)

```python
from notpixel import Ads

ads = Ads(publisher_id="pub_10565")
ad = ads.get_ad(input="Best serverless Postgres database")
if ad:
    print(ad.text)
    ads.track_click(ad)
```

## Privacy

Ad matching uses local embeddings automatically. The SDK sends a numerical vector
to NotPixel instead of the prompt text. No privacy flag is needed.

If the local model cannot generate an embedding, `get_ad()` reports the error through
`on_error` and returns `None`, without sending the prompt to NotPixel.

Your LLM calls remain under your application's control and follow your provider's
own data handling rules. Keep personal data out of optional context and event metadata.
