cleanup

Author: tschellenbach

agents-core/vision_agents/core/stt/__init__.py

@@ -1,3 +1,4 @@
 from .stt import STT
+from .events import TranscriptResponse
 
-__all__ = ["STT"]
+__all__ = ["STT", "TranscriptResponse"]

agents-core/vision_agents/core/stt/events.py

@@ -3,23 +3,51 @@
 from typing import Optional, Any
 
 
+@dataclass
+class TranscriptResponse:
+    confidence: Optional[float] = None
+    language: Optional[str] = None
+    processing_time_ms: Optional[float] = None
+    audio_duration_ms: Optional[float] = None
+    other: Optional[dict] = None
+
 @dataclass
 class STTTranscriptEvent(PluginBaseEvent):
     """Event emitted when a complete transcript is available."""
 
     type: str = field(default='plugin.stt_transcript', init=False)
     text: str = ""
-    confidence: Optional[float] = None
-    language: Optional[str] = None
-    processing_time_ms: Optional[float] = None
-    audio_duration_ms: Optional[float] = None
-    model_name: Optional[str] = None
-    words: Optional[list[dict[str, Any]]] = None
+    response: TranscriptResponse = field(default_factory=TranscriptResponse)
     is_final: bool = True
 
     def __post_init__(self):
         if not self.text:
             raise ValueError("Transcript text cannot be empty")
+    
+    # Convenience properties for backward compatibility
+    @property
+    def confidence(self) -> Optional[float]:
+        return self.response.confidence
+    
+    @property
+    def language(self) -> Optional[str]:
+        return self.response.language
+    
+    @property
+    def processing_time_ms(self) -> Optional[float]:
+        return self.response.processing_time_ms
+    
+    @property
+    def audio_duration_ms(self) -> Optional[float]:
+        return self.response.audio_duration_ms
+    
+    @property
+    def model_name(self) -> Optional[str]:
+        return self.response.model_name
+    
+    @property
+    def words(self) -> Optional[list[dict[str, Any]]]:
+        return self.response.words
 
 
 @dataclass
@@ -28,13 +56,33 @@ class STTPartialTranscriptEvent(PluginBaseEvent):
 
     type: str = field(default='plugin.stt_partial_transcript', init=False)
     text: str = ""
-    confidence: Optional[float] = None
-    language: Optional[str] = None
-    processing_time_ms: Optional[float] = None
-    audio_duration_ms: Optional[float] = None
-    model_name: Optional[str] = None
-    words: Optional[list[dict[str, Any]]] = None
+    response: TranscriptResponse = field(default_factory=TranscriptResponse)
     is_final: bool = False
+    
+    # Convenience properties for backward compatibility
+    @property
+    def confidence(self) -> Optional[float]:
+        return self.response.confidence
+    
+    @property
+    def language(self) -> Optional[str]:
+        return self.response.language
+    
+    @property
+    def processing_time_ms(self) -> Optional[float]:
+        return self.response.processing_time_ms
+    
+    @property
+    def audio_duration_ms(self) -> Optional[float]:
+        return self.response.audio_duration_ms
+    
+    @property
+    def model_name(self) -> Optional[str]:
+        return self.response.model_name
+    
+    @property
+    def words(self) -> Optional[list[dict[str, Any]]]:
+        return self.response.words
 
 
 @dataclass

agents-core/vision_agents/core/stt/stt.py

@@ -7,6 +7,7 @@
 from ..edge.types import Participant
 from vision_agents.core.events.manager import EventManager
 from . import events
+from .events import TranscriptResponse
 
 logger = logging.getLogger(__name__)
 
@@ -37,62 +38,52 @@ def __init__(
     def _emit_transcript_event(
         self,
         text: str,
-        user_metadata: Optional[Union[Dict[str, Any], Participant]],
-        metadata: Dict[str, Any],
+        participant: Optional[Union[Dict[str, Any], Participant]],
+        response: TranscriptResponse,
     ):
         """
         Emit a final transcript event with structured data.
 
         Args:
             text: The transcribed text.
-            user_metadata: User-specific metadata.
-            metadata: Transcription metadata (processing time, confidence, etc.).
+            participant: Participant metadata.
+            response: Transcription response metadata.
         """
         self.events.send(events.STTTranscriptEvent(
             session_id=self.session_id,
             plugin_name=self.provider_name,
             text=text,
-            user_metadata=user_metadata,
-            confidence=metadata.get("confidence"),
-            language=metadata.get("language"),
-            processing_time_ms=metadata.get("processing_time_ms"),
-            audio_duration_ms=metadata.get("audio_duration_ms"),
-            model_name=metadata.get("model_name"),
-            words=metadata.get("words"),
+            user_metadata=participant,
+            response=response,
         ))
 
     def _emit_partial_transcript_event(
         self,
         text: str,
-        user_metadata: Optional[Union[Dict[str, Any], Participant]],
-        metadata: Dict[str, Any],
+        participant: Optional[Union[Dict[str, Any], Participant]],
+        response: TranscriptResponse,
     ):
         """
         Emit a partial transcript event with structured data.
 
         Args:
             text: The partial transcribed text.
-            user_metadata: User-specific metadata.
-            metadata: Transcription metadata (processing time, confidence, etc.).
+            participant: Participant metadata.
+            response: Transcription response metadata.
         """
         self.events.send(events.STTPartialTranscriptEvent(
             session_id=self.session_id,
             plugin_name=self.provider_name,
             text=text,
-            user_metadata=user_metadata,
-            confidence=metadata.get("confidence"),
-            language=metadata.get("language"),
-            processing_time_ms=metadata.get("processing_time_ms"),
-            audio_duration_ms=metadata.get("audio_duration_ms"),
-            model_name=metadata.get("model_name"),
-            words=metadata.get("words"),
+            user_metadata=participant,
+            response=response,
         ))
 
     def _emit_error_event(
         self,
         error: Exception,
         context: str = "",
-        user_metadata: Optional[Union[Dict[str, Any], Participant]] = None,
+        participant: Optional[Union[Dict[str, Any], Participant]] = None,
     ):
         """
         Emit an error event. Note this should only be emitted for temporary errors.
@@ -103,7 +94,7 @@ def _emit_error_event(
             plugin_name=self.provider_name,
             error=error,
             context=context,
-            user_metadata=user_metadata,
+            user_metadata=participant,
             error_code=getattr(error, "error_code", None),
             is_recoverable=not isinstance(error, (SystemExit, KeyboardInterrupt)),
         ))

docs/ai/instructions/ai-stt.md

@@ -2,6 +2,7 @@
 
 ```python
 from vision_agents.core import stt
+from vision_agents.core.stt.events import TranscriptResponse
 
 class MySTT(stt.STT):
 
@@ -24,12 +25,19 @@ class MySTT(stt.STT):
         parts = self.client.stt(pcm_data, stream=True)
         full_text = ""
         for part in parts:
+            response = TranscriptResponse(
+                confidence=0.9, 
+                language='en', 
+                processing_time_ms=300,
+                audio_duration_ms=2000,
+                other={}
+            )
             # parts that aren't finished
-            self._emit_partial_transcript_event(part, participant, metadata)
+            self._emit_partial_transcript_event(part, participant, response)
             full_text += part
 
         # the full text
-        self._emit_transcript_event(full_text, participant, metadata)
+        self._emit_transcript_event(full_text, participant, response)
 
 ```