Metadata-Version: 2.4
Name: raindrop-vertex-ai
Version: 0.0.3
Summary: Raindrop integration for Google Vertex AI / Gen AI
Author-email: Raindrop AI <sdk@raindrop.ai>
License-Expression: MIT
Project-URL: Homepage, https://raindrop.ai
Project-URL: Documentation, https://docs.raindrop.ai
Project-URL: Repository, https://github.com/invisible-tools/dawn/tree/main/packages/vertex-ai-python
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: raindrop-ai>=0.0.42
Requires-Dist: google-genai>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: requests>=2.28; extra == "dev"
Dynamic: license-file

# raindrop-vertex-ai

Raindrop integration for [Google Vertex AI / Gen AI](https://cloud.google.com/vertex-ai) (Python). Automatically captures `models.generate_content()` and `aio.models.generate_content()` calls.

## Installation

```bash
pip install raindrop-vertex-ai google-genai
```

`google-genai` is a required dependency.

## Quick Start

```python
from raindrop_vertex_ai import RaindropVertexAI
from google import genai

raindrop = RaindropVertexAI(api_key="your-write-key", user_id="user-123")

client = genai.Client(api_key="...")
wrapped = raindrop.wrap(client)

response = wrapped.models.generate_content(
    model="gemini-2.0-flash", contents="Hello!"
)
print(response.text)

raindrop.shutdown()
```

Omitting `api_key` disables telemetry shipping (a warning is emitted) but does not crash your application.

## What Gets Tracked

- **generate_content** — input content, output text, model name
- **Token usage** — prompt_token_count and candidates_token_count from usage metadata
- **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 type and message in properties, then re-raised
- **Async support** — both `models.generate_content` (sync) and `aio.models.generate_content` (async) are instrumented
- **Double-wrap guard** — calling `wrap()` on an already-wrapped client is a safe no-op

## Configuration

```python
raindrop = RaindropVertexAI(
    api_key="rk_...",                    # Optional: your Raindrop API key
    user_id="user-123",                  # Optional: associate events with a user
    convo_id="convo-456",                # Optional: conversation/thread ID
    tracing_enabled=True,                # Optional: enable Raindrop tracing (default: True)
    bypass_otel_for_tools=True,          # Optional: bypass OTEL for tools (default: True)
    debug=True,                          # Optional: enable verbose DEBUG logging
)
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `api_key` | `str` | `None` | Raindrop API key |
| `user_id` | `str` | `None` | Associate all events with a user |
| `convo_id` | `str` | `None` | Group events into a conversation |
| `tracing_enabled` | `bool` | `True` | Enable Raindrop tracing |
| `bypass_otel_for_tools` | `bool` | `True` | Bypass OpenTelemetry for tool instrumentation |
| `debug` | `bool` | `False` | Enable verbose DEBUG-level logging |

## Debug Logging

```python
raindrop = RaindropVertexAI(api_key="rk_...", debug=True)
```

## Async Usage

```python
import asyncio
from raindrop_vertex_ai import RaindropVertexAI
from google import genai

raindrop = RaindropVertexAI(api_key="rk_...")
client = genai.Client(api_key="...")
wrapped = raindrop.wrap(client)

async def main():
    response = await wrapped.aio.models.generate_content(
        model="gemini-2.0-flash", contents="Hello!"
    )
    print(response.text)

asyncio.run(main())
raindrop.shutdown()
```

## identify()

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

Always call `shutdown()` before your process exits to ensure all telemetry is shipped:

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

## Factory Function

A `create_raindrop_vertex_ai()` factory is also available for convenience:

```python
from raindrop_vertex_ai import create_raindrop_vertex_ai

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

## Full Documentation

See the [Raindrop docs](https://docs.raindrop.ai) for complete API reference.

## Testing

```bash
cd packages/vertex-ai-python
pip install -e ".[dev]"
python -m pytest tests/ -v
```

## License

MIT
