chore: import upstream snapshot with attribution

apps/opik-documentation/documentation/fern/docs/reference/python-sdk/overview.mdx

@@ -0,0 +1,9 @@
+---
+headline: Opik Python SDK | Opik Documentation
+og:description: Build powerful applications with Opik's Python SDK, enabling seamless
+  integration and functionality for your projects.
+og:site_name: Opik Documentation
+og:title: Opik Python SDK - Simplify Your Python Development
+title: Overview
+canonical-url: https://www.comet.com/docs/opik/reference/overview
+---

apps/opik-documentation/documentation/fern/docs/reference/python-sdk/rest-api.mdx

@@ -0,0 +1,212 @@
+---
+headline: REST API Client | Opik Documentation
+og:description: Access all Opik platform functionality with the Python SDK's REST
+  API client for advanced operations and custom integrations.
+og:site_name: Opik Documentation
+og:title: REST API Client - Opik Python SDK
+title: REST API Client
+canonical-url: https://www.comet.com/docs/opik/reference/python-sdk/rest-api
+---
+
+The Opik Python SDK includes a complete REST API client that provides direct access to all Opik platform functionality. This low-level client is available through the `rest_client` property and is useful for advanced operations, custom integrations, and scenarios where the high-level SDK doesn't provide the needed functionality.
+
+<Warning>
+  The REST client is not guaranteed to be backward compatible with future SDK versions. While it provides convenient
+  access to the current REST API, it's not considered safe to heavily rely on its API as Opik's REST API contracts may
+  change.
+</Warning>
+
+## Accessing the REST Client
+
+The REST client is accessible through any Opik instance:
+
+```python
+import opik
+
+# Initialize Opik client
+client = opik.Opik()
+
+# Access the REST API client
+rest_client = client.rest_client
+
+# Now you can use any of the available client methods
+traces = rest_client.traces.search_traces(project_name="my-project")
+```
+
+## Available Clients
+
+The REST API is organized into functional client modules:
+
+### Core Resources
+
+- **`traces`** - Manage traces and their lifecycle
+- **`spans`** - Manage spans within traces
+- **`datasets`** - Manage datasets and dataset items
+- **`experiments`** - Manage experiments and results
+- **`projects`** - Manage projects and project settings
+
+### Feedback & Evaluation
+
+- **`feedback_definitions`** - Define feedback score types
+- **`automation_rule_evaluators`** - Set up automated evaluation rules
+- **`optimizations`** - Run optimization experiments
+
+### Content & Assets
+
+- **`prompts`** - Manage prompt templates and versions
+- **`attachments`** - Handle file attachments for traces and spans
+
+### System & Configuration
+
+- **`check`** - System health and access verification
+- **`workspaces`** - Workspace management
+- **`llm_provider_key`** - API key management for LLM providers
+- **`service_toggles`** - Feature flag management
+- **`system_usage`** - Usage metrics and monitoring
+
+### Integrations
+
+- **`chat_completions`** - Chat completion endpoints
+- **`open_telemetry_ingestion`** - OpenTelemetry data ingestion
+- **`guardrails`** - Content validation and safety checks
+
+## Common Usage Patterns
+
+### Working with Traces
+
+```python
+# Get a specific trace by ID
+trace = client.rest_client.traces.get_trace_by_id("trace-id")
+
+# Search traces with advanced filters
+traces = client.rest_client.traces.search_traces(
+    project_name="my-project",
+    filters=[{
+        "field": "name",
+        "operator": "contains",
+        "value": "important"
+    }],
+    max_results=100
+)
+
+# Add feedback to a trace
+client.rest_client.traces.add_trace_feedback_score(
+    id="trace-id",
+    name="accuracy",
+    value=0.95,
+    source="manual"
+)
+```
+
+### Managing Datasets
+
+```python
+# List all datasets with pagination
+datasets = client.rest_client.datasets.find_datasets(
+    page=0,
+    size=20
+)
+
+# Create a new dataset
+dataset = client.rest_client.datasets.create_dataset(
+    name="evaluation-dataset",
+    description="Dataset for model evaluation",
+    project_name="my-project"
+)
+
+# Add items to the dataset
+items = [
+    {
+        "input": {"question": "What is machine learning?"},
+        "expected_output": {"answer": "A subset of AI..."}
+    }
+]
+client.rest_client.datasets.create_or_update_dataset_items(
+    dataset_id=dataset.id,
+    items=items
+)
+```
+
+### Running Experiments
+
+```python
+# Create an experiment linked to a dataset
+experiment = client.rest_client.experiments.create_experiment(
+    name="model-comparison",
+    dataset_name="evaluation-dataset"
+)
+
+# Add experiment results
+client.rest_client.experiments.create_experiment_items(
+    experiment_id=experiment.id,
+    items=[{
+        "dataset_item_id": "item-id",
+        "trace_id": "trace-id",
+        "output": {"prediction": "model output"},
+        "feedback_scores": [
+            {"name": "accuracy", "value": 0.8}
+        ]
+    }]
+)
+```
+
+## Response Types and Pagination
+
+Most list operations return paginated responses with a consistent structure:
+
+```python
+# Example paginated response
+response = client.rest_client.datasets.find_datasets(page=0, size=10)
+
+# Access the response data
+datasets = response.content    # List of dataset objects
+total_count = response.total   # Total number of items
+current_page = response.page   # Current page number
+page_size = response.size      # Items per page
+```
+
+## Error Handling
+
+The REST API raises specific exceptions for different error conditions:
+
+```python
+from opik.rest_api.core.api_error import ApiError
+
+try:
+    trace = client.rest_client.traces.get_trace_by_id("invalid-id")
+except ApiError as e:
+    if e.status_code == 404:
+        print("Trace not found")
+    elif e.status_code == 403:
+        print("Access denied")
+    else:
+        print(f"API error: {e.status_code} - {e.body}")
+```
+
+## When to Use the REST API
+
+Consider using the REST API client when you need to:
+
+- **Advanced Filtering**: Complex search operations with multiple filters
+- **Batch Operations**: Process large amounts of data efficiently
+- **Custom Integrations**: Build tools that integrate with external systems
+- **Raw Data Access**: Work directly with API responses for specific use cases
+- **Unsupported Operations**: Access functionality not available in the high-level SDK
+
+## Complete API Reference
+
+For comprehensive documentation of all REST API methods, parameters, and response types, see the complete [REST API Reference](https://www.comet.com/docs/opik/python-sdk-reference/rest_api/overview.html).
+
+The reference documentation includes:
+
+- **[Overview & Getting Started](https://www.comet.com/docs/opik/python-sdk-reference/rest_api/overview.html)** - Detailed usage patterns and examples
+- **[API Clients](https://www.comet.com/docs/opik/python-sdk-reference/rest_api/clients/index.html)** - Complete method reference for all clients
+- **[Data Types](https://www.comet.com/docs/opik/python-sdk-reference/rest_api/objects.html)** - Response models and data structures
+
+## Best Practices
+
+1. **Use High-Level SDK First**: Try the main SDK APIs before resorting to REST client
+2. **Handle Pagination**: Always implement proper pagination for list operations
+3. **Error Handling**: Implement robust error handling for network and API errors
+4. **Rate Limiting**: Be mindful of API rate limits for batch operations
+5. **Version Compatibility**: Test thoroughly when upgrading SDK versions

apps/opik-documentation/documentation/fern/docs/reference/python-sdk/troubleshooting/batching-and-updates.mdx

@@ -0,0 +1,106 @@
+---
+headline: Batching and update operations | Opik Documentation
+og:description: Understand how batching affects update operations and how to avoid data loss when using the Opik Python SDK.
+og:site_name: Opik Documentation
+og:title: Batching and Update Operations
+title: Batching and update operations
+canonical-url: https://www.comet.com/docs/opik/reference/python-sdk/troubleshooting/batching-and-updates
+---
+
+By default, the Opik Python SDK batches create requests for traces and spans to improve ingestion throughput. While this is the recommended setting for most use cases, it can cause issues when you update a span or trace shortly after creating it.
+
+## What can go wrong
+
+When batching is enabled, create requests are queued and sent to the server in batches. If you call `.end()` or `.update()` on a span or trace before its batched create request has been flushed, the update may arrive at the server first. Since the server has no record of that span or trace yet, the update is silently dropped and the data is lost.
+
+This only affects the low-level client API (`client.trace()`, `client.span()`, `client.update_trace()`, `client.update_span()`, `.end()`, `.update()`). The [`@track` decorator](/v1/tracing/log_traces) and [`start_as_current_span` context manager](/v1/tracing/log_traces) handle lifecycle automatically and are not affected.
+
+## Recommended approaches
+
+### Use decorators or context managers (recommended)
+
+The safest way to create and manage spans and traces is through the [`@track` decorator or `start_as_current_span` context manager](/v1/tracing/log_traces). These handle the full lifecycle — creation, data capture, and finalization — in a single operation with no separate update step.
+
+```python
+import opik
+
+# Using the @track decorator
+@opik.track
+def my_llm_call(prompt: str) -> str:
+    response = call_llm(prompt)
+    return response
+
+# Using context managers
+with opik.start_as_current_span(name="my_span") as span:
+    result = call_llm("Hello")
+```
+
+### Re-send the full payload to overwrite
+
+If you need to use the low-level client API, you can call `client.trace()` or `client.span()` again with the same ID and the complete data. The backend treats each create request as an upsert — if a trace or span with that ID already exists, the new payload overwrites the previous one entirely. This avoids the race condition because you are not relying on a separate update arriving after the original create.
+
+```python
+import datetime
+import opik
+
+client = opik.Opik()
+
+# First call — creates the trace (batched)
+trace = client.trace(
+    name="my_trace",
+    input={"prompt": "Hello"},
+)
+
+# ... do work ...
+
+# Second call with the same ID — overwrites the trace with full data
+client.trace(
+    id=trace.id,
+    name="my_trace",
+    input={"prompt": "Hello"},
+    output={"response": "Hi there"},
+    end_time=datetime.datetime.now(datetime.timezone.utc),
+)
+```
+
+This also works for spans — call `client.span()` with the same `id` and `trace_id` to overwrite.
+
+### Disable batching
+
+If your workflow requires creating spans and then updating them shortly after (for example, to add output data that is only available after an async operation completes), you can disable batching. This ensures each create request is sent immediately, so subsequent updates will always find the span on the server.
+
+```python
+import opik
+
+client = opik.Opik(batching=False)
+
+trace = client.trace(name="my_trace", input={"prompt": "Hello"})
+span = trace.span(name="llm_call", input={"prompt": "Hello"})
+
+# Safe to call .end() because the create was sent immediately
+span.end(output={"response": "Hi there"})
+trace.end(output={"response": "Hi there"})
+```
+
+<Warning>
+Disabling batching reduces ingestion throughput. Only use this option if you need to call `.end()` or `.update()` shortly after creation.
+</Warning>
+
+### Suppress the warning
+
+If you are calling `.end()` or `.update()` well after creation (for example, after a long-running operation completes), the batched create will have already been flushed and there is no risk of data loss. In this case, you can suppress the warning by setting an environment variable:
+
+```bash
+export OPIK_SUPPRESS_BATCHING_UPDATE_WARNING=true
+```
+
+Or in your Opik configuration file (`~/.opik.config`):
+
+```ini
+[opik]
+suppress_batching_update_warning = true
+```
+
+## Use integrations
+
+All Opik integrations (LangChain, LlamaIndex, DSPy, OpenAI, Anthropic, and others) handle span and trace lifecycle internally and are not affected by this issue. If you are using an integration, no changes are needed.