Context processing

Choose where to process context for ad matching. NotPixel manages the model and precision in both modes. Your application’s calls to its chosen LLM provider are separate from this choice.

Local: the default

Install notpixel and use its default client:

import Ads from 'notpixel';
const ads = new Ads({ publisherId: 'pub_10565' });
const ad = await ads.getAd({ input: 'How do I optimize PostgreSQL?' });

from notpixel import Ads
# Install notpixel for local processing.
ads = Ads(publisher_id="pub_10565")
ad = ads.get_ad(input="How do I optimize PostgreSQL?")

The SDK sanitizes email/phone patterns and limits input locally. It generates a 384-dimensional vector and sends that vector to NotPixel. If local processing fails, no text is sent as a fallback. The SDK returns no ad and reports the failure through its error hook; the LLM answer can continue.

Remote: explicit choice

import Ads from 'notpixel';
const ads = new Ads({
  publisherId: 'pub_10565',
  embeddingMode: 'remote',
});

from notpixel import Ads
ads = Ads(publisher_id="pub_10565", embedding_mode="remote")

Remote mode sends sanitized context to NotPixel and its Cloudflare inference infrastructure. It does not initialize or download a local model. The default package includes the local runtime. NotPixel uses the generated vector for the same ad search and auction. Context text is not stored in NotPixel’s database or request logs. Remote processing is subject to publisher eligibility and included usage limits.

There is no automatic switch between modes. If remote processing is unavailable, limited or times out, ad selection returns no ad while the LLM answer continues.

Preloading and status

In local mode, you can move the initial model download to startup:

await ads.embedding.preload({ onProgress: p => console.log(p.status, p.progress) });
console.log(ads.embedding.info());

ads.embedding.preload()  # await with AsyncAds
print(ads.embedding.info())

In remote mode, preloading is a no-op and does not download a model. The status includes the configured mode and does not claim a local model is loaded.

Inspect requests

Local ad requests contain embedding; remote requests contain input. Neither requires a REST mode parameter. Optional context and event metadata are sent as provided, so keep personal data out of them. Vectors carry semantic information and should not be assumed anonymous.

See the HTTP API guide, installation assistant and Network Inspector.