SDK · Python 3.10+
LlamaIndex AI ads integration.
Surfacedd integration for LlamaIndex query engines, chat engines, and agents. Python and TypeScript bindings.
Install
# Python pip install surfacedd-llamaindex
Import
from surfacedd_llamaindex import SurfaceddQueryEngineWrapper
Initialize
query_engine = SurfaceddQueryEngineWrapper(
base=index.as_query_engine(),
app_id='app_xxx',
)Fetch a sponsored answer
response = query_engine.query('Which CRM should I use?')Features
- Query engine wrapper (drop-in replacement)
- Chat engine wrapper with streaming support
- Agent integration via tool-call sponsored recommendations
- RAG-aware: sponsored results differentiated from retrieved context
- Attribution preserved: cited sources, disclosed sponsors
Install in three steps
- Install. pip install surfacedd-llamaindex.
- Wrap your query engine. Replace query_engine = index.as_query_engine() with SurfaceddQueryEngineWrapper(base=index.as_query_engine(), app_id="app_xxx").
- Render sponsored blocks. Consume response.sponsored (a list of sponsored surfaces) in your UI and render them with the provided "Sponsored" label component.
Frequently asked questions
Does it work with any LlamaIndex retriever?
Yes. The wrapper sits at the query/chat engine layer, which is retriever-agnostic. Vector stores (Pinecone, Weaviate, Chroma, Qdrant), graph stores, and hybrid retrievers all work.
How does it distinguish sponsored content from retrieved context?
Sponsored blocks are returned in a separate field on the response object and tagged with source_type="sponsored". Your UI layer renders them with a distinct visual treatment and the "Sponsored" label.
Does it support agent workflows?
Yes. For agent-based LlamaIndex apps, we provide a SurfaceddSponsoredToolSpec that registers as a tool the agent can choose when a commercial action is the best next step.
Related SDKs
Ready to ship ads in your LlamaIndex app?
Join the waitlist for SDK access. 60% revenue share, no minimums, no contracts.