Cognatu SDKs — on-device ad matching, seven platforms

Choose a platform

Pick your SDK

Every SDK exposes the same shape: a client (or middleware) configured with your publisher ID and gateway URL, one call per turn/screen, and an on-device ZKP wallet that's on by default.

Go

Reference implementation

Contextual ad injection for Go LLM apps. Every other Cognatu SDK ports from or calls into this implementation via FFI/WASM/gomobile. Not yet on a module proxy under its own path — import directly from this repo's module.

Install

go get github.com/shirishgarg/cognatu@latest

Quickstart

import "github.com/shirishgarg/cognatu/pkg/sdk"

mw := sdk.NewMiddleware(sdk.Config{
    PublisherID:   "pub_your_id",
    GatewayURL:    "https://gateway.cognatu.com",
    GatewayAPIKey: "pub_key_...",              // authenticates auction calls — server-side only
    UpstreamURL:   "https://api.groq.com/openai",
    APIKey:        os.Getenv("GROQ_API_KEY"),  // upstream LLM credential, NOT the gateway key
    LLMModel:      "llama-3.3-70b-versatile",
})
http.Handle("/v1/chat/completions", mw)

Middleware wraps any OpenAI-compatible chat completions endpoint: it forwards the request upstream, extracts a conversation context from the messages + response, runs the ad auction, and — on a win — appends a clearly labelled sponsored block before returning.

Python

FastAPI · Starlette · Django ASGI

Contextual ad injection for Python LLM apps. Matching, topic decay, and ZKP proving run on-device in your own process.

Install

pip install cognatu

Quickstart — zero-code (ASGI middleware)

from cognatu import CognatuMiddleware

app.add_middleware(
    CognatuMiddleware,
    publisher_id="pub_your_id",
    gateway_url="https://gateway.cognatu.com",
    api_key="pub_key_your_gateway_key",
)

Quickstart — explicit client

from cognatu import CognatuClient

client = CognatuClient(
    publisher_id="pub_your_id",
    gateway_url="https://gateway.cognatu.com",
    api_key="pub_key_your_gateway_key",
)

# Async (FastAPI, async Django)
enriched = await client.enrich(messages, llm_response_text)

# Sync (Flask, Django sync views)
enriched = client.enrich_sync(messages, llm_response_text)

Use the middleware when you want zero code changes; use the explicit client when you call the LLM yourself and want control over when/where the ad appears — works with the OpenAI SDK, LangChain, liteLLM, etc.

iOS (Swift)

iOS 15+ / macOS 12+

Contextual ad injection for native iOS/macOS apps. Matching and ZKP proving both run on-device via a real Groth16 prover (BN254). Not yet on a registry (SPM index or CocoaPods trunk) — add as a local or git-URL Swift Package dependency.

Quickstart

let cognatu = CognatuClient(
    publisherID: "pub_your_id",
    gatewayURL: "https://gateway.cognatu.com",
    persistWallet: true, // wallet persistence across app restarts (Keychain)
)
let result = await cognatu.auction(screenName: "ArticleDetail", contentText: article.body)
if result.won, let ad = result.winningAd {
    CognatuAdView(ad: ad, result: result, client: cognatu)
}

Building or running without the native ZKP library present still works — wallet construction degrades to no wallet rather than crashing; require_proof line items just won't match.

Android (Kotlin)

JDK 17

Contextual ad injection for native Android apps. Matching and ZKP proving both run on-device, backed by the same Go/Groth16 prover every other Cognatu SDK uses. Not yet on Maven — add as a Gradle source dependency.

Quickstart

val cognatu = CognatuClient(
    publisherID = "pub_your_id",
    gatewayURL  = "https://gateway.cognatu.com",
    context     = applicationContext, // wallet persistence across app restarts
)
val result = cognatu.auction(screenName = "ArticleDetail", contentText = article.body)
if (result.won) CognatuAdCard(ad = result.winningAd!!, result = result, client = cognatu)

