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

agno/db/redis/schemas.py

@@ -0,0 +1,159 @@
+"""Table schemas and related utils used by the RedisDb class"""
+
+from typing import Any
+
+SESSION_SCHEMA = {
+    "session_id": {"type": "string", "primary_key": True},
+    "session_type": {"type": "string"},
+    "agent_id": {"type": "string"},
+    "team_id": {"type": "string"},
+    "workflow_id": {"type": "string"},
+    "user_id": {"type": "string"},
+    "session_data": {"type": "json"},
+    "agent_data": {"type": "json"},
+    "team_data": {"type": "json"},
+    "workflow_data": {"type": "json"},
+    "metadata": {"type": "json"},
+    "runs": {"type": "json"},
+    "summary": {"type": "json"},
+    "created_at": {"type": "integer"},
+    "updated_at": {"type": "integer"},
+}
+
+USER_MEMORY_SCHEMA = {
+    "memory_id": {"type": "string", "primary_key": True},
+    "memory": {"type": "json"},
+    "agent_id": {"type": "string"},
+    "team_id": {"type": "string"},
+    "user_id": {"type": "string"},
+    "topics": {"type": "json"},
+    "input": {"type": "string"},
+    "feedback": {"type": "string"},
+    "created_at": {"type": "integer"},
+    "updated_at": {"type": "integer"},
+}
+
+METRICS_SCHEMA = {
+    "id": {"type": "string", "primary_key": True},
+    "agent_runs_count": {"type": "integer", "default": 0},
+    "team_runs_count": {"type": "integer", "default": 0},
+    "workflow_runs_count": {"type": "integer", "default": 0},
+    "agent_sessions_count": {"type": "integer", "default": 0},
+    "team_sessions_count": {"type": "integer", "default": 0},
+    "workflow_sessions_count": {"type": "integer", "default": 0},
+    "users_count": {"type": "integer", "default": 0},
+    "token_metrics": {"type": "json", "default": {}},
+    "model_metrics": {"type": "json", "default": {}},
+    "date": {"type": "date"},
+    "aggregation_period": {"type": "string"},
+    "created_at": {"type": "integer"},
+    "updated_at": {"type": "integer"},
+    "completed": {"type": "boolean", "default": False},
+}
+
+EVAL_SCHEMA = {
+    "run_id": {"type": "string", "primary_key": True},
+    "eval_type": {"type": "string"},
+    "eval_data": {"type": "json"},
+    "eval_input": {"type": "json"},
+    "name": {"type": "string"},
+    "agent_id": {"type": "string"},
+    "team_id": {"type": "string"},
+    "workflow_id": {"type": "string"},
+    "model_id": {"type": "string"},
+    "model_provider": {"type": "string"},
+    "evaluated_component_name": {"type": "string"},
+    "created_at": {"type": "integer"},
+    "updated_at": {"type": "integer"},
+}
+
+KNOWLEDGE_SCHEMA = {
+    "id": {"type": "string", "primary_key": True},
+    "name": {"type": "string"},
+    "description": {"type": "string"},
+    "metadata": {"type": "json"},
+    "type": {"type": "string"},
+    "size": {"type": "integer"},
+    "linked_to": {"type": "string"},
+    "access_count": {"type": "integer"},
+    "created_at": {"type": "integer"},
+    "updated_at": {"type": "integer"},
+    "status": {"type": "string"},
+    "status_message": {"type": "string"},
+    "external_id": {"type": "string"},
+}
+
+
+CULTURAL_KNOWLEDGE_SCHEMA = {
+    "id": {"type": "string", "primary_key": True},
+    "name": {"type": "string"},
+    "summary": {"type": "string"},
+    "content": {"type": "json"},
+    "metadata": {"type": "json"},
+    "input": {"type": "string"},
+    "created_at": {"type": "integer"},
+    "updated_at": {"type": "integer"},
+    "agent_id": {"type": "string"},
+    "team_id": {"type": "string"},
+}
+
+TRACE_SCHEMA = {
+    "trace_id": {"type": "string", "primary_key": True},
+    "name": {"type": "string"},
+    "status": {"type": "string"},
+    "duration_ms": {"type": "integer"},
+    "run_id": {"type": "string"},
+    "session_id": {"type": "string"},
+    "user_id": {"type": "string"},
+    "agent_id": {"type": "string"},
+    "team_id": {"type": "string"},
+    "workflow_id": {"type": "string"},
+    "start_time": {"type": "string"},
+    "end_time": {"type": "string"},
+    "created_at": {"type": "string"},
+}
+
+SPAN_SCHEMA = {
+    "span_id": {"type": "string", "primary_key": True},
+    "trace_id": {"type": "string"},
+    "parent_span_id": {"type": "string"},
+    "name": {"type": "string"},
+    "span_kind": {"type": "string"},
+    "status_code": {"type": "string"},
+    "status_message": {"type": "string"},
+    "start_time": {"type": "string"},
+    "end_time": {"type": "string"},
+    "attributes": {"type": "json"},
+    "created_at": {"type": "string"},
+}
+
+
+def get_table_schema_definition(table_type: str) -> dict[str, Any]:
+    """
+    Get the expected schema definition for the given table.
+
+    For Redis, we don't need actual schemas since it's a key-value store,
+    but we maintain this for compatibility with the base interface.
+
+    Args:
+        table_type (str): The type of table to get the schema for.
+
+    Returns:
+        Dict[str, Any]: Dictionary containing schema information for the table
+    """
+    schemas = {
+        "sessions": SESSION_SCHEMA,
+        "memories": USER_MEMORY_SCHEMA,
+        "metrics": METRICS_SCHEMA,
+        "evals": EVAL_SCHEMA,
+        "knowledge": KNOWLEDGE_SCHEMA,
+        "culture": CULTURAL_KNOWLEDGE_SCHEMA,
+        "traces": TRACE_SCHEMA,
+        "spans": SPAN_SCHEMA,
+    }
+
+    schema = schemas.get(table_type, {})
+    if not schema:
+        raise ValueError(f"Unknown table type: {table_type}")
+
+    return schema

