agno 0.1.2__py3-none-any.whl → 2.3.13__py3-none-any.whl

agno/models/openrouter/__init__.py

@@ -1 +1,5 @@
 from agno.models.openrouter.openrouter import OpenRouter
+
+__all__ = [
+    "OpenRouter",
+]

agno/models/openrouter/openrouter.py

@@ -1,8 +1,12 @@
 from dataclasses import dataclass
 from os import getenv
-from typing import Optional
+from typing import Any, Dict, List, Optional, Type, Union
 
+from pydantic import BaseModel
+
+from agno.exceptions import ModelAuthenticationError
 from agno.models.openai.like import OpenAILike
+from agno.run.agent import RunOutput
 
 
 @dataclass
@@ -13,16 +17,69 @@ class OpenRouter(OpenAILike):
     Attributes:
         id (str): The model id. Defaults to "gpt-4o".
         name (str): The model name. Defaults to "OpenRouter".
-        provider (str): The provider name. Defaults to "OpenRouter: " + id.
-        api_key (Optional[str]): The API key. Defaults to None.
+        provider (str): The provider name. Defaults to "OpenRouter".
+        api_key (Optional[str]): The API key.
         base_url (str): The base URL. Defaults to "https://openrouter.ai/api/v1".
         max_tokens (int): The maximum number of tokens. Defaults to 1024.
