From af95ebd78f6b6bde426224d67dd92d7dc61aa77c Mon Sep 17 00:00:00 2001
From: Vilson Rodrigues <vilsonrodrigues07@hotmail.com>
Date: Wed, 28 Jan 2026 16:48:45 -0300
Subject: [PATCH] RELEASE: v1.2.0
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This release updates:
- version.py: 1.1.0 → 1.2.0
- CHANGELOG.md: Added release section for v1.2.0

After merging this PR:
- publish.yml workflow will trigger automatically
- Package will be built and published to PyPI
- GitHub release will be created with tag v1.2.0

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md            | 69 +++++++++++++++++++++++++++++++++++++++++
 src/msgtrace/version.py |  2 +-
 2 files changed, 70 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dc450ab..5f10027 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-01-28
+
+### Added
+
+#### Span Events Infrastructure (`msgtrace.sdk.events`)
+
+New module for emitting span events and real-time streaming, following OpenTelemetry GenAI semantic conventions.
+
+##### Event Types (`EventType`)
+Constants for span event names:
+- **Agent lifecycle**: `AGENT_START`, `AGENT_STEP`, `AGENT_COMPLETE`, `AGENT_ERROR`
+- **Model interactions**: `MODEL_REQUEST`, `MODEL_RESPONSE`, `MODEL_RESPONSE_CHUNK`, `MODEL_REASONING`, `MODEL_REASONING_CHUNK`
+- **Tool operations**: `TOOL_CALL`, `TOOL_RESULT`, `TOOL_ERROR`
+- **Flow control**: `FLOW_STEP`, `FLOW_REASONING`, `FLOW_COMPLETE` (for ReAct, CoT, etc.)
+- **Module lifecycle**: `MODULE_START`, `MODULE_COMPLETE`, `MODULE_ERROR`
+
+##### Core Function: `add_event(name, attributes)`
+Dual emission to both OTel span and streaming queue:
+```python
+from msgtrace.sdk.events import add_event, EventType
+
+add_event(EventType.TOOL_CALL, {
+    "tool_name": "search",
+    "tool_id": "call_123",
+    "arguments": {"query": "weather"},
+})
+```
+
+##### Convenience Functions
+- `add_agent_start_event(agent_name, **extra)`
+- `add_agent_complete_event(agent_name, response=None, **extra)`
+- `add_agent_step_event(agent_name, step_number, step_type="", **extra)`
+- `add_model_request_event(model=None, message_count=None, **extra)`
+- `add_model_response_event(response_type, **extra)`
+- `add_model_response_chunk_event(chunk, index=0, **extra)`
+- `add_model_reasoning_event(reasoning, step=None, **extra)`
+- `add_tool_call_event(tool_name, tool_id, arguments=None, step=None, **extra)`
+- `add_tool_result_event(tool_name, tool_id, result=None, step=None, **extra)`
+- `add_tool_error_event(tool_name, tool_id, error, step=None, **extra)`
+- `add_flow_step_event(step_number, **extra)`
+- `add_flow_reasoning_event(reasoning, step=None, **extra)`
+- `add_flow_complete_event(step=None, **extra)`
+
+##### Real-Time Streaming (`EventStream`)
+Context manager for capturing span events as an async stream:
+```python
+from msgtrace.sdk.events import EventStream
+
+async with EventStream() as stream:
+    task = asyncio.create_task(agent.acall("Hello"))
+    async for event in stream:
+        print(event.name, event.attributes)
+    await task
+```
+
+##### Stream Event Data Structure (`StreamEvent`)
+Frozen dataclass with:
+- `name`: Event name (EventType constant)
+- `attributes`: Event-specific data
+- `timestamp_ns`: Nanoseconds since epoch
+- `span_name`, `span_id`, `trace_id`: Span context
+
+### Benefits
+- Zero overhead when not streaming (context variable is None)
+- Automatic JSON serialization for complex types (dicts, lists)
+- Full compatibility with OpenTelemetry span events
+- Thread-safe through context variables
+- Enables real-time UI updates and streaming responses
+
 ## [1.1.0] - 2025-12-04
 
 ### Added
diff --git a/src/msgtrace/version.py b/src/msgtrace/version.py
index 4a8c2c7..eacfa49 100644
--- a/src/msgtrace/version.py
+++ b/src/msgtrace/version.py
@@ -1,3 +1,3 @@
 """Version information for msgtrace-sdk."""
 
-__version__ = "1.1.0"
+__version__ = "1.2.0"