promptbid 0.1.0

Python SDK for PromptBid - Real-time bidding platform for AI app monetization

PromptBid Python SDK

A comprehensive Python SDK for interacting with PromptBid's real-time bidding platform for AI app monetization. Supports both synchronous and asynchronous clients for builders (publishers) and advertisers.

Installation

Install the SDK using pip:

pip install promptbid

For async support with HTTP/2:

pip install promptbid[async]

Quick Start

For Builders (Publishers)

Get ads to display in your AI app and record interactions:

from promptbid import PromptBid

# Initialize the client with your API key
pb = PromptBid(api_key="pb_live_your_key_here")

# Request ads for a conversation
ads = pb.get_ads(
    conversation_id="conv_abc123",
    session_id="sess_xyz789",
    message="I need help with Python",
    categories=["IAB1", "IAB2"],
    keywords=["programming", "python"],
    slot_count=2
)

# Display ads and record interactions
for ad in ads:
    print(f"[Sponsored] {ad['headline']}")
    print(f"  {ad['description']}")
    print(f"  {ad['cta_text']} → {ad['cta_url']}")

    # When user clicks the ad
    if user_clicked(ad['impression_id']):
        pb.record_click(ad['impression_id'])

# Get your earnings
earnings = pb.get_builder_earnings()
print(f"Total Earnings: ${earnings.total_earnings:.2f}")
print(f"Pending Payout: ${earnings.pending_payout:.2f}")

pb.close()

For Advertisers

Create and manage ad campaigns:

from promptbid import PromptBid

pb = PromptBid(api_key="ad_live_your_key_here")

# Create a new campaign
campaign = pb.create_campaign(
    name="Summer Sale Campaign",
    bid_amount=2.50,  # $2.50 CPM
    daily_budget=100.0,  # $100/day
    total_budget=1000.0,  # $1000 total
    creative={
        "headline": "Summer Sale - 50% Off",
        "description": "Get ready for summer with our amazing deals",
        "cta_text": "Shop Now",
        "cta_url": "https://example.com/summer-sale",
        "image_url": "https://example.com/image.jpg"
    }
)

print(f"Campaign created: {campaign.id}")
print(f"Status: {campaign.status}")

# List your campaigns
campaigns = pb.list_campaigns(status="active", limit=10)
print(f"Active campaigns: {len(campaigns['items'])}")

# Update a campaign
updated = pb.update_campaign(
    campaign_id=campaign.id,
    bid_amount=3.0,
    daily_budget=150.0
)

# Pause a campaign
paused = pb.pause_campaign(campaign.id)
print(f"Campaign paused: {paused.status}")

# Resume a campaign
resumed = pb.resume_campaign(campaign.id)
print(f"Campaign resumed: {resumed.status}")

# Check your balance
balance = pb.get_advertiser_balance()
print(f"Account Balance: ${balance['balance']:.2f}")

# Add funds
pb.deposit(100.0)  # Deposit $100

pb.close()

Async Support

Use the async client for high-concurrency applications:

import asyncio
from promptbid import AsyncPromptBid

async def main():
    async with AsyncPromptBid(api_key="pb_live_your_key_here") as pb:
        # Get ads
        ads = await pb.get_ads(
            conversation_id="conv_123",
            session_id="sess_456",
            message="Help me"
        )

        # Record clicks in parallel
        tasks = [pb.record_click(ad['impression_id']) for ad in ads]
        results = await asyncio.gather(*tasks)

        # Get earnings
        earnings = await pb.get_builder_earnings()
        print(f"Earnings: ${earnings.total_earnings:.2f}")

asyncio.run(main())

Authentication

The SDK supports two authentication methods:

1. API Key Authentication (recommended)

   pb = PromptBid(api_key="pb_live_xxxx")
   

2. Email/Password Authentication

   pb = PromptBid(api_key="temp_key")
   builder = pb.builder_login(email="[e-mail]", password="your_password")
   # API key is now updated in the client
   

API Reference

Bidding Endpoints (Builders)

get_ads()

Request ads for a conversation context.

ads = pb.get_ads(
    conversation_id="conv_abc123",  # Required
    session_id="sess_xyz789",        # Required
    message="I need help",            # Optional
    categories=["IAB1"],              # Optional
    keywords=["python"],              # Optional
    slot_count=2                      # Optional (1-3)
)

Returns: List of ad dictionaries with fields: impression_id, headline, description, cta_text, cta_url, image_url, position, sponsored

