rippit-sdk 0.4.0

Rippit SDK for logging conversation data

rippit-sdk

The official Python SDK for shipping conversation data to Rippit -- the platform for analyzing AI conversation quality, identifying trends, and improving your AI products.

Use this SDK to log every turn of a conversation (both user messages and assistant responses) so Rippit can provide analytics, quality scoring, and insights across your conversations.

Quickstart

pip install rippit-sdk
export RIPPIT_API_TOKEN="rpt_pat_abc123.xyzSecretTokenValue"

import os
import rippit.sdk
from rippit.sdk import store_conversation_moment

# Pass your token here, or set the RIPPIT_API_TOKEN env var instead (see Configuration).
rippit.sdk.configure(api_token=os.environ["RIPPIT_API_TOKEN"])

# Log the user's message
store_conversation_moment(
    message="What's the weather like today?",
    role="user",
    conversation_id="conv-123",
)

# Log the assistant's response
store_conversation_moment(
    message="The weather today is sunny with a high of 75F.",
    role="assistant",
    conversation_id="conv-123",
    attributes={"model": "gpt-4"},
)

That's it. Each call sends the data to Rippit in the background without blocking your application.

Requirements

• Python 3.9+
• A Rippit API token (get one from the Rippit app settings page or the Rippit CLI)

Configuration

You must provide an API token through one of the two methods below. No other setup is needed -- just provide the token and start calling store_conversation_moment.

Environment variable (recommended for production/CI -- no setup code required):

export RIPPIT_API_TOKEN="rpt_pat_abc123.xyzSecretTokenValue"

When the env var is set, store_conversation_moment picks it up automatically. No call to configure() is needed.

Explicit in code (handy for quick testing):

import rippit.sdk

rippit.sdk.configure(api_token="rpt_pat_abc123.xyzSecretTokenValue")

configure(api_token=...) requires the api_token keyword argument -- it cannot be called without one. It takes priority over the environment variable.

If neither method is used, store_conversation_moment prints a warning and returns a no-op Future -- your application keeps running, but no data is sent.

Usage

Call store_conversation_moment for every turn in a conversation -- both user messages and assistant responses. Use the same conversation_id to tie them together.

from rippit.sdk import store_conversation_moment

# Log a user message
store_conversation_moment(
    message="What's the weather like today?",
    role="user",
    conversation_id="conv-123",
)

# Log an assistant response (include the model)
store_conversation_moment(
    message="The weather today is sunny with a high of 75F.",
    role="assistant",
    conversation_id="conv-123",
    attributes={"model": "gpt-4"},
)

# With some optional params
store_conversation_moment(
    message="Hello from support",
    role="user",
    conversation_id="conv-456",
    attributes={
        "user_id": "user-789",
        "message_id": "msg-001",
    },
)

Parameters

store_conversation_moment(message=..., role=..., conversation_id=..., attributes=...)

Parameter	Required	Description
message	Yes	The message content
role	Yes	One of "user", "assistant", "system", "tool"
conversation_id	Yes	Identifier linking all messages in a conversation
attributes	No	Optional dict with additional fields (see below)

The optional attributes dict accepts:

Attribute	Default	Description
app_dataset_id	"app_dataset"	Dataset to log to (see below)
message_id	""	Unique identifier for this message
user_id	""	Identifier for the user
model	""	Model name (e.g. "gpt-4")
raw_message	""	Full model response payload, if available

You can also pass any additional keys in the attributes dict. These are stored alongside your log data so you can use them to segment, filter, or analyze your conversations however you like.

Datasets

The SDK automatically creates and manages datasets in Rippit. On the first call, the SDK calls /sdk/init to ensure the dataset exists, then caches the result for the lifetime of the process. No manual setup needed.

By default, all logs go to a dataset called "app_dataset". If your application has distinct areas you want to analyze separately, pass a different app_dataset_id:

store_conversation_moment(message="...", role="user", conversation_id="c-1", attributes={"app_dataset_id": "support_logs"})
store_conversation_moment(message="...", role="user", conversation_id="c-2", attributes={"app_dataset_id": "onboarding_logs"})

The following fields are auto-generated by the SDK and do not need to be provided:

Field	Description
created_at	UTC timestamp when the log was created
updated_at	UTC timestamp (same as created_at)

Async behavior

store_conversation_moment sends data to Rippit in a background thread and returns a Future. By default this is fire-and-forget -- your application is never blocked.

If you need to wait for the send to complete (e.g. in a script or test):

future = store_conversation_moment(message="hi", role="user", conversation_id="c-1")
future.result()  # blocks until the POST finishes

Error handling

The SDK is designed to never crash your application. All errors -- network failures, timeouts, server errors, missing fields, invalid roles, and reserved field conflicts -- are caught, logged as warnings to stderr, and a no-op Future is returned. No exceptions are ever raised.

To see network-level debug information:

import logging
logging.getLogger("rippit.sdk").setLevel(logging.DEBUG)

Development Setup

cd sdks/python
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Running Tests

pytest

Running the Smoke Test

export RIPPIT_API_TOKEN="rpt_pat_abc123.xyzSecretTokenValue"
python examples/smoke_test.py

Publishing to PyPI

1. Update the version in pyproject.toml and src/rippit/sdk/_version.py.

2. Build the package:

pip install build
python -m build

1. Upload to PyPI:

pip install twine
twine upload dist/*

To publish to Test PyPI first:

twine upload --repository testpypi dist/*
pip install --index-url https://test.pypi.org/simple/ rippit-sdk