chore: import upstream snapshot with attribution

apps/opik-documentation/python-sdk-docs/source/Objects/Attachment.rst

@@ -0,0 +1,4 @@
+Attachment
+==========
+
+.. autoclass:: opik.Attachment

apps/opik-documentation/python-sdk-docs/source/Objects/AttachmentClient.rst

@@ -0,0 +1,7 @@
+AttachmentClient
+================
+
+.. autoclass:: opik.api_objects.attachment.client.AttachmentClient
+    :members:
+    :inherited-members:
+    :special-members: __init__

apps/opik-documentation/python-sdk-docs/source/Objects/ChatPrompt.rst

@@ -0,0 +1,8 @@
+ChatPrompt
+==========
+
+.. autoclass:: opik.api_objects.prompt.chat.chat_prompt.ChatPrompt
+    :members:
+    :inherited-members:
+    :special-members: __init__
+

apps/opik-documentation/python-sdk-docs/source/Objects/DistributedTraceHeadersDict.rst

@@ -0,0 +1,7 @@
+DistributedTraceHeadersDict
+===========================
+
+.. autoclass:: opik.types.DistributedTraceHeadersDict
+   :members:
+   :undoc-members:
+   :show-inheritance:

apps/opik-documentation/python-sdk-docs/source/Objects/EvaluationResult.rst

@@ -0,0 +1,5 @@
+EvaluationResult
+================
+
+.. autoclass:: opik.evaluation.evaluation_result.EvaluationResult
+    :members:

apps/opik-documentation/python-sdk-docs/source/Objects/Experiment.rst

@@ -0,0 +1,7 @@
+Experiment
+==========
+
+.. autoclass:: opik.api_objects.experiment.experiment.Experiment
+    :members:
+    :inherited-members:
+    :special-members: __init__

apps/opik-documentation/python-sdk-docs/source/Objects/ExperimentItemContent.rst

@@ -0,0 +1,7 @@
+ExperimentItemContent
+=====================
+
+.. autoclass:: opik.api_objects.experiment.experiment_item.ExperimentItemContent
+    :members:
+    :inherited-members:
+    :special-members: __init__

apps/opik-documentation/python-sdk-docs/source/Objects/ExperimentItemReferences.rst

@@ -0,0 +1,7 @@
+ExperimentItemReferences
+========================
+
+.. autoclass:: opik.api_objects.experiment.experiment_item.ExperimentItemReferences
+    :members:
+    :inherited-members:
+    :special-members: __init__

apps/opik-documentation/python-sdk-docs/source/Objects/FeedbackScoreDict.rst

@@ -0,0 +1,5 @@
+FeedbackScoreDict
+=================
+
+.. autoclass:: opik.types.FeedbackScoreDict
+    :members:

apps/opik-documentation/python-sdk-docs/source/Objects/LiteLLMChatModel.rst

@@ -0,0 +1,7 @@
+LiteLLMChatModel
+================
+
+.. autoclass:: opik.evaluation.models.LiteLLMChatModel
+    :members:
+    :inherited-members:
+    :special-members: __init__

apps/opik-documentation/python-sdk-docs/source/Objects/OpikBaseModel.rst

@@ -0,0 +1,7 @@
+OpikBaseModel
+=============
+
+.. autoclass:: opik.evaluation.models.OpikBaseModel
+    :members:
+    :inherited-members:
+    :special-members: __init__

apps/opik-documentation/python-sdk-docs/source/Objects/Prompt.rst

@@ -0,0 +1,7 @@
+Prompt
+======
+
+.. autoclass:: opik.api_objects.prompt.text.prompt.Prompt
+    :members:
+    :inherited-members:
+    :special-members: __init__

apps/opik-documentation/python-sdk-docs/source/Objects/ScoreResult.rst

@@ -0,0 +1,5 @@
+ScoreResult
+===========
+
+.. autoclass:: opik.evaluation.metrics.score_result.ScoreResult
+    :members:

apps/opik-documentation/python-sdk-docs/source/Objects/Span.rst

@@ -0,0 +1,7 @@
+Span
+====
+
+.. autoclass:: opik.api_objects.span.Span
+    :members:
+    :inherited-members:
+    :special-members: __init__

apps/opik-documentation/python-sdk-docs/source/Objects/SpanData.rst

@@ -0,0 +1,5 @@
+SpanData
+=========
+
+.. autoclass:: opik.api_objects.span.SpanData
+    :members:

apps/opik-documentation/python-sdk-docs/source/Objects/SpanPublic.rst

@@ -0,0 +1,5 @@
+SpanPublic
+===========
+
+.. autoclass:: opik.rest_api.types.span_public.SpanPublic
+    :members:

apps/opik-documentation/python-sdk-docs/source/Objects/TestResult.rst

@@ -0,0 +1,5 @@
+TestResult
+==========
+
+.. autoclass:: opik.evaluation.test_result.TestResult
+    :members:

apps/opik-documentation/python-sdk-docs/source/Objects/Trace.rst

@@ -0,0 +1,7 @@
+Trace
+=====
+
+.. autoclass:: opik.api_objects.trace.Trace
+    :members:
+    :inherited-members:
+    :special-members: __init__

apps/opik-documentation/python-sdk-docs/source/Objects/TraceData.rst

@@ -0,0 +1,5 @@
+TraceData
+=========
+
+.. autoclass:: opik.api_objects.trace.TraceData
+    :members:

apps/opik-documentation/python-sdk-docs/source/Objects/TracePublic.rst

@@ -0,0 +1,5 @@
+TracePublic
+===========
+
+.. autoclass:: opik.rest_api.types.trace_public.TracePublic
+    :members:

apps/opik-documentation/python-sdk-docs/source/Opik.rst

@@ -0,0 +1,8 @@
+Opik
+====
+
+.. autoclass:: opik.Opik
+    :members:
+    :inherited-members:
+    :special-members: __init__
+    

apps/opik-documentation/python-sdk-docs/source/cli.rst

@@ -0,0 +1,6 @@
+CLI Reference
+=============
+
+.. click:: opik.cli:cli
+   :prog: opik
+   :nested: full

apps/opik-documentation/python-sdk-docs/source/conf.py

@@ -0,0 +1,67 @@
+import sys
+import os
+
+# Add the source directory to the Python path so Sphinx can find our extensions
+sys.path.insert(0, os.path.abspath("."))
+
+# Configuration file for the Sphinx documentation builder.
+#
+# Full list of options can be found in the Sphinx documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+# -- Project information -----------------------------------------------------
+#
+
+project = "opik"
+copyright = "Comet ML"
+
+# -- General configuration ---------------------------------------------------
+#
+
+extensions = [
+    # Sphinx's own extensions
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.todo",
+    "sphinx_click.ext",
+    # Custom extensions
+    "docstring_override",
+]
+
+# -- Options for Autodoc --------------------------------------------------------------
+
+autodoc_member_order = "bysource"
+autodoc_preserve_defaults = True
+
+# Keep the type hints outside the function signature, moving them to the
+# descriptions of the relevant function/methods.
+# autodoc_typehints = "description"
+
+# Document all functions, including __init__ and include members
+autodoc_default_options = {
+    "undoc-members": True,
+    "private-members": False,
+    "show-inheritance": True,
+}
+
+# -- Options for Markdown files ----------------------------------------------
+#
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+]
+myst_heading_anchors = 3
+
+# -- Options for HTML output -------------------------------------------------
+#
+
+html_theme = "furo"
+html_title = "opik"
+language = "en"
+
+html_static_path = ["_static"]
+html_favicon = "_static/favicon.ico"
+html_css_files = ["pied-piper-admonition.css"]

apps/opik-documentation/python-sdk-docs/source/configure.rst

@@ -0,0 +1,4 @@
+configure
+=========
+
+.. autofunction:: opik.configure

apps/opik-documentation/python-sdk-docs/source/context_manager/distributed_headers.rst

@@ -0,0 +1,90 @@
+distributed_headers
+===================
+
+.. autofunction:: opik.decorator.context_manager.distributed_headers
+
+Examples
+--------
+
+Basic usage in a server endpoint
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   from opik.decorator.context_manager import distributed_headers
+   from fastapi import FastAPI, Request
+
+   app = FastAPI()
+
+   @app.post("/generate_response")
+   def generate_llm_response(request: Request) -> str:
+       # Extract distributed headers from the incoming request
+       headers = {
+           "opik_trace_id": request.headers.get("opik_trace_id"),
+           "opik_parent_span_id": request.headers.get("opik_parent_span_id"),
+       }
+
+       # Use the context manager to handle distributed headers
+       with distributed_headers(headers):
+           result = my_llm_application()
+
+       return result
+
+With flush enabled
+~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   from opik.decorator.context_manager import distributed_headers
+
+   def process_request(headers_dict):
+       # Flush data immediately after the root span is processed
+       with distributed_headers(headers_dict, flush=True):
+           # Your processing logic here
+           pass
+
+Using with the track decorator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   from opik import track
+   from opik.decorator.context_manager import distributed_headers
+   from flask import Flask, request
+
+   app = Flask(__name__)
+
+   @track()
+   def my_llm_function(prompt: str) -> str:
+       # Your LLM logic here
+       return "response"
+
+   @app.route("/api/generate", methods=["POST"])
+   def api_endpoint():
+       # Extract headers from the request
+       headers = {
+           "opik_trace_id": request.headers.get("opik_trace_id"),
+           "opik_parent_span_id": request.headers.get("opik_parent_span_id"),
+       }
+
+       # Create distributed trace context
+       with distributed_headers(headers):
+           result = my_llm_function(prompt=request.json.get("prompt"))
+
+       return {"result": result}
+
+Error handling
+~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   from opik.decorator.context_manager import distributed_headers
+
+   try:
+       with distributed_headers(incoming_headers):
+           # Code that might fail
+           result = risky_operation()
+   except Exception as e:
+       # The context manager automatically logs the error
+       # and attaches error information to the root span
+       print(f"Operation failed: {e}")

apps/opik-documentation/python-sdk-docs/source/context_manager/index.rst

