agno 2.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/prompt_injection.py

@@ -32,6 +32,7 @@ class PromptInjectionGuardrail(BaseGuardrail):
             "ignore safeguards",
             "admin override",
             "root access",
+            "forget everything",
         ]
 
     def check(self, run_input: Union[RunInput, TeamRunInput]) -> None:

agno/hooks/__init__.py

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

agno/hooks/decorator.py

@@ -0,0 +1,164 @@
+from functools import wraps
+from typing import Any, Callable, TypeVar, Union, overload
+
+# Type variable for better type hints
+F = TypeVar("F", bound=Callable[..., Any])
+
+# Attribute name used to mark hooks for background execution
+HOOK_RUN_IN_BACKGROUND_ATTR = "_agno_run_in_background"
+
+
+def _is_async_function(func: Callable) -> bool:
+    """
+    Check if a function is async, even when wrapped by decorators like @staticmethod.
+    Traverses the full wrapper chain to find the original function.
+    """
+    from inspect import iscoroutinefunction, unwrap
+
+    # First, try the standard inspect function on the wrapper
+    if iscoroutinefunction(func):
+        return True
+
+    # Use unwrap to traverse the full __wrapped__ chain to the original function
+    try:
+        original_func = unwrap(func)
+        if original_func is not func and iscoroutinefunction(original_func):
+            return True
+    except ValueError:
+        # unwrap raises ValueError if it hits a cycle
+        pass
+
+    # Check if the function has CO_COROUTINE flag in its code object
+    try:
+        if hasattr(func, "__code__") and func.__code__.co_flags & 0x80:  # CO_COROUTINE flag
+            return True
+    except (AttributeError, TypeError):
+        pass
+
+    return False
+
+
+@overload
+def hook() -> Callable[[F], F]: ...
+
+
+@overload
+def hook(
+    *,
+    run_in_background: bool = False,
+) -> Callable[[F], F]: ...
+
+
+@overload
+def hook(func: F) -> F: ...
+
+
+def hook(*args, **kwargs) -> Union[F, Callable[[F], F]]:
+    """Decorator to configure hook behavior.
+
+    Args:
+        run_in_background: If True, this hook will be scheduled as a FastAPI background task
+                          when background_tasks is available, regardless of the agent/team's
+                          run_hooks_in_background setting. This allows per-hook control over
+                          background execution.  This is only use-able when running with AgentOS.
+
+    Returns:
+        Union[F, Callable[[F], F]]: Decorated function or decorator
+
+    Examples:
+        @hook
+        def my_hook(run_output, agent):
+            # This runs normally (blocking)
+            process_output(run_output.content)
+
+        @hook()
+        def another_hook(run_output, agent):
+            # Same as above - runs normally
+            process_output(run_output.content)
+
+        @hook(run_in_background=True)
+        def my_background_hook(run_output, agent):
+            # This will run in the background when background_tasks is available
+            send_notification(run_output.content)
+
+        @hook(run_in_background=True)
+        async def my_async_background_hook(run_output, agent):
+            # Async hooks also supported
+            await send_async_notification(run_output.content)
+
+        agent = Agent(
+            model=OpenAIChat(id="gpt-4o"),
+            post_hooks=[my_hook, my_background_hook],
+        )
+    """
+    # Valid kwargs for the hook decorator
+    VALID_KWARGS = frozenset({"run_in_background"})
+
+    # Validate kwargs
+    invalid_kwargs = set(kwargs.keys()) - VALID_KWARGS
+    if invalid_kwargs:
+        raise ValueError(
+            f"Invalid hook configuration arguments: {invalid_kwargs}. Valid arguments are: {sorted(VALID_KWARGS)}"
+        )
+
+    def decorator(func: F) -> F:
+        run_in_background = kwargs.get("run_in_background", False)
+
+        # Preserve existing hook attributes from previously applied decorators
+        # Use OR logic: if any decorator sets run_in_background=True, it stays True
+        existing_run_in_background = should_run_in_background(func)
+        final_run_in_background = run_in_background or existing_run_in_background
+
+        @wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            return func(*args, **kwargs)
+
+        @wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            return await func(*args, **kwargs)
+
+        # Choose appropriate wrapper based on function type
+        if _is_async_function(func):
+            wrapper = async_wrapper
+        else:
+            wrapper = sync_wrapper
+
+        # Set the background execution attribute (combined from all decorators)
+        setattr(wrapper, HOOK_RUN_IN_BACKGROUND_ATTR, final_run_in_background)
+
+        return wrapper  # type: ignore
+
+    # Handle both @hook and @hook() cases
+    if len(args) == 1 and callable(args[0]) and not kwargs:
+        return decorator(args[0])
+
+    return decorator
+
+
+def should_run_in_background(hook_func: Callable) -> bool:
+    """
+    Check if a hook function is marked to run in background.
+    Traverses the wrapper chain to find the attribute when multiple decorators are stacked.
+
+    Args:
+        hook_func: The hook function to check
+
+    Returns:
+        True if the hook is decorated with @hook(run_in_background=True)
+    """
+    # Check the function directly first
+    if hasattr(hook_func, HOOK_RUN_IN_BACKGROUND_ATTR):
+        return getattr(hook_func, HOOK_RUN_IN_BACKGROUND_ATTR)
+
+    # Traverse the wrapper chain to find the attribute
+    current = hook_func
+    seen: set[int] = set()
+    while hasattr(current, "__wrapped__"):
+        if id(current) in seen:
+            break
+        seen.add(id(current))
+        current = current.__wrapped__
+        if hasattr(current, HOOK_RUN_IN_BACKGROUND_ATTR):
+            return getattr(current, HOOK_RUN_IN_BACKGROUND_ATTR)
+
+    return False

