agno 2.0.1__py3-none-any.whl → 2.3.0__py3-none-any.whl

agno/db/surrealdb/utils.py

@@ -0,0 +1,147 @@
+import dataclasses
+from typing import Any, Dict, Optional, Sequence, TypeVar, Union, cast
+
+from surrealdb import BlockingHttpSurrealConnection, BlockingWsSurrealConnection, Surreal
+
+from agno.db.schemas.culture import CulturalKnowledge
+from agno.utils.log import logger
+
+RecordType = TypeVar("RecordType")
+
+
+def build_client(
+    url: str, creds: dict[str, str], ns: str, db: str
+) -> Union[BlockingWsSurrealConnection, BlockingHttpSurrealConnection]:
+    client = Surreal(url=url)
+    client.signin(creds)
+    client.use(namespace=ns, database=db)
+    return client
+
+
+def _query_aux(
+    client: Union[BlockingWsSurrealConnection, BlockingHttpSurrealConnection],
+    query: str,
+    vars: dict[str, Any],
+) -> Union[list, dict, str, int]:
+    try:
+        response = client.query(query, vars)
+    except Exception as e:
+        msg = f"!! Query execution error: {query} with {vars}, Error: {e}"
+        logger.error(msg)
+        raise RuntimeError(msg)
+    return response
+
+
+def query(
+    client: Union[BlockingWsSurrealConnection, BlockingHttpSurrealConnection],
+    query: str,
+    vars: dict[str, Any],
+    record_type: type[RecordType],
+) -> Sequence[RecordType]:
+    response = _query_aux(client, query, vars)
+    if isinstance(response, list):
+        if dataclasses.is_dataclass(record_type) and hasattr(record_type, "from_dict"):
+            return [getattr(record_type, "from_dict").__call__(x) for x in response]
+        else:
+            result: list[RecordType] = []
+            for x in response:
+                if isinstance(x, dict):
+                    result.append(record_type(**x))
+                else:
+                    result.append(record_type.__call__(x))
+            return result
+    else:
+        raise ValueError(f"Unexpected response type: {type(response)}")
+
+
+def query_one(
+    client: Union[BlockingWsSurrealConnection, BlockingHttpSurrealConnection],
+    query: str,
+    vars: dict[str, Any],
+    record_type: type[RecordType],
+) -> Optional[RecordType]:
+    response = _query_aux(client, query, vars)
+    if response is None:
+        return None
+    elif not isinstance(response, list):
+        if dataclasses.is_dataclass(record_type) and hasattr(record_type, "from_dict"):
+            return getattr(record_type, "from_dict").__call__(response)
+        elif isinstance(response, dict):
+            return record_type(**response)
+        else:
+            return record_type.__call__(response)
+    elif isinstance(response, list):
+        # Handle list responses - SurrealDB might return a list with a single element
+        if len(response) == 1 and isinstance(response[0], dict):
+            result = response[0]
+            if dataclasses.is_dataclass(record_type) and hasattr(record_type, "from_dict"):
+                return getattr(record_type, "from_dict").__call__(result)
+            elif record_type is dict:
+                return cast(RecordType, result)
+            else:
+                return record_type(**result)
+        elif len(response) == 0:
+            return None
+        else:
+            raise ValueError(f"Expected single record, got {len(response)} records: {response}")
+    else:
+        raise ValueError(f"Unexpected response type: {type(response)}")
+
+
+# -- Cultural Knowledge util methods --
+
+
+def serialize_cultural_knowledge_for_db(cultural_knowledge: CulturalKnowledge) -> Dict[str, Any]:
+    """Serialize a CulturalKnowledge object for database storage.
+
+    Converts the model's separate content, categories, and notes fields
+    into a single dict for the database content field.
+
+    Args:
+        cultural_knowledge (CulturalKnowledge): The cultural knowledge object to serialize.
+
+    Returns:
+        Dict[str, Any]: A dictionary with content, categories, and notes.
+    """
+    content_dict: Dict[str, Any] = {}
+    if cultural_knowledge.content is not None:
+        content_dict["content"] = cultural_knowledge.content
+    if cultural_knowledge.categories is not None:
+        content_dict["categories"] = cultural_knowledge.categories
+    if cultural_knowledge.notes is not None:
+        content_dict["notes"] = cultural_knowledge.notes
+
+    return content_dict if content_dict else {}
+
+
+def deserialize_cultural_knowledge_from_db(db_row: Dict[str, Any]) -> CulturalKnowledge:
+    """Deserialize a database row to a CulturalKnowledge object.
+
+    The database stores content as a dict containing content, categories, and notes.
+    This method extracts those fields and converts them back to the model format.
+
+    Args:
+        db_row (Dict[str, Any]): The database row as a dictionary.
+
+    Returns:
+        CulturalKnowledge: The cultural knowledge object.
+    """
+    # Extract content, categories, and notes from the content field
+    content_json = db_row.get("content", {}) or {}
+
+    return CulturalKnowledge.from_dict(
+        {
+            "id": db_row.get("id"),
+            "name": db_row.get("name"),
+            "summary": db_row.get("summary"),
+            "content": content_json.get("content"),
+            "categories": content_json.get("categories"),
+            "notes": content_json.get("notes"),
+            "metadata": db_row.get("metadata"),
+            "input": db_row.get("input"),
+            "created_at": db_row.get("created_at"),
+            "updated_at": db_row.get("updated_at"),
+            "agent_id": db_row.get("agent_id"),
+            "team_id": db_row.get("team_id"),
+        }
+    )

