opik python_sdk.instructions.md

Opik Python SDK Code Review Guidelines

This document provides essential guidelines for reviewing Opik Python SDK code. It focuses on the most critical architectural patterns, design principles, and best practices that ensure code quality and maintainability.

🔧 Core Architecture Principles

Three-Layer Architecture

The SDK uses a strict 3-layer architecture. Always ensure code belongs to the correct layer:

Layer 1: Public API (opik.Opik, @opik.track)

• User-facing interface, input validation, context management

Layer 2: Message Processing (observability operations only)

• Background workers for trace/span/feedback operations

Layer 3: REST API Client

• HTTP communication with Opik backend

Execution Paths

Asynchronous Path (traces, spans, feedback):

client.trace(name="test")           # Non-blocking, batched
client.log_traces_feedback_scores() # Background processing

Synchronous Path (datasets, experiments, search):

dataset = client.create_dataset(name="test")  # Blocking, returns immediately
traces = client.search_traces(...)           # Direct REST call

📋 API Design Standards

Opik.Opik is the Main Entry Point

# ✅ Good: Always use Opik as factory
client = opik.Opik()
experiment = client.create_experiment(name="test")
dataset = client.create_dataset(name="data")

# ❌ Bad: Direct instantiation
from opik.api_objects.experiment import Experiment
experiment = Experiment(name="test")  # Bypasses main API

Consistent Parameter Patterns

# ✅ Good: Follow established patterns
def create_experiment(self, name: str, description: Optional[str] = None)
def create_dataset(self, name: str, description: Optional[str] = None)

# ❌ Bad: Inconsistent ordering
def create_experiment(self, description: str, name: str)  # Wrong order
def create_dataset(self, name: str, desc: str)           # Different param name

Method Naming Conventions

• CRUD: create_*, get_*, update_*, delete_*
• Search: search_* for complex queries
• Batch: batch_* for bulk operations