agno 2.4.1__py3-none-any.whl → 2.4.2__py3-none-any.whl

agno/models/ollama/responses.py

@@ -0,0 +1,100 @@
+from dataclasses import dataclass, field
+from os import getenv
+from typing import Any, Dict, Optional
+
+from agno.models.openai.open_responses import OpenResponses
+from agno.utils.log import log_debug
+
+
+@dataclass
+class OllamaResponses(OpenResponses):
+    """
+    A class for interacting with Ollama models using the OpenAI Responses API.
+
+    This uses Ollama's OpenAI-compatible `/v1/responses` endpoint, which was added
+    in Ollama v0.13.3. It allows using Ollama models with the Responses API format.
+
+    Note: Ollama's Responses API is stateless - it does not support `previous_response_id`
+    or conversation chaining. Each request is independent.
+
+    Requirements:
+    - Ollama v0.13.3 or later
+    - For local usage: Ollama server running at http://localhost:11434
+    - For Ollama Cloud: Set OLLAMA_API_KEY environment variable
+
+    For more information, see: https://docs.ollama.com/api/openai-compatibility
+
+    Attributes:
+        id (str): The model id. Defaults to "gpt-oss:20b".
+        name (str): The model name. Defaults to "OllamaResponses".
+        provider (str): The provider name. Defaults to "Ollama".
+        host (Optional[str]): The Ollama server host. Defaults to "http://localhost:11434".
+        api_key (Optional[str]): The API key for Ollama Cloud. Not required for local usage.
+    """
+
+    id: str = "gpt-oss:20b"
+    name: str = "OllamaResponses"
+    provider: str = "Ollama"
+
+    # Ollama server host - defaults to local instance
+    host: Optional[str] = None
+
+    # API key for Ollama Cloud (not required for local)
+    api_key: Optional[str] = field(default_factory=lambda: getenv("OLLAMA_API_KEY"))
+
+    # Ollama's Responses API is stateless
+    store: Optional[bool] = False
+
+    def _get_client_params(self) -> Dict[str, Any]:
+        """
+        Get client parameters for API requests.
+
+        Returns:
+            Dict[str, Any]: Client parameters including base_url and optional api_key.
+        """
+        # Determine the base URL
+        if self.host:
+            base_url = self.host.rstrip("/")
+            if not base_url.endswith("/v1"):
+                base_url = f"{base_url}/v1"
+        elif self.api_key:
+            # Ollama Cloud
+            base_url = "https://ollama.com/v1"
+            log_debug(f"Using Ollama Cloud endpoint: {base_url}")
+        else:
+            # Local Ollama instance
+            base_url = "http://localhost:11434/v1"
+
+        # Build client params
+        base_params: Dict[str, Any] = {
+            "base_url": base_url,
+            "timeout": self.timeout,
+            "max_retries": self.max_retries,
+            "default_headers": self.default_headers,
+            "default_query": self.default_query,
+        }
+
+        # Add API key if provided (required for Ollama Cloud, ignored for local)
+        if self.api_key:
+            base_params["api_key"] = self.api_key
+        else:
+            # OpenAI client requires an api_key, but Ollama ignores it locally
+            base_params["api_key"] = "ollama"
+
+        # Filter out 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
+
+    def _using_reasoning_model(self) -> bool:
+        """
+        Ollama doesn't have native reasoning models like OpenAI's o-series.
+
+        Some models may support thinking/reasoning through their architecture
+        (like DeepSeek-R1), but they don't use OpenAI's reasoning API format.
+        """
+        return False

agno/models/openai/__init__.py

@@ -1,9 +1,11 @@
 from agno.models.openai.chat import OpenAIChat
 from agno.models.openai.like import OpenAILike
+from agno.models.openai.open_responses import OpenResponses
 from agno.models.openai.responses import OpenAIResponses
 
 __all__ = [
     "OpenAIChat",
     "OpenAILike",
     "OpenAIResponses",
+    "OpenResponses",
 ]

agno/models/openai/open_responses.py

