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

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

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

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

import { trackGemini } from "opik-gemini";

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

// Traces will appear as "MyCustomGeminiCall" in Opik

Nested Tracing

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

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

Always call flush() before process exit (especially in short-lived scripts):
```
await trackedGenAI.flush();
```

Use descriptive tags for easier filtering:

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

Reuse Opik client across your application for consistency:

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

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 for the complete list of available models and their capabilities.

Development

Building

npm run build

Type Checking

npm run typecheck

Testing

npm test

Examples

Check out the examples directory for more usage examples.

Documentation

Support

License

Apache-2.0

Contributing

Contributions are welcome! Please see our Contributing Guide.

Keywords

opik gemini google-ai google-generative-ai genai gemini-integration sdk javascript javascript-sdk typescript typescript-sdk llm tracing observability comet