# opik-gemini

> Opik TypeScript and JavaScript SDK integration with Google Gemini AI

Latest version **2.2.71** (published 2026-09-19) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install opik-gemini
pnpm add opik-gemini
yarn add opik-gemini
bun add opik-gemini
```

## Health

**Score 80/100 (A)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score; popular repo.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.2.71 |
| Published | 2026-09-19 |
| First published | 2025-10-01 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 0 |
| Unpacked size | 25.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 21967 |
| Author | Comet |
| Maintainers | cometml |
| Keywords | opik, gemini, google-ai, google-generative-ai, genai, gemini-integration, sdk, javascript, javascript-sdk, typescript, typescript-sdk, llm, tracing, observability, comet |

## Links

- npm: https://www.npmjs.com/package/opik-gemini
- Repository: https://github.com/comet-ml/opik
- Homepage: https://www.comet.com/docs/opik/
- Issues: https://github.com/comet-ml/opik/issues
- npm.io page: https://npm.io/package/opik-gemini

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 2.2.71 (latest) — 2026-09-19
- 2.2.70 — 2026-09-18
- 2.2.69 — 2026-09-18
- 2.2.68 — 2026-09-17
- 2.2.67 — 2026-09-17
- 2.2.66 — 2026-09-16
- 2.2.65 — 2026-09-16
- 2.2.64 — 2026-09-15
- 2.2.63 — 2026-09-15
- 2.2.62 — 2026-09-15
- 2.2.61 — 2026-09-14
- 2.2.60 — 2026-09-14
- 2.2.59 — 2026-09-11
- 2.2.58 — 2026-09-10
- 2.2.57 — 2026-09-10
- … 303 more at https://npm.io/package/opik-gemini/versions

## README

# Opik Gemini Integration

[![npm version](https://img.shields.io/npm/v/opik-gemini.svg)](https://www.npmjs.com/package/opik-gemini)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/comet-ml/opik/blob/main/LICENSE)

Seamlessly integrate [Opik](https://www.comet.com/docs/opik/) observability with your [Google Gemini](https://ai.google.dev/) applications.

## Features

- 🔍 **Comprehensive Tracing**: Automatically trace Gemini API calls
- 📊 **Hierarchical Visualization**: View execution as structured traces and spans
- 📝 **Detailed Metadata**: Record model names, prompts, completions, token usage
- 🚨 **Error Handling**: Capture and visualize errors with full context
- 🏷️ **Custom Tagging**: Add custom tags and metadata to organize traces
- 🔄 **Streaming Support**: Full support for streamed responses
- ⚡ **Non-blocking**: Minimal performance impact with async batching
- 🎯 **Type-Safe**: Full TypeScript support with comprehensive types

## Installation

```bash
npm install opik-gemini @google/genai
```

### Requirements

- Node.js ≥ 18
- @google/genai SDK (≥ 1.0.0)
- Opik SDK (automatically installed as peer dependency)

**Note**: The official Google GenAI SDK package is `@google/genai` (not `@google/generative-ai`). This is Google Deepmind's unified SDK for both Gemini Developer API and Vertex AI.

## Quick Start

### Basic Usage

```typescript
import { GoogleGenAI } from "@google/genai";
import { trackGemini } from "opik-gemini";

// Initialize Gemini client
const genAI = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

// Wrap with Opik tracking
const trackedGenAI = trackGemini(genAI, {
  traceMetadata: {
    tags: ["production", "my-app"],
  },
});

// Use normally - all calls are automatically tracked
async function main() {
  const response = await trackedGenAI.models.generateContent({
    model: "gemini-2.0-flash-001",
    contents: "What is the capital of France?",
  });

  console.log(response.text);

  // Ensure all traces are sent before exit
  await trackedGenAI.flush();
}

main();
```

### Streaming Support

```typescript
import { GoogleGenAI } from "@google/genai";
import { trackGemini } from "opik-gemini";

const genAI = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const trackedGenAI = trackGemini(genAI);

async function streamExample() {
  const response = await trackedGenAI.models.generateContentStream({
    model: "gemini-2.0-flash-001",
    contents: "Write a haiku about AI",
  });

  // Stream is automatically tracked
  let streamedContent = "";
  for await (const chunk of response) {
    const chunkText = chunk.text;
    if (chunkText) {
      process.stdout.write(chunkText);
      streamedContent += chunkText;
    }
  }

  console.log("\n");
  await trackedGenAI.flush();
}