@@ -0,0 +1,46 @@
+from dataclasses import dataclass
+from typing import Optional
+
+from agno.models.openai.responses import OpenAIResponses
+
+
+@dataclass
+class OpenResponses(OpenAIResponses):
+    """
+    A base class for interacting with any provider using the Open Responses API specification.
+
+    Open Responses is an open-source specification for building multi-provider, interoperable
+    LLM interfaces based on the OpenAI Responses API. This class provides a foundation for
+    providers that implement the spec (e.g., Ollama, OpenRouter).
+
+    For more information, see: https://openresponses.org
+
+    Key differences from OpenAIResponses:
+    - Configurable base_url for pointing to different API endpoints
+    - Stateless by default (no previous_response_id chaining)
+    - Flexible api_key handling for providers that don't require authentication
+
+    Args:
+        id (str): The model id. Defaults to "not-provided".
+        name (str): The model name. Defaults to "OpenResponses".
+        api_key (Optional[str]): The API key. Defaults to "not-provided".
+    """
+
+    id: str = "not-provided"
+    name: str = "OpenResponses"
+    provider: str = "OpenResponses"
+    api_key: Optional[str] = "not-provided"
+
+    # Disable stateful features by default for compatible providers
+    # Most OpenAI-compatible providers don't support previous_response_id chaining
+    store: Optional[bool] = False
+
+    def _using_reasoning_model(self) -> bool:
+        """
+        Override to disable reasoning model detection for compatible providers.
+
+        Most compatible providers don't support OpenAI's reasoning models,
+        so we disable the special handling by default. Subclasses can override
+        this if they support specific reasoning models.
+        """
+        return False

agno/models/openrouter/__init__.py

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

agno/models/openrouter/responses.py