@@ -0,0 +1,67 @@
+Context Managers
+================
+
+Opik provides context managers for creating and managing traces and spans in your application. These context managers allow you to easily instrument your code with tracing capabilities while ensuring proper cleanup and error handling.
+
+Context managers are particularly useful when you need fine-grained control over trace and span creation, or when working with code that doesn't fit well with the `@track` decorator pattern.
+
+Available Context Managers
+---------------------------
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+
+   start_as_current_span
+   start_as_current_trace
+   distributed_headers
+
+Key Features
+------------
+
+- **Automatic Error Handling**: Context managers automatically capture and log errors that occur within their scope
+- **Distributed Tracing**: Support for distributed tracing headers to maintain trace context across service boundaries
+- **Flexible Configuration**: Rich set of parameters for customizing trace and span behavior
+- **Resource Management**: Automatic cleanup and flushing of trace data
+- **Nested Support**: Context managers can be nested to create hierarchical trace structures
+
+Basic Usage Pattern
+-------------------
+
+.. code-block:: python
+
+   import opik
+
+   with opik.start_as_current_trace("my-trace", project_name="my-project") as trace:
+        # Your application logic here
+        trace.input = {"user_query": "Explain quantum computing"}
+        trace.output = {"response": "Quantum computing is..."}
+        trace.tags = ["chat"]
+        trace.metadata = {"model": "gpt-4", "temperature": 0.7}
+
+        # Basic span creation
+        with opik.start_as_current_span("llm-call", type="llm", project_name="my-project") as span:
+            # Your LLM call here
+            span.input = {"prompt": "Explain quantum computing"}
+            span.output = {"response": "Quantum computing is..."}
+            span.model = "gpt-4"
+            span.provider = "openai"
+            span.usage = {
+                "prompt_tokens": 10,
+                "completion_tokens": 50,
+                "total_tokens": 60
+            }
+
+
+When to Use Context Managers
+----------------------------
+
+Use context managers when:
+
+- You need explicit control over trace/span lifecycle
+- Working with code that can't be easily decorated
+- Implementing custom error handling patterns
+- Building distributed tracing across service boundaries
+- Creating complex nested trace hierarchies
+
+For simpler use cases, consider using the `@track` decorator instead.

apps/opik-documentation/python-sdk-docs/source/context_manager/start_as_current_span.rst

@@ -0,0 +1,71 @@
+start_as_current_span
+=====================
+
+.. autofunction:: opik.start_as_current_span
+
+Examples
+--------
+
+Basic usage
+~~~~~~~~~~~
+
+.. code-block:: python
+
+   import opik
+
+   with opik.start_as_current_span("my_operation") as span:
+       # Your code here
+       span.metadata["custom_key"] = "custom_value"
+       print("Executing operation...")
+
+With input and output data
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   import opik
+
+   with opik.start_as_current_span(
+       name="llm_completion",
+       type="llm",
+       input={"prompt": "What is the capital of France?"},
+       output={"response": "The capital of France is Paris."},
+       tags=["llm", "completion"],
+       metadata={"model": "gpt-3.5-turbo"}
+   ) as span:
+       # Your LLM code here
+       pass
+
+With distributed tracing
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   import os
+   import opik
+
+   # extract headers from environment
+   distributed_trace_headers = os.environ.get("opik_distributed_trace_headers")
+
+   with opik.start_as_current_span(
+       "process_request",
+       opik_distributed_trace_headers=distributed_trace_headers
+   ) as span:
+       # Your code here
+       pass
+
+Error handling
+~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   import opik
+
+   try:
+       with opik.start_as_current_span("risky_operation") as span:
+           # Code that might fail
+           raise ValueError("Something went wrong")
+   except ValueError as e:
+       # The span will automatically capture error information
+       print(f"Operation failed: {e}")
+       # Error details are stored in span.error_info

apps/opik-documentation/python-sdk-docs/source/context_manager/start_as_current_trace.rst

@@ -0,0 +1,87 @@
+start_as_current_trace
+======================
+
+.. autofunction:: opik.start_as_current_trace
+
+Examples
+--------
+
+Basic usage
+~~~~~~~~~~~
+
+.. code-block:: python
+
+   import opik
+
+   with opik.start_as_current_trace("my_trace") as trace:
+       # Your code here
+       trace.metadata["custom_key"] = "custom_value"
+       print("Executing trace...")
+
+With input and output data
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   import opik
+
+   with opik.start_as_current_trace(
+       name="user_query_processing",
+       input={"user_question": "What is machine learning?"},
+       output={"answer": "Machine learning is a subset of AI..."},
+       tags=["user_query", "ai"],
+       metadata={"session_id": "abc123"}
+   ) as trace:
+       # Your processing code here
+       pass
+
+With conversational threads support using `thread_id` identifier
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   import opik
+   import threading
+
+   with opik.start_as_current_trace(
+       "chatbot_conversation",
+       project_name="my_project",
+       thread_id="00f067aa0ba902b7",
+   ) as trace:
+       # Your processing code here
+       pass
+
+
+Error handling
+~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   import opik
+
+   try:
+       with opik.start_as_current_trace("risky_trace") as trace:
+           # Code that might fail
+           raise RuntimeError("Something went wrong")
+   except RuntimeError as e:
+       # The trace will automatically capture error information
+       print(f"Trace failed: {e}")
+       # Error details are stored in trace.error_info
+
+Nested spans within a trace
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   import opik
+
+   with opik.start_as_current_trace("main_workflow") as trace:
+       # Main workflow code
+       
+       with opik.start_as_current_span("sub_operation_1") as span1:
+           # First sub-operation
+           pass
+       
+       with opik.start_as_current_span("sub_operation_2") as span2:
+           # Second sub-operation
+           pass

apps/opik-documentation/python-sdk-docs/source/docstring_override.py