streamExample();
```

### Using with Existing Opik Client

```typescript
import { Opik } from "opik";
import { GoogleGenAI } from "@google/genai";
import { trackGemini } from "opik-gemini";

const opikClient = new Opik({
  projectName: "gemini-project",
});

const genAI = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const trackedGenAI = trackGemini(genAI, {
  client: opikClient,
  traceMetadata: {
    tags: ["gemini", "production"],
    environment: "prod",
  },
});

// All calls will be logged to "gemini-project"
const response = await trackedGenAI.models.generateContent({
  model: "gemini-2.0-flash-001",
  contents: "Hello, Gemini!",
});

console.log(response.text);
```

### Custom Generation Names

```typescript
import { trackGemini } from "opik-gemini";

const trackedGenAI = trackGemini(genAI, {
  generationName: "MyCustomGeminiCall",
});

// Traces will appear as "MyCustomGeminiCall" in Opik
```

### Nested Tracing

```typescript
import { Opik } from "opik";
import { trackGemini } from "opik-gemini";

const opikClient = new Opik();
const trackedGenAI = trackGemini(genAI, { client: opikClient });

async function processQuery(query: string) {
  // Create parent trace
  const trace = opikClient.trace({
    name: "ProcessUserQuery",
    input: { query },
  });

  // Gemini call will be nested under this trace
  const trackedGenAIWithParent = trackGemini(genAI, {
    parent: trace,
    client: opikClient,
  });

  const response = await trackedGenAIWithParent.models.generateContent({
    model: "gemini-2.0-flash-001",
    contents: query,
  });

  trace.update({
    output: { response: response.text },
  });
  trace.end();

  return response;
}
```

## Configuration

### TrackOpikConfig Options

```typescript
interface TrackOpikConfig {
  /** Opik client instance (optional, creates singleton if not provided) */
  client?: Opik;

  /** Custom name for the generation (optional, defaults to method name) */
  generationName?: string;

  /** Parent trace or span for nested tracing (optional) */
  parent?: Trace | Span;

  /** Additional metadata for traces (optional) */
  traceMetadata?: {
    tags?: string[];
    [key: string]: unknown;
  };
}
```

## What Gets Tracked

The integration automatically captures:

- **Input**: Prompt contents and generation config
- **Output**: Generated text, candidates, and safety ratings
- **Model**: Model name/version (e.g., "gemini-pro", "gemini-1.5-flash")
- **Usage**: Token counts (prompt, completion, total)
- **Metadata**: Provider info, model settings, safety settings
- **Errors**: Error messages and stack traces
- **Timing**: Start/end times and duration

## Best Practices

1. **Always call `flush()` before process exit** (especially in short-lived scripts):

   ```typescript
   await trackedGenAI.flush();
   ```

2. **Use descriptive tags** for easier filtering:

   ```typescript
   trackGemini(genAI, {
     traceMetadata: {
       tags: ["production", "customer-support", "v2"],
     },
   });
   ```

3. **Reuse Opik client** across your application for consistency:

   ```typescript
   const opikClient = new Opik({ projectName: "my-project" });
   const trackedGenAI = trackGemini(genAI, { client: opikClient });
   ```

4. **Use nested tracing** for complex workflows to understand call hierarchies.

## Supported Gemini Models

This integration supports all Google Gemini models including:

- `gemini-2.0-flash-001` (Latest, recommended for most use cases)
- `gemini-1.5-pro`
- `gemini-1.5-flash`
- `gemini-pro`
- `gemini-pro-vision`
- Any future Gemini models

Refer to [Google's official documentation](https://ai.google.dev/models/gemini) for the complete list of available models and their capabilities.

## Development

### Building

```bash
npm run build
```

### Type Checking

```bash
npm run typecheck
```

### Testing

```bash
npm test
```

## Examples

Check out the [examples directory](../../../../examples) for more usage examples.

## Documentation

- [Opik Documentation](https://www.comet.com/docs/opik/)
- [Google Gemini Documentation](https://ai.google.dev/)
- [TypeScript SDK Guide](https://www.comet.com/docs/opik/typescript-sdk)

## Support

- [GitHub Issues](https://github.com/comet-ml/opik/issues)
- [Comet Support](mailto:support@comet.com)
- [Community Slack](https://www.comet.com/docs/opik/community/)

## License

Apache-2.0

## Contributing

Contributions are welcome! Please see our [Contributing Guide](https://github.com/comet-ml/opik/blob/main/CONTRIBUTING.md).

---
_Source: https://npm.io/package/opik-gemini · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._