@@ -0,0 +1,146 @@
+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.open_responses import OpenResponses
+from agno.models.message import Message
+
+
+@dataclass
+class OpenRouterResponses(OpenResponses):
+    """
+    A class for interacting with OpenRouter models using the OpenAI Responses API.
+
+    OpenRouter's Responses API (currently in beta) provides OpenAI-compatible access
+    to multiple AI models through a unified interface. It supports tools, reasoning,
+    streaming, and plugins.
+
+    Note: OpenRouter's Responses API is stateless - each request is independent and
+    no server-side state is persisted.
+
+    For more information, see: https://openrouter.ai/docs/api/reference/responses/overview
+
+    Attributes:
+        id (str): The model id. Defaults to "openai/gpt-oss-20b".
+        name (str): The model name. Defaults to "OpenRouterResponses".
+        provider (str): The provider name. Defaults to "OpenRouter".
+        api_key (Optional[str]): The API key. Uses OPENROUTER_API_KEY env var if not set.
+        base_url (str): The base URL. Defaults to "https://openrouter.ai/api/v1".
+        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"]
+
+    Example:
+        ```python
+        from agno.agent import Agent
+        from agno.models.openrouter import OpenRouterResponses
+
+        agent = Agent(
+            model=OpenRouterResponses(id="anthropic/claude-sonnet-4"),
+            markdown=True,
+        )
+        agent.print_response("Write a haiku about coding")
+        ```
+    """
+
+    id: str = "openai/gpt-oss-20b"
+    name: str = "OpenRouterResponses"
+    provider: str = "OpenRouter"
+
+    api_key: Optional[str] = None
+    base_url: str = "https://openrouter.ai/api/v1"
+
+    # Dynamic model routing - fallback models if primary fails
+    # https://openrouter.ai/docs/features/model-routing
+    models: Optional[List[str]] = None
+
+    # OpenRouter's Responses API is stateless
+    store: Optional[bool] = False
+
+    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.
+
+        Raises:
+            ModelAuthenticationError: If OPENROUTER_API_KEY is not set.
+        """
+        # 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,
+                )
+
+        # Build client params
+        base_params: Dict[str, Any] = {
+            "api_key": self.api_key,
+            "base_url": self.base_url,
+            "organization": self.organization,
+            "timeout": self.timeout,
+            "max_retries": self.max_retries,
+            "default_headers": self.default_headers,
+            "default_query": self.default_query,
+        }
+
+        # Filter out 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
+
+    def get_request_params(
+        self,
+        messages: Optional[List[Message]] = None,
+        response_format: Optional[Union[Dict, Type[BaseModel]]] = None,
+        tools: Optional[List[Dict[str, Any]]] = None,
+        tool_choice: Optional[Union[str, Dict[str, Any]]] = 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(
+            messages=messages,
+            response_format=response_format,
+            tools=tools,
+            tool_choice=tool_choice,
+        )
+
+        # 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
+
+    def _using_reasoning_model(self) -> bool:
+        """
+        Check if the model is a reasoning model that requires special handling.
+
+        OpenRouter hosts various reasoning models, but they may not all use
+        OpenAI's reasoning API format. We check for known reasoning model patterns.
+        """
+        # Check for OpenAI reasoning models hosted on OpenRouter
+        if self.id.startswith("openai/o3") or self.id.startswith("openai/o4"):
+            return True
+        return False

agno/os/routers/knowledge/schemas.py

@@ -175,7 +175,7 @@ class RemoteContentSourceSchema(BaseModel):
 
     id: str = Field(..., description="Unique identifier for the content source")
     name: str = Field(..., description="Display name for the content source")
-    type: str = Field(..., description="Type of content source (s3, gcs, sharepoint, github)")
+    type: str = Field(..., description="Type of content source (s3, gcs, sharepoint, github, azureblob)")
     metadata: Optional[Dict[str, Any]] = Field(None, description="Custom metadata for the content source")
 
 

agno/vectordb/lightrag/lightrag.py

@@ -109,7 +109,7 @@ class LightRag(VectorDb):
             async with httpx.AsyncClient(timeout=30.0) as client:
                 response = await client.post(
                     f"{self.server_url}/query",
-                    json={"query": query, "mode": "hybrid"},
+                    json={"query": query, "mode": "hybrid", "include_references": True},
                     headers=self._get_headers(),
                 )
 
@@ -322,7 +322,7 @@ class LightRag(VectorDb):
             async with httpx.AsyncClient(timeout=30.0) as client:
                 response = await client.post(
                     f"{self.server_url}/query",
-                    json={"query": query, "mode": "hybrid"},
+                    json={"query": query, "mode": "hybrid", "include_references": True},
                     headers=self._get_headers(),
                 )
 
@@ -349,10 +349,11 @@ class LightRag(VectorDb):
         # LightRAG server returns a dict with 'response' key, but we expect a list of documents
         # Convert the response to the expected format
         if isinstance(result, dict) and "response" in result:
-            # Wrap the response in a Document object
-            return [
-                Document(content=result["response"], meta_data={"source": "lightrag", "query": query, "mode": mode})
-            ]
+            meta_data = {"source": "lightrag", "query": query, "mode": mode}
+            # Preserve references from LightRAG response for document citations
+            if "references" in result:
+                meta_data["references"] = result["references"]
+            return [Document(content=result["response"], meta_data=meta_data)]
         elif isinstance(result, list):
             # Convert list items to Document objects
             documents = []

agno/vectordb/milvus/milvus.py

@@ -241,7 +241,7 @@ class Milvus(VectorDb):
             "id": doc_id,
             "text": cleaned_content,
             "name": document.name,
-            "content_id": document.content_id,
+            "content_id": document.content_id or "",
             "meta_data": meta_data_str,
             "content": cleaned_content,
             "usage": usage_str,
@@ -334,6 +334,7 @@ class Milvus(VectorDb):
             scroll_result = self.client.query(
                 collection_name=self.collection,
                 filter=expr,
+                output_fields=["id"],
                 limit=1,
             )
             return len(scroll_result) > 0 and len(scroll_result[0]) > 0
@@ -363,6 +364,7 @@ class Milvus(VectorDb):
             scroll_result = self.client.query(
                 collection_name=self.collection,
                 filter=expr,
+                output_fields=["id"],
                 limit=1,
             )
             return len(scroll_result) > 0 and len(scroll_result[0]) > 0
@@ -429,7 +431,7 @@ class Milvus(VectorDb):
                     "id": doc_id,
                     "vector": document.embedding,
                     "name": document.name,
-                    "content_id": document.content_id,
+                    "content_id": document.content_id or "",
                     "meta_data": meta_data,
                     "content": cleaned_content,
                     "usage": document.usage,
@@ -512,7 +514,7 @@ class Milvus(VectorDb):
                     "id": doc_id,
                     "vector": document.embedding,
                     "name": document.name,
-                    "content_id": document.content_id,
+                    "content_id": document.content_id or "",
                     "meta_data": meta_data,
                     "content": cleaned_content,
                     "usage": document.usage,
@@ -547,30 +549,41 @@ class Milvus(VectorDb):
             filters (Optional[Dict[str, Any]]): Filters to apply while upserting
         """
         log_debug(f"Upserting {len(documents)} documents")