agno/integrations/discord/client.py

@@ -14,7 +14,7 @@ try:
     import discord
 
 except (ImportError, ModuleNotFoundError):
-    print("`discord.py` not installed. Please install using `pip install discord.py`")
+    raise ImportError("`discord.py` not installed. Please install using `pip install discord.py`")
 
 
 class RequiresConfirmationView(discord.ui.View):

agno/knowledge/chunking/agentic.py

@@ -1,28 +1,31 @@
-from typing import List, Optional
+from typing import List, Optional, Union
 
 from agno.knowledge.chunking.strategy import ChunkingStrategy
 from agno.knowledge.document.base import Document
 from agno.models.base import Model
 from agno.models.defaults import DEFAULT_OPENAI_MODEL_ID
 from agno.models.message import Message
+from agno.models.utils import get_model
 
 
 class AgenticChunking(ChunkingStrategy):
     """Chunking strategy that uses an LLM to determine natural breakpoints in the text"""
 
-    def __init__(self, model: Optional[Model] = None, max_chunk_size: int = 5000):
+    def __init__(self, model: Optional[Union[Model, str]] = None, max_chunk_size: int = 5000):
+        # Convert model string to Model instance
+        model = get_model(model)
         if model is None:
             try:
                 from agno.models.openai import OpenAIChat
             except Exception:
                 raise ValueError("`openai` isn't installed. Please install it with `pip install openai`")
             model = OpenAIChat(DEFAULT_OPENAI_MODEL_ID)
-        self.max_chunk_size = max_chunk_size
+        self.chunk_size = max_chunk_size
         self.model = model
 
     def chunk(self, document: Document) -> List[Document]:
         """Split text into chunks using LLM to determine natural breakpoints based on context"""
-        if len(document.content) <= self.max_chunk_size:
+        if len(document.content) <= self.chunk_size:
             return [document]
 
         chunks: List[Document] = []
@@ -31,22 +34,22 @@ class AgenticChunking(ChunkingStrategy):
         chunk_number = 1
 
         while remaining_text:
-            # Ask model to find a good breakpoint within max_chunk_size
-            prompt = f"""Analyze this text and determine a natural breakpoint within the first {self.max_chunk_size} characters.
+            # Ask model to find a good breakpoint within chunk_size
+            prompt = f"""Analyze this text and determine a natural breakpoint within the first {self.chunk_size} characters.
             Consider semantic completeness, paragraph boundaries, and topic transitions.
             Return only the character position number of where to break the text:
 
-            {remaining_text[: self.max_chunk_size]}"""
+            {remaining_text[: self.chunk_size]}"""
 
             try:
                 response = self.model.response([Message(role="user", content=prompt)])
                 if response and response.content:
-                    break_point = min(int(response.content.strip()), self.max_chunk_size)
+                    break_point = min(int(response.content.strip()), self.chunk_size)
                 else:
-                    break_point = self.max_chunk_size
+                    break_point = self.chunk_size
             except Exception:
                 # Fallback to max size if model fails
-                break_point = self.max_chunk_size
+                break_point = self.chunk_size
 
             # Extract chunk and update remaining text
             chunk = remaining_text[:break_point].strip()

agno/knowledge/chunking/fixed.py

@@ -53,5 +53,8 @@ class FixedSizeChunking(ChunkingStrategy):
                 )
             )
             chunk_number += 1
-            start = end - self.overlap
+            # Ensure start always advances by at least 1 to prevent infinite loops
+            # when overlap is large relative to chunk_size
+            new_start = max(start + 1, end - self.overlap)
+            start = new_start
         return chunked_documents

agno/knowledge/chunking/semantic.py

@@ -4,14 +4,19 @@ from typing import Any, Dict, List, Optional
 from agno.knowledge.chunking.strategy import ChunkingStrategy
 from agno.knowledge.document.base import Document
 from agno.knowledge.embedder.base import Embedder
-from agno.knowledge.embedder.openai import OpenAIEmbedder
+from agno.utils.log import log_info
 
 
 class SemanticChunking(ChunkingStrategy):
     """Chunking strategy that splits text into semantic chunks using chonkie"""
 
     def __init__(self, embedder: Optional[Embedder] = None, chunk_size: int = 5000, similarity_threshold: float = 0.5):
-        self.embedder = embedder or OpenAIEmbedder(id="text-embedding-3-small")  # type: ignore
+        if embedder is None:
+            from agno.knowledge.embedder.openai import OpenAIEmbedder
+
+            embedder = OpenAIEmbedder()  # type: ignore
+            log_info("Embedder not provided, using OpenAIEmbedder as default.")
+        self.embedder = embedder
         self.chunk_size = chunk_size
         self.similarity_threshold = similarity_threshold
         self.chunker = None  # Will be initialized lazily when needed
@@ -50,10 +55,10 @@ class SemanticChunking(ChunkingStrategy):
                     # Fallback to model id
                     params["embedding_model"] = getattr(self.embedder, "id", None) or "text-embedding-3-small"
 
-                self.chunker = SemanticChunker(**params)
+                self.chunker = SemanticChunker(**params)  # type: ignore
             except Exception:
                 # As a final fallback, use the original behavior
-                self.chunker = SemanticChunker(
+                self.chunker = SemanticChunker(  # type: ignore
                     embedding_model=getattr(self.embedder, "id", None) or "text-embedding-3-small",
                     chunk_size=self.chunk_size,
                     threshold=self.similarity_threshold,