agno 2.2.13__py3-none-any.whl

agno/session/__init__.py

@@ -0,0 +1,10 @@
+from typing import Union
+
+from agno.session.agent import AgentSession
+from agno.session.summary import SessionSummaryManager
+from agno.session.team import TeamSession
+from agno.session.workflow import WorkflowSession
+
+Session = Union[AgentSession, TeamSession, WorkflowSession]
+
+__all__ = ["AgentSession", "TeamSession", "WorkflowSession", "Session", "SessionSummaryManager"]

agno/session/agent.py

@@ -0,0 +1,295 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any, Dict, List, Mapping, Optional, Union
+
+from agno.models.message import Message
+from agno.run.agent import RunOutput
+from agno.run.base import RunStatus
+from agno.run.team import TeamRunOutput
+from agno.session.summary import SessionSummary
+from agno.utils.log import log_debug, log_warning
+
+
+@dataclass
+class AgentSession:
+    """Agent Session that is stored in the database"""
+
+    # Session UUID
+    session_id: str
+
+    # ID of the agent that this session is associated with
+    agent_id: Optional[str] = None
+    # ID of the team that this session is associated with
+    team_id: Optional[str] = None
+    # # ID of the user interacting with this agent
+    user_id: Optional[str] = None
+    # ID of the workflow that this session is associated with
+    workflow_id: Optional[str] = None
+
+    # Session Data: session_name, session_state, images, videos, audio
+    session_data: Optional[Dict[str, Any]] = None
+    # Metadata stored with this agent
+    metadata: Optional[Dict[str, Any]] = None
+    # Agent Data: agent_id, name and model
+    agent_data: Optional[Dict[str, Any]] = None
+    # List of all runs in the session
+    runs: Optional[List[Union[RunOutput, TeamRunOutput]]] = None
+    # Summary of the session
+    summary: Optional["SessionSummary"] = None
+
+    # The unix timestamp when this session was created
+    created_at: Optional[int] = None
+    # The unix timestamp when this session was last updated
+    updated_at: Optional[int] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        session_dict = asdict(self)
+
+        session_dict["runs"] = [run.to_dict() for run in self.runs] if self.runs else None
+        session_dict["summary"] = self.summary.to_dict() if self.summary else None
+
+        return session_dict
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> Optional[AgentSession]:
+        if data is None or data.get("session_id") is None:
+            log_warning("AgentSession is missing session_id")
+            return None
+
+        runs = data.get("runs")
+        serialized_runs: List[Union[RunOutput, TeamRunOutput]] = []
+        if runs is not None and isinstance(runs[0], dict):
+            for run in runs:
+                if "agent_id" in run:
+                    serialized_runs.append(RunOutput.from_dict(run))
+                elif "team_id" in run:
+                    serialized_runs.append(TeamRunOutput.from_dict(run))
+
+        summary = data.get("summary")
+        if summary is not None and isinstance(summary, dict):
+            summary = SessionSummary.from_dict(summary)
+
+        metadata = data.get("metadata")
+
+        return cls(
+            session_id=data.get("session_id"),  # type: ignore
+            agent_id=data.get("agent_id"),
+            user_id=data.get("user_id"),
+            workflow_id=data.get("workflow_id"),
+            team_id=data.get("team_id"),
+            agent_data=data.get("agent_data"),
+            session_data=data.get("session_data"),
+            metadata=metadata,
+            created_at=data.get("created_at"),
+            updated_at=data.get("updated_at"),
+            runs=serialized_runs,
+            summary=summary,
+        )
+
+    def upsert_run(self, run: RunOutput):
+        """Adds a RunOutput, together with some calculated data, to the runs list."""
+        messages = run.messages
+        for m in messages or []:
+            if m.metrics is not None:
+                m.metrics.duration = None
+
+        if not self.runs:
+            self.runs = []
+
+        for i, existing_run in enumerate(self.runs or []):
+            if existing_run.run_id == run.run_id:
+                self.runs[i] = run
+                break
+        else:
+            self.runs.append(run)
+
+        log_debug("Added RunOutput to Agent Session")
+
+    def get_run(self, run_id: str) -> Optional[Union[RunOutput, TeamRunOutput]]:
+        for run in self.runs or []:
+            if run.run_id == run_id:
+                return run
+        return None
+
+    def _should_skip_message(
+        self, message: Message, skip_role: Optional[str] = None, skip_history_messages: bool = True
+    ) -> bool:
+        """Processes a message for history"""
+        # Skip messages that were tagged as history in previous runs
+        if hasattr(message, "from_history") and message.from_history and skip_history_messages:
+            return True
+
+        # Skip messages with specified role
+        if skip_role and message.role == skip_role:
+            return True
+        return False
+
+    def get_messages_from_last_n_runs(
+        self,
+        agent_id: Optional[str] = None,
+        team_id: Optional[str] = None,
+        last_n: Optional[int] = None,
+        last_n_messages: Optional[int] = None,
+        skip_role: Optional[str] = None,
+        skip_status: Optional[List[RunStatus]] = None,
+        skip_history_messages: bool = True,
+    ) -> List[Message]:
+        """Returns the messages from the last_n runs, excluding previously tagged history messages.
+        Args:
+            agent_id: The id of the agent to get the messages from.
+            team_id: The id of the team to get the messages from.
+            last_n: The number of runs to return from the end of the conversation. Defaults to all runs.
+            last_n_messages: The number of messages to return from the end of the conversation. Defaults to all messages.
+            skip_role: Skip messages with this role.
+            skip_status: Skip messages with this status.
+            skip_history_messages: Skip messages that were tagged as history in previous runs.
+        Returns:
+            A list of Messages from the specified runs, excluding history messages.
+        """
+        if not self.runs:
+            return []
+
+        if skip_status is None:
+            skip_status = [RunStatus.paused, RunStatus.cancelled, RunStatus.error]
+
+        session_runs = self.runs
+        # Filter by agent_id and team_id
+        if agent_id:
+            session_runs = [run for run in session_runs if hasattr(run, "agent_id") and run.agent_id == agent_id]  # type: ignore
+        if team_id:
+            session_runs = [run for run in session_runs if hasattr(run, "team_id") and run.team_id == team_id]  # type: ignore
+
+        # Skip any messages that might be part of members of teams (for session re-use)
+        session_runs = [run for run in session_runs if run.parent_run_id is None]  # type: ignore
+
+        # Filter by status
+        session_runs = [run for run in session_runs if hasattr(run, "status") and run.status not in skip_status]  # type: ignore
+
+        messages_from_history = []
+        system_message = None
+
+        # Filter by last_n_messages
+        if last_n_messages is not None:
+            for run_response in session_runs:
+                if not run_response or not run_response.messages:
+                    continue
+
+                for message in run_response.messages or []:
+                    if self._should_skip_message(message, skip_role, skip_history_messages):
+                        continue
+
+                    if message.role == "system":
+                        # Only add the system message once
+                        if system_message is None:
+                            system_message = message
+                    else:
+                        messages_from_history.append(message)
+
+            if system_message:
+                messages_from_history = [system_message] + messages_from_history[
+                    -(last_n_messages - 1) :
+                ]  # Grab one less message then add the system message
+            else:
+                messages_from_history = messages_from_history[-last_n_messages:]
+
+            # Remove tool result messages that don't have an associated assistant message with tool calls
+            while len(messages_from_history) > 0 and messages_from_history[0].role == "tool":
+                messages_from_history.pop(0)
+
+        else:
+            # Filter by last_n runs
+            runs_to_process = session_runs[-last_n:] if last_n is not None else session_runs
+            for run_response in runs_to_process:
+                if not run_response or not run_response.messages:
+                    continue
+
+                for message in run_response.messages or []:
+                    if self._should_skip_message(message, skip_role, skip_history_messages):
+                        continue
+
+                    if message.role == "system":
+                        # Only add the system message once
+                        if system_message is None:
+                            system_message = message
+                            messages_from_history.append(system_message)
+                    else:
+                        messages_from_history.append(message)
+
+        log_debug(f"Getting messages from previous runs: {len(messages_from_history)}")
+        return messages_from_history
+
+    def get_tool_calls(self, num_calls: Optional[int] = None) -> List[Dict[str, Any]]:
+        """Returns a list of tool calls from the messages"""
+
+        tool_calls = []
+        if self.runs:
+            session_runs = self.runs
+            for run_response in session_runs[::-1]:
+                if run_response and run_response.messages:
+                    for message in run_response.messages or []:
+                        if message.tool_calls:
+                            for tool_call in message.tool_calls:
+                                tool_calls.append(tool_call)
+                                if num_calls and len(tool_calls) >= num_calls:
+                                    return tool_calls
+        return tool_calls
+
+    def get_messages_for_session(
+        self,
+        user_role: str = "user",
+        assistant_role: Optional[List[str]] = None,
+        skip_history_messages: bool = True,
+    ) -> List[Message]:
+        """Returns a list of messages for the session that iterate through user message and assistant response."""
+
+        if assistant_role is None:
+            # TODO: Check if we still need CHATBOT as a role
+            assistant_role = ["assistant", "model", "CHATBOT"]
+
+        final_messages: List[Message] = []
+        session_runs = self.runs
+        if not session_runs:
+            return []
+
+        for run_response in session_runs:
+            if run_response and run_response.messages:
+                user_message_from_run = None
+                assistant_message_from_run = None
+
+                # Start from the beginning to look for the user message
+                for message in run_response.messages or []:
+                    if hasattr(message, "from_history") and message.from_history and skip_history_messages:
+                        continue
+                    if message.role == user_role:
+                        user_message_from_run = message
+                        break
+
+                # Start from the end to look for the assistant response
+                for message in run_response.messages[::-1]:
+                    if hasattr(message, "from_history") and message.from_history and skip_history_messages:
+                        continue
+                    if message.role in assistant_role:
+                        assistant_message_from_run = message
+                        break
+
+                if user_message_from_run and assistant_message_from_run:
+                    final_messages.append(user_message_from_run)
+                    final_messages.append(assistant_message_from_run)
+        return final_messages
+
+    def get_session_summary(self) -> Optional[SessionSummary]:
+        """Get the session summary for the session"""
+
+        if self.summary is None:
+            return None
+        return self.summary
+
+    # Chat History functions
+    def get_chat_history(self) -> List[Message]:
+        """Get the chat history for the session"""
+
+        messages = []
+        for run in self.runs or []:
+            messages.extend([msg for msg in run.messages or [] if not msg.from_history])
+        return messages

