refactor(tracing): Migrate tracing models from dataclasses to Pydantic for improved type safety

- Replace dataclass implementations with Pydantic BaseModel in tracing_models.py
- Remove manual to_dict() methods in favor of Pydantic's built-in model_dump() functionality
- Simplify attribute access and type handling in responder.py
- Update method calls to use model_dump() and to_api_dict() for consistent serialization
- Improve type safety and reduce manual type conversion code
- Remove redundant attribute checks and simplify conditional logic

Author: arthurbrenno

agentle/responses/responder.py

@@ -974,27 +974,18 @@ def _prepare_trace_input_data(
         tools_count = len(tools)
 
         # Extract structured output information
-        has_structured_output = (
-            create_response.text is not None
-            and hasattr(create_response.text, "format")
-            and create_response.text.format is not None
-            and hasattr(create_response.text.format, "type")
-            and create_response.text.format.type == "json_schema"
-        )
+        has_structured_output = False
+        if create_response.text is not None and create_response.text.format is not None:
+            format_type = getattr(create_response.text.format, "type", None)
+            has_structured_output = format_type == "json_schema"
 
         # Extract reasoning information
         reasoning_enabled = create_response.reasoning is not None
         reasoning_effort: str | None = None
-        if create_response.reasoning is not None and hasattr(
-            create_response.reasoning, "effort"
-        ):
+        if create_response.reasoning is not None:
             effort_value = create_response.reasoning.effort
             if effort_value is not None:
-                reasoning_effort = (
-                    effort_value.value
-                    if hasattr(effort_value, "value")
-                    else str(effort_value)
-                )
+                reasoning_effort = effort_value.value
 
         return TraceInputData(
             input=input_data,
@@ -1191,8 +1182,8 @@ async def _create_tracing_contexts(
                 # Create trace context
                 trace_gen = client.trace_context(
                     name="responder_api_call",
-                    input_data=input_data.to_dict(),
-                    metadata=metadata.to_dict(),
+                    input_data=input_data.model_dump(),
+                    metadata=metadata.to_api_dict(),
                 )
                 trace_ctx = await trace_gen.__anext__()
 
@@ -1205,8 +1196,8 @@ async def _create_tracing_contexts(
                     name="response_generation",
                     model=model,
                     provider=metadata.provider,
-                    input_data=input_data.to_dict(),
-                    metadata=metadata.to_dict(),
+                    input_data=input_data.model_dump(),
+                    metadata=metadata.to_api_dict(),
                 )
                 generation_ctx = await generation_gen.__anext__()
 
@@ -1350,10 +1341,10 @@ async def _update_tracing_success(
         }
 
         if usage_details:
-            metadata["usage"] = usage_details.to_dict()
+            metadata["usage"] = usage_details.model_dump()
 
         if cost_details:
-            metadata["cost"] = cost_details.to_dict()
+            metadata["cost"] = cost_details.model_dump()
 
         # Update contexts for each client
         for ctx in active_contexts:
@@ -1369,10 +1360,10 @@ async def _update_tracing_success(
                         await ctx.client.update_generation(
                             ctx.generation_ctx,
                             output_data=output_data,
-                            usage_details=usage_details.to_dict()
+                            usage_details=usage_details.model_dump()
                             if usage_details
                             else None,
-                            cost_details=cost_details.to_dict()
+                            cost_details=cost_details.model_dump()
                             if cost_details
                             else None,
                             metadata=metadata,
@@ -1457,7 +1448,7 @@ async def _update_tracing_error(
         logger.debug(f"Latency until error: {latency:.3f}s")
 
         # Prepare error metadata
-        error_metadata = metadata.to_dict()
+        error_metadata = metadata.to_api_dict()
         error_metadata.update(
             {
                 "error_type": type(error).__name__,

agentle/responses/tracing_models.py

@@ -3,15 +3,15 @@
 from __future__ import annotations
 
 from collections.abc import AsyncGenerator
-from dataclasses import dataclass
 from typing import Any
 
+from pydantic import BaseModel, Field, computed_field
+
 from agentle.generations.tracing.otel_client import GenerationContext, TraceContext
 from agentle.generations.tracing.otel_client_type import OtelClientType
 
 
-@dataclass
-class TraceInputData:
+class TraceInputData(BaseModel):
     """Structured input data for trace context."""
 
     input: str | list[dict[str, Any]] | None
@@ -26,34 +26,17 @@ class TraceInputData:
     max_output_tokens: int | None
     stream: bool
 
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for API calls."""
-        return {
-            "input": self.input,
-            "model": self.model,
-            "has_tools": self.has_tools,
-            "tools_count": self.tools_count,
-            "has_structured_output": self.has_structured_output,
-            "reasoning_enabled": self.reasoning_enabled,
-            "reasoning_effort": self.reasoning_effort,
-            "temperature": self.temperature,
-            "top_p": self.top_p,
-            "max_output_tokens": self.max_output_tokens,
-            "stream": self.stream,
-        }
-
 
-@dataclass
-class TraceMetadata:
+class TraceMetadata(BaseModel):
     """Metadata for trace context."""
 
     model: str
     provider: str
     base_url: str
-    custom_metadata: dict[str, Any]
+    custom_metadata: dict[str, Any] = Field(default_factory=dict)
 
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for API calls."""
+    def to_api_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for API calls, merging custom_metadata."""
         result = {
             "model": self.model,
             "provider": self.provider,
@@ -63,8 +46,7 @@ def to_dict(self) -> dict[str, Any]:
         return result
 
 
-@dataclass
-class UsageDetails:
+class UsageDetails(BaseModel):
     """Token usage details from API response."""
 
     input: int
@@ -73,21 +55,8 @@ class UsageDetails:
     unit: str
     reasoning_tokens: int | None = None
 
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for API calls."""
-        result = {
-            "input": self.input,
-            "output": self.output,
-            "total": self.total,
-            "unit": self.unit,
-        }
-        if self.reasoning_tokens is not None and self.reasoning_tokens > 0:
-            result["reasoning_tokens"] = self.reasoning_tokens
-        return result
-
 
-@dataclass
-class CostDetails:
+class CostDetails(BaseModel):
     """Cost calculation details."""
 
     input: float
@@ -97,28 +66,19 @@ class CostDetails:
     input_tokens: int
     output_tokens: int
 
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for API calls."""
-        return {
-            "input": self.input,
-            "output": self.output,
-            "total": self.total,
-            "currency": self.currency,
-            "input_tokens": self.input_tokens,
-            "output_tokens": self.output_tokens,
-        }
 
-
-@dataclass
-class TracingContext:
+class TracingContext(BaseModel):
     """Container for a single client's tracing contexts."""
 
+    model_config = {"arbitrary_types_allowed": True}
+
     client: OtelClientType
     trace_gen: AsyncGenerator[TraceContext | None, None]
     trace_ctx: TraceContext | None
     generation_gen: AsyncGenerator[GenerationContext | None, None]
     generation_ctx: GenerationContext | None
 
+    @computed_field
     @property
     def client_name(self) -> str:
         """Get the client class name for logging."""