Installation

npm

npm install @raindrop-ai/vertex-ai @google/genai

pip

Quick Start

TypeScript

import { createRaindropVertexAI } from "@raindrop-ai/vertex-ai";
import { GoogleGenAI } from "@google/genai";

const raindrop = createRaindropVertexAI({
  writeKey: "your-write-key",
  userId: "user-123",
});

const client = new GoogleGenAI({ apiKey: "..." });
const wrapped = raindrop.wrap(client);

const response = await wrapped.models.generateContent({
  model: "gemini-2.0-flash",
  contents: "What is the capital of France?",
});

console.log(response.text);
await raindrop.shutdown();

Python

What Gets Traced

• generateContent — input text (user messages only), output, model, token usage (promptTokenCount/candidatesTokenCount)
• Cached tokens — cached_content_token_count from usage metadata → ai.usage.cached_tokens
• Thinking tokens — thoughts_token_count from usage metadata (Gemini 2.5) → ai.usage.thoughts_tokens
• Finish reason — candidate.finish_reason (STOP, MAX_TOKENS, SAFETY, RECITATION) → vertex_ai.finish_reason
• Errors — captured with error status, re-thrown to caller

Configuration

TypeScript

const raindrop = createRaindropVertexAI({
  writeKey: "your-write-key",       // Optional: omit to disable telemetry
  endpoint: "...",          // Optional: custom Raindrop API endpoint
  userId: "user-123",      // Optional: associate events with a user
  convoId: "convo-456",    // Optional: conversation/thread ID
  debug: false,             // Optional: enable verbose logging
});

Python

raindrop.identify(user_id="user-123", traits={"plan": "pro", "org": "acme"})

track_signal()

Python

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

Flushing and Shutdown

TypeScript

await raindrop.flush();     // flush pending data
await raindrop.shutdown();  // flush + release resources

Python

finish_reason Tracking

The Python wrapper captures candidate.finish_reason from Vertex AI responses and maps it to vertex_ai.finish_reason in event properties. Possible values: STOP, MAX_TOKENS, SAFETY, RECITATION.

Token Tracking

The following token usage fields are captured from usage_metadata:

Factory Function

A create_raindrop_vertex_ai() factory is also available:

from raindrop_vertex_ai import create_raindrop_vertex_ai

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

Known Limitations

• Python SDK: No events.* API — use raindrop.analytics directly. identify() and track_signal() are available on the wrapper instance.
• Streaming: generateContentStream() is not instrumented. Only generateContent() is traced.