Python SDK

pip install gravity-sdk

+ import asyncio
+ from gravity_sdk import Gravity

+ gravity = Gravity(production=True)

  @app.post("/api/chat")
  async def chat(request: Request):
      body = await request.json()
      messages = body["messages"]

+     ad_task = asyncio.create_task(
+         gravity.get_ads(request, messages, [{"placement": "below_response", "placement_id": "main"}])
+     )

      async def event_stream():
          async for token in stream_your_llm(messages):
              yield f"data: {json.dumps({'type': 'chunk', 'content': token})}\n\n"

-         yield f"data: {json.dumps({'type': 'done'})}\n\n"
+         ad_result = await ad_task
+         ads = [a.to_dict() for a in ad_result.ads]
+         yield f"data: {json.dumps({'type': 'done', 'ads': ads})}\n\n"

      return StreamingResponse(event_stream(), media_type="text/event-stream")

Gravity(*, api_key=None, api_url=None, timeout=3.0, production=False, relevancy=0.2)

await gravity.get_ads(request, messages, placements, *, production=None, relevancy=None)

@dataclass
class AdResult:
    ads: list[AdResponse]   # Parsed ad objects
    status: int             # 200, 204, 0 (error)
    elapsed_ms: str         # e.g. "142"
    request_body: dict | None
    error: str | None

@dataclass
class AdResponse:
    ad_text: str
    title: str | None
    cta: str | None
    brand_name: str | None
    url: str | None
    favicon: str | None
    imp_url: str | None
    click_url: str | None
    placement: str | None
    placement_id: str | None
    campaign_id: str | None
    # Experiment / composition fields (present when an experiment is active)
    variant: str | None
    experiment_id: str | None
    composition_id: str | None
    renderer_key: str | None
    composition_mode: str | None
    composition: dict | None
    # Lead-form envelope (present only for lead_form ad units)
    lead_form: LeadFormConfig | None

from gravity_sdk import hash_pii

hashed = hash_pii(email=user.email, phone=user.phone)
# Include hashed PII in the gravity_context.user sent from your client:
# { "gravity_context": { "user": { "id": "u123", "email_hash": "...", "hashed_phone": "..." } } }

@dataclass
class LeadFormConfig:
    fields: list[LeadFormField]
    submit_url: str
    headline: str | None
    description: str | None
    cta_text: str | None
    success_message: str | None
    privacy_text: str | None
    consent_text: str | None
    success_redirect_url: str | None
    display: str              # "inline" | "modal-center" | "modal-bottom-right"
    prefill: LeadFormPrefill | None

@dataclass
class LeadFormField:
    name: str
    label: str
    type: str                 # "text", "email", "tel", etc.
    required: bool
    placeholder: str | None
    options: list[str] | None

@dataclass
class LeadFormPrefill:
    email: bool
    phone: bool