agno 2.0.0rc2__py3-none-any.whl → 2.3.0__py3-none-any.whl

agno/utils/audio.py

@@ -1,5 +1,6 @@
 import base64
 import os
+import wave
 
 from agno.utils.log import log_info
 
@@ -20,3 +21,29 @@ def write_audio_to_file(audio, filename: str):
     with open(filename, "wb") as f:
         f.write(wav_bytes)
     log_info(f"Audio file saved to {filename}")
+
+
+def write_wav_audio_to_file(
+    filename: str, pcm_data: bytes, channels: int = 1, rate: int = 24000, sample_width: int = 2
+):
+    """
+    Create a WAV file from raw PCM audio data.
+
+    Args:
+        filename: The filepath to save the WAV file to
+        pcm_data: Raw PCM audio data as bytes
+        channels: Number of audio channels (1 for mono, 2 for stereo)
+        rate: Sample rate in Hz (e.g., 24000, 44100, 48000)
+        sample_width: Sample width in bytes (1, 2, or 4)
+    """
+    # Create directory if it doesn't exist
+    if os.path.dirname(filename):
+        os.makedirs(os.path.dirname(filename), exist_ok=True)
+
+    with wave.open(filename, "wb") as wf:
+        wf.setnchannels(channels)
+        wf.setsampwidth(sample_width)
+        wf.setframerate(rate)
+        wf.writeframes(pcm_data)
+
+    log_info(f"WAV file saved to {filename}")

agno/utils/common.py

@@ -1,5 +1,5 @@
 from dataclasses import asdict
-from typing import Any, List, Optional, Type
+from typing import Any, List, Optional, Set, Type, Union, get_type_hints
 
 
 def isinstanceany(obj: Any, class_list: List[Type]) -> bool:
@@ -41,3 +41,92 @@ def nested_model_dump(value):
     elif isinstance(value, list):
         return [nested_model_dump(item) for item in value]
     return value
+
+
+def is_typed_dict(cls: Type[Any]) -> bool:
+    """Check if a class is a TypedDict"""
+    return (
+        hasattr(cls, "__annotations__")
+        and hasattr(cls, "__total__")
+        and hasattr(cls, "__required_keys__")
+        and hasattr(cls, "__optional_keys__")
+    )
+
+
+def check_type_compatibility(value: Any, expected_type: Type) -> bool:
+    """Basic type compatibility checking."""
+    from typing import get_args, get_origin
+
+    # Handle None/Optional types
+    if value is None:
+        return (
+            type(None) in get_args(expected_type) if hasattr(expected_type, "__args__") else expected_type is type(None)
+        )
+
+    # Handle Union types (including Optional)
+    origin = get_origin(expected_type)
+    if origin is Union:
+        return any(check_type_compatibility(value, arg) for arg in get_args(expected_type))
+
+    # Handle List types
+    if origin is list or expected_type is list:
+        if not isinstance(value, list):
+            return False
+        if origin is list and get_args(expected_type):
+            element_type = get_args(expected_type)[0]
+            return all(check_type_compatibility(item, element_type) for item in value)
+        return True
+
+    if expected_type in (str, int, float, bool):
+        return isinstance(value, expected_type)
+
+    if expected_type is Any:
+        return True
+
+    try:
+        return isinstance(value, expected_type)
+    except TypeError:
+        return True
+
+
+def validate_typed_dict(data: dict, schema_cls) -> dict:
+    """Validate input data against a TypedDict schema."""
+    if not isinstance(data, dict):
+        raise ValueError(f"Expected dict for TypedDict {schema_cls.__name__}, got {type(data)}")
+
+    # Get type hints from the TypedDict
+    try:
+        type_hints = get_type_hints(schema_cls)
+    except Exception as e:
+        raise ValueError(f"Could not get type hints for TypedDict {schema_cls.__name__}: {e}")
+
+    # Get required and optional keys
+    required_keys: Set[str] = getattr(schema_cls, "__required_keys__", set())
+    optional_keys: Set[str] = getattr(schema_cls, "__optional_keys__", set())
+    all_keys = required_keys | optional_keys
+
+    # Check for missing required fields
+    missing_required = required_keys - set(data.keys())
+    if missing_required:
+        raise ValueError(f"Missing required fields in TypedDict {schema_cls.__name__}: {missing_required}")
+
+    # Check for unexpected fields
+    unexpected_fields = set(data.keys()) - all_keys
+    if unexpected_fields:
+        raise ValueError(f"Unexpected fields in TypedDict {schema_cls.__name__}: {unexpected_fields}")
+
+    # Basic type checking for provided fields
+    validated_data = {}
+    for field_name, value in data.items():
+        if field_name in type_hints:
+            expected_type = type_hints[field_name]
+
+            # Handle simple type checking
+            if not check_type_compatibility(value, expected_type):
+                raise ValueError(
+                    f"Field '{field_name}' expected type {expected_type}, got {type(value)} with value {value}"
+                )
+
+            validated_data[field_name] = value
+
+    return validated_data

