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

agno/filters.py

@@ -0,0 +1,354 @@
+"""Search filter expressions for filtering knowledge base documents and search results.
+
+This module provides a set of filter operators for constructing complex search queries
+that can be applied to knowledge bases, vector databases, and other searchable content.
+
+Filter Types:
+    - Comparison: EQ (equals), GT (greater than), LT (less than)
+    - Inclusion: IN (value in list)
+    - Logical: AND, OR, NOT
+
+Example:
+    >>> from agno.filters import EQ, GT, IN, AND, OR, NOT
+    >>>
+    >>> # Simple equality filter
+    >>> filter = EQ("category", "technology")
+    >>>
+    >>> # Complex filter with multiple conditions
+    >>> filter = AND(
+    ...     EQ("status", "published"),
+    ...     GT("views", 1000),
+    ...     IN("category", ["tech", "science"])
+    ... )
+    >>>
+    >>> # Using OR logic
+    >>> filter = OR(EQ("priority", "high"), EQ("urgent", True))
+    >>>
+    >>> # Negating conditions
+    >>> filter = NOT(EQ("status", "archived"))
+    >>>
+    >>> # Complex nested logic
+    >>> filter = OR(
+    ...     AND(EQ("type", "article"), GT("word_count", 500)),
+    ...     AND(EQ("type", "tutorial"), NOT(EQ("difficulty", "beginner")))
+    ... )
+"""
+
+from __future__ import annotations
+
+from typing import Any, List
+
+# ============================================================
+# Base Expression
+# ============================================================
+
+
+class FilterExpr:
+    """Base class for all filter expressions.
+
+    Filters can be combined using AND, OR, and NOT classes:
+    - AND: Combine filters where both expressions must be true
+    - OR: Combine filters where either expression can be true
+    - NOT: Negate a filter expression
+
+    Example:
+        >>> # Create complex filters using AND, OR, NOT
+        >>> filter = OR(AND(EQ("status", "active"), GT("age", 18)), EQ("role", "admin"))
+        >>> # Equivalent to: (status == "active" AND age > 18) OR role == "admin"
+    """
+
+    # Logical operator overloads
+    def __or__(self, other: FilterExpr) -> OR:
+        """Combine two filters with OR logic."""
+        return OR(self, other)
+
+    def __and__(self, other: FilterExpr) -> AND:
+        """Combine two filters with AND logic."""
+        return AND(self, other)
+
+    def __invert__(self) -> NOT:
+        """Negate a filter."""
+        return NOT(self)
+
+    def to_dict(self) -> dict:
+        """Convert the filter expression to a dictionary representation."""
+        raise NotImplementedError("Subclasses must implement to_dict()")
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.__dict__})"
+
+
+# ============================================================
+# Comparison & Inclusion Filters
+# ============================================================
+
+
+class EQ(FilterExpr):
+    """Equality filter - matches documents where a field equals a specific value.
+
+    Args:
+        key: The field name to compare
+        value: The value to match against
+
+    Example:
+        >>> # Match documents where status is "published"
+        >>> filter = EQ("status", "published")
+        >>>
+        >>> # Match documents where author_id is 123
+        >>> filter = EQ("author_id", 123)
+    """
+
+    def __init__(self, key: str, value: Any):
+        self.key = key
+        self.value = value
+
+    def to_dict(self) -> dict:
+        return {"op": "EQ", "key": self.key, "value": self.value}
+
+
+class IN(FilterExpr):
+    """Inclusion filter - matches documents where a field's value is in a list of values.
+
+    Args:
+        key: The field name to check
+        values: List of acceptable values
+
+    Example:
+        >>> # Match documents where category is either "tech", "science", or "engineering"
+        >>> filter = IN("category", ["tech", "science", "engineering"])
+        >>>
+        >>> # Match documents where status is either "draft" or "published"
+        >>> filter = IN("status", ["draft", "published"])
+    """
+
+    def __init__(self, key: str, values: List[Any]):
+        self.key = key
+        self.values = values
+
+    def to_dict(self) -> dict:
+        return {"op": "IN", "key": self.key, "values": self.values}
+
+
+class GT(FilterExpr):
+    """Greater than filter - matches documents where a field's value is greater than a threshold.
+
+    Args:
+        key: The field name to compare
+        value: The threshold value
+
+    Example:
+        >>> # Match documents where age is greater than 18
+        >>> filter = GT("age", 18)
+        >>>
+        >>> # Match documents where price is greater than 100.0
+        >>> filter = GT("price", 100.0)
+        >>>
+        >>> # Match documents created after a certain timestamp
+        >>> filter = GT("created_at", 1234567890)
+    """
+
+    def __init__(self, key: str, value: Any):
+        self.key = key
+        self.value = value
+
+    def to_dict(self) -> dict:
+        return {"op": "GT", "key": self.key, "value": self.value}
+
+
+class LT(FilterExpr):
+    """Less than filter - matches documents where a field's value is less than a threshold.
+
+    Args:
+        key: The field name to compare
+        value: The threshold value
+
+    Example:
+        >>> # Match documents where age is less than 65
+        >>> filter = LT("age", 65)
+        >>>
+        >>> # Match documents where price is less than 50.0
+        >>> filter = LT("price", 50.0)
+        >>>
+        >>> # Match documents created before a certain timestamp
+        >>> filter = LT("created_at", 1234567890)
+    """
+
+    def __init__(self, key: str, value: Any):
+        self.key = key
+        self.value = value
+
+    def to_dict(self) -> dict:
+        return {"op": "LT", "key": self.key, "value": self.value}
+
+
+# ============================================================
+# Logical Operators
+# ============================================================
+
+
+class AND(FilterExpr):
+    """Logical AND operator - matches documents where ALL expressions are true.
+
+    Combines multiple filter expressions where every expression must be satisfied
+    for a document to match.
+
+    Args:
+        *expressions: Variable number of FilterExpr expressions to combine with AND logic
+
+    Example:
+        >>> # Match documents where status is "published" AND age > 18
+        >>> filter = AND(EQ("status", "published"), GT("age", 18))
+        >>>
+        >>> # Multiple expressions
+        >>> filter = AND(
+        ...     EQ("status", "active"),
+        ...     GT("score", 80),
+        ...     IN("category", ["tech", "science"])
+        ... )
+    """
+
+    def __init__(self, *expressions: FilterExpr):
+        self.expressions = list(expressions)
+
+    def to_dict(self) -> dict:
+        return {"op": "AND", "conditions": [e.to_dict() for e in self.expressions]}
+
+
+class OR(FilterExpr):
+    """Logical OR operator - matches documents where ANY expression is true.
+
+    Combines multiple filter expressions where at least one expression must be satisfied
+    for a document to match.
+
+    Args:
+        *expressions: Variable number of FilterExpr expressions to combine with OR logic
+
+    Example:
+        >>> # Match documents where status is "published" OR status is "archived"
+        >>> filter = OR(EQ("status", "published"), EQ("status", "archived"))
+        >>>
+        >>> # Complex: Match VIP users OR users with high score
+        >>> filter = OR(
+        ...     EQ("membership", "VIP"),
+        ...     GT("score", 1000)
+        ... )
+    """
+
+    def __init__(self, *expressions: FilterExpr):
+        self.expressions = list(expressions)
+
+    def to_dict(self) -> dict:
+        return {"op": "OR", "conditions": [e.to_dict() for e in self.expressions]}
+
+
+class NOT(FilterExpr):
+    """Logical NOT operator - matches documents where the expression is NOT true.
+
+    Negates a filter expression, matching documents that don't satisfy the expression.
+
+    Args:
+        expression: The FilterExpr expression to negate
+
+    Example:
+        >>> # Match documents where status is NOT "draft"
+        >>> filter = NOT(EQ("status", "draft"))
+        >>>
+        >>> # Exclude inactive users with low scores
+        >>> filter = NOT(AND(EQ("status", "inactive"), LT("score", 10)))
+        >>>
+        >>> # Match users who are NOT in the blocked list
+        >>> filter = NOT(IN("user_id", [101, 102, 103]))
+    """
+
+    def __init__(self, expression: FilterExpr):
+        self.expression = expression
+
+    def to_dict(self) -> dict:
+        return {"op": "NOT", "condition": self.expression.to_dict()}
+
+
+# ============================================================
+# Deserialization
+# ============================================================
+
+
+def from_dict(filter_dict: dict) -> FilterExpr:
+    """Reconstruct a FilterExpr object from its dictionary representation.
+
+    This function deserializes filter expressions that were serialized using the
+    to_dict() method, enabling filters to be passed through JSON APIs and reconstructed
+    on the server side.
+
+    Args:
+        filter_dict: Dictionary representation of a filter expression with an "op" key
+
+    Returns:
+        FilterExpr: The reconstructed filter expression object
+
+    Raises:
+        ValueError: If the filter dictionary has an invalid structure or unknown operator
+
+    Example:
+        >>> # Serialize and deserialize a simple filter
+        >>> original = EQ("status", "published")
+        >>> serialized = original.to_dict()
+        >>> # {"op": "EQ", "key": "status", "value": "published"}
+        >>> reconstructed = from_dict(serialized)
+        >>>
+        >>> # Complex filter with nested expressions
+        >>> complex_filter = OR(AND(EQ("type", "article"), GT("views", 1000)), IN("priority", ["high", "urgent"]))
+        >>> serialized = complex_filter.to_dict()
+        >>> reconstructed = from_dict(serialized)
+        >>>
+        >>> # From JSON API
+        >>> import json
+        >>> json_str = '{"op": "AND", "conditions": [{"op": "EQ", "key": "status", "value": "active"}, {"op": "GT", "key": "age", "value": 18}]}'
+        >>> filter_dict = json.loads(json_str)
+        >>> filter_expr = from_dict(filter_dict)
+    """
+    if not isinstance(filter_dict, dict) or "op" not in filter_dict:
+        raise ValueError(f"Invalid filter dictionary: must contain 'op' key. Got: {filter_dict}")
+
+    op = filter_dict["op"]
+
+    # Comparison and inclusion operators
+    if op == "EQ":
+        if "key" not in filter_dict or "value" not in filter_dict:
+            raise ValueError(f"EQ filter requires 'key' and 'value' fields. Got: {filter_dict}")
+        return EQ(filter_dict["key"], filter_dict["value"])
+
+    elif op == "IN":
+        if "key" not in filter_dict or "values" not in filter_dict:
+            raise ValueError(f"IN filter requires 'key' and 'values' fields. Got: {filter_dict}")
+        return IN(filter_dict["key"], filter_dict["values"])
+
+    elif op == "GT":
+        if "key" not in filter_dict or "value" not in filter_dict:
+            raise ValueError(f"GT filter requires 'key' and 'value' fields. Got: {filter_dict}")
+        return GT(filter_dict["key"], filter_dict["value"])
+
+    elif op == "LT":
+        if "key" not in filter_dict or "value" not in filter_dict:
+            raise ValueError(f"LT filter requires 'key' and 'value' fields. Got: {filter_dict}")
+        return LT(filter_dict["key"], filter_dict["value"])
+
+    # Logical operators
+    elif op == "AND":
+        if "conditions" not in filter_dict:
+            raise ValueError(f"AND filter requires 'conditions' field. Got: {filter_dict}")
+        conditions = [from_dict(cond) for cond in filter_dict["conditions"]]
+        return AND(*conditions)
+
+    elif op == "OR":
+        if "conditions" not in filter_dict:
+            raise ValueError(f"OR filter requires 'conditions' field. Got: {filter_dict}")
+        conditions = [from_dict(cond) for cond in filter_dict["conditions"]]
+        return OR(*conditions)
+
+    elif op == "NOT":
+        if "condition" not in filter_dict:
+            raise ValueError(f"NOT filter requires 'condition' field. Got: {filter_dict}")
+        return NOT(from_dict(filter_dict["condition"]))
+
+    else:
+        raise ValueError(f"Unknown filter operator: {op}")