-        for document in documents:
-            document.embed(embedder=self.embedder)
-            cleaned_content = document.content.replace("\x00", "\ufffd")
-            doc_id = md5(cleaned_content.encode()).hexdigest()
-
-            meta_data = document.meta_data or {}
-            if filters:
-                meta_data.update(filters)
-
-            data = {
-                "id": doc_id,
-                "vector": document.embedding,
-                "name": document.name,
-                "content_id": document.content_id,
-                "meta_data": document.meta_data,
-                "content": cleaned_content,
-                "usage": document.usage,
-                "content_hash": content_hash,
-            }
-            self.client.upsert(
-                collection_name=self.collection,
-                data=data,
-            )
-            log_debug(f"Upserted document: {document.name} ({document.meta_data})")
+
+        if self.search_type == SearchType.hybrid:
+            for document in documents:
+                document.embed(embedder=self.embedder)
+                data = self._prepare_document_data(content_hash=content_hash, document=document, include_vectors=True)
+                self.client.upsert(
+                    collection_name=self.collection,
+                    data=data,
+                )
+                log_debug(f"Upserted hybrid document: {document.name} ({document.meta_data})")
+        else:
+            for document in documents:
+                document.embed(embedder=self.embedder)
+                cleaned_content = document.content.replace("\x00", "\ufffd")
+                doc_id = md5(cleaned_content.encode()).hexdigest()
+
+                meta_data = document.meta_data or {}
+                if filters:
+                    meta_data.update(filters)
+
+                data = {
+                    "id": doc_id,
+                    "vector": document.embedding,
+                    "name": document.name,
+                    "content_id": document.content_id or "",
+                    "meta_data": meta_data,  # type: ignore[dict-item]
+                    "content": cleaned_content,
+                    "usage": document.usage,  # type: ignore[dict-item]
+                    "content_hash": content_hash,
+                }
+                self.client.upsert(
+                    collection_name=self.collection,
+                    data=data,
+                )
+                log_debug(f"Upserted document: {document.name} ({document.meta_data})")
 
     async def async_upsert(
         self, content_hash: str, documents: List[Document], filters: Optional[Dict[str, Any]] = None
@@ -616,28 +629,46 @@ class Milvus(VectorDb):
             embed_tasks = [document.async_embed(embedder=self.embedder) for document in documents]
             await asyncio.gather(*embed_tasks, return_exceptions=True)
 
-        async def process_document(document):
-            cleaned_content = document.content.replace("\x00", "\ufffd")
-            doc_id = md5(cleaned_content.encode()).hexdigest()
-            data = {
-                "id": doc_id,
-                "vector": document.embedding,
-                "name": document.name,
-                "content_id": document.content_id,
-                "meta_data": document.meta_data,
-                "content": cleaned_content,
-                "usage": document.usage,
-                "content_hash": content_hash,
-            }
-            await self.async_client.upsert(
-                collection_name=self.collection,
-                data=data,
-            )
-            log_debug(f"Upserted document asynchronously: {document.name} ({document.meta_data})")
-            return data
+        if self.search_type == SearchType.hybrid:
+
+            async def process_hybrid_document(document):
+                data = self._prepare_document_data(content_hash=content_hash, document=document, include_vectors=True)
+                await self.async_client.upsert(
+                    collection_name=self.collection,
+                    data=data,
+                )
+                log_debug(f"Upserted hybrid document asynchronously: {document.name} ({document.meta_data})")
+                return data
+
+            await asyncio.gather(*[process_hybrid_document(doc) for doc in documents])
+        else:
+
+            async def process_document(document):
+                cleaned_content = document.content.replace("\x00", "\ufffd")
+                doc_id = md5(cleaned_content.encode()).hexdigest()
+
+                meta_data = document.meta_data or {}
+                if filters:
+                    meta_data.update(filters)
+
+                data = {
+                    "id": doc_id,
+                    "vector": document.embedding,
+                    "name": document.name,
+                    "content_id": document.content_id or "",
+                    "meta_data": meta_data,  # type: ignore[dict-item]
+                    "content": cleaned_content,
+                    "usage": document.usage,  # type: ignore[dict-item]
+                    "content_hash": content_hash,
+                }
+                await self.async_client.upsert(
+                    collection_name=self.collection,
+                    data=data,
+                )
+                log_debug(f"Upserted document asynchronously: {document.name} ({document.meta_data})")
+                return data
 
-        # Process all documents in parallel
-        await asyncio.gather(*[process_document(doc) for doc in documents])
+            await asyncio.gather(*[process_document(doc) for doc in documents])
 
         log_debug(f"Upserted {len(documents)} documents asynchronously in parallel")
 

{agno-2.4.1.dist-info → agno-2.4.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agno
-Version: 2.4.1
+Version: 2.4.2
 Summary: Agno: a lightweight library for building Multi-Agent Systems
 Author-email: Ashpreet Bedi <ashpreet@agno.com>
 Project-URL: homepage, https://agno.com