agno/utils/events.py

@@ -1,6 +1,6 @@
-from typing import Any, List, Optional
+from typing import Any, Dict, List, Optional, Union
 
-from agno.media import AudioResponse, ImageArtifact
+from agno.media import Audio, Image
 from agno.models.message import Citations
 from agno.models.response import ToolExecution
 from agno.reasoning.step import ReasoningStep
@@ -11,17 +11,27 @@ from agno.run.agent import (
     OutputModelResponseStartedEvent,
     ParserModelResponseCompletedEvent,
     ParserModelResponseStartedEvent,
+    PostHookCompletedEvent,
+    PostHookStartedEvent,
+    PreHookCompletedEvent,
+    PreHookStartedEvent,
     ReasoningCompletedEvent,
     ReasoningStartedEvent,
     ReasoningStepEvent,
     RunCancelledEvent,
     RunCompletedEvent,
+    RunContentCompletedEvent,
     RunContentEvent,
     RunContinuedEvent,
     RunErrorEvent,
+    RunEvent,
+    RunInput,
     RunOutput,
+    RunOutputEvent,
     RunPausedEvent,
     RunStartedEvent,
+    SessionSummaryCompletedEvent,
+    SessionSummaryStartedEvent,
     ToolCallCompletedEvent,
     ToolCallStartedEvent,
 )
@@ -31,17 +41,25 @@ from agno.run.team import OutputModelResponseCompletedEvent as TeamOutputModelRe
 from agno.run.team import OutputModelResponseStartedEvent as TeamOutputModelResponseStartedEvent
 from agno.run.team import ParserModelResponseCompletedEvent as TeamParserModelResponseCompletedEvent
 from agno.run.team import ParserModelResponseStartedEvent as TeamParserModelResponseStartedEvent
+from agno.run.team import PostHookCompletedEvent as TeamPostHookCompletedEvent
+from agno.run.team import PostHookStartedEvent as TeamPostHookStartedEvent
+from agno.run.team import PreHookCompletedEvent as TeamPreHookCompletedEvent
+from agno.run.team import PreHookStartedEvent as TeamPreHookStartedEvent
 from agno.run.team import ReasoningCompletedEvent as TeamReasoningCompletedEvent
 from agno.run.team import ReasoningStartedEvent as TeamReasoningStartedEvent
 from agno.run.team import ReasoningStepEvent as TeamReasoningStepEvent
 from agno.run.team import RunCancelledEvent as TeamRunCancelledEvent
 from agno.run.team import RunCompletedEvent as TeamRunCompletedEvent
+from agno.run.team import RunContentCompletedEvent as TeamRunContentCompletedEvent
 from agno.run.team import RunContentEvent as TeamRunContentEvent
 from agno.run.team import RunErrorEvent as TeamRunErrorEvent
 from agno.run.team import RunStartedEvent as TeamRunStartedEvent