agno/guardrails/__init__.py

@@ -0,0 +1,6 @@
+from agno.guardrails.base import BaseGuardrail
+from agno.guardrails.openai import OpenAIModerationGuardrail
+from agno.guardrails.pii import PIIDetectionGuardrail
+from agno.guardrails.prompt_injection import PromptInjectionGuardrail
+
+__all__ = ["BaseGuardrail", "OpenAIModerationGuardrail", "PIIDetectionGuardrail", "PromptInjectionGuardrail"]

agno/guardrails/base.py

@@ -0,0 +1,19 @@
+from abc import ABC, abstractmethod
+from typing import Union
+
+from agno.run.agent import RunInput
+from agno.run.team import TeamRunInput
+
+
+class BaseGuardrail(ABC):
+    """Abstract base class for all guardrail implementations."""
+
+    @abstractmethod
+    def check(self, run_input: Union[RunInput, TeamRunInput]) -> None:
+        """Perform synchronous guardrail check."""
+        pass
+
+    @abstractmethod
+    async def async_check(self, run_input: Union[RunInput, TeamRunInput]) -> None:
+        """Perform asynchronous guardrail check."""
+        pass

agno/guardrails/openai.py

@@ -0,0 +1,144 @@
+from os import getenv
+from typing import Any, Dict, List, Literal, Optional, Union
+
+from agno.exceptions import CheckTrigger, InputCheckError
+from agno.guardrails.base import BaseGuardrail
+from agno.run.agent import RunInput
+from agno.run.team import TeamRunInput
+from agno.utils.log import log_debug
+from agno.utils.openai import images_to_message
+
+
+class OpenAIModerationGuardrail(BaseGuardrail):
+    """Guardrail for detecting content that violates OpenAI's content policy.
+
+    Args:
+        moderation_model (str): The model to use for moderation. Defaults to "omni-moderation-latest".
+        raise_for_categories (List[str]): The categories to raise for.
+                                          Options are: "sexual", "sexual/minors", "harassment",
+                                          "harassment/threatening", "hate", "hate/threatening",
+                                          "illicit", "illicit/violent", "self-harm", "self-harm/intent",
+                                          "self-harm/instructions", "violence", "violence/graphic".
+                                          Defaults to include all categories.
+        api_key (str): The API key to use for moderation. Defaults to the OPENAI_API_KEY environment variable.
+    """
+
+    def __init__(
+        self,
+        moderation_model: str = "omni-moderation-latest",
+        raise_for_categories: Optional[
+            List[
+                Literal[
+                    "sexual",
+                    "sexual/minors",
+                    "harassment",
+                    "harassment/threatening",
+                    "hate",
+                    "hate/threatening",
+                    "illicit",
+                    "illicit/violent",
+                    "self-harm",
+                    "self-harm/intent",
+                    "self-harm/instructions",
+                    "violence",
+                    "violence/graphic",
+                ]
+            ]
+        ] = None,
+        api_key: Optional[str] = None,
+    ):
+        self.moderation_model = moderation_model
+        self.api_key = api_key or getenv("OPENAI_API_KEY")
+        self.raise_for_categories = raise_for_categories
+
+    def check(self, run_input: Union[RunInput, TeamRunInput]) -> None:
+        """Check for content that violates OpenAI's content policy."""
+        try:
+            from openai import OpenAI as OpenAIClient
+        except ImportError:
+            raise ImportError("`openai` not installed. Please install using `pip install openai`")
+
+        content = run_input.input_content_string()
+        images = run_input.images
+
+        log_debug(f"Moderating content using {self.moderation_model}")
+        client = OpenAIClient(api_key=self.api_key)
+
+        model_input: Union[str, List[Dict[str, Any]]] = content
+
+        if images is not None:
+            model_input = [{"type": "text", "text": content}, *images_to_message(images=images)]
+
+        # Prepare input based on content type
+        response = client.moderations.create(model=self.moderation_model, input=model_input)  # type: ignore
+
+        result = response.results[0]
+
+        if result.flagged:
+            moderation_result = {
+                "categories": result.categories.model_dump(),
+                "category_scores": result.category_scores.model_dump(),
+            }
+
+            trigger_validation = False
+
+            if self.raise_for_categories is not None:
+                for category in self.raise_for_categories:
+                    if moderation_result["categories"][category]:
+                        trigger_validation = True
+            else:
+                # Since at least one category is flagged, we need to raise the check
+                trigger_validation = True
+
+            if trigger_validation:
+                raise InputCheckError(
+                    "OpenAI moderation violation detected.",
+                    additional_data=moderation_result,
+                    check_trigger=CheckTrigger.INPUT_NOT_ALLOWED,
+                )
+
+    async def async_check(self, run_input: Union[RunInput, TeamRunInput]) -> None:
+        """Check for content that violates OpenAI's content policy."""
+        try:
+            from openai import AsyncOpenAI as OpenAIClient
+        except ImportError:
+            raise ImportError("`openai` not installed. Please install using `pip install openai`")
+
+        content = run_input.input_content_string()
+        images = run_input.images
+
+        log_debug(f"Moderating content using {self.moderation_model}")
+        client = OpenAIClient(api_key=self.api_key)
+
+        model_input: Union[str, List[Dict[str, Any]]] = content
+
+        if images is not None:
+            model_input = [{"type": "text", "text": content}, *images_to_message(images=images)]
+
+        # Prepare input based on content type
+        response = await client.moderations.create(model=self.moderation_model, input=model_input)  # type: ignore
+
+        result = response.results[0]
+
+        if result.flagged:
+            moderation_result = {
+                "categories": result.categories.model_dump(),
+                "category_scores": result.category_scores.model_dump(),
+            }
+
+            trigger_validation = False
+
+            if self.raise_for_categories is not None:
+                for category in self.raise_for_categories:
+                    if moderation_result["categories"][category]:
+                        trigger_validation = True
+            else:
+                # Since at least one category is flagged, we need to raise the check
+                trigger_validation = True
+
+            if trigger_validation:
+                raise InputCheckError(
+                    "OpenAI moderation violation detected.",
+                    additional_data=moderation_result,
+                    check_trigger=CheckTrigger.INPUT_NOT_ALLOWED,
+                )

