sidekick-ads 0.2.0

Python SDK for the Sidekick ad-injection API

sidekick-ads

Python SDK for the Sidekick ad-injection API.

Installation

# Core (httpx only)
pip install sidekick-ads

# With aiogram support
pip install sidekick-ads[aiogram]

# With python-telegram-bot support
pip install sidekick-ads[ptb]

Quick start

aiogram 3.x with middleware

from aiogram import Bot, Dispatcher, Router
from aiogram.types import Message
from sidekick_ads import Sidekick
from sidekick_ads.middleware import SidekickMiddleware

bot = Bot(token="BOT_TOKEN")
dp = Dispatcher()
router = Router()
dp.include_router(router)

# Register the middleware — it injects a Sidekick instance into every handler
dp.message.middleware(
    SidekickMiddleware(api_key="sk_xxx", platform_id="plt_xxx")
)


@router.message()
async def handle(message: Message, sidekick: Sidekick):
    llm_response = "Here is your answer..."

    user = message.from_user
    user_id = user.id if user else 0
    language_code = user.language_code if user else None
    is_premium = user.is_premium if user else None

    result = await sidekick.inject(
        user_id=user_id,
        message=llm_response,
        language_code=language_code,
        is_premium=is_premium,
        keyboard=None,  # or an existing InlineKeyboardMarkup
    )

    await message.answer(
        result.message,
        reply_markup=result.keyboard,
    )

aiogram 3.x without middleware

from aiogram import Bot, Dispatcher, Router
from aiogram.types import Message
from sidekick_ads import Sidekick

bot = Bot(token="BOT_TOKEN")
dp = Dispatcher()
router = Router()
dp.include_router(router)

sidekick = Sidekick(api_key="sk_xxx", platform_id="plt_xxx")


@router.message()
async def handle(message: Message):
    llm_response = "Here is your answer..."

    user = message.from_user
    user_id = user.id if user else 0
    language_code = user.language_code if user else None
    is_premium = user.is_premium if user else None

    result = await sidekick.inject(
        user_id=user_id,
        message=llm_response,
        language_code=language_code,
        is_premium=is_premium,
        keyboard=None,  # or an existing InlineKeyboardMarkup
    )

    await message.answer(
        result.message,
        reply_markup=result.keyboard,
    )

python-telegram-bot v20+

from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
from telegram.ext import ApplicationBuilder, CommandHandler, ContextTypes
from sidekick_ads import Sidekick

sidekick = Sidekick(api_key="sk_xxx", platform_id="plt_xxx")


async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    llm_response = "Here is your answer..."

    user = update.effective_user
    user_id = user.id if user else 0
    language_code = user.language_code if user else None
    is_premium = user.is_premium if user else None

    # Example: existing keyboard with one button
    existing_kb = InlineKeyboardMarkup(
        [[InlineKeyboardButton(text="My button", url="https://example.com")]]
    )

    result = await sidekick.inject(
        user_id=user_id,
        message=llm_response,
        language_code=language_code,
        is_premium=is_premium,
        keyboard=existing_kb,
    )

    await update.message.reply_text(
        result.message,
        reply_markup=result.keyboard,
    )


app = ApplicationBuilder().token("BOT_TOKEN").build()
app.add_handler(CommandHandler("start", start))
app.run_polling()

Raw usage (no framework)

import asyncio
from sidekick_ads import Sidekick


async def main():
    sidekick = Sidekick(api_key="sk_xxx", platform_id="plt_xxx")

    result = await sidekick.inject(
        user_id=123456789,
        message="Here is your answer...",
        language_code="en",
        is_premium=False,
    )

    print(result.message)
    print(result.has_ad)
    print(result.impression_id)
    print(result.ad)
    print(result.keyboard)

    await sidekick.close()


asyncio.run(main())

API reference

Sidekick(api_key, platform_id, *, base_url, timeout, platform)

Parameter	Type	Default
api_key	str	required
platform_id	str	required
base_url	str	https://sidekick-ads.com
timeout	float	1.0
platform	str	"telegram"

await sidekick.inject(...) -> InjectResult

Parameter	Type	Default
user_id	int	required
message	str	required
language_code	str | None	None
is_premium	bool | None	None
keyboard	Any | None	None
ad_button_position	str	"bottom"

InjectResult

Field	Type
message	str
has_ad	bool
impression_id	str | None
ad	dict | None
keyboard	Any | None

await sidekick.close()

Closes the underlying HTTP connection pool. The client is automatically recreated on the next inject() call if needed.