raindrop-ai 0.0.53

Raindrop AI (Python SDK)

Raindrop Python SDK

The official Python SDK for Raindrop AI — track AI events, collect user signals, and instrument LLM applications with OpenTelemetry-based tracing.

Installation

pip install raindrop-ai

Requires Python 3.10+

Quick Start

import raindrop.analytics as raindrop

raindrop.init(api_key="your-api-key", tracing_enabled=True)

# Track an AI event
raindrop.track_ai(
    user_id="user-123",
    event="chat-completion",
    model="gpt-4",
    input="What is the weather?",
    output="It's sunny and 72°F.",
    convo_id="conv-456",
)

Payload size limits

As of 0.0.52, text fields (ai input/output, tool span I/O, LLM span content) are capped at 1,000,000 characters per field by default and truncated with a ...[truncated by raindrop] marker. Fields up to 1M chars — i.e. everything the ingest API accepts today — round-trip unchanged. The cap is enforced before (or during) serialization, so oversized payloads cost the cap — not the payload — on your calling thread, and a single capped ASCII field still fits under the 1 MB event-level ingest limit. Tune it via:

raindrop.init(api_key="...", max_text_field_chars=250_000)

A stricter OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT env var is still honored for span content. All outbound HTTP carries finite timeouts, and the atexit shutdown flush runs under a 10s deadline so a dead network can never wedge your process exit.

Projects

Route events to a specific Raindrop project by passing project_id to init(). When set, every outbound request attaches an X-Raindrop-Project-Id: <slug> header so events land under the named project instead of the org default:

raindrop.init(api_key="your-api-key", project_id="my-project")

The header is attached to every channel — manual events (track_ai, identify, track_signal, partial events, direct tool/trace POSTs), the local Workshop mirror, and auto-instrumented OpenTelemetry spans exported via Traceloop — so all telemetry routes to the same project.

Slugs must match ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$ (lowercase alphanumerics and dashes, not starting or ending with a dash). Invalid values are logged as a warning and ignored — no exception is raised and no header is sent. Omitting project_id is fully backward compatible: no header is sent and the server falls back to your org's default project.

Interactions

Use begin() and finish() for multi-step AI workflows:

interaction = raindrop.begin(
    user_id="user-123",
    event="agent-run",
    input="Search for weather data",
    convo_id="conv-456",
)

# Update incrementally
interaction.set_property("region", "us-east")
interaction.add_attachments([
    raindrop.Attachment(type="code", value="print('hello')", language="python")
])

# Complete the interaction
interaction.finish(output="Found weather data for NYC")

Resuming Interactions

Access the current interaction from nested functions:

@raindrop.tool("sentiment_analyzer")
def analyze_sentiment(text: str):
    interaction = raindrop.resume_interaction()
    interaction.set_property("sentiment", "positive")
    return {"sentiment": "positive"}

Decorators

Instrument functions with automatic span creation:

@raindrop.interaction("my_workflow")
def run_workflow():
    ...

@raindrop.task("process_data")
def process():
    ...

@raindrop.tool("search")
def search(query: str):
    ...

Spans

Context Managers

with raindrop.task_span("process_data"):
    result = do_processing()

with raindrop.tool_span("web_search"):
    results = search(query)

Manual Spans

For async or distributed operations where you need explicit control:

span = raindrop.start_span(kind="tool", name="async_search")
span.record_input({"query": "weather"})

# ... later, when the result arrives
span.record_output({"result": "sunny"})
span.end()

Retroactive Tool Logging

Log tool calls after they complete, without wrapping them in spans:

interaction = raindrop.begin(user_id="user-123", event="agent-run")

interaction.track_tool(
    name="web_search",
    input={"query": "weather in NYC"},
    output={"results": ["Sunny, 72°F"]},
    duration_ms=150,
)

interaction.track_tool(
    name="database_query",
    input={"query": "SELECT * FROM users"},
    duration_ms=50,
    error=ConnectionError("Connection timeout"),
)

interaction.finish(output="Done")

Signals

Track user feedback on AI outputs:

# Basic signal
raindrop.track_signal(event_id="evt-123", name="thumbs_up")

# Feedback with comment
raindrop.track_signal(
    event_id="evt-123",
    name="user_feedback",
    signal_type="feedback",
    comment="This answer was helpful",
    sentiment="POSITIVE",
)

# Edit signal
raindrop.track_signal(
    event_id="evt-123",
    name="user_edit",
    signal_type="edit",
    after="The corrected response text",
)

User Identification

raindrop.identify("user-123", traits={"plan": "pro", "company": "Acme"})

PII Redaction

Enable automatic redaction of emails, phone numbers, credit cards, SSNs, and other PII from AI inputs and outputs:

raindrop.set_redact_pii(True)

Auto-Instrumentation

By default, Raindrop auto-instruments detected LLM libraries (OpenAI, Anthropic, Bedrock, etc.) via Traceloop. To disable:

raindrop.init(api_key="your-key", tracing_enabled=True, auto_instrument=False)

Or selectively control which libraries are instrumented:

from raindrop.analytics import Instruments

raindrop.init(
    api_key="your-key",
    tracing_enabled=True,
    instruments={Instruments.OPENAI},
)

Note: When auto-instrumentation is enabled, the SDK automatically suppresses noisy warnings from instrumentors for providers you don't use (e.g. "Error initializing MistralAI instrumentor") and from OTel attribute type validation (e.g. provider SDKs using sentinel types like Omit). Enable set_debug_logs(True) to see these messages for troubleshooting.

Buffering and Performance

All event-tracking calls (track_ai, identify, track_signal, and Interaction.set_input / set_properties / add_attachments / finish) are non-blocking from the caller's perspective. They append to an in-memory buffer that a background daemon thread drains every second by POSTing to the Raindrop API. The HTTP request never runs on the calling thread, so it is safe to call these from a request hot path.

shutdown() is registered via atexit and drains any still-pending events before the process exits. Call flush() explicitly if you need to force a drain at a known point.

# Tune the in-memory buffer size (default 10_000 events)
import raindrop.analytics as raindrop
raindrop.max_queue_size = 500

Configuration

Function	Description
init(api_key, tracing_enabled=False, auto_instrument=True)	Initialize the SDK
init(..., project_id="my-project")	Route events to a named project via the X-Raindrop-Project-Id header
set_debug_logs(True)	Enable debug logging
set_redact_pii(True)	Enable PII redaction
flush()	Flush buffered events
shutdown()	Graceful shutdown (called automatically on exit)

Environment Variables

Variable	Description
TRACELOOP_TRACE_CONTENT	Enable/disable content capture (default: "true")
OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT	Max span attribute value length

Development

# Install dependencies
pip install poetry
poetry install

# Run tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=raindrop

# Run specific test file
poetry run pytest tests/test_analytics.py -v

License

MIT