raindrop-dspy

Raindrop observability integration for DSPy. Wraps DSPy modules (Predict, ChainOfThought, etc.) to automatically capture input fields, output fields, model name, and token usage.

Installation

pip install raindrop-dspy dspy

Quick Start

import dspy
from raindrop_dspy import RaindropDSPy

raindrop = RaindropDSPy(api_key="rk_...", user_id="user-123")

lm = dspy.LM("openai/gpt-4o-mini")
dspy.configure(lm=lm)

predict = dspy.Predict("question -> answer")
wrapped = raindrop.wrap(predict)

result = wrapped(question="What is the capital of France?")
print(result.answer)

raindrop.shutdown()

Projects

Route events to a specific project by passing its slug as project_id:

raindrop = RaindropDSPy(
    api_key="rk_...",
    project_id="support-prod",
)

project_id sets the X-Raindrop-Project-Id header on every event. Omit it (or pass "default") to use your org's default Production project, which is the existing behavior. The same option is accepted by the create_raindrop_dspy(...) factory. Invalid slugs are ignored with a warning and no header is sent.

Debug Mode

Enable verbose logging to troubleshoot issues:

raindrop = RaindropDSPy(api_key="rk_...", debug=True)

Factory Function (Legacy)

The create_raindrop_dspy factory function is still available for backwards compatibility:

from raindrop_dspy import create_raindrop_dspy

raindrop = create_raindrop_dspy(
    api_key="rk_...",
    user_id="user-123",
    tracing_enabled=True,
    bypass_otel_for_tools=True,
)
wrapped = raindrop.wrap(predict)

What Gets Captured

API Reference

RaindropDSPy(api_key=None, user_id=None, convo_id=None, project_id=None, tracing_enabled=True, bypass_otel_for_tools=True, disable_auto_instrument=True, debug=False)

Create a new Raindrop DSPy integration instance.

Library auto-instrumentation is opt-in

As of 0.0.4, disable_auto_instrument defaults to True: the integration no longer lets Traceloop monkey-patch every LLM client library it recognizes in your process (including the OpenAI client DSPy drives through LiteLLM). The wrapper captures input/output, token usage, and model name directly from the wrapped module's forward() calls and DSPy LM history, so no library patching is needed for full dashboards.

If you specifically want LLM-call-level spans from library instrumentation and have verified compatibility in your environment, opt back in with disable_auto_instrument=False.

Methods

Identifying Users

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

Tracking Signals

raindrop.track_signal(
    event_id="evt-abc",
    name="thumbs_up",
    signal_type="feedback",
    sentiment="POSITIVE",
    comment="Great response!",
)

Flushing and Shutdown

raindrop.flush()     # flush pending data
raindrop.shutdown()  # flush + release resources

Async Support

DSPy modules with async forward methods are automatically detected and wrapped:

import dspy
from raindrop_dspy import RaindropDSPy

raindrop = RaindropDSPy(api_key="rk_...")

class AsyncPredict(dspy.Module):
    async def forward(self, question: str) -> dspy.Prediction:
        ...

wrapped = raindrop.wrap(AsyncPredict())
result = await wrapped(question="Hello")

Tool catalog capture (ai.prompt.tools)

Every model span records the native tools DSPy passed to the LM on that call as ai.prompt.tools: an OTel string array, one JSON document per tool with name, description and the full JSON Schema as inputSchema ({"type": "function", ...}). The capture is exact, per LM call: while a wrapped module's forward runs, the wrapper installs a DSPy callback (through dspy.context(callbacks=...)) whose on_lm_start receives the LM call's kwargs["tools"], the OpenAI-shaped list ChatAdapter(use_native_function_calling=True) built for that request, and binds it through the core's prompt_tools_scope mechanism until on_lm_end. An LM call without native tools (the default adapter, which describes tools in the prompt text) records [].

Model spans are litellm.chat spans from the OpenLLMetry LiteLLM instrumentor, which only runs with disable_auto_instrument=False. OpenLLMetry 0.62 writes the same list to gen_ai.tool.definitions, not llm.request.functions.*, so raindrop-ai does not rebuild ai.prompt.tools from the instrumentor; the wrapper-side scope is required. With the default disable_auto_instrument=True there is no model span at all, and nothing to carry the attribute. wrap() instruments forward (sync, or an async def forward); acall() / aforward are not instrumented by this wrapper, so LM calls made that way carry no attribute.

