agno 2.3.24__py3-none-any.whl → 2.3.26__py3-none-any.whl

agno/learn/utils.py

@@ -0,0 +1,209 @@
+"""
+Learning Machine Utilities
+==========================
+Helper functions for safe data handling.
+
+All functions are designed to never raise exceptions -
+they return None on any failure. This prevents learning
+extraction errors from crashing the main agent.
+"""
+
+from dataclasses import asdict, fields
+from typing import Any, Dict, List, Optional, Type, TypeVar
+
+T = TypeVar("T")
+
+
+def _safe_get(data: Any, key: str, default: Any = None) -> Any:
+    """Safely get a key from dict-like data.
+
+    Args:
+        data: Dict or object with attributes.
+        key: Key or attribute name to get.
+        default: Value to return if not found.
+
+    Returns:
+        The value, or default if not found.
+    """
+    if isinstance(data, dict):
+        return data.get(key, default)
+    return getattr(data, key, default)
+
+
+def _parse_json(data: Any) -> Optional[Dict]:
+    """Parse JSON string to dict, or return dict as-is.
+
+    Args:
+        data: JSON string, dict, or None.
+
+    Returns:
+        Parsed dict, or None if parsing fails.
+    """
+    if data is None:
+        return None
+    if isinstance(data, dict):
+        return data
+    if isinstance(data, str):
+        import json
+
+        try:
+            return json.loads(data)
+        except Exception:
+            return None
+    return None
+
+
+def from_dict_safe(cls: Type[T], data: Any) -> Optional[T]:
+    """Safely create a dataclass instance from dict-like data.
+
+    Works with any dataclass - automatically handles subclass fields.
+    Never raises - returns None on any failure.
+
+    Args:
+        cls: The dataclass type to instantiate.
+        data: Dict, JSON string, or existing instance.
+
+    Returns:
+        Instance of cls, or None if parsing fails.
+
+    Example:
+        >>> profile = from_dict_safe(UserProfile, {"user_id": "123"})
+        >>> profile.user_id
+        '123'
+    """
+    if data is None:
+        return None
+
+    # Already the right type
+    if isinstance(data, cls):
+        return data
+
+    try:
+        # Parse JSON string if needed
+        parsed = _parse_json(data)
+        if parsed is None:
+            return None
+
+        # Get valid field names for this class
+        field_names = {f.name for f in fields(cls)}  # type: ignore
+
+        # Filter to only valid fields
+        kwargs = {k: v for k, v in parsed.items() if k in field_names}
+
+        return cls(**kwargs)
+    except Exception:
+        return None
+
+
+def print_panel(
+    title: str,
+    subtitle: str,
+    lines: List[str],
+    *,
+    empty_message: str = "No data",
+    raw_data: Any = None,
+    raw: bool = False,
+) -> None:
+    """Print formatted panel output for learning stores.
+
+    Uses rich library for formatted output with a bordered panel.
+    Falls back to pprint when raw=True or rich is unavailable.
+
+    Args:
+        title: Panel title (e.g., "User Profile", "Session Context")
+        subtitle: Panel subtitle (e.g., user_id, session_id)
+        lines: Content lines to display inside the panel
+        empty_message: Message shown when lines is empty
+        raw_data: Object to pprint when raw=True
+        raw: If True, use pprint instead of formatted panel
+
+    Example:
+        >>> print_panel(
+        ...     title="User Profile",
+        ...     subtitle="alice@example.com",
+        ...     lines=["Name: Alice", "Memories:", "  [abc123] Loves Python"],
+        ...     raw_data=profile,
+        ... )
+        ╭──────────────── User Profile ─────────────────╮
+        │ Name: Alice                                   │
+        │ Memories:                                     │
+        │   [abc123] Loves Python                       │
+        ╰─────────────── alice@example.com ─────────────╯
+    """
+    if raw and raw_data is not None:
+        from pprint import pprint
+
+        pprint(to_dict_safe(raw_data) or raw_data)
+        return
+
+    try:
+        from rich.console import Console
+        from rich.panel import Panel
+
+        console = Console()
+
+        if not lines:
+            content = f"[dim]{empty_message}[/dim]"
+        else:
+            content = "\n".join(lines)
+
+        panel = Panel(
+            content,
+            title=f"[bold]{title}[/bold]",
+            subtitle=f"[dim]{subtitle}[/dim]",
+            border_style="blue",
+        )
+        console.print(panel)
+
+    except ImportError:
+        # Fallback if rich not installed
+        from pprint import pprint
+
+        print(f"=== {title} ({subtitle}) ===")
+        if not lines:
+            print(f"  {empty_message}")
+        else:
+            for line in lines:
+                print(f"  {line}")
+        print()
+
+
+def to_dict_safe(obj: Any) -> Optional[Dict[str, Any]]:
+    """Safely convert a dataclass to dict.
+
+    Works with any dataclass. Never raises - returns None on failure.
+
+    Args:
+        obj: Dataclass instance to convert.
+
+    Returns:
+        Dict representation, or None if conversion fails.
+
+    Example:
+        >>> profile = UserProfile(user_id="123")
+        >>> to_dict_safe(profile)
+        {'user_id': '123', 'name': None, ...}
+    """
+    if obj is None:
+        return None
+
+    try:
+        # Already a dict
+        if isinstance(obj, dict):
+            return obj
+
+        # Has to_dict method
+        if hasattr(obj, "to_dict"):
+            return obj.to_dict()
+
+        # Is a dataclass
+        if hasattr(obj, "__dataclass_fields__"):
+            return asdict(obj)
+
+        # Has __dict__
+        if hasattr(obj, "__dict__"):
+            return dict(obj.__dict__)
+
+        return None
+    except Exception:
+        return None