agno/db/utils.py

@@ -4,7 +4,6 @@ import json
 from datetime import date, datetime
 from uuid import UUID
 
-from agno.db.base import SessionType
 from agno.models.message import Message
 from agno.models.metrics import Metrics
 
@@ -55,34 +54,63 @@ def serialize_session_json_fields(session: dict) -> dict:
 
 
 def deserialize_session_json_fields(session: dict) -> dict:
-    """Deserialize all JSON fields in the given Session dictionary.
+    """Deserialize JSON fields in the given Session dictionary.
 
     Args:
         session (dict): The dictionary to deserialize.
 
     Returns:
-        dict: The dictionary with JSON fields deserialized.
+        dict: The dictionary with JSON string fields deserialized to objects.
     """
-    if session.get("agent_data") is not None:
-        session["agent_data"] = json.loads(session["agent_data"])
-    if session.get("team_data") is not None:
-        session["team_data"] = json.loads(session["team_data"])
-    if session.get("workflow_data") is not None:
-        session["workflow_data"] = json.loads(session["workflow_data"])
-    if session.get("metadata") is not None:
-        session["metadata"] = json.loads(session["metadata"])
-    if session.get("chat_history") is not None:
-        session["chat_history"] = json.loads(session["chat_history"])
-    if session.get("summary") is not None:
-        session["summary"] = json.loads(session["summary"])
+    from agno.utils.log import log_warning
+
+    if session.get("agent_data") is not None and isinstance(session["agent_data"], str):
+        try:
+            session["agent_data"] = json.loads(session["agent_data"])
+        except (json.JSONDecodeError, TypeError) as e:
+            log_warning(f"Warning: Could not parse agent_data as JSON, keeping as string: {e}")
+
+    if session.get("team_data") is not None and isinstance(session["team_data"], str):
+        try:
+            session["team_data"] = json.loads(session["team_data"])
+        except (json.JSONDecodeError, TypeError) as e:
+            log_warning(f"Warning: Could not parse team_data as JSON, keeping as string: {e}")
+
+    if session.get("workflow_data") is not None and isinstance(session["workflow_data"], str):
+        try:
+            session["workflow_data"] = json.loads(session["workflow_data"])
+        except (json.JSONDecodeError, TypeError) as e:
+            log_warning(f"Warning: Could not parse workflow_data as JSON, keeping as string: {e}")
+
+    if session.get("metadata") is not None and isinstance(session["metadata"], str):
+        try:
+            session["metadata"] = json.loads(session["metadata"])
+        except (json.JSONDecodeError, TypeError) as e:
+            log_warning(f"Warning: Could not parse metadata as JSON, keeping as string: {e}")
+
+    if session.get("chat_history") is not None and isinstance(session["chat_history"], str):
+        try:
+            session["chat_history"] = json.loads(session["chat_history"])
+        except (json.JSONDecodeError, TypeError) as e:
+            log_warning(f"Warning: Could not parse chat_history as JSON, keeping as string: {e}")
+
+    if session.get("summary") is not None and isinstance(session["summary"], str):
+        try:
+            session["summary"] = json.loads(session["summary"])
+        except (json.JSONDecodeError, TypeError) as e:
+            log_warning(f"Warning: Could not parse summary as JSON, keeping as string: {e}")
+
     if session.get("session_data") is not None and isinstance(session["session_data"], str):
-        session["session_data"] = json.loads(session["session_data"])
-    if session.get("runs") is not None:
-        if session["session_type"] == SessionType.AGENT.value:
-            session["runs"] = json.loads(session["runs"])
-        if session["session_type"] == SessionType.TEAM.value:
-            session["runs"] = json.loads(session["runs"])
-        if session["session_type"] == SessionType.WORKFLOW.value:
+        try:
+            session["session_data"] = json.loads(session["session_data"])
+        except (json.JSONDecodeError, TypeError) as e:
+            log_warning(f"Warning: Could not parse session_data as JSON, keeping as string: {e}")
+
+    # Handle runs field with session type checking
+    if session.get("runs") is not None and isinstance(session["runs"], str):
+        try:
             session["runs"] = json.loads(session["runs"])
+        except (json.JSONDecodeError, TypeError) as e:
+            log_warning(f"Warning: Could not parse runs as JSON, keeping as string: {e}")
 
     return session

agno/eval/accuracy.py

@@ -7,13 +7,13 @@ from uuid import uuid4
 from pydantic import BaseModel, Field
 
 from agno.agent import Agent
-from agno.db.base import BaseDb
+from agno.db.base import AsyncBaseDb, BaseDb
 from agno.db.schemas.evals import EvalType
 from agno.eval.utils import async_log_eval, log_eval_run, store_result_in_file
 from agno.exceptions import EvalError
 from agno.models.base import Model
 from agno.team.team import Team
-from agno.utils.log import logger, set_log_level_to_debug, set_log_level_to_info
+from agno.utils.log import log_error, logger, set_log_level_to_debug, set_log_level_to_info
 
 if TYPE_CHECKING:
     from rich.console import Console
@@ -176,7 +176,7 @@ class AccuracyEval:
     # Enable debug logs
     debug_mode: bool = getenv("AGNO_DEBUG", "false").lower() == "true"
     # The database to store Evaluation results
-    db: Optional[BaseDb] = None
+    db: Optional[Union[BaseDb, AsyncBaseDb]] = None
 
     # Telemetry settings
     # telemetry=True logs minimal telemetry for analytics
@@ -327,6 +327,9 @@ Remember: You must only compare the agent_output to the expected_output. The exp
         print_summary: bool = True,
         print_results: bool = True,
     ) -> Optional[AccuracyResult]:
+        if isinstance(self.db, AsyncBaseDb):
+            raise ValueError("run() is not supported with an async DB. Please use arun() instead.")
+
         if self.agent is None and self.team is None:
             logger.error("You need to provide one of 'agent' or 'team' to run the evaluation.")
             return None
@@ -661,47 +664,51 @@ Remember: You must only compare the agent_output to the expected_output. The exp
                 )
         # Log results to the Agno DB if requested
         if self.db:
-            if self.agent is not None:
-                agent_id = self.agent.id
-                team_id = None
-                model_id = self.agent.model.id if self.agent.model is not None else None
-                model_provider = self.agent.model.provider if self.agent.model is not None else None
-                evaluated_component_name = self.agent.name
-            elif self.team is not None:
-                agent_id = None
-                team_id = self.team.id
-                model_id = self.team.model.id if self.team.model is not None else None
-                model_provider = self.team.model.provider if self.team.model is not None else None
-                evaluated_component_name = self.team.name
-            else:
-                agent_id = None
-                team_id = None
-                model_id = None
-                model_provider = None
-                evaluated_component_name = None
+            if isinstance(self.db, AsyncBaseDb):
+                log_error("You are using an async DB in a non-async method. The evaluation won't be stored in the DB.")
 
-            log_eval_input = {
-                "additional_guidelines": self.additional_guidelines,
-                "additional_context": self.additional_context,
-                "num_iterations": self.num_iterations,
-                "expected_output": self.expected_output,
-                "input": self.input,
-            }
-
-            log_eval_run(
-                db=self.db,
-                run_id=self.eval_id,  # type: ignore
-                run_data=asdict(self.result),
-                eval_type=EvalType.ACCURACY,
-                name=self.name if self.name is not None else None,
-                agent_id=agent_id,
-                team_id=team_id,
-                model_id=model_id,
-                model_provider=model_provider,
-                evaluated_component_name=evaluated_component_name,
-                workflow_id=None,
-                eval_input=log_eval_input,
-            )
+            else:
+                if self.agent is not None:
+                    agent_id = self.agent.id
+                    team_id = None
+                    model_id = self.agent.model.id if self.agent.model is not None else None
+                    model_provider = self.agent.model.provider if self.agent.model is not None else None
+                    evaluated_component_name = self.agent.name
+                elif self.team is not None:
+                    agent_id = None
+                    team_id = self.team.id
+                    model_id = self.team.model.id if self.team.model is not None else None
+                    model_provider = self.team.model.provider if self.team.model is not None else None
+                    evaluated_component_name = self.team.name
+                else:
+                    agent_id = None
+                    team_id = None
+                    model_id = None
+                    model_provider = None
+                    evaluated_component_name = None
+
+                log_eval_input = {
+                    "additional_guidelines": self.additional_guidelines,
+                    "additional_context": self.additional_context,
+                    "num_iterations": self.num_iterations,
+                    "expected_output": self.expected_output,
+                    "input": self.input,
+                }
+
+                log_eval_run(
+                    db=self.db,
+                    run_id=self.eval_id,  # type: ignore
+                    run_data=asdict(self.result),
+                    eval_type=EvalType.ACCURACY,
+                    name=self.name if self.name is not None else None,
+                    agent_id=agent_id,
+                    team_id=team_id,
+                    model_id=model_id,
+                    model_provider=model_provider,
+                    evaluated_component_name=evaluated_component_name,
+                    workflow_id=None,
+                    eval_input=log_eval_input,
+                )
 
         if self.telemetry:
             from agno.api.evals import EvalRunCreate, create_eval_run_telemetry

agno/eval/performance.py

@@ -3,10 +3,10 @@ import gc
 import tracemalloc
 from dataclasses import dataclass, field
 from os import getenv
-from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Union
 from uuid import uuid4
 
-from agno.db.base import BaseDb
+from agno.db.base import AsyncBaseDb, BaseDb
 from agno.db.schemas.evals import EvalType
 from agno.eval.utils import async_log_eval, log_eval_run, store_result_in_file
 from agno.utils.log import log_debug, set_log_level_to_debug, set_log_level_to_info
@@ -222,7 +222,7 @@ class PerformanceEval:
     # Enable debug logs
     debug_mode: bool = getenv("AGNO_DEBUG", "false").lower() == "true"
     # The database to store Evaluation results
-    db: Optional[BaseDb] = None
+    db: Optional[Union[BaseDb, AsyncBaseDb]] = None
 
     # Telemetry settings
     # telemetry=True logs minimal telemetry for analytics
@@ -491,6 +491,9 @@ class PerformanceEval:
         6. Print results as requested
         7. Log results to the Agno platform if requested
         """