record_click()

Record when a user clicks on a served ad.

success = pb.record_click(impression_id="imp_abc123")

Returns: Boolean indicating success

Builder Profile Endpoints

builder_register()

Register a new builder account.

response = pb.builder_register(
    name="My App",
    email="[e-mail]",
    app_name="ChatBot Pro",
    app_url="https://chatbot.example.com",
    app_description="Advanced AI chatbot",
    categories=["IAB1", "IAB2"],
    password="secure_password"  # Optional
)

builder_login()

Login with email and password.

builder = pb.builder_login(
    email="[e-mail]",
    password="secure_password"
)

get_builder_profile()

Get your builder profile.

profile = pb.get_builder_profile()
print(profile.app_name)
print(profile.monthly_impressions)

update_builder_profile()

Update your builder profile.

updated = pb.update_builder_profile(
    app_name="Updated Name",
    app_url="https://new-url.example.com",
    categories=["IAB1", "IAB3"]
)

get_builder_earnings()

Get your earnings summary.

earnings = pb.get_builder_earnings()
print(f"Total: ${earnings.total_earnings:.2f}")
print(f"Pending: ${earnings.pending_payout:.2f}")
print(f"Last 30 days: ${earnings.last_30_days_earnings:.2f}")
print(f"Impressions: {earnings.impression_count}")

reset_builder_api_key()

Rotate your API key.

builder = pb.reset_builder_api_key()
# The client's API key is automatically updated
print(f"New API key: {builder.api_key}")

Advertiser Profile Endpoints

advertiser_register()

Register a new advertiser account.

response = pb.advertiser_register(
    name="My Company",
    email="[e-mail]",
    company_url="https://company.example.com",
    logo_url="https://company.example.com/logo.png",
    industry="Technology",
    monthly_budget=5000.0,
    daily_budget=500.0,
    password="secure_password"  # Optional
)

advertiser_login()

Login with email and password.

advertiser = pb.advertiser_login(
    email="[e-mail]",
    password="secure_password"
)

get_advertiser_profile()

Get your advertiser profile.

profile = pb.get_advertiser_profile()
print(profile.name)
print(profile.balance)

update_advertiser_profile()

Update your advertiser profile.

updated = pb.update_advertiser_profile(
    company_url="https://new-site.example.com",
    industry="E-commerce",
    daily_budget=600.0
)

get_advertiser_balance()

Get your account balance and spending information.

balance = pb.get_advertiser_balance()
print(f"Balance: ${balance['balance']:.2f}")
print(f"Total Spend: ${balance['total_spend']:.2f}")
print(f"Remaining Budget: ${balance['remaining_budget']:.2f}")

deposit()

Add funds to your account.

updated_profile = pb.deposit(amount=100.0)  # $100

reset_advertiser_api_key()

Rotate your API key.

advertiser = pb.reset_advertiser_api_key()
print(f"New API key: {advertiser.api_key}")

Campaign Endpoints

create_campaign()

Create a new advertising campaign.

campaign = pb.create_campaign(
    name="Summer Sale",
    bid_amount=2.5,
    daily_budget=100.0,
    total_budget=1000.0,
    creative_type="native",
    targeting={
        "categories": ["IAB1", "IAB2"],
        "keywords": ["summer", "sale"],
        "exclude_categories": ["IAB8"]
    },
    creative={
        "headline": "50% Off Summer Sale",
        "description": "Limited time offer",
        "cta_text": "Shop Now",
        "cta_url": "https://example.com",
        "image_url": "https://example.com/ad.jpg"
    },
    frequency_cap=3  # Max 3 impressions per session per day
)

list_campaigns()

List your campaigns with optional filtering.

campaigns = pb.list_campaigns(
    status="active",  # Filter by status
    limit=20,
    offset=0
)

for campaign in campaigns['items']:
    print(f"{campaign.name}: ${campaign.balance:.2f} spent")

print(f"Total campaigns: {campaigns['total']}")

get_campaign()

Get a single campaign.

campaign = pb.get_campaign(campaign_id="camp_abc123")
print(f"CTR: {campaign.ctr:.2f}%")
print(f"Spent: ${campaign.spent:.2f}")

update_campaign()

Update a campaign.

updated = pb.update_campaign(
    campaign_id="camp_abc123",
    bid_amount=3.0,
    daily_budget=150.0,
    creative={
        "headline": "New Headline",
        "description": "New description"
    }
)

