## Installation

### npm

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

### pip

## Quick Start

### TypeScript

```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

```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`:

| Field                           | Property Key                     | Description            |
|---------------------------------|----------------------------------|------------------------|
| `prompt_token_count`            | `ai.usage.prompt_tokens`        | Input tokens           |
| `candidates_token_count`        | `ai.usage.completion_tokens`    | Output tokens          |
| `cached_content_token_count`    | `ai.usage.cached_tokens`        | Cached input tokens    |
| `thoughts_token_count`          | `ai.usage.thoughts_tokens`      | Thinking tokens (Gemini 2.5) |

## 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.