Override:

rd = RaindropDSPy(api_key="...", user_id="u1", disable_auto_instrument=False,
                  tools=[{"type": "function", "name": "get_weather", "inputSchema": {...}}])
module = rd.wrap(dspy.Predict(Sig))               # constructor default applies to every LM call
module = rd.wrap(dspy.Predict(Sig), tools=[...])  # per-wrap value replaces the default

An override is bound for the whole forward call and the per-LM-call callback is not installed. tools=[] at either level records an empty catalog. An enclosing raindrop.prompt_tools(...) / begin(..., tools=...) scope is also treated as an override and is never shadowed by the inferred list.

Semantics shared with every Raindrop SDK:

• Attribute absent: the wrapper could not see the tool list (or there is no model span, see below).
• []: the model had no tools.
• Override replaces, never merges. A tools= you pass wins over anything inferred; tools=[] records an empty catalog.
• Content gate. Tool definitions are prompt content. With TRACELOOP_TRACE_CONTENT=false nothing is recorded, overrides included.
• Malformed entries are skipped with a debug log; nothing here raises into your application.

Accepted shapes for tools=: canonical {"type": "function", "name", "description", "inputSchema"}, OpenAI {"type": "function", "function": {...}}, Anthropic {"name", "description", "input_schema"}, and {"type": "provider-defined", "name", ...}. The core normalises them; the JSON Schema is kept exactly as given.

Needs raindrop-ai>=0.0.70; on an older core the wrapper logs at debug and records nothing.

Double-Wrap Protection

Calling wrap() on an already-wrapped module is a no-op — the module is returned unchanged.

Application Git metadata

RaindropDSPy(...) and create_raindrop_dspy(...) accept the keyword-only app_git option. It defaults to True: explicit Raindrop Git environment or deployment context is applied immediately, and the base SDK may perform one bounded background local-Git lookup from the process working directory. Event capture, flush, and shutdown never wait for that lookup. Pass False to disable enrichment, or pass an AppGitOptions mapping with commit_sha, commit_dirty, branch, source_directory, detect_branch, and/or auto_detect. Automatic branch discovery remains opt-in through detect_branch=True (or RAINDROP_GIT_DETECT_BRANCH=true).

For an ordinary in-process application, the process working directory is treated as the application-under-test checkout. A remote, coding, workflow, or observer process must not rely on its own checkout: pass app_git=False, provide explicit revision values, or set source_directory to the actual application checkout. Canonical per-operation properties remain authoritative. When supplying client=, configure app_git while constructing that Raindrop client; the supplied client is authoritative and the wrapper's app_git argument does not reconfigure it.

Release order is deliberate: first publish the base SDK feature, then publish the wrapper feature release with its minimum dependency coordinated to that base release. The existing raindrop-ai lower bound remains compatible, but application Git metadata is unavailable on an older core and must not be claimed complete until the base is upgraded. Until coordination assigns a released version, the wrapper checks for an explicit base app_git parameter and omits the option when unsupported. Explicit non-default configuration is debug-logged and omitted. Unsupported app_git is determined by signature inspection before construction, not by retrying initialization after a TypeError; Git configuration adds no initialization attempts and does not change any existing framework-specific initialization fallback.

Development

cd packages/dspy-python
pip install -e ".[dev]"
python -m pytest tests/ -v   # unit tests (no external services)

End-to-end behavior is verified by the cross-SDK conformance harness. This package ships a thin conformance driver at conformance/driver.py that maps the shared scenario corpus onto the wrapper's public API; known gaps are tracked as ticket-linked entries in conformance/failures.txt. The fault lane runs on every PR touching packages/*-python/** (.github/workflows/conformance-wrappers-python.yml) against a local capture server; the prod lane verifies delivery by reading back through the public Query API. The harness is pinned by commit SHA (HARNESS_REF). See the harness docs: HOW-IT-WORKS · AGENTS · README.

License

MIT

Full documentation