-from agno.run.team import TeamRunOutput
+from agno.run.team import SessionSummaryCompletedEvent as TeamSessionSummaryCompletedEvent
+from agno.run.team import SessionSummaryStartedEvent as TeamSessionSummaryStartedEvent
+from agno.run.team import TeamRunEvent, TeamRunInput, TeamRunOutput, TeamRunOutputEvent
 from agno.run.team import ToolCallCompletedEvent as TeamToolCallCompletedEvent
 from agno.run.team import ToolCallStartedEvent as TeamToolCallStartedEvent
+from agno.session.summary import SessionSummary
 
 
 def create_team_run_started_event(from_run_response: TeamRunOutput) -> TeamRunStartedEvent:
@@ -76,6 +94,7 @@ def create_team_run_completed_event(from_run_response: TeamRunOutput) -> TeamRun
         content_type=from_run_response.content_type,  # type: ignore
         reasoning_content=from_run_response.reasoning_content,  # type: ignore
         citations=from_run_response.citations,  # type: ignore
+        model_provider_data=from_run_response.model_provider_data,  # type: ignore
         images=from_run_response.images,  # type: ignore
         videos=from_run_response.videos,  # type: ignore
         audio=from_run_response.audio,  # type: ignore
@@ -87,6 +106,7 @@ def create_team_run_completed_event(from_run_response: TeamRunOutput) -> TeamRun
         member_responses=from_run_response.member_responses,  # type: ignore
         metadata=from_run_response.metadata,  # type: ignore
         metrics=from_run_response.metrics,  # type: ignore
+        session_state=from_run_response.session_state,  # type: ignore
     )
 
 
@@ -100,6 +120,7 @@ def create_run_completed_event(from_run_response: RunOutput) -> RunCompletedEven
         content_type=from_run_response.content_type,  # type: ignore
         reasoning_content=from_run_response.reasoning_content,  # type: ignore
         citations=from_run_response.citations,  # type: ignore
+        model_provider_data=from_run_response.model_provider_data,  # type: ignore
         images=from_run_response.images,  # type: ignore
         videos=from_run_response.videos,  # type: ignore
         audio=from_run_response.audio,  # type: ignore
@@ -110,6 +131,7 @@ def create_run_completed_event(from_run_response: RunOutput) -> RunCompletedEven
         reasoning_messages=from_run_response.reasoning_messages,  # type: ignore
         metadata=from_run_response.metadata,  # type: ignore
         metrics=from_run_response.metrics,  # type: ignore
+        session_state=from_run_response.session_state,  # type: ignore
     )
 
 
@@ -175,6 +197,114 @@ def create_run_cancelled_event(from_run_response: RunOutput, reason: str) -> Run
     )
 
 
