Python SDK - NotPixel Docs

The Python SDK offers synchronous Ads and asynchronous AsyncAds for backend ad selection, inference, streaming and event tracking, with backend inference and streaming across 18 provider/gateway routes.

Installation

Install directly for local processing (the default):


python -m pip install 'notpixel'

Configure publisher_id in code, as below. For remote processing, use the same installation and import Ads or AsyncAds from notpixel.remote. Package installation has no prompts; SDK usage does not require CLI login.

For optional assisted setup, install the base package and run:


python -m pip install notpixel
python -m notpixel install

The English assistant offers login or account creation, asks local/remote, uses the same package for both modes and generates configuration. Either installation path works with new or existing accounts. Python does not require Node.js.

Usage


from contextlib import aclosing
from notpixel import AsyncAds
 
# Set the API key for your chosen provider.
ads = AsyncAds(publisher_id="pub_xxx", model="openai/your-model")
result = await ads.offer(input="How can I optimize PostgreSQL?")
print(result.text)
 
async with aclosing(ads.stream(input="Explain database indexes")) as stream:
    async for chunk in stream:
        if chunk.type in ("text", "ad"):
            print(chunk.content, end="")
 
batch = await ads.ads_batch(inputs=["SQL", "Hosting"], max_concurrency=8)
await ads.prefetch(["SQL", "Hosting"])

Both clients support the 18 provider prefixes of the JavaScript SDK, custom LLM callbacks with respond, local embeddings, cache, batch/prefetch, impression, click, conversion and feedback. Sync methods use normal calls/iteration; async methods use await and async for.

Ad selection defaults to local processing. Choose embedding_mode="remote" to send sanitized context to NotPixel without installing FastEmbed. offer and stream send the original prompt to the chosen LLM provider and append a separate sponsored block after inference. An ad failure preserves the LLM response. Use test_mode=True to preview real ads without tracking or spend.

Streaming yields text, an optional final ad, and done. Inference errors yield error and then raise on the next iteration. Close iterators on early exit; cancelling the consuming asyncio task also closes upstream HTTP streams.

Ad requests default to 1500 ms; inference uses llm_timeout_ms=60000. Model and locale may be configured per call, in the constructor, or through NOTPIXEL_MODEL / NOTPIXEL_LOCALE. Provider keys use the same environment names as the JavaScript SDK. Logs are opt-in and can contain prompt/output text.

See the Python README for all options and the parity matrix for automated coverage and runtime differences. FastAPI and Django examples are included with the source distribution. Automated coverage uses simulated transports; live provider/model availability is separate.