agno/models/base.py

@@ -174,6 +174,49 @@ class Model(ABC):
             return self.delay_between_retries * (2**attempt)
         return self.delay_between_retries
 
+    def _is_retryable_error(self, error: ModelProviderError) -> bool:
+        """Determine if an error is worth retrying.
+
+        Non-retryable errors include:
+        - Client errors (400, 401, 403, 413, 422) that won't change on retry
+        - Context window/token limit exceeded errors
+        - Payload too large errors
+
+        Retryable errors include:
+        - Rate limit errors (429)
+        - Server errors (500, 502, 503, 504)
+
+        Args:
+            error: The ModelProviderError to evaluate.
+
+        Returns:
+            True if the error is transient and worth retrying, False otherwise.
+        """
+        # Non-retryable status codes (client errors that won't change)
+        non_retryable_codes = {400, 401, 403, 404, 413, 422}
+        if error.status_code in non_retryable_codes:
+            return False
+
+        # Non-retryable error message patterns (context/token limits)
+        non_retryable_patterns = [
+            "context_length_exceeded",
+            "context window",
+            "maximum context length",
+            "token limit",
+            "max_tokens",
+            "too many tokens",
+            "payload too large",
+            "content_too_large",
+            "request too large",
+            "input too long",
+            "exceeds the model",
+        ]
+        error_msg = str(error.message).lower()
+        if any(pattern in error_msg for pattern in non_retryable_patterns):
+            return False
+
+        return True
+
     def _invoke_with_retry(self, **kwargs) -> ModelResponse:
         """
         Invoke the model with retry logic for ModelProviderError.
@@ -189,6 +232,10 @@ class Model(ABC):
                 return self.invoke(**kwargs)
             except ModelProviderError as e:
                 last_exception = e
+                # Check if error is non-retryable
+                if not self._is_retryable_error(e):
+                    log_error(f"Non-retryable model provider error: {e}")
+                    raise
                 if attempt < self.retries:
                     delay = self._get_retry_delay(attempt)
                     log_warning(
@@ -232,6 +279,10 @@ class Model(ABC):
                 return await self.ainvoke(**kwargs)
             except ModelProviderError as e:
                 last_exception = e
+                # Check if error is non-retryable
+                if not self._is_retryable_error(e):
+                    log_error(f"Non-retryable model provider error: {e}")
+                    raise
                 if attempt < self.retries:
                     delay = self._get_retry_delay(attempt)
                     log_warning(
@@ -277,6 +328,10 @@ class Model(ABC):
                 return  # Success, exit the retry loop
             except ModelProviderError as e:
                 last_exception = e
+                # Check if error is non-retryable (e.g., context window exceeded, auth errors)
+                if not self._is_retryable_error(e):
+                    log_error(f"Non-retryable model provider error: {e}")
+                    raise
                 if attempt < self.retries:
                     delay = self._get_retry_delay(attempt)
                     log_warning(
@@ -325,6 +380,10 @@ class Model(ABC):
                 return  # Success, exit the retry loop
             except ModelProviderError as e:
                 last_exception = e
+                # Check if error is non-retryable
+                if not self._is_retryable_error(e):
+                    log_error(f"Non-retryable model provider error: {e}")
+                    raise
                 if attempt < self.retries:
                     delay = self._get_retry_delay(attempt)
                     log_warning(

agno/os/routers/agents/router.py

@@ -243,7 +243,7 @@ def get_agent_router(
                 log_warning("Metadata parameter passed in both request state and kwargs, using request state")
             kwargs["metadata"] = metadata
 
-        agent = get_agent_by_id(agent_id, os.agents)
+        agent = get_agent_by_id(agent_id, os.agents, create_fresh=True)
         if agent is None:
             raise HTTPException(status_code=404, detail="Agent not found")
 
@@ -405,7 +405,7 @@ def get_agent_router(
         agent_id: str,
         run_id: str,
     ):
-        agent = get_agent_by_id(agent_id, os.agents)
+        agent = get_agent_by_id(agent_id, os.agents, create_fresh=True)
         if agent is None:
             raise HTTPException(status_code=404, detail="Agent not found")
 
@@ -464,7 +464,7 @@ def get_agent_router(
         except json.JSONDecodeError:
             raise HTTPException(status_code=400, detail="Invalid JSON in tools field")
 
-        agent = get_agent_by_id(agent_id, os.agents)
+        agent = get_agent_by_id(agent_id, os.agents, create_fresh=True)
         if agent is None:
             raise HTTPException(status_code=404, detail="Agent not found")
 
@@ -630,7 +630,7 @@ def get_agent_router(
         dependencies=[Depends(require_resource_access("agents", "read", "agent_id"))],
     )
     async def get_agent(agent_id: str, request: Request) -> AgentResponse:
-        agent = get_agent_by_id(agent_id, os.agents)
+        agent = get_agent_by_id(agent_id, os.agents, create_fresh=True)
         if agent is None:
             raise HTTPException(status_code=404, detail="Agent not found")
 

agno/os/routers/knowledge/knowledge.py

@@ -860,6 +860,7 @@ def attach_routes(router: APIRouter, knowledge_instances: List[Union[Knowledge,
                                     "name": "TextReader",
                                     "description": "Reads text files",
                                     "chunkers": [
+                                        "CodeChunker",
                                         "FixedSizeChunker",
                                         "AgenticChunker",
                                         "DocumentChunker",
@@ -898,6 +899,12 @@ def attach_routes(router: APIRouter, knowledge_instances: List[Union[Knowledge,
                                     "description": "Chunking strategy that uses an LLM to determine natural breakpoints in the text",
                                     "metadata": {"chunk_size": 5000},
                                 },
+                                "CodeChunker": {
+                                    "key": "CodeChunker",
+                                    "name": "CodeChunker",
+                                    "description": "The CodeChunker splits code into chunks based on its structure, leveraging Abstract Syntax Trees (ASTs) to create contextually relevant segments",
+                                    "metadata": {"chunk_size": 2048},
+                                },
                                 "DocumentChunker": {
                                     "key": "DocumentChunker",
                                     "name": "DocumentChunker",

agno/os/routers/teams/router.py

@@ -194,7 +194,7 @@ def get_team_router(
 
         logger.debug(f"Creating team run: {message=} {session_id=} {monitor=} {user_id=} {team_id=} {files=} {kwargs=}")
 
-        team = get_team_by_id(team_id, os.teams)
+        team = get_team_by_id(team_id, os.teams, create_fresh=True)
         if team is None:
             raise HTTPException(status_code=404, detail="Team not found")
 
@@ -321,7 +321,7 @@ def get_team_router(
         team_id: str,
         run_id: str,
     ):
-        team = get_team_by_id(team_id, os.teams)
+        team = get_team_by_id(team_id, os.teams, create_fresh=True)
         if team is None:
             raise HTTPException(status_code=404, detail="Team not found")
 
@@ -526,7 +526,7 @@ def get_team_router(
         dependencies=[Depends(require_resource_access("teams", "read", "team_id"))],
     )
     async def get_team(team_id: str, request: Request) -> TeamResponse:
-        team = get_team_by_id(team_id, os.teams)
+        team = get_team_by_id(team_id, os.teams, create_fresh=True)
         if team is None:
             raise HTTPException(status_code=404, detail="Team not found")
 

agno/os/routers/workflows/router.py

@@ -61,7 +61,7 @@ async def handle_workflow_via_websocket(websocket: WebSocket, message: dict, os:
             return
 
         # Get workflow from OS
-        workflow = get_workflow_by_id(workflow_id, os.workflows)
+        workflow = get_workflow_by_id(workflow_id, os.workflows, create_fresh=True)
         if not workflow:
             await websocket.send_text(json.dumps({"event": "error", "error": f"Workflow {workflow_id} not found"}))
             return
@@ -141,7 +141,7 @@ async def handle_workflow_subscription(websocket: WebSocket, message: dict, os:
         if buffer_status is None:
             # Run not in buffer - check database
             if workflow_id and session_id:
-                workflow = get_workflow_by_id(workflow_id, os.workflows)
+                workflow = get_workflow_by_id(workflow_id, os.workflows, create_fresh=True)
                 if workflow and isinstance(workflow, Workflow):
                     workflow_run = await workflow.aget_run_output(run_id, session_id)
 
@@ -571,7 +571,7 @@ def get_workflow_router(
         dependencies=[Depends(require_resource_access("workflows", "read", "workflow_id"))],
     )
     async def get_workflow(workflow_id: str, request: Request) -> WorkflowResponse:
-        workflow = get_workflow_by_id(workflow_id, os.workflows)
+        workflow = get_workflow_by_id(workflow_id, os.workflows, create_fresh=True)
         if workflow is None:
             raise HTTPException(status_code=404, detail="Workflow not found")
         if isinstance(workflow, RemoteWorkflow):
@@ -650,7 +650,7 @@ def get_workflow_router(
             kwargs["metadata"] = metadata
 
         # Retrieve the workflow by ID
-        workflow = get_workflow_by_id(workflow_id, os.workflows)
+        workflow = get_workflow_by_id(workflow_id, os.workflows, create_fresh=True)
         if workflow is None:
             raise HTTPException(status_code=404, detail="Workflow not found")
 
@@ -716,7 +716,7 @@ def get_workflow_router(
         dependencies=[Depends(require_resource_access("workflows", "run", "workflow_id"))],
     )
     async def cancel_workflow_run(workflow_id: str, run_id: str):
-        workflow = get_workflow_by_id(workflow_id, os.workflows)
+        workflow = get_workflow_by_id(workflow_id, os.workflows, create_fresh=True)
 
         if workflow is None:
             raise HTTPException(status_code=404, detail="Workflow not found")

agno/os/utils.py

@@ -414,37 +414,89 @@ def extract_format(file: UploadFile) -> Optional[str]:
 
 
 def get_agent_by_id(
-    agent_id: str, agents: Optional[List[Union[Agent, RemoteAgent]]] = None
+    agent_id: str,
+    agents: Optional[List[Union[Agent, RemoteAgent]]] = None,
+    create_fresh: bool = False,
 ) -> Optional[Union[Agent, RemoteAgent]]:
+    """Get an agent by ID, optionally creating a fresh instance for request isolation.
+
+    When create_fresh=True, creates a new agent instance using deep_copy() to prevent
+    state contamination between concurrent requests. The new instance shares heavy
+    resources (db, model, MCP tools) but has isolated mutable state.
+
+    Args:
+        agent_id: The agent ID to look up
+        agents: List of agents to search
+        create_fresh: If True, creates a new instance using deep_copy()
+
+    Returns:
+        The agent instance (shared or fresh copy based on create_fresh)
+    """
     if agent_id is None or agents is None:
         return None
 
     for agent in agents:
         if agent.id == agent_id:
+            if create_fresh and isinstance(agent, Agent):
+                return agent.deep_copy()
             return agent
     return None
 
 
 def get_team_by_id(
-    team_id: str, teams: Optional[List[Union[Team, RemoteTeam]]] = None
+    team_id: str,
+    teams: Optional[List[Union[Team, RemoteTeam]]] = None,
+    create_fresh: bool = False,
 ) -> Optional[Union[Team, RemoteTeam]]:
+    """Get a team by ID, optionally creating a fresh instance for request isolation.
+
+    When create_fresh=True, creates a new team instance using deep_copy() to prevent
+    state contamination between concurrent requests. Member agents are also deep copied.
+
+    Args:
+        team_id: The team ID to look up
+        teams: List of teams to search
+        create_fresh: If True, creates a new instance using deep_copy()
+
+    Returns:
+        The team instance (shared or fresh copy based on create_fresh)
+    """
     if team_id is None or teams is None:
         return None
 
     for team in teams:
         if team.id == team_id:
+            if create_fresh and isinstance(team, Team):
+                return team.deep_copy()
             return team
     return None
 
 
 def get_workflow_by_id(
-    workflow_id: str, workflows: Optional[List[Union[Workflow, RemoteWorkflow]]] = None
+    workflow_id: str,
+    workflows: Optional[List[Union[Workflow, RemoteWorkflow]]] = None,
+    create_fresh: bool = False,
 ) -> Optional[Union[Workflow, RemoteWorkflow]]:
+    """Get a workflow by ID, optionally creating a fresh instance for request isolation.
+
+    When create_fresh=True, creates a new workflow instance using deep_copy() to prevent
+    state contamination between concurrent requests. Steps containing agents/teams are also deep copied.
+
+    Args:
+        workflow_id: The workflow ID to look up
+        workflows: List of workflows to search
+        create_fresh: If True, creates a new instance using deep_copy()
+
+    Returns:
+        The workflow instance (shared or fresh copy based on create_fresh)
+    """
     if workflow_id is None or workflows is None:
         return None
 
     for workflow in workflows:
         if workflow.id == workflow_id:
+            if create_fresh and isinstance(workflow, Workflow):
+                return workflow.deep_copy()
             return workflow
     return None
 

agno/team/team.py

@@ -9392,3 +9392,134 @@ class Team:
             )
         except Exception as e:
             log_debug(f"Could not create Team run telemetry event: {e}")
+
+    def deep_copy(self, *, update: Optional[Dict[str, Any]] = None) -> "Team":
+        """Create and return a deep copy of this Team, optionally updating fields.
+
+        This creates a fresh Team instance with isolated mutable state while sharing
+        heavy resources like database connections and models. Member agents are also
+        deep copied to ensure complete isolation.
+
+        Args:
+            update: Optional dictionary of fields to override in the new Team.
+
+        Returns:
+            Team: A new Team instance with copied state.
+        """
+        from dataclasses import fields
+
+        # Extract the fields to set for the new Team
+        fields_for_new_team: Dict[str, Any] = {}
+
+        for f in fields(self):
+            # Skip private fields (not part of __init__ signature)
+            if f.name.startswith("_"):
+                continue
+
+            field_value = getattr(self, f.name)
+            if field_value is not None:
+                try:
+                    fields_for_new_team[f.name] = self._deep_copy_field(f.name, field_value)
+                except Exception as e:
+                    log_warning(f"Failed to deep copy field '{f.name}': {e}. Using original value.")
+                    fields_for_new_team[f.name] = field_value
+
+        # Update fields if provided
+        if update:
+            fields_for_new_team.update(update)
+
+        # Create a new Team
+        try:
+            new_team = self.__class__(**fields_for_new_team)
+            log_debug(f"Created new {self.__class__.__name__}")
+            return new_team
+        except Exception as e:
+            log_error(f"Failed to create deep copy of {self.__class__.__name__}: {e}")
+            raise
+
+    def _deep_copy_field(self, field_name: str, field_value: Any) -> Any:
+        """Helper method to deep copy a field based on its type."""
+        from copy import copy, deepcopy
+
+        # For members, deep copy each agent/team
+        if field_name == "members" and field_value is not None:
+            copied_members = []
+            for member in field_value:
+                if hasattr(member, "deep_copy"):
+                    copied_members.append(member.deep_copy())
+                else:
+                    copied_members.append(member)
+            return copied_members
+
+        # For tools, share MCP tools but copy others
+        if field_name == "tools" and field_value is not None:
+            try:
+                copied_tools = []
+                for tool in field_value:
+                    try:
+                        # Share MCP tools (they maintain server connections)
+                        is_mcp_tool = hasattr(type(tool), "__mro__") and any(
+                            c.__name__ in ["MCPTools", "MultiMCPTools"] for c in type(tool).__mro__
+                        )
+                        if is_mcp_tool:
+                            copied_tools.append(tool)
+                        else:
+                            try:
+                                copied_tools.append(deepcopy(tool))
+                            except Exception:
+                                # Tool can't be deep copied, share by reference
+                                copied_tools.append(tool)
+                    except Exception:
+                        # MCP detection failed, share tool by reference to be safe
+                        copied_tools.append(tool)
+                return copied_tools
+            except Exception as e:
+                # If entire tools processing fails, log and return original list
+                log_warning(f"Failed to process tools for deep copy: {e}")
+                return field_value
+
+        # Share heavy resources - these maintain connections/pools that shouldn't be duplicated
+        if field_name in (
+            "db",
+            "model",
+            "reasoning_model",
+            "knowledge",
+            "memory_manager",
+            "parser_model",
+            "output_model",
+            "session_summary_manager",
+            "culture_manager",
+            "compression_manager",
+            "learning",
+            "skills",
+        ):
+            return field_value
+
+        # For compound types, attempt a deep copy
+        if isinstance(field_value, (list, dict, set)):
+            try:
+                return deepcopy(field_value)
+            except Exception:
+                try:
+                    return copy(field_value)
+                except Exception as e:
+                    log_warning(f"Failed to copy field: {field_name} - {e}")
+                    return field_value
+
+        # For pydantic models, attempt a model_copy
+        if isinstance(field_value, BaseModel):
+            try:
+                return field_value.model_copy(deep=True)
+            except Exception:
+                try:
+                    return field_value.model_copy(deep=False)
+                except Exception as e:
+                    log_warning(f"Failed to copy field: {field_name} - {e}")
+                    return field_value
+
+        # For other types, attempt a shallow copy first
+        try:
+            return copy(field_value)
+        except Exception:
+            # If copy fails, return as is
+            return field_value