Index of every page on this site: llms.txt
All skills
comet-ml avatar

/opik-integrations

@9b3d88e
by Cometcomet-ml/opik23k stars
1,964
Run it yourself

Build, update, test, and document Opik SDK integrations (Python & TypeScript). Use when adding a new framework/provider integration under sdks/python/src/opik/integrations or sdks/typescript/src/opik/integrations, updating an existing one, or verifying that an integration logs traces correctly.

  • 4 files
  • 38 KB
  • Updated 5 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/comet-ml/opik/opik-integrations

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

typescript.md

≈1k tokens on demand. Your agent reads this file only when SKILL.md points to it.

TypeScript Integration Anatomy

Reference for building integrations under sdks/typescript/src/opik/integrations/opik-<name>/. Read this alongside the typescript-sdk skill (layered client, flush semantics, testing).

The canonical guide comes first

sdks/typescript/design/INTEGRATIONS.md is the authoritative, maintained guide: it has the three patterns with full code, the package structure, a step-by-step "Creating New Integrations" walkthrough, and streaming helpers. Read it before writing anything. This file only records the conventions that guide does not stress and that bite newcomers.

Companion design docs: design/API_AND_DATA_FLOW.md (client/batching/context), design/TESTING.md (vitest + MSW), design/README.md (navigation).

Each integration is its own npm package

Unlike Python (one package, many integration modules), every TS integration is a separate published package (opik-openai, opik-langchain, opik-vercel, opik-gemini). That means:

  • Its own package.json, tsconfig.json, tsup.config.ts, vitest.config.ts, README.md.
  • opik and the wrapped framework are peerDependencies, not dependencies — pin sane ranges and keep the opik range current.
  • Dual CJS + ESM build via tsup, emitting dist/index.js (ESM), dist/index.cjs (CJS), dist/index.d.ts.
  • A lazy OpikClient singleton (singleton.ts) so the integration doesn't spin up multiple clients.

Clone the closest sibling package wholesale (its configs are correct) and rename, rather than hand-writing build config.

Patterns

Pattern When Template package
Proxy wrapper SDK client with methods (most providers) opik-openai, opik-gemini
Callback handler framework with a callback interface opik-langchain
OTel exporter framework emitting OpenTelemetry spans opik-vercel

See design/INTEGRATIONS.md for each pattern's code. Shared imports come from opik: Opik, Trace, Span, OpikSpanType, generateId, logger.

OpenTelemetry is backend-first. Opik's backend ingests OTLP directly and maps spans to traces, so an OTel-instrumented framework can often be integrated with docs alone (point its exporter at Opik). Write a client-side SpanExporter — the opik-vercel pattern — only when you need to remap attributes/semantics, accumulate spans into trace trees, or bridge a framework that won't emit raw OTLP. Check the docs-only path first.

Conventions that bite

  • Never leak rest_api. Integrations wrap the public opik API only — never import generated clients from opik/rest_api.
  • Provide a flush() escape hatch. Proxy wrappers expose flush on the returned object; handlers/exporters expose a flush() method. Required for CLIs/tests where the process exits before the async queue drains.
  • Keep adapters thin and non-blocking — domain objects enqueue, they don't do HTTP.
  • Version references in prose. When you change a peer-dep range or minimum version, update the integration's README.md and the root README.md in the same change — the typescript-sdk skill calls this out as a recurring miss.

Tests

tests/*.test.ts with vitest, per design/TESTING.md and the typescript-sdk testing skill. Integration-specific shape:

  • Mock the API layer (vi.spyOn(client.api.spans, "createSpans")) or use MSW to intercept HTTP — mirror the sibling package's mockUtils.ts.
  • await client.flush() (or advance fake timers) before asserting; data only persists after the queue drains.
  • Assert on captured spans with toMatchObject({...}) — name, input, output, parentSpanId hierarchy, usage, model.
  • Keep tests/setup.ts (it disables the logger). Don't let ERROR logs leak in tests.

Examples

Add a runnable example to sdks/typescript/examples/ mirroring track-decorator.ts / langchain-with-thread-id.ts. This doubles as the script you run during Phase 5 MCP verification.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 9b3d88e. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 5 months ago

README badge

README badge for comet-ml/opik/opik-integrations