+        fallback_models (Optional[List[str]]): List of fallback model IDs to use if the primary model
+            fails due to rate limits, timeouts, or unavailability. OpenRouter will automatically try
+            these models in order. Example: ["anthropic/claude-sonnet-4", "deepseek/deepseek-r1"]
     """
 
     id: str = "gpt-4o"
     name: str = "OpenRouter"
-    provider: str = "OpenRouter: " + id
+    provider: str = "OpenRouter"
 
-    api_key: Optional[str] = getenv("OPENROUTER_API_KEY")
+    api_key: Optional[str] = None
     base_url: str = "https://openrouter.ai/api/v1"
     max_tokens: int = 1024
+    models: Optional[List[str]] = None  # Dynamic model routing https://openrouter.ai/docs/features/model-routing
+
+    def _get_client_params(self) -> Dict[str, Any]:
+        """
+        Returns client parameters for API requests, checking for OPENROUTER_API_KEY.
+
+        Returns:
+            Dict[str, Any]: A dictionary of client parameters for API requests.
+        """
+        # Fetch API key from env if not already set
+        if not self.api_key:
+            self.api_key = getenv("OPENROUTER_API_KEY")
+            if not self.api_key:
+                raise ModelAuthenticationError(
+                    message="OPENROUTER_API_KEY not set. Please set the OPENROUTER_API_KEY environment variable.",
+                    model_name=self.name,
+                )
+
+        return super()._get_client_params()
+
+    def get_request_params(
+        self,
+        response_format: Optional[Union[Dict, Type[BaseModel]]] = None,
+        tools: Optional[List[Dict[str, Any]]] = None,
+        tool_choice: Optional[Union[str, Dict[str, Any]]] = None,
+        run_response: Optional[RunOutput] = None,
+    ) -> Dict[str, Any]:
+        """
+        Returns keyword arguments for API requests, including fallback models configuration.
+
+        Returns:
+            Dict[str, Any]: A dictionary of keyword arguments for API requests.
+        """
+        # Get base request params from parent class
+        request_params = super().get_request_params(
+            response_format=response_format, tools=tools, tool_choice=tool_choice, run_response=run_response
+        )
+
+        # Add fallback models to extra_body if specified
+        if self.models:
+            # Get existing extra_body or create new dict
+            extra_body = request_params.get("extra_body") or {}
+
+            # Merge fallback models into extra_body
+            extra_body["models"] = self.models
+
+            # Update request params
+            request_params["extra_body"] = extra_body
+
+        return request_params

agno/models/perplexity/__init__.py

@@ -0,0 +1,5 @@
+from agno.models.perplexity.perplexity import Perplexity
+
+__all__ = [
+    "Perplexity",
+]

agno/models/perplexity/perplexity.py

@@ -0,0 +1,203 @@
+from dataclasses import dataclass, field
+from os import getenv
+from typing import Any, Dict, Optional, Type, Union
+
+from pydantic import BaseModel
+
+from agno.exceptions import ModelAuthenticationError, ModelProviderError
+from agno.models.message import Citations, UrlCitation
+from agno.models.metrics import Metrics
+from agno.models.response import ModelResponse
+from agno.utils.log import log_debug, log_warning
+
+try:
+    from openai.types.chat.chat_completion import ChatCompletion
+    from openai.types.chat.chat_completion_chunk import (
+        ChatCompletionChunk,
+        ChoiceDelta,
+    )
+    from openai.types.chat.parsed_chat_completion import ParsedChatCompletion
+    from openai.types.completion_usage import CompletionUsage
+except ModuleNotFoundError:
+    raise ImportError("`openai` not installed. Please install using `pip install openai`")
+
+from agno.models.openai.like import OpenAILike
+
+
+@dataclass
+class Perplexity(OpenAILike):
+    """
+    A class for using models hosted on Perplexity.
+
+    Attributes:
+        id (str): The model id. Defaults to "sonar".
+        name (str): The model name. Defaults to "Perplexity".
+        provider (str): The provider name. Defaults to "Perplexity".
+        api_key (Optional[str]): The API key.
+        base_url (str): The base URL. Defaults to "https://api.perplexity.ai/chat/completions".
+        max_tokens (int): The maximum number of tokens. Defaults to 1024.
+    """
+
+    id: str = "sonar"
+    name: str = "Perplexity"
+    provider: str = "Perplexity"
+
+    api_key: Optional[str] = field(default_factory=lambda: getenv("PERPLEXITY_API_KEY"))
+    base_url: str = "https://api.perplexity.ai/"
+    max_tokens: int = 1024
+    top_k: Optional[float] = None
+
+    supports_native_structured_outputs: bool = False
+    supports_json_schema_outputs: bool = True
+
+    def _get_client_params(self) -> Dict[str, Any]:
+        """
+        Returns client parameters for API requests, checking for PERPLEXITY_API_KEY.
+
+        Returns:
+            Dict[str, Any]: A dictionary of client parameters for API requests.
+        """
+        if not self.api_key:
+            self.api_key = getenv("PERPLEXITY_API_KEY")
+            if not self.api_key:
+                raise ModelAuthenticationError(
+                    message="PERPLEXITY_API_KEY not set. Please set the PERPLEXITY_API_KEY environment variable.",
+                    model_name=self.name,
+                )
+        return super()._get_client_params()
+
+    def get_request_params(
+        self,
+        response_format: Optional[Union[Dict, Type[BaseModel]]] = None,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        """
+        Returns keyword arguments for API requests.
+        """
+        # Define base request parameters
+        base_params: Dict[str, Any] = {
+            "max_tokens": self.max_tokens,
+            "temperature": self.temperature,
+            "top_p": self.top_p,
+            "top_k": self.top_k,
+            "presence_penalty": self.presence_penalty,
+            "frequency_penalty": self.frequency_penalty,
+        }
+
+        if response_format is not None:
+            base_params["response_format"] = response_format
+
+        # Filter out None values
+        request_params = {k: v for k, v in base_params.items() if v is not None}
+        # Add additional request params if provided
+        if self.request_params:
+            request_params.update(self.request_params)
+
+        if request_params:
+            log_debug(f"Calling {self.provider} with request parameters: {request_params}", log_level=2)
+        return request_params
+
+    def parse_provider_response(self, response: Union[ChatCompletion, ParsedChatCompletion], **kwargs) -> ModelResponse:
+        """
+        Parse the Perplexity response into a ModelResponse.
+
+        Args:
+            response: Response from invoke() method
+
+        Returns:
+            ModelResponse: Parsed response data
+        """
+        model_response = ModelResponse()
+
+        if hasattr(response, "error") and response.error:
+            raise ModelProviderError(
+                message=response.error.get("message", "Unknown model error"),
+                model_name=self.name,
+                model_id=self.id,
+            )
+
+        # Get response message
+        response_message = response.choices[0].message
+
+        # Add role
+        if response_message.role is not None:
+            model_response.role = response_message.role
+
+        # Add content
+        if response_message.content is not None:
+            model_response.content = response_message.content
+
+        # Add tool calls
+        if response_message.tool_calls is not None and len(response_message.tool_calls) > 0:
+            try:
+                model_response.tool_calls = [t.model_dump() for t in response_message.tool_calls]
+            except Exception as e:
+                log_warning(f"Error processing tool calls: {e}")
+
+        # Add citations if present
+        if hasattr(response, "citations") and response.citations is not None:
+            model_response.citations = Citations(
+                urls=[UrlCitation(url=c) for c in response.citations],
+            )
+
+        if response.usage is not None:
+            model_response.response_usage = self._get_metrics(response.usage)
+
+        return model_response
+
+    def parse_provider_response_delta(self, response_delta: ChatCompletionChunk) -> ModelResponse:
+        """
+        Parse the Perplexity streaming response into a ModelResponse.
+
+        Args:
+            response_delta: Raw response chunk from Perplexity
+
+        Returns:
+            ProviderResponse: Iterator of parsed response data
+        """
+        model_response = ModelResponse()
+        if response_delta.choices and len(response_delta.choices) > 0:
+            choice_delta: ChoiceDelta = response_delta.choices[0].delta
+
+            if choice_delta:
+                # Add content
+                if choice_delta.content is not None:
+                    model_response.content = choice_delta.content
+
+                # Add tool calls
+                if choice_delta.tool_calls is not None:
+                    model_response.tool_calls = choice_delta.tool_calls  # type: ignore
+
+        # Add citations if present
+        if hasattr(response_delta, "citations") and response_delta.citations is not None:
+            model_response.citations = Citations(
+                urls=[UrlCitation(url=c) for c in response_delta.citations],
+            )
+
+        # Add usage metrics if present
+        if response_delta.usage is not None:
+            model_response.response_usage = self._get_metrics(response_delta.usage)
+
+        return model_response
+
+    def _get_metrics(self, response_usage: CompletionUsage) -> Metrics:
+        """
+        Parse the given Perplexity usage into an Agno Metrics object.
+        """
+        metrics = Metrics()
+
+        metrics.input_tokens = response_usage.prompt_tokens or 0
+        metrics.output_tokens = response_usage.completion_tokens or 0
+        metrics.total_tokens = response_usage.total_tokens or 0
+
+        # Add the prompt_tokens_details field
+        if prompt_token_details := response_usage.prompt_tokens_details:
+            metrics.audio_input_tokens = prompt_token_details.audio_tokens or 0
+            metrics.cache_read_tokens = prompt_token_details.cached_tokens or 0
+
+        # Add the completion_tokens_details field
+        if completion_tokens_details := response_usage.completion_tokens_details:
+            metrics.audio_output_tokens = completion_tokens_details.audio_tokens or 0
+            metrics.reasoning_tokens = completion_tokens_details.reasoning_tokens or 0
+
+        return metrics

agno/models/portkey/__init__.py

@@ -0,0 +1,3 @@
+from agno.models.portkey.portkey import Portkey
+
+__all__ = ["Portkey"]

agno/models/portkey/portkey.py

@@ -0,0 +1,82 @@
+from dataclasses import dataclass
+from os import getenv
+from typing import Any, Dict, Optional, cast
+
+from agno.exceptions import ModelAuthenticationError
+from agno.models.openai.like import OpenAILike
+
+try:
+    from portkey_ai import PORTKEY_GATEWAY_URL, createHeaders
+except ImportError:
+    raise ImportError("`portkey-ai` not installed. Please install using `pip install portkey-ai`")
+
+
+@dataclass
+class Portkey(OpenAILike):
+    """
+    A class for using models through the Portkey AI Gateway.
+
+    Attributes:
+        id (str): The model id. Defaults to "gpt-4o-mini".
+        name (str): The model name. Defaults to "Portkey".
+        provider (str): The provider name. Defaults to "Portkey".
+        portkey_api_key (Optional[str]): The Portkey API key.
+        virtual_key (Optional[str]): The virtual key for model routing.
+        config (Optional[Dict[str, Any]]): Portkey configuration for routing, retries, etc.
+        base_url (str): The Portkey gateway URL.
+    """
+
+    id: str = "gpt-4o-mini"
+    name: str = "Portkey"
+    provider: str = "Portkey"
+
+    portkey_api_key: Optional[str] = None
+    virtual_key: Optional[str] = None
+    config: Optional[Dict[str, Any]] = None
+    base_url: str = PORTKEY_GATEWAY_URL
+
+    def _get_client_params(self) -> Dict[str, Any]:
+        # Check for required keys
+        if not self.portkey_api_key:
+            raise ModelAuthenticationError(
+                message="PORTKEY_API_KEY not set. Please set the PORTKEY_API_KEY environment variable.",
+                model_name=self.name,
+            )
+
+        self.virtual_key = self.virtual_key or getenv("PORTKEY_VIRTUAL_KEY")
+
+        # Create headers using Portkey's createHeaders function
+        header_params: Dict[str, Any] = {
+            "api_key": self.portkey_api_key,
+            "virtual_key": self.virtual_key,
+        }
+
+        if self.config is not None:
+            header_params["config"] = self.config
+
+        portkey_headers = cast(Dict[str, Any], createHeaders(**header_params))
+
+        # Merge with any existing default headers
+        default_headers: Dict[str, Any] = {}
+        if self.default_headers and isinstance(self.default_headers, dict):
+            default_headers.update(self.default_headers)
+        default_headers.update(portkey_headers)
+
+        # Define base client params
+        base_params = {
+            "api_key": "not-needed",  # We use virtual keys instead
+            "organization": self.organization,
+            "base_url": self.base_url,
+            "timeout": self.timeout,
+            "max_retries": self.max_retries,
+            "default_headers": default_headers,
+            "default_query": self.default_query,
+        }
+
+        # Create client_params dict with non-None values
+        client_params = {k: v for k, v in base_params.items() if v is not None}
+
+        # Add additional client params if provided
+        if self.client_params:
+            client_params.update(self.client_params)
+        return client_params

agno/models/requesty/__init__.py

@@ -0,0 +1,5 @@
+from agno.models.requesty.requesty import Requesty
+
+__all__ = [
+    "Requesty",
+]

agno/models/requesty/requesty.py

@@ -0,0 +1,69 @@
+from dataclasses import dataclass
+from os import getenv
+from typing import Any, Dict, List, Optional, Type, Union
+
+from pydantic import BaseModel
+
+from agno.exceptions import ModelAuthenticationError
+from agno.models.openai.like import OpenAILike
+from agno.run.agent import RunOutput
+from agno.run.team import TeamRunOutput
+
+
+@dataclass
+class Requesty(OpenAILike):
+    """
+    A class for using models hosted on Requesty.
+
+    Attributes:
+        id (str): The model id. Defaults to "openai/gpt-4.1".
+        provider (str): The provider name. Defaults to "Requesty".
+        api_key (Optional[str]): The API key.
+        base_url (str): The base URL. Defaults to "https://router.requesty.ai/v1".
+        max_tokens (int): The maximum number of tokens. Defaults to 1024.
+    """
+
+    id: str = "openai/gpt-4.1"
+    name: str = "Requesty"
+    provider: str = "Requesty"
+
+    api_key: Optional[str] = None
+    base_url: str = "https://router.requesty.ai/v1"
+    max_tokens: int = 1024
+
+    def _get_client_params(self) -> Dict[str, Any]:
+        """
+        Returns client parameters for API requests, checking for REQUESTY_API_KEY.
+
+        Returns:
+            Dict[str, Any]: A dictionary of client parameters for API requests.
+        """
+        if not self.api_key:
+            self.api_key = getenv("REQUESTY_API_KEY")
+            if not self.api_key:
+                raise ModelAuthenticationError(
+                    message="REQUESTY_API_KEY not set. Please set the REQUESTY_API_KEY environment variable.",
+                    model_name=self.name,
+                )
+        return super()._get_client_params()
+
+    def get_request_params(
+        self,
+        response_format: Optional[Union[Dict, Type[BaseModel]]] = None,
+        tools: Optional[List[Dict[str, Any]]] = None,
+        tool_choice: Optional[Union[str, Dict[str, Any]]] = None,
+        run_response: Optional[Union[RunOutput, TeamRunOutput]] = None,
+    ) -> Dict[str, Any]:
+        params = super().get_request_params(
+            response_format=response_format, tools=tools, tool_choice=tool_choice, run_response=run_response
+        )
+
+        if "extra_body" not in params:
+            params["extra_body"] = {}
+        params["extra_body"]["requesty"] = {}
+        if run_response and run_response.user_id:
+            params["extra_body"]["requesty"]["user_id"] = run_response.user_id
+        if run_response and run_response.session_id:
+            params["extra_body"]["requesty"]["trace_id"] = run_response.session_id
+
+        return params

agno/models/response.py

@@ -1,31 +1,201 @@
-from dataclasses import dataclass
+from dataclasses import asdict, dataclass, field
 from enum import Enum
 from time import time
 from typing import Any, Dict, List, Optional
 
-from agno.media import AudioOutput
+from agno.media import Audio, File, Image, Video
+from agno.models.message import Citations
+from agno.models.metrics import Metrics
+from agno.tools.function import UserInputField
 
 
 class ModelResponseEvent(str, Enum):
-    """Events that can be sent by the Model.response() method"""
+    """Events that can be sent by the model provider"""
 
+    tool_call_paused = "ToolCallPaused"
     tool_call_started = "ToolCallStarted"
     tool_call_completed = "ToolCallCompleted"
     assistant_response = "AssistantResponse"
 
 
+@dataclass
+class ToolExecution:
+    """Execution of a tool"""
+
+    tool_call_id: Optional[str] = None
+    tool_name: Optional[str] = None
+    tool_args: Optional[Dict[str, Any]] = None
+    tool_call_error: Optional[bool] = None
+    result: Optional[str] = None
+    metrics: Optional[Metrics] = None
+
+    # In the case where a tool call creates a run of an agent/team/workflow
+    child_run_id: Optional[str] = None
+
+    # If True, the agent will stop executing after this tool call.
+    stop_after_tool_call: bool = False
+
+    created_at: int = field(default_factory=lambda: int(time()))
+
+    # User control flow (HITL) fields
+    requires_confirmation: Optional[bool] = None
+    confirmed: Optional[bool] = None
+    confirmation_note: Optional[str] = None
+
+    requires_user_input: Optional[bool] = None
+    user_input_schema: Optional[List[UserInputField]] = None
+    answered: Optional[bool] = None
+
+    external_execution_required: Optional[bool] = None
+
+    @property
+    def is_paused(self) -> bool:
+        return bool(self.requires_confirmation or self.requires_user_input or self.external_execution_required)
+
+    def to_dict(self) -> Dict[str, Any]:
+        _dict = asdict(self)
+        if self.metrics is not None:
+            _dict["metrics"] = self.metrics.to_dict()
+
+        if self.user_input_schema is not None:
+            _dict["user_input_schema"] = [field.to_dict() for field in self.user_input_schema]
+
+        return _dict
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ToolExecution":
+        return cls(
+            tool_call_id=data.get("tool_call_id"),
+            tool_name=data.get("tool_name"),
+            tool_args=data.get("tool_args"),
+            tool_call_error=data.get("tool_call_error"),
+            result=data.get("result"),
+            child_run_id=data.get("child_run_id"),
+            stop_after_tool_call=data.get("stop_after_tool_call", False),
+            requires_confirmation=data.get("requires_confirmation"),
+            confirmed=data.get("confirmed"),
+            confirmation_note=data.get("confirmation_note"),
+            requires_user_input=data.get("requires_user_input"),
+            user_input_schema=[UserInputField.from_dict(field) for field in data.get("user_input_schema") or []]
+            if "user_input_schema" in data
+            else None,
+            external_execution_required=data.get("external_execution_required"),
+            metrics=Metrics(**(data.get("metrics", {}) or {})),
+            **{"created_at": data["created_at"]} if "created_at" in data else {},
+        )
+
+
 @dataclass
 class ModelResponse:
-    """Response returned by Model.response()"""
+    """Response from the model provider"""
+
+    role: Optional[str] = None
 
-    content: Optional[str] = None
+    content: Optional[Any] = None
     parsed: Optional[Any] = None
-    audio: Optional[AudioOutput] = None
-    tool_calls: Optional[List[Dict[str, Any]]] = None
+    audio: Optional[Audio] = None
+
+    # Unified media fields for LLM-generated and tool-generated media artifacts
+    images: Optional[List[Image]] = None
+    videos: Optional[List[Video]] = None
+    audios: Optional[List[Audio]] = None
+    files: Optional[List[File]] = None
+
+    # Model tool calls
+    tool_calls: List[Dict[str, Any]] = field(default_factory=list)
+
+    # Actual tool executions
+    tool_executions: Optional[List[ToolExecution]] = field(default_factory=list)
+
     event: str = ModelResponseEvent.assistant_response.value
+
+    provider_data: Optional[Dict[str, Any]] = None
+
+    redacted_reasoning_content: Optional[str] = None
+    reasoning_content: Optional[str] = None
+
+    citations: Optional[Citations] = None
+
+    response_usage: Optional[Metrics] = None
+
     created_at: int = int(time())
 
+    extra: Optional[Dict[str, Any]] = None
+
+    updated_session_state: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize ModelResponse to dictionary for caching."""
+        _dict = asdict(self)
+
+        # Handle special serialization for audio
+        if self.audio is not None:
+            _dict["audio"] = self.audio.to_dict()
+
+        # Handle lists of media objects
+        if self.images is not None:
+            _dict["images"] = [img.to_dict() for img in self.images]
+        if self.videos is not None:
+            _dict["videos"] = [vid.to_dict() for vid in self.videos]
+        if self.audios is not None:
+            _dict["audios"] = [aud.to_dict() for aud in self.audios]
+        if self.files is not None:
+            _dict["files"] = [f.to_dict() for f in self.files]
+
+        # Handle tool executions
+        if self.tool_executions is not None:
+            _dict["tool_executions"] = [tool_execution.to_dict() for tool_execution in self.tool_executions]
+
+        # Handle response usage which might be a Pydantic BaseModel
+        response_usage = _dict.pop("response_usage", None)
+        if response_usage is not None:
+            try:
+                from pydantic import BaseModel
+
+                if isinstance(response_usage, BaseModel):
+                    _dict["response_usage"] = response_usage.model_dump()
+                else:
+                    _dict["response_usage"] = response_usage
+            except ImportError:
+                _dict["response_usage"] = response_usage
+
+        return _dict
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ModelResponse":
+        """Reconstruct ModelResponse from cached dictionary."""
+        # Reconstruct media objects
+        if data.get("audio"):
+            data["audio"] = Audio(**data["audio"])
+
+        if data.get("images"):
+            data["images"] = [Image(**img) for img in data["images"]]
+        if data.get("videos"):
+            data["videos"] = [Video(**vid) for vid in data["videos"]]
+        if data.get("audios"):
+            data["audios"] = [Audio(**aud) for aud in data["audios"]]
+        if data.get("files"):
+            data["files"] = [File(**f) for f in data["files"]]
+
+        # Reconstruct tool executions
+        if data.get("tool_executions"):
+            data["tool_executions"] = [ToolExecution.from_dict(te) for te in data["tool_executions"]]
+
+        # Reconstruct citations
+        if data.get("citations") and isinstance(data["citations"], dict):
+            data["citations"] = Citations(**data["citations"])
+
+        # Reconstruct response usage (Metrics)
+        if data.get("response_usage") and isinstance(data["response_usage"], dict):
+            from agno.models.metrics import Metrics
+
+            data["response_usage"] = Metrics(**data["response_usage"])
+
+        return cls(**data)
+
 
 class FileType(str, Enum):
     MP4 = "mp4"
     GIF = "gif"
+    MP3 = "mp3"
+    WAV = "wav"

agno/models/sambanova/__init__.py

@@ -1 +1,5 @@
 from agno.models.sambanova.sambanova import Sambanova
+
+__all__ = [
+    "Sambanova",
+]