+        if isinstance(self.db, AsyncBaseDb):
+            raise ValueError("run() is not supported with an async DB. Please use arun() instead.")
+
         from rich.console import Console
         from rich.live import Live
         from rich.status import Status

agno/eval/reliability.py

@@ -1,9 +1,9 @@
 from dataclasses import asdict, dataclass, field
 from os import getenv
-from typing import TYPE_CHECKING, Any, Dict, List, Optional
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
 from uuid import uuid4
 
-from agno.db.base import BaseDb
+from agno.db.base import AsyncBaseDb, BaseDb
 
 if TYPE_CHECKING:
     from rich.console import Console
@@ -63,7 +63,7 @@ class ReliabilityEval:
     # Enable debug logs
     debug_mode: bool = getenv("AGNO_DEBUG", "false").lower() == "true"
     # The database to store Evaluation results
-    db: Optional[BaseDb] = None
+    db: Optional[Union[BaseDb, AsyncBaseDb]] = None
 
     # Telemetry settings
     # telemetry=True logs minimal telemetry for analytics
@@ -71,6 +71,9 @@ class ReliabilityEval:
     telemetry: bool = True
 
     def run(self, *, print_results: bool = False) -> Optional[ReliabilityResult]:
+        if isinstance(self.db, AsyncBaseDb):
+            raise ValueError("run() is not supported with an async DB. Please use arun() instead.")
+
         if self.agent_response is None and self.team_response is None:
             raise ValueError("You need to provide 'agent_response' or 'team_response' to run the evaluation.")
 

