onstoa 0.2.11

Business telemetry and payments SDK for AI products

Stoa Python SDK

Business telemetry and payments for AI products.

Stoa instruments native AI provider clients, attaches your application's user_id, and helps you understand which users, features, and product areas are driving AI usage, cost, and outcomes.

Installation

pip install onstoa

Quick Start

from openai import OpenAI
from stoa import Stoa

stoa = Stoa()

# Idempotently create or update the user profile in Stoa.
stoa.identify(
    user_id=user.id,
    metadata={"plan": "pro"},
)

# Build the native provider client in your app, then wrap it with Stoa.
openai = stoa.openai(
    OpenAI(timeout=30),
    user_id=user.id,
)


@stoa.context(feature="summary_export", product="docs")
def generate_summary(document: str):
    response = openai.responses.create(
        model="gpt-4.1-mini",
        input=f"Summarize this document:\n\n{document}",
    )

    stoa.track(
        "summary_export.completed",
        user_id=user.id,
        metadata={"format": "pdf"},
    )

    return response

Identify Users

Call identify when a user signs up, logs in, or when you want to sync stable user metadata.

stoa.identify(
    user_id="user_123",
    metadata={
        "plan": "enterprise",
        "workspace_id": "ws_456",
    },
)

identify is idempotent. It creates the user profile if it does not exist and updates metadata if it does. It does not set active identity; provider instrumentation and custom events still require an explicit user_id.

Instrument AI Providers

Construct provider clients exactly as you would without Stoa, then pass them to Stoa.

from openai import OpenAI

openai = stoa.openai(
    OpenAI(api_key="sk-...", timeout=30, max_retries=2),
    user_id=user.id,
)

Every provider call made through the returned client is attributed to that user_id.

OpenAI

openai = stoa.openai(OpenAI(), user_id=user.id)

response = openai.responses.create(
    model="gpt-4.1-mini",
    input="Write a release note",
)

Anthropic

from anthropic import Anthropic

anthropic = stoa.anthropic(Anthropic(), user_id=user.id)

message = anthropic.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a release note"}],
)

ElevenLabs

from elevenlabs.client import ElevenLabs

elevenlabs = stoa.elevenlabs(ElevenLabs(), user_id=user.id)

audio = elevenlabs.text_to_speech.convert(
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_multilingual_v2",
    text="Welcome back",
)

OpenRouter

openrouter = stoa.openrouter(
    OpenAI(
        api_key=os.environ["OPENROUTER_API_KEY"],
        base_url="https://openrouter.ai/api/v1",
    ),
    user_id=user.id,
)

Add Context

Use context to attach feature, product, workflow, experiment, or route metadata to work done inside a scope.

with stoa.context(feature="chat", product="assistant"):
    openai.responses.create(...)

context can also be used as a decorator.

@stoa.context(feature="summary_export", product="docs")
def generate_summary(document: str):
    return openai.responses.create(
        model="gpt-4.1-mini",
        input=document,
    )

Nested context merges automatically. Inner values override outer values.

Track Custom Events

Use track for product or business events Stoa cannot infer from provider calls.

stoa.track(
    "report.exported",
    user_id=user.id,
    metadata={
        "format": "csv",
        "rows": 1200,
    },
)

Tracked events inherit active context metadata.

Create Payments

Use create_payment when you want to start a Stripe payment flow for a user.

payment = stoa.create_payment(
    user_id=user.id,
    email=user.email,
    return_url="https://app.example.com/billing/return",
)

redirect_user_to(payment.checkout_url)

Billing Webhooks

Stoa's SDK does not block AI provider calls by default.

Use webhooks to react to billing events such as:

balance.low
balance.depleted
payment.succeeded
payment.failed
subscription.updated

Your app decides what to do when those events arrive, such as notifying the user, prompting for payment, or changing access.

Environment Variables

STOA_API_KEY=...
STOA_BASE_URL=https://www.onstoa.com/api