pause_campaign()

Pause a campaign.

paused = pb.pause_campaign(campaign_id="camp_abc123")
print(paused.status)  # "paused"

resume_campaign()

Resume a paused campaign.

resumed = pb.resume_campaign(campaign_id="camp_abc123")
print(resumed.status)  # "active"

delete_campaign()

Soft-delete a campaign.

deleted = pb.delete_campaign(campaign_id="camp_abc123")
print(deleted.status)  # "deleted"

Payment Endpoints

create_checkout_session()

Create a Stripe Checkout session for deposits.

session = pb.create_checkout_session(amount=100.0)  # $100
print(f"Checkout URL: {session.url}")

get_payment_history()

Get payment history for your account.

history = pb.get_payment_history(limit=20, offset=0)
for payment in history.payments:
    print(f"{payment.type}: ${payment.amount:.2f} ({payment.status})")

create_builder_connect_account()

Create a Stripe Connect account for payouts.

account = pb.create_builder_connect_account()
print(f"Account ID: {account['account_id']}")

get_builder_onboarding_link()

Get Stripe onboarding link.

link = pb.get_builder_onboarding_link(account_id="acct_abc123")
print(f"Onboarding URL: {link['onboarding_url']}")

request_builder_payout()

Request a payout to your Stripe account.

payout = pb.request_builder_payout(
    amount=500.0,  # $500
    account_id="acct_abc123"
)
print(f"Payout ID: {payout['payout_id']}")
print(f"Status: {payout['status']}")

get_builder_payment_history()

Get payment history for builder account.

history = pb.get_builder_payment_history(limit=20)

Error Handling

The SDK raises specific exceptions for different error types:

from promptbid import (
    PromptBidError,
    AuthenticationError,
    ValidationError,
    NotFoundError,
    RateLimitError,
    ServerError
)

try:
    campaign = pb.get_campaign(campaign_id="nonexistent")
except NotFoundError as e:
    print(f"Campaign not found: {e.message}")
except AuthenticationError as e:
    print(f"Invalid API key: {e.message}")
except ValidationError as e:
    print(f"Invalid parameters: {e.message}")
except RateLimitError as e:
    print(f"Rate limited, retry after {e}")
except ServerError as e:
    print(f"Server error: {e.message}")
except PromptBidError as e:
    print(f"Generic error: {e.message}")

Configuration

Custom Base URL

pb = PromptBid(
    api_key="pb_live_xxxx",
    base_url="https://api.staging.promptbid.ai"
)

Custom Timeout and Retries

pb = PromptBid(
    api_key="pb_live_xxxx",
    timeout=60.0,  # 60 second timeout
    max_retries=5   # Retry up to 5 times
)

Debug Logging

pb = PromptBid(
    api_key="pb_live_xxxx",
    debug=True
)

Context Manager Usage

Both sync and async clients support context managers:

# Sync
with PromptBid(api_key="pb_live_xxxx") as pb:
    ads = pb.get_ads(...)

# Async
async with AsyncPromptBid(api_key="pb_live_xxxx") as pb:
    ads = await pb.get_ads(...)

Models

The SDK includes Pydantic models for type safety:

• Advertiser: Advertiser profile with budget and balance info
• Builder: Builder profile with app details
• Campaign: Campaign with metrics and budget info
• Earnings: Builder earnings summary
• PaymentHistory: Payment transaction record
• CheckoutSessionResponse: Stripe checkout session

Best Practices

1. Store API keys securely: Use environment variables or secrets management

   import os
   api_key = os.getenv("PROMPTBID_API_KEY")
   

2. Use context managers: Ensures proper resource cleanup

   with PromptBid(api_key=api_key) as pb:
       ads = pb.get_ads(...)
   

3. Handle rate limits: Implement exponential backoff

   from promptbid import RateLimitError
   import time
   
   for attempt in range(3):
       try:
           ads = pb.get_ads(...)
           break
       except RateLimitError:
           time.sleep(2 ** attempt)
   

4. Monitor quota: Check available balance before creating campaigns

   balance = pb.get_advertiser_balance()
   if balance['balance'] < campaign_budget:
       raise ValueError("Insufficient balance")
   

Support

For issues, feature requests, or questions:

• Documentation: https://docs.promptbid.ai
• GitHub: https://github.com/promptbid/sdk-python
• Email: [e-mail]

License

MIT License - see LICENSE file for details