agno/db/redis/utils.py

@@ -0,0 +1,346 @@
+"""Utility functions for the Redis database class."""
+
+import json
+import time
+from datetime import date, datetime, timedelta, timezone
+from typing import Any, Dict, List, Optional, Union
+from uuid import UUID
+
+from agno.db.schemas.culture import CulturalKnowledge
+from agno.utils.log import log_warning
+
+try:
+    from redis import Redis, RedisCluster
+except ImportError:
+    raise ImportError("`redis` not installed. Please install it using `pip install redis`")
+
+
+# -- Serialization and deserialization --
+
+
+class CustomEncoder(json.JSONEncoder):
+    """Custom encoder to handle non JSON serializable types."""
+
+    def default(self, obj):
+        if isinstance(obj, UUID):
+            return str(obj)
+        elif isinstance(obj, (date, datetime)):
+            return obj.isoformat()
+
+        return super().default(obj)
+
+
+def serialize_data(data: dict) -> str:
+    return json.dumps(data, ensure_ascii=False, cls=CustomEncoder)
+
+
+def deserialize_data(data: str) -> dict:
+    return json.loads(data)
+
+
+# -- Redis utils --
+
+
+def generate_redis_key(prefix: str, table_type: str, key_id: str) -> str:
+    """Generate Redis key with proper namespacing."""
+    return f"{prefix}:{table_type}:{key_id}"
+
+
+def generate_index_key(prefix: str, table_type: str, index_field: str, index_value: str) -> str:
+    """Generate Redis key for index entries."""
+    return f"{prefix}:{table_type}:index:{index_field}:{index_value}"
+
+
+def get_all_keys_for_table(redis_client: Union[Redis, RedisCluster], prefix: str, table_type: str) -> List[str]:
+    """Get all relevant keys for the given table type.
+
+    Args:
+        redis_client (Redis): The Redis client.
+        prefix (str): The prefix for the keys.
+        table_type (str): The table type.
+
+    Returns:
+        List[str]: A list of all relevant keys for the given table type.
+    """
+    pattern = f"{prefix}:{table_type}:*"
+    all_keys = redis_client.scan_iter(match=pattern)
+    relevant_keys = []
+
+    for key in all_keys:
+        if ":index:" in key:  # Skip index keys
+            continue
+        relevant_keys.append(key)
+
+    return relevant_keys
+
+
+# -- DB util methods --
+
+
+def apply_sorting(
+    records: List[Dict[str, Any]], sort_by: Optional[str] = None, sort_order: Optional[str] = None
+) -> List[Dict[str, Any]]:
+    if sort_by is None:
+        return records
+
+    def get_sort_key(record):
+        value = record.get(sort_by, 0)
+        if value is None:
+            return 0 if isinstance(records[0].get(sort_by, 0), (int, float)) else ""
+        return value
+
+    try:
+        is_reverse = sort_order == "desc"
+        return sorted(records, key=get_sort_key, reverse=is_reverse)
+
+    except Exception as e:
+        log_warning(f"Error sorting Redisrecords: {e}")
+        return records
+
+
+def apply_pagination(
+    records: List[Dict[str, Any]], limit: Optional[int] = None, page: Optional[int] = None
+) -> List[Dict[str, Any]]:
+    if limit is None:
+        return records
+
+    if page is not None and page > 0:
+        start_idx = (page - 1) * limit
+        end_idx = start_idx + limit
+        return records[start_idx:end_idx]
+
+    return records[:limit]
+
+
+def apply_filters(records: List[Dict[str, Any]], conditions: Dict[str, Any]) -> List[Dict[str, Any]]:
+    if not conditions:
+        return records
+
+    filtered_records = []
+    for record in records:
+        match = True
+        for key, value in conditions.items():
+            if key not in record or record[key] != value:
+                match = False
+                break
+        if match:
+            filtered_records.append(record)
+
+    return filtered_records
+
+
+def create_index_entries(
+    redis_client: Union[Redis, RedisCluster],
+    prefix: str,
+    table_type: str,
+    record_id: str,
+    record_data: Dict[str, Any],
+    index_fields: List[str],
+) -> None:
+    for field in index_fields:
+        if field in record_data and record_data[field] is not None:
+            index_key = generate_index_key(prefix, table_type, field, str(record_data[field]))
+            redis_client.sadd(index_key, record_id)
+
+
+def remove_index_entries(
+    redis_client: Union[Redis, RedisCluster],
+    prefix: str,
+    table_type: str,
+    record_id: str,
+    record_data: Dict[str, Any],
+    index_fields: List[str],
+) -> None:
+    for field in index_fields:
+        if field in record_data and record_data[field] is not None:
+            index_key = generate_index_key(prefix, table_type, field, str(record_data[field]))
+            redis_client.srem(index_key, record_id)
+
+
+# -- Metrics utils --
+
+
+def calculate_date_metrics(date_to_process: date, sessions_data: dict) -> dict:
+    """Calculate metrics for the given date.
+
+    Args:
+        date_to_process (date): The date to calculate metrics for.
+        sessions_data (dict): The sessions data.
+
+    Returns:
+        dict: A dictionary with the calculated metrics.
+    """
+    metrics = {
+        "users_count": 0,
+        "agent_sessions_count": 0,
+        "team_sessions_count": 0,
+        "workflow_sessions_count": 0,
+        "agent_runs_count": 0,
+        "team_runs_count": 0,
+        "workflow_runs_count": 0,
+    }
+    token_metrics = {
+        "input_tokens": 0,
+        "output_tokens": 0,
+        "total_tokens": 0,
+        "audio_total_tokens": 0,
+        "audio_input_tokens": 0,
+        "audio_output_tokens": 0,
+        "cache_read_tokens": 0,
+        "cache_write_tokens": 0,
+        "reasoning_tokens": 0,
+    }
+    model_counts: Dict[str, int] = {}
+
+    session_types = [
+        ("agent", "agent_sessions_count", "agent_runs_count"),
+        ("team", "team_sessions_count", "team_runs_count"),
+        ("workflow", "workflow_sessions_count", "workflow_runs_count"),
+    ]
+    all_user_ids = set()
+
+    for session_type, sessions_count_key, runs_count_key in session_types:
+        sessions = sessions_data.get(session_type, []) or []
+        metrics[sessions_count_key] = len(sessions)
+
+        for session in sessions:
+            if session.get("user_id"):
+                all_user_ids.add(session["user_id"])
+            metrics[runs_count_key] += len(session.get("runs", []))
+            if runs := session.get("runs", []):
+                for run in runs:
+                    if model_id := run.get("model"):
+                        model_provider = run.get("model_provider", "")
+                        model_counts[f"{model_id}:{model_provider}"] = (
+                            model_counts.get(f"{model_id}:{model_provider}", 0) + 1
+                        )
+
+            session_metrics = session.get("session_data", {}).get("session_metrics", {})
+            for field in token_metrics:
+                token_metrics[field] += session_metrics.get(field, 0)
+
+    model_metrics = []
+    for model, count in model_counts.items():
+        model_id, model_provider = model.rsplit(":", 1)
+        model_metrics.append({"model_id": model_id, "model_provider": model_provider, "count": count})
+
+    metrics["users_count"] = len(all_user_ids)
+    current_time = int(time.time())
+
+    # Create a deterministic ID based on date and aggregation period. This simplifies avoiding duplicates
+    metric_id = f"{date_to_process.isoformat()}_daily"
+
+    return {
+        "id": metric_id,
+        "date": date_to_process,
+        "completed": date_to_process < datetime.now(timezone.utc).date(),
+        "token_metrics": token_metrics,
+        "model_metrics": model_metrics,
+        "created_at": current_time,
+        "updated_at": current_time,
+        "aggregation_period": "daily",
+        **metrics,
+    }
+
+
+def fetch_all_sessions_data(
+    sessions: List[Dict[str, Any]], dates_to_process: list[date], start_timestamp: int
+) -> Optional[dict]:
+    """Return all session data for the given dates, for all session types.
+
+    Args:
+        sessions (List[Dict[str, Any]]): The sessions data.
+        dates_to_process (list[date]): The dates to process.
+        start_timestamp (int): The start timestamp.
+
+    Returns:
+        Optional[dict]: A dictionary with the session data for the given dates, for all session types.
+    """
+    if not dates_to_process:
+        return None
+
+    all_sessions_data: Dict[str, Dict[str, List[Dict[str, Any]]]] = {
+        date_to_process.isoformat(): {"agent": [], "team": [], "workflow": []} for date_to_process in dates_to_process
+    }
+
+    for session in sessions:
+        session_date = (
+            datetime.fromtimestamp(session.get("created_at", start_timestamp), tz=timezone.utc).date().isoformat()
+        )
+        if session_date in all_sessions_data:
+            all_sessions_data[session_date][session["session_type"]].append(session)
+
+    return all_sessions_data
+
+
+def get_dates_to_calculate_metrics_for(starting_date: date) -> list[date]:
+    """Return the list of dates to calculate metrics for.
+
+    Args:
+        starting_date (date): The starting date.
+
+    Returns:
+        list[date]: The list of dates to calculate metrics for.
+    """
+    today = datetime.now(timezone.utc).date()
+    days_diff = (today - starting_date).days + 1
+    if days_diff <= 0:
+        return []
+    return [starting_date + timedelta(days=x) for x in range(days_diff)]
+
+
+# -- 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 column.
+
+    Args:
+        cultural_knowledge (CulturalKnowledge): The cultural knowledge object to serialize.
+
+    Returns:
+        Dict[str, Any]: A dictionary with the content field as a dict containing 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/schemas/__init__.py