Pass any Android Context (application context is fine) and wallet attribute history is saved to EncryptedSharedPreferences.

React Native

Expo & bare RN · Android + iOS

Contextual ad injection for React Native / Expo apps. Matching and ZKP proving both run on-device on both platforms, via each platform's own native module. Not yet on npm — point package.json at a path or git URL.

Install

npm install /path/to/cognit/pkg/sdk/react-native
# or: npm install github:shirishgarg/cognatu#path:pkg/sdk/react-native

Quickstart

import { CognatuClient, CognatuAdView } from 'cognatu-rn';

const cognatu = new CognatuClient({
  publisherID: 'pub_your_id',
  gatewayURL: 'https://gateway.cognatu.com',
});

<CognatuAdView client={cognatu} screenName="ArticleDetail" contentText={article.body} />

Reuse one CognatuClient across screens — only the client instance holds the decay-accumulated topic state that makes multi-screen targeting work. Call resetConversation() when the user starts an unrelated task.

Browser JS

Any static site or SPA

No build step, no package — a single script tag. Matching and (optional) ZKP proving both run in the browser via WASM; the WordPress plugin is just this same script enqueued for you.

Quickstart — content slot

<script src="https://gateway.cognatu.com/sdk.js" data-pub="pub_pk_..." async></script>
<div data-cognatu-slot></div>

Quickstart — conversational mode (chat widgets)

<script src="https://gateway.cognatu.com/sdk.js" data-pub="pub_pk_..." data-mode="conversation" async></script>
<script>
  window.Cognatu.matchTurn(userText, onStep);
</script>

ZK proving is on by default — add data-disable-wallet="true" to opt out and guarantee the ~4.8MB proving WASM module is never fetched (matching-only WASM is 1.65MB and always loads).

WordPress

WordPress 5.9+ · PHP 7.4+

A thin plugin that enqueues the Browser JS SDK above with your publisher key — all on-device matching and ZKP proving happen in that same script, WordPress just wires up the settings page and shortcode.

Install (development)

cp -r pkg/sdk/wordpress /path/to/wp-content/plugins/cognatu-ads

Activate the plugin, then configure under Settings → Cognatu Ads (publisher ID, gateway URL, timeout, wallet toggle). Add [cognatu_ad] to any post, page, or widget — no code required.

Under the hood

What "on-device" actually means

Identical pipeline across all seven SDKs — only the runtime changes.

STEP 01

Classify locally

A tiny word-vector model, fetched and cached once, embeds and classifies the conversation/page text into topic scores — in-process, on text you already have in memory.

STEP 02

Match locally

Topic scores (with decay across turns) match against a cached catalog, producing an opaque line-item shortlist — never a relevance score, never the raw text — sent to the gateway.

STEP 03

Prove locally (optional)

Line items that require proof are proven against an on-device ZKP wallet — real Groth16 over BN254, on by default, gracefully degrading to "no wallet" if the native library isn't present.

Reference

Common config fields

Field names vary slightly by language convention (camelCase vs. snake_case vs. PascalCase); the shape is identical everywhere.

Field	Required	Notes
publisherID	Yes	Identifies your account in the ad auction.
gatewayURL	Yes	Defaults to `https://gateway.cognatu.com` in every SDK.
gatewayAPIKey / apiKey	Server-side SDKs only	Authenticates auction calls — server-side secret, never shipped to a client/device.
persistWallet	No	Persists the ZKP wallet across app restarts (Keychain on iOS, EncryptedSharedPreferences on Android).
disableZkpWallet	No	Opts out of the on-device ZKP wallet — on by default everywhere.

One SDK call.Matching stays on-device.

Pick your SDK

Go

Python

iOS (Swift)

Android (Kotlin)

React Native

Browser JS

WordPress

What "on-device" actually means

Classify locally

Match locally

Prove locally (optional)

Common config fields

One SDK call.
Matching stays on-device.