+def create_pre_hook_started_event(
+    from_run_response: RunOutput, pre_hook_name: Optional[str] = None, run_input: Optional[RunInput] = None
+) -> PreHookStartedEvent:
+    from copy import deepcopy
+
+    return PreHookStartedEvent(
+        session_id=from_run_response.session_id,
+        agent_id=from_run_response.agent_id,  # type: ignore
+        agent_name=from_run_response.agent_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        pre_hook_name=pre_hook_name,
+        run_input=deepcopy(run_input),
+    )
+
+
+def create_team_pre_hook_started_event(
+    from_run_response: TeamRunOutput, pre_hook_name: Optional[str] = None, run_input: Optional[TeamRunInput] = None
+) -> TeamPreHookStartedEvent:
+    from copy import deepcopy
+
+    return TeamPreHookStartedEvent(
+        session_id=from_run_response.session_id,
+        team_id=from_run_response.team_id,  # type: ignore
+        team_name=from_run_response.team_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        pre_hook_name=pre_hook_name,
+        run_input=deepcopy(run_input),
+    )
+
+
+def create_pre_hook_completed_event(
+    from_run_response: RunOutput, pre_hook_name: Optional[str] = None, run_input: Optional[RunInput] = None
+) -> PreHookCompletedEvent:
+    from copy import deepcopy
+
+    return PreHookCompletedEvent(
+        session_id=from_run_response.session_id,
+        agent_id=from_run_response.agent_id,  # type: ignore
+        agent_name=from_run_response.agent_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        pre_hook_name=pre_hook_name,
+        run_input=deepcopy(run_input),
+    )
+
+
+def create_team_pre_hook_completed_event(
+    from_run_response: TeamRunOutput, pre_hook_name: Optional[str] = None, run_input: Optional[TeamRunInput] = None
+) -> TeamPreHookCompletedEvent:
+    from copy import deepcopy
+
+    return TeamPreHookCompletedEvent(
+        session_id=from_run_response.session_id,
+        team_id=from_run_response.team_id,  # type: ignore
+        team_name=from_run_response.team_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        pre_hook_name=pre_hook_name,
+        run_input=deepcopy(run_input),
+    )
+
+
+def create_post_hook_started_event(
+    from_run_response: RunOutput, post_hook_name: Optional[str] = None
+) -> PostHookStartedEvent:
+    return PostHookStartedEvent(
+        session_id=from_run_response.session_id,
+        agent_id=from_run_response.agent_id,  # type: ignore
+        agent_name=from_run_response.agent_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        post_hook_name=post_hook_name,
+    )
+
+
+def create_team_post_hook_started_event(
+    from_run_response: TeamRunOutput, post_hook_name: Optional[str] = None
+) -> TeamPostHookStartedEvent:
+    return TeamPostHookStartedEvent(
+        session_id=from_run_response.session_id,
+        team_id=from_run_response.team_id,  # type: ignore
+        team_name=from_run_response.team_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        post_hook_name=post_hook_name,
+    )
+
+
+def create_post_hook_completed_event(
+    from_run_response: RunOutput, post_hook_name: Optional[str] = None
+) -> PostHookCompletedEvent:
+    return PostHookCompletedEvent(
+        session_id=from_run_response.session_id,
+        agent_id=from_run_response.agent_id,  # type: ignore
+        agent_name=from_run_response.agent_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        post_hook_name=post_hook_name,
+    )
+
+
+def create_team_post_hook_completed_event(
+    from_run_response: TeamRunOutput, post_hook_name: Optional[str] = None
+) -> TeamPostHookCompletedEvent:
+    return TeamPostHookCompletedEvent(
+        session_id=from_run_response.session_id,
+        team_id=from_run_response.team_id,  # type: ignore
+        team_name=from_run_response.team_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        post_hook_name=post_hook_name,
+    )
+
+
 def create_memory_update_started_event(from_run_response: RunOutput) -> MemoryUpdateStartedEvent:
     return MemoryUpdateStartedEvent(
         session_id=from_run_response.session_id,
@@ -211,6 +341,50 @@ def create_team_memory_update_completed_event(from_run_response: TeamRunOutput)
     )
 
 
