How It Works
Penguin connects AI agents with businesses through a real-time ad auction system powered by semantic matching.
The flow
User Message → Your Agent → Penguin SDK → Ad Auction → Matched Results → Your Agent → User
- User sends a message to your AI agent
- Your agent calls
decideFromContext()with the message as context - Penguin generates embeddings (OpenAI text-embedding-3-small) from the context
- Semantic matching finds campaigns with similar embeddings (cosine similarity + Cohere reranking)
- Second-price auction ranks eligible ads by quality-adjusted bid
- Results returned with HMAC-signed tracking URLs
- Impressions auto-tracked by the SDK
- Clicks billed when users follow the tracking URL
Matching pipeline
1. Semantic matching (primary)
Your user's context is embedded and compared against campaign embeddings using pgvector cosine similarity. A minimum threshold of 0.25 filters out irrelevant matches.
2. Cohere reranking
Candidates are reranked using Cohere's cross-encoder for more accurate relevance scoring. Scores above 0.7 are trusted directly; lower scores use a normalized cosine rescaling.
3. IAB taxonomy fallback
If semantic matching returns no results (e.g., embeddings unavailable), the system falls back to IAB Content Taxonomy 3.0 category matching.
Auction mechanics
- Second-price auction: The winner pays $0.01 more than the second-highest bid, not their full bid
- Quality-adjusted ranking: Final score = bid × quality_score × relevance_score
- Position tracking: Each returned ad includes its auction position for transparency
Billing model
| Event | Who pays | Who earns |
|---|---|---|
| Impression | Free | — |
| Click (static offer) | Advertiser | Developer gets 70% |
| Session start (dynamic capability) | Advertiser | Developer gets 70% |
| Service completion | Advertiser | Developer gets 70% |
All click billing uses HMAC-signed tokens to prevent tampering. The track-click endpoint validates the token, charges the advertiser's wallet atomically, and creates the developer's earnings record before redirecting to the destination URL.
Security
- HMAC-signed tracking URLs — Click URLs contain a signed JWT that encodes the ad unit, agent, clearing price, and timestamp. Cannot be forged.
- Impression-gated clicks — An impression must be recorded before a click earns revenue (anti-fraud).
- Rate limiting — Distributed, database-backed rate limits per IP and per API key.
- Input validation — All payloads validated server-side with size limits and sanitization.
Dynamic capabilities
Some campaigns offer interactive sessions instead of static links. These let your users:
- Get personalized quotes
- Book appointments
- Compare plans
- Fill out applications
Sessions are managed through the client.sessions.* API. Each session runs an LLM-powered business agent with RAG (retrieval-augmented generation) from the advertiser's knowledge base.
See Sessions Guide for details.