Skip to main content
Use the gravity-sdk package to request Gravity ads from your Python server. This page describes version 0.1.0, the version on PyPI. For the terms on this page, see Core concepts.

Before you start

  • Your server runs Python 3.10 or later.
  • You have a Gravity API key. Get it from your dashboard under Settings → Platform Settings.
  • Your web client calls gravityContext() from @gravity-ai/api and posts the result as gravity_context. See Prepare the context.

Install

  1. Install the package. Its only dependency is httpx.
  2. Set GRAVITY_API_KEY in your server environment.

Quick start

Add these lines to the chat endpoint that streams your model response. The ad request runs at the same time as your model call, so it does not delay the response.
The last event of the stream contains the ads. When no ad matches, ads is an empty list. The SDK works with FastAPI, Starlette, Django, and Flask.

Constructor

The client keeps its HTTP connection pool between calls. To close it, use async with Gravity() as g: or call await gravity.close().

get_ads()

get_ads() reads gravity_context (session, user, and device) from the body of the request. It adds the end user’s IP address from the request headers. It does not make a device object. Your browser client must call gravityContext() and post the result, and your backend must keep it in the body.
Forward the device object from the client, with device.ip and device.ua, in each request. If the request has no end-user ua and ip, Gravity cannot run fraud and bot detection on it, and the Device and Geography reports do not include it. See Device signals.
get_ads() never raises an exception. On any failure, it returns an AdResult with an empty ads list. You can await it at the end of your stream with no risk to the stream.

User tags and model usage

user.tags travel in the gravity_context.user your client posts, next to the user ID: { "gravity_context": { "user": { "userId": "u123", "tags": { "plan": "free" } } } }. See Understand what your users earn you for the rules.
gravity-sdk doesn’t have a model usage option. To report model usage, send it in a direct HTTP request to the ad API: see Report model usage.

Return types

Both classes have a to_dict() method. It returns the camelCase JSON shape that the JavaScript renderers use.
AdResponse in version 0.1.0 keeps only the fields above. It drops renderer_spec, brandImage, and the experiment fields. A React GravityAd that gets these ads shows the built-in text card.

Messages that the SDK sends

The SDK sends the last two conversation messages to Gravity for contextual matching. It keeps only messages with these roles:
  • user, assistant, system, developer, and model (the Gemini name for assistant)
The SDK removes messages with other roles (for example tool, function, or ipython), because they usually contain structured data, not natural language.

Experiments

Gravity runs experiments on the server. Return the ad as usual and show it with the standard SDK component. You do not need experiment code.

Troubleshoot