agno/guardrails/pii.py

@@ -0,0 +1,94 @@
+from re import Pattern
+from typing import Dict, Optional, Union
+
+from agno.exceptions import CheckTrigger, InputCheckError
+from agno.guardrails.base import BaseGuardrail
+from agno.run.agent import RunInput
+from agno.run.team import TeamRunInput
+
+
+class PIIDetectionGuardrail(BaseGuardrail):
+    """Guardrail for detecting Personally Identifiable Information (PII).
+
+    Args:
+        mask_pii: Whether to mask the PII in the input, rather than raising an error.
+        enable_ssn_check: Whether to check for Social Security Numbers. True by default.
+        enable_credit_card_check: Whether to check for credit cards. True by default.
+        enable_email_check: Whether to check for emails. True by default.
+        enable_phone_check: Whether to check for phone numbers. True by default.
+        custom_patterns: A dictionary of custom PII patterns to detect. This is added to the default patterns.
+    """
+
+    def __init__(
+        self,
+        mask_pii: bool = False,
+        enable_ssn_check: bool = True,
+        enable_credit_card_check: bool = True,
+        enable_email_check: bool = True,
+        enable_phone_check: bool = True,
+        custom_patterns: Optional[Dict[str, Pattern[str]]] = None,
+    ):
+        import re
+
+        self.mask_pii = mask_pii
+        self.pii_patterns = {}
+
+        if enable_ssn_check:
+            self.pii_patterns["SSN"] = re.compile(r"\b\d{3}-\d{2}-\d{4}\b")
+        if enable_credit_card_check:
+            self.pii_patterns["Credit Card"] = re.compile(r"\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b")
+        if enable_email_check:
+            self.pii_patterns["Email"] = re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b")
+        if enable_phone_check:
+            self.pii_patterns["Phone"] = re.compile(r"\b\d{3}[\s.-]?\d{3}[\s.-]?\d{4}\b")
+
+        if custom_patterns:
+            self.pii_patterns.update(custom_patterns)
+
+    def check(self, run_input: Union[RunInput, TeamRunInput]) -> None:
+        """Check for PII patterns in the input."""
+        content = run_input.input_content_string()
+        detected_pii = []
+        for pii_type, pattern in self.pii_patterns.items():
+            if pattern.search(content):
+                detected_pii.append(pii_type)
+        if detected_pii:
+            if self.mask_pii:
+                for pii_type in detected_pii:
+
+                    def mask_match(match):
+                        return "*" * len(match.group(0))
+
+                    content = self.pii_patterns[pii_type].sub(mask_match, content)
+                run_input.input_content = content
+                return
+            else:
+                raise InputCheckError(
+                    "Potential PII detected in input",
+                    additional_data={"detected_pii": detected_pii},
+                    check_trigger=CheckTrigger.PII_DETECTED,
+                )
+
+    async def async_check(self, run_input: Union[RunInput, TeamRunInput]) -> None:
+        """Asynchronously check for PII patterns in the input."""
+        content = run_input.input_content_string()
+        detected_pii = []
+        for pii_type, pattern in self.pii_patterns.items():
+            if pattern.search(content):
+                detected_pii.append(pii_type)
+        if detected_pii:
+            if self.mask_pii:
+                for pii_type in detected_pii:
+
+                    def mask_match(match):
+                        return "*" * len(match.group(0))
+
+                    content = self.pii_patterns[pii_type].sub(mask_match, content)
+                run_input.input_content = content
+                return
+            else:
+                raise InputCheckError(
+                    "Potential PII detected in input",
+                    additional_data={"detected_pii": detected_pii},
+                    check_trigger=CheckTrigger.PII_DETECTED,
+                )

