Add dynamic trace metadata updates with context management

Co-authored-by: vinicius <[email protected]>

Author: cursoragent

CURSOR_MEMORY.md

@@ -0,0 +1,77 @@
+# Cursor Memory - Openlayer Python SDK
+
+## Project Guidelines and Lessons Learned
+
+### Trace Metadata Enhancement Implementation (2025)
+
+**Successfully implemented dynamic trace metadata update functionality allowing users to set trace-level metadata (user_id, session_id, etc.) without passing through function arguments.**
+
+#### Key Implementation Patterns:
+
+1. **Enhanced Trace Class Design**
+   - Added metadata fields to Trace class: `name`, `tags`, `metadata`, `thread_id`, `user_id`, `input`, `output`, `feedback`, `test_case`
+   - Created `update_metadata()` method with merge logic for existing metadata
+   - Used Optional typing for all new fields to maintain backward compatibility
+
+2. **Context Variable Management**
+   - Leveraged existing `_current_trace` and `_current_step` context variables
+   - No additional context variables needed - reused existing infrastructure
+   - Thread-safe by design using Python's contextvars module
+
+3. **Public API Design**
+   - `update_current_trace()` - Updates trace-level metadata dynamically
+   - `update_current_span()` - Updates current step/span metadata
+   - Both functions include comprehensive error handling with meaningful warning messages
+   - Used Optional parameters with None defaults for clean API
+
+4. **Trace Processing Integration**
+   - Modified `post_process_trace()` to include trace-level metadata in final trace data
+   - Trace metadata takes precedence over step metadata in final output
+   - Maintained backward compatibility with existing trace data structure
+
+5. **Type Safety and Exports**
+   - Created placeholder types `LLMTestCase` and `Feedback` as `Dict[str, Any]`
+   - Exported new functions and types through `src/openlayer/lib/__init__.py`
+   - Used forward references for type annotations to avoid circular imports
+
+#### Critical Design Decisions:
+
+- **Metadata Merging Strategy**: Trace-level metadata overrides step-level metadata in final output
+- **Error Handling**: Warning messages instead of exceptions when no active trace/span
+- **Type Definitions**: Simple Dict[str, Any] placeholders for extensibility
+- **API Naming**: `update_current_trace()` and `update_current_span()` for clarity
+
+#### Usage Pattern:
+```python
+import openlayer
+
+@openlayer.trace()
+def my_function():
+    # Set trace metadata dynamically
+    openlayer.update_current_trace(
+        user_id="user123",
+        metadata={"session_id": "sess456"}
+    )
+    # ... function logic
+```
+
+#### Testing Approach:
+- All modified files compile successfully with `python3 -m py_compile`
+- Created comprehensive example in `examples/tracing/trace_metadata_updates.py`
+- Demonstrated error handling, async support, and complex metadata scenarios
+
+#### Key Files Modified:
+- `src/openlayer/lib/tracing/traces.py` - Enhanced Trace class
+- `src/openlayer/lib/tracing/tracer.py` - Added update functions and trace processing
+- `src/openlayer/lib/__init__.py` - Exported new functionality
+- `examples/tracing/trace_metadata_updates.py` - Comprehensive usage examples
+
+#### Backward Compatibility:
+- All existing functionality preserved
+- New fields optional with None defaults
+- No breaking changes to existing APIs
+- Maintains existing trace data structure compatibility
+
+---
+
+*This implementation successfully addresses the user requirement to dynamically set trace metadata without passing it through function arguments, providing a clean and intuitive API for complex tracing scenarios.*