agno/eval/utils.py

@@ -2,7 +2,7 @@ from dataclasses import asdict
 from pathlib import Path
 from typing import TYPE_CHECKING, Optional, Union
 
-from agno.db.base import BaseDb
+from agno.db.base import AsyncBaseDb, BaseDb
 from agno.db.schemas.evals import EvalRunRecord, EvalType
 from agno.utils.log import log_debug, logger
 
@@ -49,7 +49,7 @@ def log_eval_run(
 
 
 async def async_log_eval(
-    db: BaseDb,
+    db: Union[BaseDb, AsyncBaseDb],
     run_id: str,
     run_data: dict,
     eval_type: EvalType,
@@ -65,21 +65,38 @@ async def async_log_eval(
     """Call the API to create an evaluation run."""
 
     try:
-        db.create_eval_run(
-            EvalRunRecord(
-                run_id=run_id,
-                eval_type=eval_type,
-                eval_data=run_data,
-                eval_input=eval_input,
-                agent_id=agent_id,
-                model_id=model_id,
-                model_provider=model_provider,
-                name=name,
-                evaluated_component_name=evaluated_component_name,
-                team_id=team_id,
-                workflow_id=workflow_id,
+        if isinstance(db, AsyncBaseDb):
+            await db.create_eval_run(
+                EvalRunRecord(
+                    run_id=run_id,
+                    eval_type=eval_type,
+                    eval_data=run_data,
+                    eval_input=eval_input,
+                    agent_id=agent_id,
+                    model_id=model_id,
+                    model_provider=model_provider,
+                    name=name,
+                    evaluated_component_name=evaluated_component_name,
+                    team_id=team_id,
+                    workflow_id=workflow_id,
+                )
+            )
+        else:
+            db.create_eval_run(
+                EvalRunRecord(
+                    run_id=run_id,
+                    eval_type=eval_type,
+                    eval_data=run_data,
+                    eval_input=eval_input,
+                    agent_id=agent_id,
+                    model_id=model_id,
+                    model_provider=model_provider,
+                    name=name,
+                    evaluated_component_name=evaluated_component_name,
+                    team_id=team_id,
+                    workflow_id=workflow_id,
+                )
             )
-        )
     except Exception as e:
         log_debug(f"Could not create agent event: {e}")
 

agno/exceptions.py

@@ -1,4 +1,5 @@
-from typing import List, Optional, Union
+from enum import Enum
+from typing import Any, Dict, List, Optional, Union
 
 from agno.models.message import Message
 
@@ -17,6 +18,8 @@ class AgentRunException(Exception):
         self.agent_message = agent_message
         self.messages = messages
         self.stop_execution = stop_execution
+        self.type = "agent_run_error"
+        self.error_id = "agent_run_error"
 
 
 class RetryAgentRun(AgentRunException):
@@ -32,6 +35,7 @@ class RetryAgentRun(AgentRunException):
         super().__init__(
             exc, user_message=user_message, agent_message=agent_message, messages=messages, stop_execution=False
         )
+        self.error_id = "retry_agent_run_error"
 
 
 class StopAgentRun(AgentRunException):
@@ -47,6 +51,7 @@ class StopAgentRun(AgentRunException):
         super().__init__(
             exc, user_message=user_message, agent_message=agent_message, messages=messages, stop_execution=True
         )
+        self.error_id = "stop_agent_run_error"
 
 
 class RunCancelledException(Exception):
@@ -54,6 +59,8 @@ class RunCancelledException(Exception):
 
     def __init__(self, message: str = "Operation cancelled by user"):
         super().__init__(message)
+        self.type = "run_cancelled_error"
+        self.error_id = "run_cancelled_error"
 
 
 class AgnoError(Exception):
@@ -63,6 +70,8 @@ class AgnoError(Exception):
         super().__init__(message)
         self.message = message
         self.status_code = status_code
+        self.type = "agno_error"
+        self.error_id = "agno_error"
 
     def __str__(self) -> str:
         return str(self.message)
@@ -78,6 +87,9 @@ class ModelProviderError(AgnoError):
         self.model_name = model_name
         self.model_id = model_id
 
+        self.type = "model_provider_error"
+        self.error_id = "model_provider_error"
+
 
 class ModelRateLimitError(ModelProviderError):
     """Exception raised when a model provider returns a rate limit error."""
@@ -86,9 +98,64 @@ class ModelRateLimitError(ModelProviderError):
         self, message: str, status_code: int = 429, model_name: Optional[str] = None, model_id: Optional[str] = None
     ):
         super().__init__(message, status_code, model_name, model_id)
+        self.error_id = "model_rate_limit_error"
 
 
 class EvalError(Exception):
     """Exception raised when an evaluation fails."""
 
     pass
+
+
+class CheckTrigger(Enum):
+    """Enum for guardrail triggers."""
+
+    OFF_TOPIC = "off_topic"
+    INPUT_NOT_ALLOWED = "input_not_allowed"
+    OUTPUT_NOT_ALLOWED = "output_not_allowed"
+    VALIDATION_FAILED = "validation_failed"
+
+    PROMPT_INJECTION = "prompt_injection"
+    PII_DETECTED = "pii_detected"
+
+
+class InputCheckError(Exception):
+    """Exception raised when an input check fails."""
+
+    def __init__(
+        self,
+        message: str,
+        check_trigger: CheckTrigger = CheckTrigger.INPUT_NOT_ALLOWED,
+        additional_data: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message)
+        self.type = "input_check_error"
+        if isinstance(check_trigger, CheckTrigger):
+            self.error_id = check_trigger.value
+        else:
+            self.error_id = str(check_trigger)
+
+        self.message = message
+        self.check_trigger = check_trigger
+        self.additional_data = additional_data
+
+
+class OutputCheckError(Exception):
+    """Exception raised when an output check fails."""
+
+    def __init__(
+        self,
+        message: str,
+        check_trigger: CheckTrigger = CheckTrigger.OUTPUT_NOT_ALLOWED,
+        additional_data: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message)
+        self.type = "output_check_error"
+        if isinstance(check_trigger, CheckTrigger):
+            self.error_id = check_trigger.value
+        else:
+            self.error_id = str(check_trigger)
+
+        self.message = message
+        self.check_trigger = check_trigger
+        self.additional_data = additional_data