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.

SKILL.md

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:

  1. Prepare — install/resolve the target library, locate credentials (without printing them), pick a backend the MCP can read.
  2. Investigate the target library (API surface, hooks/callbacks, streaming shape, usage/token format, errors).
  3. Collect findings + a minimal runnable example script.
  4. Design — pick the pattern, file layout, entrypoint. (Interactive mode pauses for approval here; autonomous mode records it in the report.)
  5. Implement by cloning the closest existing same-pattern integration.
  6. Verify the logged data through the Opik MCP (read/list the trace & spans).
  7. Test with the language's integration-test harness.
  8. Document the Fern page and wire its routing.
  9. 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.

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