comet-ml--opik/apps/opik-documentation/documentation/templates

Integration Documentation Templates

This directory contains templates for creating integration documentation for Opik.

📋 Integration Type Decision Matrix

Use this matrix to determine which template to use:

Integration Type	Requirements	Template to Use	Examples
Code Integration	• Users install Opik Python SDK • Users modify their code • Uses track_*() wrapper functions • Direct Python integration	integration_template_code.md	LangChain, CrewAI, DSPy, Haystack
OpenAI-Based Integration	• Uses OpenAI-compatible API • Users install Opik Python SDK • Uses track_openai() wrapper • Compatible with OpenAI SDK	integration_template_openai.md	BytePlus, OpenRouter, Any OpenAI-compatible API
LiteLLM Integration	• LLM provider supported by LiteLLM • Uses OpikLogger callback • Unified LiteLLM interface • API key configuration required	integration_template_litellm.md	OpenAI, Anthropic, Groq, Fireworks AI, Cohere, Mistral AI, xAI Grok
OpenTelemetry Integration	• Users configure OTEL endpoints • No code changes required • Configuration via env vars • Works through OTEL instrumentations	integration_template_otel.md	Ruby SDK, Pydantic AI (via Logfire), Direct OTEL Python

📁 Available Templates

integration_template_code.md

Use for: Code integrations that require users to install Opik Python SDK and use track_*() wrapper functions.

Examples: OpenAI, Anthropic, LangChain, CrewAI, DSPy, Haystack, etc.

Pattern: Users modify their code to import and wrap clients with Opik tracking.

integration_template_openai.md

Use for: OpenAI-based integrations that use OpenAI-compatible APIs.

Examples: BytePlus, OpenRouter, Any OpenAI-compatible API.

Pattern: Users use track_openai() wrapper with OpenAI SDK.

integration_template_litellm.md

Use for: LiteLLM integrations that use OpikLogger callback.

Examples: OpenAI, Anthropic, Groq, Fireworks AI, Cohere, Mistral AI, xAI Grok.

Pattern: Users configure LiteLLM with OpikLogger callback.

integration_template_otel.md

Use for: OpenTelemetry integrations that only require configuration changes.

Examples: Ruby SDK, Pydantic AI (via Logfire), Direct OTEL Python.

Pattern: Users configure OTEL endpoints and headers, no code changes needed.

🎯 How to Use These Templates

1. Use the decision matrix above to determine which template fits your integration
2. Copy the appropriate template to the correct documentation location:
   • All integrations: fern/docs/tracing/integrations/[integration_name].mdx
3. Replace all placeholder text with actual values
4. Test all code examples in a fresh environment
5. Add realistic examples - avoid "hello world" scenarios
6. Include screenshots of traces in Opik UI
7. Update integration tables in main README files

📸 Screenshot File Placement

⚠️ CRITICAL: Screenshot File Locations

Screenshots must be placed in the correct directory structure:

File System Location (Git root relative):

• apps/opik-documentation/documentation/fern/img/tracing/[integration_name]_integration.png

Documentation Reference Path:

• /img/tracing/[integration_name]_integration.png

Examples:

• Fireworks AI: fern/img/tracing/fireworks_ai_integration.png
• OpenAI: fern/img/tracing/openai_integration.png
• LangChain: fern/img/tracing/langchain_integration.png

⚠️ Common Mistakes:

• ❌ Placing screenshots in static/img/tracing/ (incorrect location)
• ❌ Using absolute paths in documentation
• ❌ Inconsistent naming conventions

📋 Quick Reference

Code Integration Placeholders

• [INTEGRATION_NAME] → "OpenAI"
• [integration_name] → "openai"
• [integration_module] → "openai"
• [integration_package] → "openai"
• [ClientClass] → "OpenAI"
• [INTEGRATION_API_KEY_NAME] → "OPENAI_API_KEY"

OpenAI-Based Integration Placeholders

• [INTEGRATION_NAME] → "BytePlus"
• [INTEGRATION_WEBSITE_URL] → "https://www.byteplus.com/"
• [INTEGRATION_DESCRIPTION] → "ByteDance's AI-native enterprise platform"
• [SPECIFIC_DESCRIPTION] → "OpenAI-compatible API endpoints"
• [INTEGRATION_BASE_URL] → "https://ark.ap-southeast.bytepluses.com/api/v3"
• [INTEGRATION_API_KEY_NAME] → "BYTEPLUS_API_KEY"
• [EXAMPLE_MODEL_NAME] → "kimi-k2-250711"

OTEL Integration Placeholders

• [FRAMEWORK_NAME] → "PydanticAI"
• [framework_name] → "pydantic-ai"
• [framework_otel_packages] → "pydantic-ai[logfire]"

📖 Complete Guidelines

For detailed guidelines on integration documentation, see: .agents/rules/integration-documentation.mdc

This includes:

• Quality checklist
• Integration-specific guidance
• Publication process
• Maintenance guidelines