agno/session/summary.py

@@ -0,0 +1,265 @@
+from dataclasses import dataclass
+from datetime import datetime
+from textwrap import dedent
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Type, Union
+
+from pydantic import BaseModel, Field
+
+from agno.models.base import Model
+from agno.models.utils import get_model
+from agno.run.agent import Message
+from agno.utils.log import log_debug, log_warning
+
+# TODO: Look into moving all managers into a separate dir
+if TYPE_CHECKING:
+    from agno.session import Session
+    from agno.session.agent import AgentSession
+    from agno.session.team import TeamSession
+
+
+@dataclass
+class SessionSummary:
+    """Model for Session Summary."""
+
+    summary: str
+    topics: Optional[List[str]] = None
+    updated_at: Optional[datetime] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        _dict = {
+            "summary": self.summary,
+            "topics": self.topics,
+            "updated_at": self.updated_at.isoformat() if self.updated_at else None,
+        }
+        return {k: v for k, v in _dict.items() if v is not None}
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "SessionSummary":
+        updated_at = data.get("updated_at")
+        if updated_at:
+            data["updated_at"] = datetime.fromisoformat(updated_at)
+        return cls(**data)
+
+
+class SessionSummaryResponse(BaseModel):
+    """Model for Session Summary."""
+
+    summary: str = Field(
+        ...,
+        description="Summary of the session. Be concise and focus on only important information. Do not make anything up.",
+    )
+    topics: Optional[List[str]] = Field(None, description="Topics discussed in the session.")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return self.model_dump(exclude_none=True)
+
+    def to_json(self) -> str:
+        return self.model_dump_json(exclude_none=True, indent=2)
+
+
+@dataclass
+class SessionSummaryManager:
+    """Session Summary Manager"""
+
+    # Model used for session summary generation
+    model: Optional[Model] = None
+
+    # Prompt used for session summary generation
+    session_summary_prompt: Optional[str] = None
+
+    # User message prompt for requesting the summary
+    summary_request_message: str = "Provide the summary of the conversation."
+
+    # Whether session summaries were created in the last run
+    summaries_updated: bool = False
+
+    def get_response_format(self, model: "Model") -> Union[Dict[str, Any], Type[BaseModel]]:  # type: ignore
+        if model.supports_native_structured_outputs:
+            return SessionSummaryResponse
+
+        elif model.supports_json_schema_outputs:
+            return {
+                "type": "json_schema",
+                "json_schema": {
+                    "name": SessionSummaryResponse.__name__,
+                    "schema": SessionSummaryResponse.model_json_schema(),
+                },
+            }
+        else:
+            return {"type": "json_object"}
+
+    def get_system_message(
+        self,
+        conversation: List[Message],
+        response_format: Union[Dict[str, Any], Type[BaseModel]],
+    ) -> Message:
+        if self.session_summary_prompt is not None:
+            system_prompt = self.session_summary_prompt
+        else:
+            system_prompt = dedent("""\
+            Analyze the following conversation between a user and an assistant, and extract the following details:
+            - Summary (str): Provide a concise summary of the session, focusing on important information that would be helpful for future interactions.
+            - Topics (Optional[List[str]]): List the topics discussed in the session.
+            Keep the summary concise and to the point. Only include relevant information.
+            """)
+        conversation_messages = []
+        system_prompt += "<conversation>"
+        for message in conversation:
+            if message.role == "user":
+                # Handle empty user messages with media - note what media was provided
+                if not message.content or (isinstance(message.content, str) and message.content.strip() == ""):
+                    media_types = []
+                    if hasattr(message, "images") and message.images:
+                        media_types.append(f"{len(message.images)} image(s)")
+                    if hasattr(message, "videos") and message.videos:
+                        media_types.append(f"{len(message.videos)} video(s)")
+                    if hasattr(message, "audio") and message.audio:
+                        media_types.append(f"{len(message.audio)} audio file(s)")
+                    if hasattr(message, "files") and message.files:
+                        media_types.append(f"{len(message.files)} file(s)")
+
+                    if media_types:
+                        conversation_messages.append(f"User: [Provided {', '.join(media_types)}]")
+                    # Skip empty messages with no media
+                else:
+                    conversation_messages.append(f"User: {message.content}")
+            elif message.role in ["assistant", "model"]:
+                conversation_messages.append(f"Assistant: {message.content}\n")
+        system_prompt += "\n".join(conversation_messages)
+        system_prompt += "</conversation>"
+
+        if response_format == {"type": "json_object"}:
+            from agno.utils.prompts import get_json_output_prompt
+
+            system_prompt += "\n" + get_json_output_prompt(SessionSummaryResponse)  # type: ignore
+
+        return Message(role="system", content=system_prompt)
+
+    def _prepare_summary_messages(
+        self,
+        session: Optional["Session"] = None,
+    ) -> Optional[List[Message]]:
+        """Prepare messages for session summary generation. Returns None if no meaningful messages to summarize."""
+        if not session:
+            return None
+
+        self.model = get_model(self.model)
+        if self.model is None:
+            return None
+
+        response_format = self.get_response_format(self.model)
+
+        system_message = self.get_system_message(
+            conversation=session.get_messages_for_session(),  # type: ignore
+            response_format=response_format,
+        )
+
+        if system_message is None:
+            return None
+
+        return [
+            system_message,
+            Message(role="user", content=self.summary_request_message),
+        ]
+
+    def _process_summary_response(self, summary_response, session_summary_model: "Model") -> Optional[SessionSummary]:  # type: ignore
+        """Process the model response into a SessionSummary"""
+        from datetime import datetime
+
+        if summary_response is None:
+            return None
+
+        # Handle native structured outputs
+        if (
+            session_summary_model.supports_native_structured_outputs
+            and summary_response.parsed is not None
+            and isinstance(summary_response.parsed, SessionSummaryResponse)
+        ):
+            session_summary = SessionSummary(
+                summary=summary_response.parsed.summary,
+                topics=summary_response.parsed.topics,
+                updated_at=datetime.now(),
+            )
+            self.summary = session_summary
+            log_debug("Session summary created", center=True)
+            return session_summary
+
+        # Handle string responses
+        if isinstance(summary_response.content, str):
+            try:
+                from agno.utils.string import parse_response_model_str
+
+                parsed_summary: SessionSummaryResponse = parse_response_model_str(  # type: ignore
+                    summary_response.content, SessionSummaryResponse
+                )
+
+                if parsed_summary is not None:
+                    session_summary = SessionSummary(
+                        summary=parsed_summary.summary, topics=parsed_summary.topics, updated_at=datetime.now()
+                    )
+                    self.summary = session_summary
+                    log_debug("Session summary created", center=True)
+                    return session_summary
+                else:
+                    log_warning("Failed to parse session summary response")
+
+            except Exception as e:
+                log_warning(f"Failed to parse session summary response: {e}")
+
+        return None
+
+    def create_session_summary(
+        self,
+        session: Union["AgentSession", "TeamSession"],
+    ) -> Optional[SessionSummary]:
+        """Creates a summary of the session"""
+        log_debug("Creating session summary", center=True)
+        self.model = get_model(self.model)
+        if self.model is None:
+            return None
+
+        messages = self._prepare_summary_messages(session)
+
+        # Skip summary generation if there are no meaningful messages
+        if messages is None:
+            log_debug("No meaningful messages to summarize, skipping session summary")
+            return None
+
+        response_format = self.get_response_format(self.model)
+
+        summary_response = self.model.response(messages=messages, response_format=response_format)
+        session_summary = self._process_summary_response(summary_response, self.model)
+
+        if session is not None and session_summary is not None:
+            session.summary = session_summary
+            self.summaries_updated = True
+
+        return session_summary
+
+    async def acreate_session_summary(
+        self,
+        session: Union["AgentSession", "TeamSession"],
+    ) -> Optional[SessionSummary]:
+        """Creates a summary of the session"""
+        log_debug("Creating session summary", center=True)
+        self.model = get_model(self.model)
+        if self.model is None:
+            return None
+
+        messages = self._prepare_summary_messages(session)
+
+        # Skip summary generation if there are no meaningful messages
+        if messages is None:
+            log_debug("No meaningful messages to summarize, skipping session summary")
+            return None
+
+        response_format = self.get_response_format(self.model)
+
+        summary_response = await self.model.aresponse(messages=messages, response_format=response_format)
+        session_summary = self._process_summary_response(summary_response, self.model)
+
+        if session is not None and session_summary is not None:
+            session.summary = session_summary
+            self.summaries_updated = True
+
+        return session_summary