+def create_team_session_summary_started_event(
+    from_run_response: TeamRunOutput,
+) -> TeamSessionSummaryStartedEvent:
+    return TeamSessionSummaryStartedEvent(
+        session_id=from_run_response.session_id,
+        team_id=from_run_response.team_id,  # type: ignore
+        team_name=from_run_response.team_name,  # type: ignore
+        run_id=from_run_response.run_id,
+    )
+
+
+def create_team_session_summary_completed_event(
+    from_run_response: TeamRunOutput, session_summary: Optional[SessionSummary] = None
+) -> TeamSessionSummaryCompletedEvent:
+    return TeamSessionSummaryCompletedEvent(
+        session_id=from_run_response.session_id,
+        team_id=from_run_response.team_id,  # type: ignore
+        team_name=from_run_response.team_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        session_summary=session_summary,
+    )
+
+
+def create_session_summary_started_event(from_run_response: RunOutput) -> SessionSummaryStartedEvent:
+    return SessionSummaryStartedEvent(
+        session_id=from_run_response.session_id,
+        agent_id=from_run_response.agent_id,  # type: ignore
+        agent_name=from_run_response.agent_name,  # type: ignore
+        run_id=from_run_response.run_id,
+    )
+
+
+def create_session_summary_completed_event(
+    from_run_response: RunOutput, session_summary: Optional[SessionSummary] = None
+) -> SessionSummaryCompletedEvent:
+    return SessionSummaryCompletedEvent(
+        session_id=from_run_response.session_id,
+        agent_id=from_run_response.agent_id,  # type: ignore
+        agent_name=from_run_response.agent_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        session_summary=session_summary,
+    )
+
+
 def create_reasoning_started_event(from_run_response: RunOutput) -> ReasoningStartedEvent:
     return ReasoningStartedEvent(
         session_id=from_run_response.session_id,
@@ -343,9 +517,10 @@ def create_run_output_content_event(
     content_type: Optional[str] = None,
     reasoning_content: Optional[str] = None,
     redacted_reasoning_content: Optional[str] = None,
+    model_provider_data: Optional[Dict[str, Any]] = None,
     citations: Optional[Citations] = None,
-    response_audio: Optional[AudioResponse] = None,
-    image: Optional[ImageArtifact] = None,
+    response_audio: Optional[Audio] = None,
+    image: Optional[Image] = None,
 ) -> RunContentEvent:
     thinking_combined = (reasoning_content or "") + (redacted_reasoning_content or "")
 
@@ -364,6 +539,7 @@ def create_run_output_content_event(
         additional_input=from_run_response.additional_input,
         reasoning_steps=from_run_response.reasoning_steps,
         reasoning_messages=from_run_response.reasoning_messages,
+        model_provider_data=model_provider_data,
     )
 
 
@@ -374,8 +550,9 @@ def create_team_run_output_content_event(
     reasoning_content: Optional[str] = None,
     redacted_reasoning_content: Optional[str] = None,
     citations: Optional[Citations] = None,
-    response_audio: Optional[AudioResponse] = None,
-    image: Optional[ImageArtifact] = None,
+    model_provider_data: Optional[Dict[str, Any]] = None,
+    response_audio: Optional[Audio] = None,
+    image: Optional[Image] = None,
 ) -> TeamRunContentEvent:
     thinking_combined = (reasoning_content or "") + (redacted_reasoning_content or "")
 
@@ -388,6 +565,7 @@ def create_team_run_output_content_event(
         content_type=content_type or "str",
         reasoning_content=thinking_combined,
         citations=citations,
+        model_provider_data=model_provider_data,
         response_audio=response_audio,
         image=image,
         references=from_run_response.references,  # type: ignore
@@ -397,6 +575,28 @@ def create_team_run_output_content_event(
     )
 
 
+def create_run_content_completed_event(
+    from_run_response: RunOutput,
+) -> RunContentCompletedEvent:
+    return RunContentCompletedEvent(
+        session_id=from_run_response.session_id,
+        agent_id=from_run_response.agent_id,  # type: ignore
+        agent_name=from_run_response.agent_name,  # type: ignore
+        run_id=from_run_response.run_id,
+    )
+
+
+def create_team_run_content_completed_event(
+    from_run_response: TeamRunOutput,
+) -> TeamRunContentCompletedEvent:
+    return TeamRunContentCompletedEvent(
+        session_id=from_run_response.session_id,
+        team_id=from_run_response.team_id,  # type: ignore
+        team_name=from_run_response.team_name,  # type: ignore
+        run_id=from_run_response.run_id,
+    )
+
+
 def create_parser_model_response_started_event(
     from_run_response: RunOutput,
 ) -> ParserModelResponseStartedEvent:
@@ -479,3 +679,18 @@ def create_team_output_model_response_completed_event(
         team_name=from_run_response.team_name,  # type: ignore
         run_id=from_run_response.run_id,
     )
+
+
+def handle_event(
+    event: Union[RunOutputEvent, TeamRunOutputEvent],
+    run_response: Union[RunOutput, TeamRunOutput],
+    events_to_skip: Optional[List[Union[RunEvent, TeamRunEvent]]] = None,
+    store_events: bool = False,
+) -> Union[RunOutputEvent, TeamRunOutputEvent]:
+    # We only store events that are not run_response_content events
+    events_to_skip = [event.value for event in events_to_skip] if events_to_skip else []
+    if store_events and event.event not in events_to_skip:
+        if run_response.events is None:
+            run_response.events = []
+        run_response.events.append(event)  # type: ignore
+    return event