Opik SDK Integrations
This skill is for building integrations into the Opik SDK itself — the code that ships inside opik / opik-* packages so that users can trace a framework (OpenAI, LangChain, Mistral, …) with one call.
Do not confuse this with the user-facing instrument / opik skills, which add Opik tracing to someone else's application. This skill is for SDK contributors editing sdks/python and sdks/typescript.
If the integration lives outside this repo — a standalone opik-* package, or Opik support contributed into a third-party project (LiteLLM, Dify, a plugin, …) — use the opik-external-integrations skill instead. This skill assumes the code ships inside sdks/.
Start with the questionnaire
Never assume or suggest a target. Collect, from the user, before doing anything: what to integrate (name + reference links), where it lives (this repo vs. external — route external requests to opik-external-integrations), language (python/typescript/both), mode (new/update/maintain), and any specific flows to cover. Do not present a menu of candidate libraries — the user names the target.
When to use
- New integration — a framework/provider has no dedicated integration yet (today it's reachable only via LiteLLM, the OpenAI-compatible shim, or OpenTelemetry, or not at all).
- Update — an integration must track new methods, capture new fields, or follow an upstream SDK change.
- Maintain / verify — confirm an existing integration still logs the correct trace/span tree after a dependency bump or refactor.
The workflow
Integration work is multi-step. By default this skill runs autonomously: it makes its own preparations (deps, credentials, backend), runs every phase, self-verifies, and ends with a high-level report — only stopping early on a true blocker. Ask for the interactive variant if you want to approve the design before any code is written. The full playbook — phases, execution modes, the Opik-MCP verification loop, and the report template — lives in workflow.md. At a glance:
- Prepare — install/resolve the target library, locate credentials (without printing them), pick a backend the MCP can read.
- Investigate the target library (API surface, hooks/callbacks, streaming shape, usage/token format, errors).
- Collect findings + a minimal runnable example script.
- Design — pick the pattern, file layout, entrypoint. (Interactive mode pauses for approval here; autonomous mode records it in the report.)
- Implement by cloning the closest existing same-pattern integration.
- Verify the logged data through the Opik MCP (
read/list the trace & spans).
- Test with the language's integration-test harness.
- Document the Fern page and wire its routing.
- Report — a high-level summary: what was done, what's supported (with evidence), what's not, and how to use it.
Golden rule: clone the closest sibling
Never build an integration from a blank file. Identify the existing integration that shares the target's mechanism, copy its structure, and adapt. The decision tree:
| Target shape |
Python pattern |
TS pattern |
Clone from |
| SDK client with methods to wrap (most providers) |
Method patching (BaseTrackDecorator subclass) |
Proxy wrapper |
openai/ · opik-openai |
| Framework with a callback/tracer interface |
Pure callback (BaseTracer) |
Callback handler |
langchain/ · opik-langchain |
| Framework already emitting OpenTelemetry spans |
OTel |
OTel exporter |
otel/ · opik-vercel |
| Callbacks exist but are unreliable / need method hooks too |
Hybrid |
(rare) |
adk/ |
If the target exposes an OpenAI-compatible endpoint, first check whether track_openai(..., provider=...) already covers the need before building a dedicated integration — sometimes the right answer is a docs page, not new code.
OpenTelemetry is backend-first. If the target already emits OpenTelemetry spans, the heavy lifting is done by Opik's OTLP ingestion endpoint on the backend — many such integrations are docs-only (point the framework's OTLP exporter at Opik with auth headers; no SDK code). Build a client-side piece only when you must shape what the backend receives — set Opik semantics, remap attributes, or bridge a framework that won't export raw OTLP. The client-side building block is a SpanProcessor in Python (integrations/otel/) or a SpanExporter in TypeScript (opik-vercel); a framework-specific OTel tracer wrapper (adk/patchers/adk_otel_tracer/) is the heavier variant. See the OTel sections in python.md / typescript.md.
Language references
- Python → python.md — integration anatomy, shared core modules, mechanism templates, dependency/import rules, test specifics.
- TypeScript → typescript.md — package anatomy, patterns, build/peer-dep rules. Delegates to the canonical
sdks/typescript/design/INTEGRATIONS.md.
Skills this one builds on (do not duplicate them)
python-sdk — three-layer architecture, batching, fake_backend, testlib verifiers, error handling.typescript-sdk — layered client, flush semantics, testing with vitest.write-docs — Fern MDX authoring, routing YAML, callouts, images.
1---2name: opik-integrations3description: 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---5
6# Opik SDK Integrations
7
8This skill is for **building integrations into the Opik SDK itself** — the code that ships inside `opik` / `opik-*` packages so that *users* can trace a framework (OpenAI, LangChain, Mistral, …) with one call.
9
10> Do not confuse this with the user-facing `instrument` / `opik` skills, which add Opik tracing to *someone else's* application. This skill is for SDK contributors editing `sdks/python` and `sdks/typescript`.
11>
12> If the integration lives **outside this repo** — a standalone `opik-*` package, or Opik support contributed into a third-party project (LiteLLM, Dify, a plugin, …) — use the **`opik-external-integrations`** skill instead. This skill assumes the code ships inside `sdks/`.
13
14## Start with the questionnaire
15
16Never assume or suggest a target. Collect, from the user, before doing anything: **what** to integrate (name + reference links), **where** it lives (this repo vs. external — route external requests to `opik-external-integrations`), **language** (python/typescript/both), **mode** (new/update/maintain), and any **specific flows** to cover. Do not present a menu of candidate libraries — the user names the target.
17
18## When to use
19
20- **New integration** — a framework/provider has no dedicated integration yet (today it's reachable only via LiteLLM, the OpenAI-compatible shim, or OpenTelemetry, or not at all).
21- **Update** — an integration must track new methods, capture new fields, or follow an upstream SDK change.
22- **Maintain / verify** — confirm an existing integration still logs the correct trace/span tree after a dependency bump or refactor.
23
24## The workflow
25
26Integration work is multi-step. By default this skill runs **autonomously**: it makes its own preparations (deps, credentials, backend), runs every phase, self-verifies, and ends with a high-level report — only stopping early on a true blocker. Ask for the interactive variant if you want to approve the design before any code is written. The full playbook — phases, execution modes, the Opik-MCP verification loop, and the report template — lives in **[workflow.md](workflow.md)**. At a glance:
27
280. **Prepare** — install/resolve the target library, locate credentials (without printing them), pick a backend the MCP can read.
291. **Investigate** the target library (API surface, hooks/callbacks, streaming shape, usage/token format, errors).
302. **Collect** findings + a minimal runnable example script.
313. **Design** — pick the pattern, file layout, entrypoint. (Interactive mode pauses for approval here; autonomous mode records it in the report.)
324. **Implement** by cloning the closest existing same-pattern integration.
335. **Verify** the logged data through the Opik MCP (`read`/`list` the trace & spans).
346. **Test** with the language's integration-test harness.
357. **Document** the Fern page and wire its routing.
368. **Report** — a high-level summary: what was done, what's supported (with evidence), what's not, and how to use it.
37
38## Golden rule: clone the closest sibling
39
40Never build an integration from a blank file. Identify the existing integration that shares the target's mechanism, copy its structure, and adapt. The decision tree:
41
42| Target shape | Python pattern | TS pattern | Clone from |
43|---|---|---|---|
44| SDK client with methods to wrap (most providers) | Method patching (`BaseTrackDecorator` subclass) | Proxy wrapper | `openai/` · `opik-openai` |
45| Framework with a callback/tracer interface | Pure callback (`BaseTracer`) | Callback handler | `langchain/` · `opik-langchain` |
46| Framework already emitting OpenTelemetry spans | OTel | OTel exporter | `otel/` · `opik-vercel` |
47| Callbacks exist but are unreliable / need method hooks too | Hybrid | (rare) | `adk/` |
48
49If the target exposes an **OpenAI-compatible endpoint**, first check whether `track_openai(..., provider=...)` already covers the need before building a dedicated integration — sometimes the right answer is a docs page, not new code.
50
51**OpenTelemetry is backend-first.** If the target already emits OpenTelemetry spans, the heavy lifting is done by Opik's OTLP ingestion endpoint on the backend — many such integrations are *docs-only* (point the framework's OTLP exporter at Opik with auth headers; no SDK code). Build a client-side piece only when you must shape what the backend receives — set Opik semantics, remap attributes, or bridge a framework that won't export raw OTLP. The client-side building block is a `SpanProcessor` in Python (`integrations/otel/`) or a `SpanExporter` in TypeScript (`opik-vercel`); a framework-specific OTel tracer wrapper (`adk/patchers/adk_otel_tracer/`) is the heavier variant. See the OTel sections in [python.md](python.md) / [typescript.md](typescript.md).
52
53## Language references
54
55- **Python** → [python.md](python.md) — integration anatomy, shared core modules, mechanism templates, dependency/import rules, test specifics.
56- **TypeScript** → [typescript.md](typescript.md) — package anatomy, patterns, build/peer-dep rules. Delegates to the canonical `sdks/typescript/design/INTEGRATIONS.md`.
57
58## Skills this one builds on (do not duplicate them)
59
60- `python-sdk` — three-layer architecture, batching, `fake_backend`, `testlib` verifiers, error handling.
61- `typescript-sdk` — layered client, flush semantics, testing with vitest.
62- `write-docs` — Fern MDX authoring, routing YAML, callouts, images.
comet-ml