@@ -0,0 +1,42 @@
+"""
+Custom Sphinx extension to remove Examples sections from docstrings.
+"""
+
+
+def override_docstring(app, what, name, obj, options, lines):
+    """
+    Remove Examples sections from method docstrings in opik.rest_api.
+
+    Args:
+        app: Sphinx application object
+        what: Type of object being documented
+        name: Full name of the object
+        obj: The actual object being documented
+        options: Options passed to the directive
+        lines: List of lines in the original docstring
+    """
+    if what == "method" and "opik.rest_api" in name:
+        # Remove everything after ".. rubric:: Examples"
+        for i, line in enumerate(lines):
+            if ".. rubric:: Examples" in line:
+                lines[:] = lines[:i]
+                break
+
+
+def setup(app):
+    """
+    Setup function for the Sphinx extension.
+
+    This registers the docstring override function with Sphinx's autodoc extension.
+
+    Args:
+        app: Sphinx application object
+    """
+    # Connect our override function to the autodoc-process-docstring event
+    app.connect("autodoc-process-docstring", override_docstring)
+
+    return {
+        "version": "1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

apps/opik-documentation/python-sdk-docs/source/evaluation/Dataset.rst

@@ -0,0 +1,6 @@
+Dataset
+=======
+
+.. autoclass:: opik.Dataset
+    :members:
+    :special-members: __init__

apps/opik-documentation/python-sdk-docs/source/evaluation/evaluate.rst

@@ -0,0 +1,4 @@
+evaluate
+========
+
+.. autofunction:: opik.evaluation.evaluate

apps/opik-documentation/python-sdk-docs/source/evaluation/evaluate_experiment.rst

@@ -0,0 +1,4 @@
+evaluate_experiment
+===================
+
+.. autofunction:: opik.evaluation.evaluate_experiment

apps/opik-documentation/python-sdk-docs/source/evaluation/evaluate_prompt.rst

@@ -0,0 +1,4 @@
+evaluate_prompt
+===============
+
+.. autofunction:: opik.evaluation.evaluate_prompt

apps/opik-documentation/python-sdk-docs/source/evaluation/evaluate_threads.rst

@@ -0,0 +1,5 @@
+evaluate_threads
+================
+
+.. autofunction:: opik.evaluation.evaluate_threads
+

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/AnswerRelevance.rst

@@ -0,0 +1,6 @@
+AnswerRelevance
+===============
+
+.. autoclass:: opik.evaluation.metrics.AnswerRelevance
+    :members:
+    :inherited-members:

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/BaseMetric.rst

@@ -0,0 +1,6 @@
+BaseMetric  
+==========
+
+.. autoclass:: opik.evaluation.metrics.BaseMetric
+    :members:
+    :inherited-members:

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/Contains.rst

@@ -0,0 +1,6 @@
+Contains
+========
+
+.. autoclass:: opik.evaluation.metrics.Contains
+    :members:
+    :inherited-members:

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/ContextPrecision.rst

@@ -0,0 +1,6 @@
+ContextPrecision
+================
+
+.. autoclass:: opik.evaluation.metrics.ContextPrecision
+    :members:
+    :inherited-members:

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/ContextRecall.rst

@@ -0,0 +1,6 @@
+ContextRecall
+=============
+
+.. autoclass:: opik.evaluation.metrics.ContextRecall
+    :members:
+    :inherited-members:

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/ConversationHeuristicMetrics.rst

@@ -0,0 +1,16 @@
+Conversation Heuristic Metrics
+==============================
+
+.. currentmodule:: opik.evaluation.metrics
+
+Use these fast, rule-based metrics when you want lightweight signals about dialogue
+quality without invoking an LLM judge. They operate over full conversation
+transcripts and surface issues such as repetition and missing context.
+
+.. autoclass:: ConversationDegenerationMetric
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: KnowledgeRetentionMetric
+    :special-members: __init__
+    :members: score

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/ConversationLLMJudges.rst

@@ -0,0 +1,56 @@
+Conversation LLM Judges
+=======================
+
+.. currentmodule:: opik.evaluation.metrics
+
+These evaluators wrap GEval-style LLM judges so you can score full conversations
+without manually extracting turns. They expect transcripts in the same format used
+by :class:`~opik.evaluation.metrics.ConversationThreadMetric` and typically rely on
+an OpenAI- or Azure-compatible backend. Refer to the relevant Fern guides for API
+keys, rate limits, and pricing considerations.
+
+Core Conversation Judges
+------------------------
+
+.. autoclass:: GEvalConversationMetric
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: ConversationalCoherenceMetric
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: SessionCompletenessQuality
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: UserFrustrationMetric
+    :special-members: __init__
+    :members: score
+
+Specialized Variants
+--------------------
+
+.. autoclass:: ConversationComplianceRiskMetric
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: ConversationDialogueHelpfulnessMetric
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: ConversationQARelevanceMetric
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: ConversationSummarizationCoherenceMetric
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: ConversationSummarizationConsistencyMetric
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: ConversationPromptUncertaintyMetric
+    :special-members: __init__
+    :members: score

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/ConversationThreadMetric.rst

@@ -0,0 +1,7 @@
+ConversationThreadMetric
+========================
+
+.. autoclass:: opik.evaluation.metrics.conversation.conversation_thread_metric.ConversationThreadMetric
+    :members:
+    :inherited-members:
+

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/Equals.rst

@@ -0,0 +1,6 @@
+Equals  
+======
+
+.. autoclass:: opik.evaluation.metrics.Equals
+    :members:
+    :inherited-members:

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/GEval.rst

@@ -0,0 +1,6 @@
+GEval
+=====
+
+.. autoclass:: opik.evaluation.metrics.GEval
+    :members:
+    :inherited-members:

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/Hallucination.rst

@@ -0,0 +1,6 @@
+Hallucination
+=============
+
+.. autoclass:: opik.evaluation.metrics.Hallucination
+    :members:
+    :inherited-members:

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/HeuristicMetrics.rst

@@ -0,0 +1,89 @@
+Heuristic Metrics
+=================
+
+.. currentmodule:: opik.evaluation.metrics
+
+This section lists the text-similarity, readability, safety, and sentiment metrics
+that can be composed into larger test suites. Several metrics rely on optional
+dependencies (for example, ``bert-score``, ``sacrebleu``, ``fasttext``, ``nltk``);
+install the relevant packages before scoring.
+
+Sentence & Token Overlap
+------------------------
+
+.. autoclass:: SentenceBLEU
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: CorpusBLEU
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: GLEU
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: ROUGE
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: ChrF
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: METEOR
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: BERTScore
+    :special-members: __init__
+    :members: score
+
+Distribution Comparisons
+------------------------
+
+.. autoclass:: JSDivergence
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: JSDistance
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: KLDivergence
+    :special-members: __init__
+    :members: score
+
+Rank & Readability
+------------------
+
+.. autoclass:: SpearmanRanking
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: Readability
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: Tone
+    :special-members: __init__
+    :members: score
+
+Prompt Safety & Sentiment
+-------------------------
+
+.. autoclass:: PromptInjection
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: LanguageAdherenceMetric
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: Sentiment
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: VADERSentiment
+    :special-members: __init__
+    :members: score

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/IsJson.rst

@@ -0,0 +1,6 @@
+IsJson
+======
+
+.. autoclass:: opik.evaluation.metrics.IsJson
+    :members:
+    :inherited-members:

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/LLMJudgePresets.rst

@@ -0,0 +1,69 @@
+LLM Judge Presets
+=================
+
+.. currentmodule:: opik.evaluation.metrics
+
+These presets wrap common GEval prompt templates so you can instantiate judges with
+one line of code. Provide an appropriate ``model`` (for example, ``"gpt-4o"``) and
+ensure the backing provider is configured via ``opik.configure``.
+
+Agent & Task Presets
+--------------------
+
+.. autoclass:: AgentTaskCompletionJudge
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: AgentToolCorrectnessJudge
+    :special-members: __init__
+    :members: score
+
+Conversation Quality Presets
+----------------------------
+
+.. autoclass:: DialogueHelpfulnessJudge
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: QARelevanceJudge
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: SummarizationCoherenceJudge
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: SummarizationConsistencyJudge
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: PromptUncertaintyJudge
+    :special-members: __init__
+    :members: score
+
+Risk & Bias Presets
+-------------------
+
+.. autoclass:: ComplianceRiskJudge
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: DemographicBiasJudge
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: GenderBiasJudge
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: PoliticalBiasJudge
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: RegionalBiasJudge
+    :special-members: __init__
+    :members: score
+
+.. autoclass:: ReligiousBiasJudge
+    :special-members: __init__
+    :members: score

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/LLMJuries.rst

@@ -0,0 +1,12 @@
+LLM Juries
+==========
+
+.. currentmodule:: opik.evaluation.metrics
+
+Use :class:`LLMJuriesJudge` when you want to call multiple judges and aggregate the
+results into a single decision. Provide a list of judge instances plus an
+aggregation strategy (majority vote, max confidence, etc.).
+
+.. autoclass:: LLMJuriesJudge
+    :special-members: __init__
+    :members: score

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/LevenshteinRatio.rst

@@ -0,0 +1,6 @@
+LevenshteinRatio  
+================
+
+.. autoclass:: opik.evaluation.metrics.LevenshteinRatio
+    :members:
+    :inherited-members:

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/Moderation.rst

@@ -0,0 +1,6 @@
+Moderation
+==========
+
+.. autoclass:: opik.evaluation.metrics.Moderation
+    :members:
+    :inherited-members:

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/RegexMatch.rst

@@ -0,0 +1,6 @@
+RegexMatch  
+==========
+
+.. autoclass:: opik.evaluation.metrics.RegexMatch
+    :members:
+    :inherited-members:

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/UtilityMetrics.rst

@@ -0,0 +1,15 @@
+Utility Metrics
+===============
+
+.. currentmodule:: opik.evaluation.metrics
+
+Helper components that adapt or combine other metrics. Use them to stitch existing
+evaluators together without rewriting orchestration logic.
+
+.. autoclass:: AggregatedMetric
+    :special-members: __init__
+    :members: score, validate_score_arguments
+
+.. autoclass:: RagasMetricWrapper
+    :special-members: __init__
+    :members: score

apps/opik-documentation/python-sdk-docs/source/evaluation/metrics/index.rst

@@ -0,0 +1,68 @@
+metrics
+=======
+
+Opik includes a number of pre-built metrics to help you evaluate your LLM application.
+
+Each metric can be called as a standalone function using the `score` method::
+
+   from opik.evaluation.metrics import Hallucination
+
+   metric = Hallucination()
+
+   metric.score(
+      input="What is the capital of France?",
+      output="The capital of France is Paris. It is famous for its iconic Eiffel Tower and rich cultural heritage.",
+      context=["France is a country in Western Europe. Its capital is Paris, which is known for landmarks like the Eiffel Tower."],
+   )
+
+Or as part of an evaluation run using the `evaluate` function.
+
+You can learn more about each metric in the following sections:
+
+.. toctree::
+   :maxdepth: 4
+   :titlesonly:
+
+   Equals
+   RegexMatch
+   Contains
+   IsJson
+   LevenshteinRatio
+
+   Hallucination
+   GEval
+   Moderation
+
+   AnswerRelevance
+   ContextPrecision
+   ContextRecall
+
+   BaseMetric
+   ConversationThreadMetric
+   HeuristicMetrics
+   ConversationHeuristicMetrics
+   ConversationLLMJudges
+   LLMJudgePresets
+   LLMJuries
+   UtilityMetrics
+
+The pages above fall into two categories:
+
+- Established metric guides (e.g., ``Equals``, ``Hallucination``) that remain the
+  authoritative deep dives.
+- Aggregation pages that collect the expanded metric families so every class
+  exported via :mod:`opik.evaluation.metrics` has an accompanying API reference.
+
+Use these aggregation pages to browse the extended catalog:
+
+- :doc:`HeuristicMetrics` — sentence/word overlap, readability, sentiment, prompt safety, and distribution comparisons.
+- :doc:`ConversationHeuristicMetrics` — fast heuristics for degeneracy and knowledge retention.
+- :doc:`ConversationLLMJudges` — LLM-as-a-judge conversation evaluators and session quality metrics.
+- :doc:`LLMJudgePresets` — pre-built GEval presets and bias checks.
+- :doc:`LLMJuries` — multi-judge aggregation.
+- :doc:`UtilityMetrics` — helpers such as ``AggregatedMetric`` and ``RagasMetricWrapper``.
+
+Import any metric directly from :mod:`opik.evaluation.metrics`, and pair these API
+references with the Fern guides in
+``apps/opik-documentation/documentation/fern/docs/evaluation/metrics`` for workflow
+context.

apps/opik-documentation/python-sdk-docs/source/guardrails/guardrail.rst

@@ -0,0 +1,7 @@
+Guardrail
+=========
+
+.. automodule:: opik.guardrails.guardrail
+    :members:
+    :undoc-members:
+    :show-inheritance:

apps/opik-documentation/python-sdk-docs/source/guardrails/pii.rst

@@ -0,0 +1,7 @@
+PII guardrail
+=============
+
+.. automodule:: opik.guardrails.guards.pii
+    :members:
+    :undoc-members:
+    :show-inheritance:

apps/opik-documentation/python-sdk-docs/source/guardrails/topic.rst

@@ -0,0 +1,7 @@
+Topic guardrail
+===============
+
+.. automodule:: opik.guardrails.guards.topic
+    :members:
+    :undoc-members:
+    :show-inheritance:

apps/opik-documentation/python-sdk-docs/source/guardrails/validation_response.rst

@@ -0,0 +1,7 @@
+ValidationResponse
+==================
+
+.. autoclass:: opik.guardrails.schemas.ValidationResponse
+    :members:
+    :undoc-members:
+    :show-inheritance:

apps/opik-documentation/python-sdk-docs/source/index.rst

@@ -0,0 +1,277 @@
+Opik
+====
+
+=============
+Main features
+=============
+
+The Comet Opik platform is a suite of tools that allow you to evaluate the output of an LLM powered application.
+
+In includes the following features:
+
+- `Tracing <https://www.comet.com/docs/opik/tracing/log_traces>`_: Ability to log LLM calls and traces to the Opik platform.
+- `LLM evaluation metrics <https://www.comet.com/docs/opik/evaluation/metrics/heuristic_metrics>`_: A set of functions that evaluate the output of an LLM, these are both heuristic metrics and LLM as a Judge.
+- `Evaluation <https://www.comet.com/docs/opik//evaluation/evaluate_your_llm>`_: Ability to log test datasets in Opik and evaluate using some of our LLM evaluation metrics.
+
+For a more detailed overview of the platform, you can refer to the `Comet Opik documentation <https://www.comet.com/docs/opik>`_.
+
+============
+Installation
+============
+
+To get start with the package, you can install it using pip::
+
+   pip install opik
+
+To finish configuring the Opik Python SDK, we recommend running the `opik configure` command from the command line:
+
+.. code-block:: bash
+
+   opik configure
+
+You can also call the configure function from the Python SDK:
+
+.. code-block:: python
+
+   import opik
+
+   opik.configure(use_local=False)
+
+=============
+Using the SDK
+=============
+
+-----------------
+Logging LLM calls
+-----------------
+
+To log your first trace, you can use the `track` decorator::
+
+   from opik import track
+
+   @track
+   def llm_function(input: str) -> str:
+      # Your LLM call
+      # ...
+
+      return "Hello, world!"
+
+   llm_function("Hello")
+
+**Note:** The `track` decorator supports nested functions, if you track multiple functions, each functionc call will be associated with the parent trace.
+
+**Integrations**: If you are using LangChain or OpenAI, Comet Opik as `built-in integrations <https://www.comet.com/docs/opik/integrations/langchain>`_ for these libraries.
+
+----------------------------
+Using LLM evaluation metrics
+----------------------------
+
+The opik package includes a number of LLM evaluation metrics, these are both heuristic metrics and LLM as a Judge.
+
+All available metrics are listed in the `metrics section <evaluation/metrics/index.html>`_.
+
+These evaluation metrics can be used as::
+
+   from opik.evaluation.metrics import Hallucination
+
+   metric = Hallucination()
+
+   input = "What is the capital of France?"
+   output = "The capital of France is Paris, a city known for its iconic Eiffel Tower."
+   context = "Paris is the capital and most populous city of France."
+
+   score = metric.score(input, output, context)
+   print(f"Hallucination score: {score}")
+
+-------------------
+Running evaluations
+-------------------
+
+Evaluations are run using the `evaluate` function, this function takes a dataset, a task and a list of metrics and returns a dictionary of scores::
+
+   from opik import Opik, track
+   from opik.evaluation import evaluate
+   from opik.evaluation.metrics import EqualsMetric, HallucinationMetric
+   from opik.integrations.openai import track_openai
+   from typing import Dict
+
+   from typing import Dict
+
+   # Define the task to evaluate
+   openai_client = track_openai(openai.OpenAI())
+
+   @track()
+   def your_llm_application(input: str) -> str:
+      response = openai_client.chat.completions.create(
+         model="gpt-3.5-turbo",
+         messages=[{"role": "user", "content": input}],
+      )
+
+      return response.choices[0].message.content
+
+   @track()
+   def your_context_retriever(input: str) -> str:
+      return ["..."]
+
+   # Fetch the dataset
+   client = Opik()
+   dataset = client.get_dataset(name="your-dataset-name")
+
+   # Define the metrics
+   equals_metric = EqualsMetric()
+   hallucination_metric = HallucinationMetric()
+
+   # Define and run the evaluation
+   def evaluation_task(x: Dict):
+      return {
+         "input": x.input['user_question'],
+         "output": your_llm_application(x.input['user_question']),
+         "context": your_context_retriever(x.input['user_question'])
+      }
+
+   evaluation = evaluate(
+      dataset=dataset,
+      task=evaluation_task,
+      metrics=[equals_metric, hallucination_metric],
+   )
+
+---------------
+Storing prompts
+---------------
+
+You can store prompts in the Opik library using the `Prompt` and `ChatPrompt` objects:
+
+**Text Prompts:**
+
+.. code-block:: python
+   
+   import opik
+
+   prompt = opik.Prompt(name="my-prompt", prompt="Write a summary of the following text: {{text}}")
+
+**Chat Prompts:**
+
+.. code-block:: python
+   
+   import opik
+
+   messages = [
+       {"role": "system", "content": "You are a helpful assistant."},
+       {"role": "user", "content": "Hello, {{name}}!"}
+   ]
+   chat_prompt = opik.ChatPrompt(name="my-chat-prompt", messages=messages)
+
+=========
+Reference
+=========
+
+You can learn more about the `opik` python SDK in the following sections:
+
+.. toctree::
+   :maxdepth: 1
+   
+   Opik
+   track
+   configure
+   opik_context/index
+   context_manager/index
+
+.. toctree::
+   :caption: Integrations
+   :maxdepth: 1
+   
+   integrations/anthropic/index
+   integrations/bedrock/index
+   integrations/crewai/index
+   integrations/dspy/index
+   integrations/guardrails/index
+   integrations/haystack/index
+   integrations/langchain/index
+   integrations/llama_index/index
+   integrations/openai/index
+   integrations/adk/index
+
+.. toctree::
+   :caption: Evaluation
+   :maxdepth: 1
+   
+   evaluation/Dataset
+   evaluation/evaluate
+   evaluation/evaluate_prompt
+   evaluation/evaluate_experiment
+   evaluation/evaluate_threads
+   evaluation/metrics/index
+   message_processing_emulation/index
+
+.. toctree::
+   :caption: Prompt management
+   :maxdepth: 1
+   
+   library/Prompt
+   library/ChatPrompt
+
+.. toctree::
+   :caption: Guardrails
+   :maxdepth: 1
+   
+   guardrails/guardrail
+   guardrails/topic
+   guardrails/pii
+   guardrails/validation_response
+
+.. toctree::
+   :caption: Testing
+   :maxdepth: 1
+   
+   testing/llm_unit
+
+.. toctree::
+   :caption: Simulation
+   :maxdepth: 1
+   
+   simulation/index
+
+.. toctree::
+   :caption: REST API Reference
+   :maxdepth: 1
+   
+   rest_api/overview
+   rest_api/clients/index
+   rest_api/objects
+
+.. toctree::
+   :caption: Objects
+   :maxdepth: 1
+
+   Objects/Trace.rst
+   Objects/TraceData.rst
+   Objects/TracePublic.rst
+   Objects/Span.rst
+   Objects/SpanData.rst
+   Objects/SpanPublic.rst
+   Objects/Attachment.rst
+   Objects/AttachmentClient.rst
+   Objects/FeedbackScoreDict.rst
+   Objects/Experiment.rst
+   Objects/ExperimentItemContent.rst
+   Objects/ExperimentItemReferences.rst
+   Objects/EvaluationResult.rst
+   Objects/TestResult.rst
+   Objects/Prompt.rst
+   Objects/ChatPrompt.rst
+   Objects/ScoreResult.rst
+   Objects/OpikBaseModel.rst
+   Objects/LiteLLMChatModel.rst
+   Objects/DistributedTraceHeadersDict.rst
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Command Line Interface
+
+   cli
+
+.. toctree::
+   :caption: Documentation Guides
+   :maxdepth: 1
+   
+   Opik Documentation <https://www.comet.com/docs/opik/>

apps/opik-documentation/python-sdk-docs/source/integrations/adk/OpikTracer.rst

@@ -0,0 +1,5 @@
+OpikTracer
+==========
+
+.. autoclass:: opik.integrations.adk.OpikTracer
+    :members:

apps/opik-documentation/python-sdk-docs/source/integrations/adk/index.rst

@@ -0,0 +1,33 @@
+ADK
+===
+
+Opik integrates with Adk to allow you to log your ADK agent run to the Opik platform, use the `OpikTracer` callback to start logging::
+
+      from google.adk.agents import Agent
+      from opik.integrations.adk import OpikTracer
+
+
+      opik_tracer = OpikTracer()
+
+      root_agent = Agent(
+         name="weather_time_agent",
+         model="gemini-2.0-flash-exp",
+         description=DESCRIPTION,
+         instruction=INSTRUCTION,
+         tools=[...],
+         before_agent_callback=opik_tracer.before_agent_callback,
+         after_agent_callback=opik_tracer.after_agent_callback,
+         before_model_callback=opik_tracer.before_model_callback,
+         after_model_callback=opik_tracer.after_model_callback,
+         before_tool_callback=opik_tracer.before_tool_callback,
+         after_tool_callback=opik_tracer.after_tool_callback,
+      )
+
+You can learn more about the `OpikTracer` object in the following section:
+
+.. toctree::
+   :maxdepth: 4
+   :titlesonly:
+
+   OpikTracer
+   track_adk_agent_recursive

apps/opik-documentation/python-sdk-docs/source/integrations/adk/track_adk_agent_recursive.rst

@@ -0,0 +1,4 @@
+track_adk_agent_recursive
+=========================
+
+.. autofunction:: opik.integrations.adk.track_adk_agent_recursive

apps/opik-documentation/python-sdk-docs/source/integrations/anthropic/index.rst

@@ -0,0 +1,26 @@
+Anthropic
+=========
+
+Opik integrates with Anthropic to allow you to log your Anthropic calls to the Opik platform, simply wrap the Anthropic client with `track_anthropic` to start logging::
+
+    from opik.integrations.anthropic import track_anthropic
+    from anthropic import Anthropic
+
+    anthropic_client = Anthropic()
+    openai_client = track_openai(openai_client)
+
+    response = anthropic_client.messages.create(
+        model="claude-3-5-sonnet-20241022",
+        max_tokens=1024,
+        messages=[
+            {"role": "user", "content": PROMPT}
+        ]
+    )
+
+You can learn more about the `track_anthropic` decorator in the following section:
+
+.. toctree::
+   :maxdepth: 4
+   :titlesonly:
+
+   track_anthropic

apps/opik-documentation/python-sdk-docs/source/integrations/anthropic/track_anthropic.rst

@@ -0,0 +1,4 @@
+track_anthropic
+===============
+
+.. autofunction:: opik.integrations.anthropic.track_anthropic

apps/opik-documentation/python-sdk-docs/source/integrations/bedrock/index.rst

@@ -0,0 +1,26 @@
+Bedrock
+=======
+
+Opik integrates with Bedrock to allow you to log your Bedrock calls to the Opik platform, simply wrap the Bedrock client with `track_bedrock` to start logging::
+
+   from opik.integrations.bedrock import track_bedrock
+   import boto3
+
+   bedrock = boto3.client(
+       service_name="bedrock-runtime",
+       region_name=REGION,
+   )
+   bedrock_client = track_bedrock(bedrock, project_name="bedrock-integration-demo")
+
+   response = bedrock_client.converse(
+       modelId=MODEL_ID,
+       messages=[{"role": "user", "content": [{"text": "Hello World!"}]}],
+   )
+
+You can learn more about the `track_bedrock` decorator in the following section:
+
+.. toctree::
+   :maxdepth: 4
+   :titlesonly:
+
+   track_bedrock

apps/opik-documentation/python-sdk-docs/source/integrations/bedrock/track_bedrock.rst

@@ -0,0 +1,4 @@
+track_bedrock
+=============
+
+.. autofunction:: opik.integrations.bedrock.track_bedrock

apps/opik-documentation/python-sdk-docs/source/integrations/crewai/index.rst

@@ -0,0 +1,65 @@
+CrewAI
+=======
+
+Opik integrates with CrewAI to allow you to log your CrewAI activities and LLM calls to the Opik platform, simply invoke `track_crewai` to start logging::
+
+    from opik.integrations.crewai import track_crewai
+    from crewai import Agent, Crew, Task, Process
+
+
+    class YourCrewName:
+        def agent_one(self) -> Agent:
+            return Agent(
+                role="Data Analyst",
+                goal="Analyze data trends in the market",
+                backstory="An experienced data analyst with a background in economics",
+                verbose=True,
+            )
+
+        def agent_two(self) -> Agent:
+            return Agent(
+                role="Market Researcher",
+                goal="Gather information on market dynamics",
+                backstory="A diligent researcher with a keen eye for detail",
+                verbose=True
+            )
+
+        def task_one(self) -> Task:
+            return Task(
+                name="Collect Data Task",
+                description="Collect recent market data and identify trends.",
+                expected_output="A report summarizing key trends in the market.",
+                agent=self.agent_one()
+            )
+
+        def task_two(self) -> Task:
+            return Task(
+                name="Market Research Task",
+                description="Research factors affecting market dynamics.",
+                expected_output="An analysis of factors influencing the market.",
+                agent=self.agent_two()
+            )
+
+        def crew(self) -> Crew:
+            return Crew(
+                agents=[self.agent_one(), self.agent_two()],
+                tasks=[self.task_one(), self.task_two()],
+                process=Process.sequential,
+                verbose=True
+            )
+
+    track_crewai(project_name="crewai-integration-demo")
+
+    my_crew = YourCrewName().crew()
+    result = my_crew.kickoff()
+
+    print(result)
+
+
+You can learn more about the `track_crewai` decorator in the following section:
+
+.. toctree::
+   :maxdepth: 4
+   :titlesonly:
+
+   track_crewai

apps/opik-documentation/python-sdk-docs/source/integrations/crewai/track_crewai.rst

@@ -0,0 +1,4 @@
+track_crewai
+=============
+
+.. autofunction:: opik.integrations.crewai.track_crewai

apps/opik-documentation/python-sdk-docs/source/integrations/dspy/OpikCallback.rst

@@ -0,0 +1,5 @@
+OpikCallback
+============
+
+.. autoclass:: opik.integrations.dspy.OpikCallback
+    :members:

apps/opik-documentation/python-sdk-docs/source/integrations/dspy/index.rst

@@ -0,0 +1,32 @@
+DSPy
+====
+
+Opik integrates with DSPy to allow you to log your DSPy runs to the Opik platform::
+
+    import dspy
+    from opik.integrations.dspy.callback import OpikCallback
+
+    project_name = "DSPY"
+
+    lm = dspy.LM(
+        model="openai/gpt-4o-mini",
+    )
+    dspy.configure(lm=lm)
+
+
+    opik_callback = OpikCallback(project_name=project_name, log_graph=True)
+    dspy.settings.configure(
+        callbacks=[opik_callback],
+    )
+
+    cot = dspy.ChainOfThought("question -> answer")
+    cot(question="What is the meaning of life?")
+
+
+You can learn more about the `OpikCallback` in the following section:
+
+.. toctree::
+   :maxdepth: 4
+   :titlesonly:
+
+   OpikCallback

apps/opik-documentation/python-sdk-docs/source/integrations/guardrails/index.rst

@@ -0,0 +1,44 @@
+Guardrails AI
+=============
+
+Opik integrates with Guardrails AI to allow you to log your activities to the Opik platform, simply invoke `track_guardrails` to start logging.
+
+
+First, install the politeness check from the guardrails hub:
+
+``guardrails hub install hub://guardrails/politeness_check``
+
+
+Then you can run the example:
+::
+
+    from guardrails import Guard, OnFailAction
+    from guardrails.hub import PolitenessCheck
+
+    import opik
+    from opik.integrations.guardrails import track_guardrails
+
+    politeness_check = PolitenessCheck(
+        llm_callable="gpt-3.5-turbo", on_fail=OnFailAction.NOOP
+    )
+
+    guard: Guard = Guard()
+    if hasattr(guard, "use_many"):
+        guard = guard.use_many(politeness_check)
+    else:
+        guard = guard.use(politeness_check)
+    guard = track_guardrails(guard, project_name="guardrails-integration-example")
+
+    result = guard.validate(
+        "Would you be so kind to pass me a cup of tea?",
+    )
+
+Every guardrails check will be logged as a separate trace. Opik will capture inputs, outputs, and provide the trace with a tag "fail" or "pass" for easier management.
+
+You can learn more about the `track_guardrails` decorator in the following section:
+
+.. toctree::
+   :maxdepth: 4
+   :titlesonly:
+
+   track_guardrails

apps/opik-documentation/python-sdk-docs/source/integrations/guardrails/track_guardrails.rst

@@ -0,0 +1,4 @@
+track_guardrails
+================
+
+.. autofunction:: opik.integrations.guardrails.track_guardrails

apps/opik-documentation/python-sdk-docs/source/integrations/haystack/OpikConnector.rst

@@ -0,0 +1,5 @@
+OpikConnector
+=============
+
+.. autoclass:: opik.integrations.haystack.OpikConnector
+    :members:

apps/opik-documentation/python-sdk-docs/source/integrations/haystack/index.rst

@@ -0,0 +1,53 @@
+Haystack
+========
+
+Opik integrates with Haystack to allow you to log your Haystack pipeline runs to the Opik platform, simply wrap the Haystack pipeline with `OpikConnector` to start logging::
+
+   import os
+
+    os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true"
+
+    from haystack import Pipeline
+    from haystack.components.builders import ChatPromptBuilder
+    from haystack.components.generators.chat import OpenAIChatGenerator
+    from haystack.dataclasses import ChatMessage
+
+    from opik.integrations.haystack import OpikConnector
+
+
+    pipe = Pipeline()
+
+    # Add the OpikConnector component to the pipeline
+    pipe.add_component(
+        "tracer", OpikConnector("Chat example")
+    )
+
+    # Continue building the pipeline
+    pipe.add_component("prompt_builder", ChatPromptBuilder())
+    pipe.add_component("llm", OpenAIChatGenerator(model="gpt-3.5-turbo"))
+
+    pipe.connect("prompt_builder.prompt", "llm.messages")
+
+    messages = [
+        ChatMessage.from_system(
+            "Always respond in German even if some input data is in other languages."
+        ),
+        ChatMessage.from_user("Tell me about {{location}}"),
+    ]
+
+    response = pipe.run(
+        data={
+            "prompt_builder": {
+                "template_variables": {"location": "Berlin"},
+                "template": messages,
+            }
+        }
+    )
+
+You can learn more about the `OpikConnector` in the following section:
+
+.. toctree::
+   :maxdepth: 4
+   :titlesonly:
+
+   OpikConnector

apps/opik-documentation/python-sdk-docs/source/integrations/langchain/OpikTracer.rst

@@ -0,0 +1,5 @@
+OpikTracer
+==========
+
+.. autoclass:: opik.integrations.langchain.OpikTracer
+    :members:

apps/opik-documentation/python-sdk-docs/source/integrations/langchain/extract_current_langgraph_span_data.rst

@@ -0,0 +1,5 @@
+extract_current_langgraph_span_data
+===================================
+
+.. autofunction:: opik.integrations.langchain.extract_current_langgraph_span_data
+

apps/opik-documentation/python-sdk-docs/source/integrations/langchain/index.rst

@@ -0,0 +1,36 @@
+langchain
+=========
+
+Opik integrates with Langchain to allow you to log your Langchain calls to the Opik platform, simply wrap the Langchain client with `OpikTracer` to start logging::
+
+   from langchain.chains import LLMChain
+   from langchain_openai import OpenAI
+   from langchain.prompts import PromptTemplate
+   from opik.integrations.langchain import OpikTracer
+
+   # Initialize the tracer
+   opik_tracer = OpikTracer()
+
+   # Create the LLM Chain using LangChain
+   llm = OpenAI(temperature=0)
+
+   prompt_template = PromptTemplate(
+      input_variables=["input"],
+      template="Translate the following text to French: {input}"
+   )
+
+   llm_chain = LLMChain(llm=llm, prompt=prompt_template)
+
+   # Generate the translations
+   translation = llm_chain.run("Hello, how are you?", callbacks=[opik_tracer])
+   print(translation)
+
+You can learn more about the LangChain integration functions in the following sections:
+
+.. toctree::
+   :maxdepth: 4
+   :titlesonly:
+
+   OpikTracer
+   track_langgraph
+   extract_current_langgraph_span_data

apps/opik-documentation/python-sdk-docs/source/integrations/langchain/track_langgraph.rst

@@ -0,0 +1,5 @@
+track_langgraph
+===============
+
+.. autofunction:: opik.integrations.langchain.track_langgraph
+

apps/opik-documentation/python-sdk-docs/source/integrations/llama_index/LlamaIndexCallbackHandler.rst

@@ -0,0 +1,4 @@
+LlamaIndexCallbackHandler
+=========================
+
+.. autofunction:: opik.integrations.llama_index.LlamaIndexCallbackHandler

apps/opik-documentation/python-sdk-docs/source/integrations/llama_index/index.rst

@@ -0,0 +1,19 @@
+llama_index
+===========
+
+Opik integrates with LlamaIndex to allow you to log your LlamaIndex calls to the Opik platform. To enable the logging to Opik, simply set::
+    
+    from llama_index.core import Settings
+    from llama_index.core.callbacks import CallbackManager
+    from opik.integrations.llama_index import LlamaIndexCallbackHandler
+
+    opik_callback_handler = LlamaIndexCallbackHandler()
+    Settings.callback_manager = CallbackManager([opik_callback_handler])
+
+You can learn more about the `LlamaIndexCallbackHandler` callback in the following section:
+
+.. toctree::
+   :maxdepth: 4
+   :titlesonly:
+
+   LlamaIndexCallbackHandler

apps/opik-documentation/python-sdk-docs/source/integrations/openai/index.rst

@@ -0,0 +1,22 @@
+openai
+=======
+
+Opik integrates with OpenAI to allow you to log your OpenAI calls to the Opik platform, simply wrap the OpenAI client with `track_openai` to start logging::
+
+   from opik.integrations.openai import track_openai
+   from openai import OpenAI
+
+   openai_client = OpenAI()
+   openai_client = track_openai(openai_client)
+
+   response = openai_client.Completion.create(
+      prompt="Hello, world!",
+   )
+
+You can learn more about the `track_openai` decorator in the following section:
+
+.. toctree::
+   :maxdepth: 4
+   :titlesonly:
+
+   track_openai

apps/opik-documentation/python-sdk-docs/source/integrations/openai/track_openai.rst

@@ -0,0 +1,4 @@
+track_openai
+============
+
+.. autofunction:: opik.integrations.openai.track_openai

apps/opik-documentation/python-sdk-docs/source/library/ChatPrompt.rst

@@ -0,0 +1,8 @@
+ChatPrompt
+==========
+
+.. autoclass:: opik.ChatPrompt
+    :members:
+    :inherited-members:
+    :special-members: __init__
+

apps/opik-documentation/python-sdk-docs/source/library/Prompt.rst

@@ -0,0 +1,7 @@
+Prompt
+======
+
+.. autoclass:: opik.Prompt
+    :members:
+    :inherited-members:
+    :special-members: __init__

apps/opik-documentation/python-sdk-docs/source/message_processing_emulation/ExperimentItemModel.rst

@@ -0,0 +1,67 @@
+ExperimentItemModel
+===================
+
+.. currentmodule:: opik.message_processing.emulation.models
+
+.. autoclass:: ExperimentItemModel
+    :special-members: __init__
+
+Description
+-----------
+
+``ExperimentItemModel`` links a trace produced during evaluation to the dataset item
+and experiment run that generated it. The SDK instantiates these records for you
+while :func:`opik.evaluate` or experiment reruns execute; most users interact with
+them through ``ScoreResult.metadata`` rather than constructing instances manually.
+Metrics that analyse evaluation outputs can rely on this structure to connect
+results back to source data.
+
+Attributes
+----------
+
+.. attribute:: id
+   :type: str
+   :noindex:
+
+   Unique identifier for the experiment item record.
+
+.. attribute:: experiment_id
+   :type: str
+   :noindex:
+
+   Identifier of the experiment that produced this item.
+
+.. attribute:: trace_id
+   :type: str
+   :noindex:
+
+   Identifier of the trace logged during the evaluation run.
+
+.. attribute:: dataset_item_id
+   :type: str
+   :noindex:
+
+   Identifier of the dataset item evaluated in this experiment result.
+
+Usage Example
+-------------
+
+The SDK populates ``ExperimentItemModel`` instances automatically while running evaluations:
+
+.. code-block:: python
+
+   from opik.message_processing.emulation.models import ExperimentItemModel
+
+   experiment_item = ExperimentItemModel(
+       id="exp_item_001",
+       experiment_id="exp_123",
+       trace_id="trace_abc",
+       dataset_item_id="dataset_item_xyz",
+   )
+
+See Also
+--------
+
+- :class:`TraceModel` - Stores the trace referenced by ``trace_id``.
+- :class:`SpanModel` - Contains spans that reference the same experiment item.
+- :doc:`../evaluation/evaluate` - How experiments produce trace results.

apps/opik-documentation/python-sdk-docs/source/message_processing_emulation/FeedbackScoreModel.rst

@@ -0,0 +1,95 @@
+FeedbackScoreModel
+==================
+
+.. currentmodule:: opik.message_processing.emulation.models
+
+.. autoclass:: FeedbackScoreModel
+    :special-members: __init__
+
+Description
+-----------
+
+The ``FeedbackScoreModel`` class represents a feedback score used to evaluate specific spans or traces in the Opik system. It stores and manages feedback scores linked to defined criteria, including identifiers, names, values, categories, and explanations for each score.
+
+This model is typically used in evaluation contexts where you need to score or rate the performance of traces and spans based on various metrics.
+
+Attributes
+----------
+
+.. attribute:: id
+   :type: str
+   :noindex:
+
+   Unique identifier for the feedback score.
+
+.. attribute:: name
+   :type: str
+   :noindex:
+
+   Name associated with the feedback score, typically describing the metric being measured.
+
+.. attribute:: value
+   :type: float
+   :noindex:
+
+   The numerical value of the feedback score. This represents the actual score or rating assigned.
+
+.. attribute:: category_name
+   :type: Optional[str]
+   :value: None
+   :noindex:
+
+   Category to which the feedback score belongs, if any. This can be used to group related feedback scores together.
+
+.. attribute:: reason
+   :type: Optional[str]
+   :value: None
+   :noindex:
+
+   Reason or explanation for the feedback score, if available. This provides context for why a particular score was assigned.
+
+Examples
+--------
+
+Creating a basic feedback score:
+
+.. code-block:: python
+
+    from opik.message_processing.emulation.models import FeedbackScoreModel
+
+    # Create a feedback score for a quality metric
+    feedback_score = FeedbackScoreModel(
+        id="score_123",
+        name="response_quality",
+        value=0.85,
+        category_name="quality",
+        reason="Response was accurate and well-structured"
+    )
+
+Creating a feedback score with minimal information:
+
+.. code-block:: python
+
+    # Create a simple feedback score
+    simple_score = FeedbackScoreModel(
+        id="score_456",
+        name="accuracy",
+        value=1.0
+    )
+
+Usage in Evaluation
+-------------------
+
+``FeedbackScoreModel`` objects are commonly used in:
+
+- **Evaluation Metrics**: Storing results from custom evaluation metrics
+- **Span Scoring**: Associating quality scores with specific spans
+- **Trace Evaluation**: Rating overall trace performance
+- **A/B Testing**: Comparing different model outputs with scored feedback
+
+See Also
+--------
+
+- :class:`SpanModel` - Contains lists of feedback scores
+- :class:`TraceModel` - Also contains lists of feedback scores
+- :doc:`../evaluation/evaluate` - For information about evaluation metrics that generate these scores

apps/opik-documentation/python-sdk-docs/source/message_processing_emulation/SpanModel.rst

@@ -0,0 +1,247 @@
+SpanModel
+=========
+
+.. currentmodule:: opik.message_processing.emulation.models
+
+.. autoclass:: SpanModel
+    :special-members: __init__
+
+Description
+-----------
+
+The ``SpanModel`` class represents a span model used to describe specific points in a process, their metadata, and associated data. This class is used to store and manipulate structured data for events or spans, including metadata, time markers, associated input/output, tags, and additional properties.
+
+It serves as a representative structure for recording and organizing event-specific information, often used in applications like logging, distributed tracing, or data processing pipelines. In the context of Opik, spans represent individual operations or function calls within a larger trace.
+
+Attributes
+----------
+
+Required Attributes
+~~~~~~~~~~~~~~~~~~~
+
+.. attribute:: id
+   :type: str
+   :noindex:
+
+   Unique identifier for the span.
+
+.. attribute:: start_time
+   :type: datetime.datetime
+   :noindex:
+
+   Start time of the span, marking when the operation began.
+
+Optional Attributes
+~~~~~~~~~~~~~~~~~~~
+
+.. attribute:: name
+   :type: Optional[str]
+   :noindex:
+   :value: None
+
+   Name of the span, if provided. This typically describes the operation being performed.
+
+.. attribute:: input
+   :type: Optional[Dict[str, Any]]
+   :noindex:
+   :value: None
+
+   Input data associated with the span, if any. This contains the parameters or data passed to the operation.
+
+.. attribute:: output
+   :type: Optional[Dict[str, Any]]
+   :noindex:
+   :value: None
+
+   Output data associated with the span, if any. This contains the results or return values from the operation.
+
+.. attribute:: tags
+   :type: Optional[List[str]]
+   :noindex:
+   :value: None
+
+   List of tags linked to the span. Tags are used for categorization and filtering.
+
+.. attribute:: metadata
+   :type: Optional[Dict[str, Any]]
+   :noindex:
+   :value: None
+
+   Additional metadata for the span. This can contain any custom information about the operation.
+
+.. attribute:: type
+   :type: str
+   :noindex:
+   :value: "general"
+
+   Type of the span, defaulting to "general". Common types include "llm", "general", "tool", etc.
+
+.. attribute:: usage
+   :type: Optional[Dict[str, Any]]
+   :noindex:
+   :value: None
+
+   Usage-related information for the span, such as token counts, API usage statistics, etc.
+
+.. attribute:: end_time
+   :type: Optional[datetime.datetime]
+   :noindex:
+   :value: None
+
+   End time of the span, if available. This marks when the operation completed.
+
+.. attribute:: project_name
+   :type: str
+   :noindex:
+   :value: OPIK_PROJECT_DEFAULT_NAME
+
+   Name of the project the span is associated with, defaulting to a predefined project name.
+
+.. attribute:: model
+   :type: Optional[str]
+   :noindex:
+   :value: None
+
+   Model identification used, if applicable. This is commonly used for LLM spans to track which model was used.
+
+.. attribute:: provider
+   :type: Optional[str]
+   :noindex:
+   :value: None
+
+   Provider of the span or associated services, if any. Examples include "openai", "anthropic", etc.
+
+.. attribute:: error_info
+   :type: Optional[ErrorInfoDict]
+   :noindex:
+   :value: None
+
+   Error information or diagnostics for the span, if applicable. Contains details about any errors that occurred.
+
+.. attribute:: total_cost
+   :type: Optional[float]
+   :noindex:
+   :value: None
+
+   Total cost incurred associated with this span, if relevant. This is useful for tracking API costs.
+
+.. attribute:: last_updated_at
+   :type: Optional[datetime.datetime]
+   :noindex:
+   :value: None
+
+   Timestamp of when the span was last updated, if available.
+
+Collection Attributes
+~~~~~~~~~~~~~~~~~~~~~
+
+.. attribute:: spans
+   :type: List[SpanModel]
+   :noindex:
+
+   List of nested spans related to this span. This creates a hierarchical structure where spans can contain child spans.
+
+.. attribute:: feedback_scores
+   :type: List[FeedbackScoreModel]
+   :noindex:
+
+   List of feedback scores associated with the span. These scores are used for evaluation and quality assessment.
+
+Examples
+--------
+
+Creating a basic span:
+
+.. code-block:: python
+
+    import datetime
+    from opik.message_processing.emulation.models import SpanModel
+
+    # Create a simple span
+    span = SpanModel(
+        id="span_123",
+        start_time=datetime.datetime.now(),
+        name="llm_call",
+        type="llm",
+        input={"prompt": "What is the capital of France?"},
+        output={"response": "Paris is the capital of France."},
+        model="gpt-4",
+        provider="openai"
+    )
+
+Creating a span with nested spans:
+
+.. code-block:: python
+
+    # Create a parent span with child spans
+    parent_span = SpanModel(
+        id="parent_123",
+        start_time=datetime.datetime.now(),
+        name="complex_operation"
+    )
+
+    child_span = SpanModel(
+        id="child_456",
+        start_time=datetime.datetime.now(),
+        name="preprocessing_step"
+    )
+
+    parent_span.spans.append(child_span)
+
+Adding feedback scores to a span:
+
+.. code-block:: python
+
+    from opik.message_processing.emulation.models import FeedbackScoreModel
+
+    # Add evaluation scores to the span
+    quality_score = FeedbackScoreModel(
+        id="score_789",
+        name="response_quality",
+        value=0.92,
+        reason="High quality response with accurate information"
+    )
+
+    span.feedback_scores.append(quality_score)
+
+Usage in Task Span Evaluation
+-----------------------------
+
+``SpanModel`` objects are particularly important in task span evaluation, where custom metrics can analyze the span data:
+
+.. code-block:: python
+
+    from opik.evaluation.metrics import BaseMetric, score_result
+
+    class CustomSpanMetric(BaseMetric):
+        def score(self, task_span: SpanModel) -> score_result.ScoreResult:
+            # Access span properties for evaluation
+            input_data = task_span.input
+            output_data = task_span.output
+
+            # Perform custom evaluation logic
+            score_value = self.evaluate_span_quality(input_data, output_data)
+
+            return score_result.ScoreResult(
+                value=score_value,
+                name=self.name,
+                reason=f"Evaluated span '{task_span.name}'"
+            )
+
+Common Use Cases
+----------------
+
+``SpanModel`` is commonly used for:
+
+- **Function Tracking**: Recording individual function or method calls
+- **LLM Operations**: Tracking language model API calls with usage and cost information
+- **Pipeline Steps**: Representing steps in data processing pipelines
+- **Evaluation**: Providing detailed execution data for custom evaluation metrics
+- **Debugging**: Analyzing the structure and performance of complex operations
+
+See Also
+--------
+
+- :class:`TraceModel` - The parent container that holds spans
+- :class:`FeedbackScoreModel` - For attaching evaluation scores to spans
+- :doc:`../evaluation/evaluate` - For information about evaluating spans with custom metrics

apps/opik-documentation/python-sdk-docs/source/message_processing_emulation/TraceModel.rst

@@ -0,0 +1,254 @@
+TraceModel
+==========
+
+.. currentmodule:: opik.message_processing.emulation.models
+
+.. autoclass:: TraceModel
+    :special-members: __init__
+
+Description
+-----------
+
+The ``TraceModel`` class represents a trace model that encapsulates data about a trace, its related metadata, and associated spans. It is used for tracking and analyzing data during execution or processing tasks.
+
+This class provides a structure to represent trace information, including the start and end times, associated project details, input/output data, feedback scores, error information, and thread association. It is designed to handle optional fields for flexible use across various scenarios.
+
+A trace represents the complete execution path of a request or operation, containing one or more spans that represent individual steps or components within that execution.
+
+Attributes
+----------
+
+Required Attributes
+~~~~~~~~~~~~~~~~~~~
+
+.. attribute:: id
+   :type: str
+   :noindex:
+
+   Unique identifier for the trace.
+
+.. attribute:: start_time
+   :type: datetime.datetime
+   :noindex:
+
+   Timestamp representing the start of the trace.
+
+.. attribute:: name
+   :type: Optional[str]
+   :noindex:
+
+   Optional name for the trace, which can provide a descriptive label for the operation being traced.
+
+.. attribute:: project_name
+   :type: str
+   :noindex:
+
+   Name of the project associated with the trace.
+
+Optional Attributes
+~~~~~~~~~~~~~~~~~~~
+
+.. attribute:: input
+   :type: Optional[Dict[str, Any]]
+   :noindex:
+   :value: None
+
+   Optional dictionary containing the input data associated with the trace. This represents the initial parameters or data that started the trace.
+
+.. attribute:: output
+   :type: Optional[Dict[str, Any]]
+   :noindex:
+   :value: None
+
+   Optional dictionary containing the output data generated by the trace. This represents the final results or return values.
+
+.. attribute:: tags
+   :type: Optional[List[str]]
+   :noindex:
+   :value: None
+
+   Optional list of tags associated with the trace for classification or filtering purposes.
+
+.. attribute:: metadata
+   :type: Optional[Dict[str, Any]]
+   :noindex:
+   :value: None
+
+   Optional metadata providing additional information about the trace.
+
+.. attribute:: end_time
+   :type: Optional[datetime.datetime]
+   :noindex:
+   :value: None
+
+   Timestamp representing the end of the trace. When set, this marks when the operation completed.
+
+.. attribute:: error_info
+   :type: Optional[ErrorInfoDict]
+   :noindex:
+   :value: None
+
+   Optional dictionary containing information about errors encountered during the trace.
+
+.. attribute:: thread_id
+   :type: Optional[str]
+   :noindex:
+   :value: None
+
+   Optional identifier of the thread associated with the trace. Useful for concurrent operations.
+
+.. attribute:: last_updated_at
+   :type: Optional[datetime.datetime]
+   :noindex:
+   :value: None
+
+   Timestamp for when the trace was last updated.
+
+Collection Attributes
+~~~~~~~~~~~~~~~~~~~~~
+
+.. attribute:: spans
+   :type: List[SpanModel]
+   :noindex:
+
+   List of spans associated with the trace, representing individual processing parts or segments within the trace. Each span represents a specific operation or step in the overall execution.
+
+.. attribute:: feedback_scores
+   :type: List[FeedbackScoreModel]
+   :noindex:
+
+   List of feedback scores associated with the trace. These are used for overall trace evaluation and quality assessment.
+
+Examples
+--------
+
+Creating a basic trace:
+
+.. code-block:: python
+
+    import datetime
+    from opik.message_processing.emulation.models import TraceModel
+
+    # Create a simple trace
+    trace = TraceModel(
+        id="trace_123",
+        start_time=datetime.datetime.now(),
+        name="user_query_processing",
+        project_name="my_project",
+        input={"user_query": "What is machine learning?"},
+        output={"response": "Machine learning is a subset of AI..."}
+    )
+
+Creating a trace with spans:
+
+.. code-block:: python
+
+    from opik.message_processing.emulation.models import SpanModel
+
+    # Create a trace with associated spans
+    trace = TraceModel(
+        id="trace_456",
+        start_time=datetime.datetime.now(),
+        name="complex_operation",
+        project_name="ai_project"
+    )
+
+    # Add spans to represent different steps
+    preprocessing_span = SpanModel(
+        id="span_1",
+        start_time=datetime.datetime.now(),
+        name="data_preprocessing"
+    )
+
+    llm_span = SpanModel(
+        id="span_2",
+        start_time=datetime.datetime.now(),
+        name="llm_call",
+        type="llm"
+    )
+
+    trace.spans.extend([preprocessing_span, llm_span])
+
+Adding feedback scores to a trace:
+
+.. code-block:: python
+
+    from opik.message_processing.emulation.models import FeedbackScoreModel
+
+    # Add overall evaluation scores to the trace
+    overall_quality = FeedbackScoreModel(
+        id="score_123",
+        name="overall_quality",
+        value=0.88,
+        reason="Good response quality with minor improvements needed"
+    )
+
+    trace.feedback_scores.append(overall_quality)
+
+Working with trace hierarchies:
+
+.. code-block:: python
+
+    # Access nested spans within a trace
+    for span in trace.spans:
+        print(f"Span: {span.name}")
+
+        # Each span can have nested spans too
+        for nested_span in span.spans:
+            print(f"  Nested: {nested_span.name}")
+
+Usage in Evaluation Context
+---------------------------
+
+``TraceModel`` objects are commonly used in evaluation scenarios where you need to analyze the complete execution:
+
+.. code-block:: python
+
+    # Example of accessing trace data in evaluation
+    def analyze_trace(trace: TraceModel):
+        # Analyze overall trace performance
+        duration = trace.end_time - trace.start_time if trace.end_time else None
+
+        # Count different types of spans
+        llm_spans = [s for s in trace.spans if s.type == "llm"]
+
+        # Analyze input/output
+        input_complexity = len(str(trace.input)) if trace.input else 0
+        output_quality = evaluate_output_quality(trace.output)
+
+        return {
+            "duration": duration,
+            "llm_calls": len(llm_spans),
+            "complexity": input_complexity,
+            "quality": output_quality
+        }
+
+Common Use Cases
+----------------
+
+``TraceModel`` is commonly used for:
+
+- **Request Tracking**: Tracking complete user requests from start to finish
+- **Performance Analysis**: Analyzing the performance of complex operations
+- **Evaluation**: Providing complete context for evaluation metrics
+- **Debugging**: Understanding the full execution path and identifying issues
+- **Cost Tracking**: Aggregating costs across all spans in a trace
+- **A/B Testing**: Comparing different execution paths and their outcomes
+
+Relationship with Spans
+-----------------------
+
+A trace acts as a container for spans, creating a hierarchical structure:
+
+- **Trace**: The top-level container representing the complete operation
+- **Spans**: Individual steps or operations within the trace
+- **Nested Spans**: Spans can contain other spans, creating a tree structure
+
+This hierarchy allows for detailed tracking of complex operations while maintaining the overall context.
+
+See Also
+--------
+
+- :class:`SpanModel` - Individual operations within a trace
+- :class:`FeedbackScoreModel` - For attaching evaluation scores to traces
+- :doc:`../evaluation/evaluate` - For information about evaluating traces with custom metrics

apps/opik-documentation/python-sdk-docs/source/message_processing_emulation/index.rst

@@ -0,0 +1,158 @@
+Message Processing Emulation Models
+====================================
+
+.. currentmodule:: opik.message_processing.emulation.models
+
+This module provides data models used for message processing emulation in Opik. These models represent the core data structures for traces, spans, and feedback scores that are used internally by the Opik SDK during evaluation.
+
+Overview
+--------
+
+The message processing emulation models are primarily used in evaluation contexts, particularly for task span evaluation where custom metrics need access to detailed execution information. These models provide a structured representation of:
+
+- **Traces**: Complete execution paths of requests or operations
+- **Spans**: Individual steps or operations within a trace
+- **Feedback Scores**: Evaluation results attached to traces and spans
+- **Experiment Items**: Links between traces, datasets, and experiment runs
+
+Key Classes
+-----------
+
+.. toctree::
+   :maxdepth: 1
+
+   FeedbackScoreModel
+   SpanModel
+   TraceModel
+   ExperimentItemModel
+   local_recording
+
+Class Hierarchy
+---------------
+
+The models form a hierarchical relationship:
+
+.. code-block:: text
+
+    TraceModel
+    ├── spans: List[SpanModel]
+    │   ├── spans: List[SpanModel]  (nested spans)
+    │   └── feedback_scores: List[FeedbackScoreModel]
+    └── feedback_scores: List[FeedbackScoreModel]
+
+Quick Start
+-----------
+
+Import the models:
+
+.. code-block:: python
+
+    from opik.message_processing.emulation.models import (
+        TraceModel,
+        SpanModel,
+        FeedbackScoreModel,
+        ExperimentItemModel
+    )
+
+Common Usage Patterns
+---------------------
+
+Task Span Evaluation
+~~~~~~~~~~~~~~~~~~~~~
+
+The primary use case for these models is in task span evaluation, where custom metrics analyze span data:
+
+.. code-block:: python
+
+    from opik.evaluation.metrics import BaseMetric, score_result
+    from opik.message_processing.emulation.models import SpanModel
+
+    class CustomSpanMetric(BaseMetric):
+        def score(self, task_span: SpanModel) -> score_result.ScoreResult:
+            # Access span properties
+            span_name = task_span.name
+            input_data = task_span.input
+            output_data = task_span.output
+
+            # Perform evaluation logic
+            score_value = self.evaluate_span(span_name, input_data, output_data)
+
+            return score_result.ScoreResult(
+                value=score_value,
+                name=self.name,
+                reason=f"Evaluated span: {span_name}"
+            )
+
+Analyzing Trace Structure
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can traverse and analyze the hierarchical structure of traces:
+
+.. code-block:: python
+
+    def analyze_trace_structure(trace: TraceModel):
+        print(f"Trace: {trace.name}")
+        print(f"Total spans: {len(trace.spans)}")
+
+        for span in trace.spans:
+            print(f"  Span: {span.name} (type: {span.type})")
+
+            # Analyze nested spans
+            for nested_span in span.spans:
+                print(f"    Nested: {nested_span.name}")
+
+Working with Feedback Scores
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Both traces and spans can contain feedback scores from evaluations:
+
+.. code-block:: python
+
+    def collect_all_scores(trace: TraceModel):
+        all_scores = []
+
+        # Collect trace-level scores
+        all_scores.extend(trace.feedback_scores)
+
+        # Collect span-level scores
+        for span in trace.spans:
+            all_scores.extend(span.feedback_scores)
+
+            # Recursively collect from nested spans
+            for nested_span in span.spans:
+                all_scores.extend(nested_span.feedback_scores)
+
+        return all_scores
+
+Integration with Evaluation System
+----------------------------------
+
+These models are automatically populated and used by the Opik evaluation system:
+
+1. **Trace Creation**: When you run ``opik.evaluate()``, traces are automatically created
+2. **Span Population**: Individual function calls become spans within the trace
+3. **Task Span Evaluation**: Metrics with ``task_span`` parameters receive ``SpanModel`` objects
+4. **Score Attachment**: Feedback scores are automatically attached to the appropriate traces and spans
+
+You typically don't need to create these models manually - they're generated automatically during evaluation. However, understanding their structure is essential for writing effective task span evaluation metrics.
+
+Use Cases
+---------
+
+These models are commonly used for:
+
+- **Custom Evaluation Metrics**: Analyzing detailed execution data in custom metrics
+- **Performance Analysis**: Understanding execution patterns and performance characteristics
+- **Debugging**: Investigating issues in complex operations
+- **Cost Tracking**: Aggregating usage and cost information across operations
+- **Quality Assessment**: Evaluating the quality of individual steps and overall operations
+
+Module Reference
+----------------
+
+For detailed API documentation, see the following class reference pages:
+
+- :doc:`TraceModel <../message_processing_emulation/TraceModel>`
+- :doc:`SpanModel <../message_processing_emulation/SpanModel>`
+- :doc:`FeedbackScoreModel <../message_processing_emulation/FeedbackScoreModel>`
+- :doc:`ExperimentItemModel <../message_processing_emulation/ExperimentItemModel>`

apps/opik-documentation/python-sdk-docs/source/message_processing_emulation/local_recording.rst

@@ -0,0 +1,49 @@
+Local Recording Context Manager
+===============================
+
+.. currentmodule:: opik
+
+`record_traces_locally`
+-----------------------
+
+The ``record_traces_locally`` context manager enables local, in-memory recording of any traces and spans created inside its block. This is useful for testing, debugging, or for programmatically inspecting your span/trace trees without sending data to the backend.
+
+Basic usage
+~~~~~~~~~~~
+
+.. code-block:: python
+
+    import opik
+
+    with opik.record_traces_locally() as storage:
+        # Your instrumented code that creates traces/spans
+        # e.g., functions decorated with @opik.track, manual opik.Opik().span()/trace(), integrations, etc.
+        ...
+
+        # Access in-memory results (automatically flushed before reading)
+        span_models = storage.span_trees
+        trace_models = storage.trace_trees
+
+What it returns
+~~~~~~~~~~~~~~~
+
+The context yields a lightweight handle having these properties:
+
+- ``span_trees``: List of :class:`opik.message_processing.emulation.models.SpanModel`
+- ``trace_trees``: List of :class:`opik.message_processing.emulation.models.TraceModel`
+
+Each accessor flushes the Opik client to ensure all in-flight messages are processed before reading the local state.
+
+No nested usage
+~~~~~~~~~~~~~~~~
+
+Nested or concurrent usages within the same process are not supported. If a local recording is already active, entering another ``record_traces_locally`` block raises ``RuntimeError``.
+
+Notes
+~~~~~
+
+- Uses the SDK's local emulator to mirror what would be sent to the backend.
+- Data is kept in memory only for the life of the context. On exit, the local recorder is disabled and state is reset.
+- Ideal for `task_span` metrics validation, writing tests or ad-hoc scripts that need access to the span/trace tree structure.
+
+

apps/opik-documentation/python-sdk-docs/source/opik_context/get_current_span_data.rst

@@ -0,0 +1,4 @@
+get_current_span_data
+=====================
+
+.. autofunction:: opik.opik_context.get_current_span_data

apps/opik-documentation/python-sdk-docs/source/opik_context/get_current_trace_data.rst

@@ -0,0 +1,4 @@
+get_current_trace_data
+======================
+
+.. autofunction:: opik.opik_context.get_current_trace_data

apps/opik-documentation/python-sdk-docs/source/opik_context/get_distributed_trace_headers.rst

@@ -0,0 +1,4 @@
+get_distributed_trace_headers
+=============================
+
+.. autofunction:: opik.opik_context.get_distributed_trace_headers

apps/opik-documentation/python-sdk-docs/source/opik_context/index.rst

@@ -0,0 +1,53 @@
+opik_context
+============
+
+The opik context module provides a way to access the current span and trace data from within a tracked function::
+
+   from opik import opik_context, track
+
+   @track
+   def my_function():
+
+      # Get the current span data
+      span_data = opik_context.get_current_span_data()
+      print(span_data)
+
+      # Get the current trace data
+      trace_data = opik_context.get_current_trace_data()
+      print(trace_data)
+
+      # Update the current span metadata
+      opik_context.update_current_span(metadata={"my_key": "my_value"})
+
+      # Update the current trace tags
+      opik_context.update_current_trace(tags=["my_tag"])
+
+
+You can also use the `get_distributed_trace_headers` function to get the distributed trace headers from the current trace::
+
+   from opik import opik_context, track
+
+   @track
+   def my_function():
+      distributed_trace_headers = opik_context.get_distributed_trace_headers()
+      print(distributed_trace_headers)
+
+You can learn more about each function in the following sections:
+
+.. toctree::
+   :maxdepth: 4
+   :titlesonly:
+
+   get_current_span_data
+   get_current_trace_data
+
+   update_current_span
+   update_current_trace
+
+   get_distributed_trace_headers
+
+Related Documentation
+---------------------
+
+For creating new traces and spans, see the :doc:`context managers <../context_manager/index>` documentation.
+   

apps/opik-documentation/python-sdk-docs/source/opik_context/update_current_span.rst

@@ -0,0 +1,4 @@
+update_current_span
+===================
+
+.. autofunction:: opik.opik_context.update_current_span

apps/opik-documentation/python-sdk-docs/source/opik_context/update_current_trace.rst

@@ -0,0 +1,4 @@
+update_current_trace
+====================
+
+.. autofunction:: opik.opik_context.update_current_trace

apps/opik-documentation/python-sdk-docs/source/rest_api/clients/annotation_queues.rst

@@ -0,0 +1,51 @@
+Annotation Queues Client
+========================
+
+The Annotation Queues client provides methods for managing annotation queues in the Opik platform.
+Annotation queues enable human-in-the-loop workflows for reviewing and annotating traces or threads.
+
+.. autoclass:: opik.rest_api.annotation_queues.client.AnnotationQueuesClient
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :inherited-members:
+   :exclude-members: with_raw_response
+
+Usage Example
+-------------
+
+.. code-block:: python
+
+   import opik
+   
+   client = opik.Opik()
+   
+   # Create an annotation queue for traces
+   queue = client.create_annotation_queue(
+       name="Review Queue",
+       scope="trace",
+       description="Queue for reviewing model outputs",
+       instructions="Check for accuracy and relevance"
+   )
+   
+   # Get traces and add them to the queue
+   traces = client.search_traces(project_name="my-project")
+   queue.add_traces(traces[:10])
+
+   # Fetch all the traces currently in the queue
+   items = queue.get_items()
+
+   # Get an existing queue by ID
+   existing_queue = client.get_annotation_queue("queue-id")
+   
+   # List all annotation queues
+   queues = client.get_annotation_queues()
+   
+   # Update queue properties
+   queue.update(description="Updated description")
+   
+   # Remove traces from the queue
+   queue.remove_traces(traces[:5])
+   
+   # Delete the queue
+   queue.delete()

apps/opik-documentation/python-sdk-docs/source/rest_api/clients/attachments.rst

@@ -0,0 +1,40 @@
+Attachments Client
+==================
+
+The Attachments client provides methods for managing file attachments in the Opik platform.
+
+.. autoclass:: opik.rest_api.attachments.client.AttachmentsClient
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :inherited-members:
+   :exclude-members: with_raw_response
+
+Usage Example
+-------------
+
+.. code-block:: python
+
+   import opik
+   
+   client = opik.Opik()
+   
+   # Upload an attachment
+   client.rest_client.attachments.upload_attachment(
+       entity_type="trace",
+       entity_id="trace-id",
+       name="results.json",
+       content=b"{'result': 'success'}"
+   )
+   
+   # List attachments for an entity
+   attachments = client.rest_client.attachments.list_attachments(
+       entity_type="trace",
+       entity_id="trace-id"
+   )
+   
+   # Download an attachment
+   content = client.rest_client.attachments.download_attachment(
+       entity_type="trace",
+       attachment_id="attachment-id"
+   )

apps/opik-documentation/python-sdk-docs/source/rest_api/clients/automation_rule_evaluators.rst

@@ -0,0 +1,38 @@
+Automation Rule Evaluators Client
+=================================
+
+The Automation Rule Evaluators client provides methods for managing automated evaluation rules in the Opik platform.
+
+.. autoclass:: opik.rest_api.automation_rule_evaluators.client.AutomationRuleEvaluatorsClient
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :inherited-members:
+   :exclude-members: with_raw_response
+
+Usage Example
+-------------
+
+.. code-block:: python
+
+   import opik
+   
+   client = opik.Opik()
+   
+   # List automation rule evaluators
+   evaluators = client.rest_client.automation_rule_evaluators.find_automation_rule_evaluators(
+       page=0,
+       size=10
+   )
+   
+   # Get an evaluator by ID
+   evaluator = client.rest_client.automation_rule_evaluators.get_automation_rule_evaluator_by_id(
+       "evaluator-id"
+   )
+   
+   # Create a new evaluator
+   client.rest_client.automation_rule_evaluators.create_automation_rule_evaluator(
+       name="my-evaluator",
+       project_id="project-id",
+       code="def evaluate(trace): return {'score': 0.8}"
+   )