agno/guardrails/prompt_injection.py

@@ -0,0 +1,52 @@
+from typing import List, Optional, Union
+
+from agno.exceptions import CheckTrigger, InputCheckError
+from agno.guardrails.base import BaseGuardrail
+from agno.run.agent import RunInput
+from agno.run.team import TeamRunInput
+
+
+class PromptInjectionGuardrail(BaseGuardrail):
+    """Guardrail for detecting prompt injection attempts.
+
+    Args:
+        injection_patterns (Optional[List[str]]): A list of patterns to check for. Defaults to a list of common prompt injection patterns.
+    """
+
+    def __init__(self, injection_patterns: Optional[List[str]] = None):
+        self.injection_patterns = injection_patterns or [
+            "ignore previous instructions",
+            "ignore your instructions",
+            "you are now a",
+            "forget everything above",
+            "developer mode",
+            "override safety",
+            "disregard guidelines",
+            "system prompt",
+            "jailbreak",
+            "act as if",
+            "pretend you are",
+            "roleplay as",
+            "simulate being",
+            "bypass restrictions",
+            "ignore safeguards",
+            "admin override",
+            "root access",
+            "forget everything",
+        ]
+
+    def check(self, run_input: Union[RunInput, TeamRunInput]) -> None:
+        """Check for prompt injection patterns in the input."""
+        if any(keyword in run_input.input_content_string().lower() for keyword in self.injection_patterns):
+            raise InputCheckError(
+                "Potential jailbreaking or prompt injection detected.",
+                check_trigger=CheckTrigger.PROMPT_INJECTION,
+            )
+
+    async def async_check(self, run_input: Union[RunInput, TeamRunInput]) -> None:
+        """Asynchronously check for prompt injection patterns in the input."""
+        if any(keyword in run_input.input_content_string().lower() for keyword in self.injection_patterns):
+            raise InputCheckError(
+                "Potential jailbreaking or prompt injection detected.",
+                check_trigger=CheckTrigger.PROMPT_INJECTION,
+            )

agno/hooks/__init__.py

@@ -0,0 +1,3 @@
+from agno.hooks.decorator import hook, should_run_in_background
+
+__all__ = ["hook", "should_run_in_background"]