@@ -0,0 +1,4 @@
+from agno.db.schemas.culture import CulturalKnowledge
+from agno.db.schemas.memory import UserMemory
+
+__all__ = ["CulturalKnowledge", "UserMemory"]

agno/db/schemas/culture.py

@@ -0,0 +1,120 @@
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional, Union
+
+from typing_extensions import List
+
+
+@dataclass
+class CulturalKnowledge:
+    """Model for Cultural Knowledge
+
+    Notice: Culture is an experimental feature and is subject to change.
+    """
+
+    # The id of the cultural knowledge, auto-generated if not provided
+    id: Optional[str] = None
+    name: Optional[str] = None
+
+    content: Optional[str] = None
+    categories: Optional[List[str]] = None
+    notes: Optional[List[str]] = None
+
+    summary: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+    input: Optional[str] = None
+
+    created_at: Optional[int] = field(default=None)
+    updated_at: Optional[int] = field(default=None)
+
+    agent_id: Optional[str] = None
+    team_id: Optional[str] = None
+
+    def __post_init__(self):
+        if self.name is not None and not self.name.strip():
+            raise ValueError("name must be a non-empty string")
+        self.created_at = _now_epoch_s() if self.created_at is None else _to_epoch_s(self.created_at)
+        self.updated_at = self.created_at if self.updated_at is None else _to_epoch_s(self.updated_at)
+
+    def bump_updated_at(self) -> None:
+        """Bump updated_at to now (UTC)."""
+        self.updated_at = _now_epoch_s()
+
+    def preview(self) -> Dict[str, Any]:
+        """Return a preview of the cultural knowledge"""
+        _preview: Dict[str, Any] = {
+            "name": self.name,
+        }
+        if self.categories is not None:
+            _preview["categories"] = self.categories
+        if self.summary is not None:
+            _preview["summary"] = self.summary[:100] + "..." if len(self.summary) > 100 else self.summary
+        if self.content is not None:
+            _preview["content"] = self.content[:100] + "..." if len(self.content) > 100 else self.content
+        if self.notes is not None:
+            _preview["notes"] = [note[:100] + "..." if len(note) > 100 else note for note in self.notes]
+        return _preview
+
+    def to_dict(self) -> Dict[str, Any]:
+        _dict = {
+            "id": self.id,
+            "name": self.name,
+            "summary": self.summary,
+            "content": self.content,
+            "categories": self.categories,
+            "metadata": self.metadata,
+            "notes": self.notes,
+            "input": self.input,
+            "created_at": (_epoch_to_rfc3339_z(self.created_at) if self.created_at is not None else None),
+            "updated_at": (_epoch_to_rfc3339_z(self.updated_at) if self.updated_at is not None else None),
+            "agent_id": self.agent_id,
+            "team_id": self.team_id,
+        }
+        return {k: v for k, v in _dict.items() if v is not None}
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "CulturalKnowledge":
+        d = dict(data)
+
+        # Preserve 0 and None explicitly; only process if key exists
+        if "created_at" in d and d["created_at"] is not None:
+            d["created_at"] = _to_epoch_s(d["created_at"])
+        if "updated_at" in d and d["updated_at"] is not None:
+            d["updated_at"] = _to_epoch_s(d["updated_at"])
+
+        return cls(**d)
+
+
+def _now_epoch_s() -> int:
+    return int(datetime.now(timezone.utc).timestamp())
+
+
+def _to_epoch_s(value: Union[int, float, str, datetime]) -> int:
+    """Normalize various datetime representations to epoch seconds (UTC)."""
+    if isinstance(value, (int, float)):
+        # assume value is already in seconds
+        return int(value)
+
+    if isinstance(value, datetime):
+        dt = value
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return int(dt.timestamp())
+
+    if isinstance(value, str):
+        s = value.strip()
+        if s.endswith("Z"):
+            s = s[:-1] + "+00:00"
+        try:
+            dt = datetime.fromisoformat(s)
+        except ValueError as e:
+            raise ValueError(f"Unsupported datetime string: {value!r}") from e
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return int(dt.timestamp())
+
+    raise TypeError(f"Unsupported datetime value: {type(value)}")
+
+
+def _epoch_to_rfc3339_z(ts: Union[int, float]) -> str:
+    return datetime.fromtimestamp(float(ts), tz=timezone.utc).isoformat().replace("+00:00", "Z")

agno/db/schemas/evals.py

@@ -0,0 +1,34 @@
+from enum import Enum
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel
+
+
+class EvalType(str, Enum):
+    ACCURACY = "accuracy"
+    AGENT_AS_JUDGE = "agent_as_judge"
+    PERFORMANCE = "performance"
+    RELIABILITY = "reliability"
+
+
+class EvalFilterType(str, Enum):
+    AGENT = "agent"
+    TEAM = "team"
+    WORKFLOW = "workflow"
+
+
+class EvalRunRecord(BaseModel):
+    """Evaluation run results stored in the database"""
+
+    agent_id: Optional[str] = None
+    model_id: Optional[str] = None
+    model_provider: Optional[str] = None
+    team_id: Optional[str] = None
+    workflow_id: Optional[str] = None
+    name: Optional[str] = None
+    evaluated_component_name: Optional[str] = None
+
+    run_id: str
+    eval_type: EvalType
+    eval_data: Dict[str, Any]
+    eval_input: Optional[Dict[str, Any]] = None