SDK · Python 3.10+
Python AI ads SDK.
The core Python SDK. Framework-agnostic, async-first, and the foundation for the LangChain and LlamaIndex integrations.
Install
pip install surfacedd
Import
from surfacedd import Surfacedd
Initialize
client = Surfacedd(app_id='app_xxx')
Fetch a sponsored answer
ad = await client.fetch_sponsored_answer(query=user_query)
Features
- Python 3.10+ with full type hints
- Async-first (asyncio) with sync fallback
- httpx-based HTTP layer
- Framework-agnostic — works with FastAPI, Django, Flask, LangChain, LlamaIndex
- Streaming-aware: sponsored surfaces compose with your streaming response
Install in three steps
- Install. pip install surfacedd.
- Instantiate the client. Create a Surfacedd client once (client = Surfacedd(app_id='app_xxx')) at app startup and reuse it.
- Fetch sponsored answers. Call await client.fetch_sponsored_answer(query=user_query) and merge the result into your AI app's response payload.
Frequently asked questions
Which Python versions are supported?
Python 3.10 and above. We target the current three major Python versions and drop support when a version reaches end-of-life.
Can I use it synchronously?
Yes. Every async method has a sync sibling (fetch_sponsored_answer_sync). We recommend async inside FastAPI, LangChain, and LlamaIndex, and sync inside Flask and Django views.
How does it differ from the LangChain and LlamaIndex integrations?
The core Python SDK exposes the raw ad-fetching API. The LangChain and LlamaIndex packages are wrappers that integrate it into those frameworks' callback and query-engine patterns. Use this SDK when you are building a framework-free Python app.
Related SDKs
Ready to ship ads in your Python app?
Join the waitlist for SDK access. 60% revenue share, no minimums, no contracts.