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

agno/utils/hooks.py

@@ -0,0 +1,171 @@
+from copy import deepcopy
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Union
+
+if TYPE_CHECKING:
+    from agno.eval.base import BaseEval
+
+from agno.guardrails.base import BaseGuardrail
+from agno.hooks.decorator import HOOK_RUN_IN_BACKGROUND_ATTR
+from agno.utils.log import log_warning
+
+# Keys that should be deep copied for background hooks to prevent race conditions
+BACKGROUND_HOOK_COPY_KEYS = frozenset(
+    {"run_input", "run_context", "run_output", "session_state", "dependencies", "metadata"}
+)
+
+
+def copy_args_for_background(args: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Create a copy of hook arguments for background execution.
+
+    This deep copies run_input, run_context, run_output, session_state, dependencies,
+    and metadata to prevent race conditions when hooks run in the background.
+
+    Args:
+        args: The original arguments dictionary
+
+    Returns:
+        A new dictionary with copied values for sensitive keys
+    """
+    copied_args = {}
+    for key, value in args.items():
+        if key in BACKGROUND_HOOK_COPY_KEYS and value is not None:
+            try:
+                copied_args[key] = deepcopy(value)
+            except Exception:
+                # If deepcopy fails (e.g., for non-copyable objects), use the original
+                log_warning(f"Could not deepcopy {key} for background hook, using original reference")
+                copied_args[key] = value
+        else:
+            copied_args[key] = value
+    return copied_args
+
+
+def should_run_hook_in_background(hook: Callable[..., Any]) -> bool:
+    """
+    Check if a hook function should run in background.
+
+    This checks for the _agno_run_in_background attribute set by the @hook decorator.
+
+    Args:
+        hook: The hook function to check
+
+    Returns:
+        True if the hook is decorated with @hook(run_in_background=True)
+    """
+    return getattr(hook, HOOK_RUN_IN_BACKGROUND_ATTR, False)
+
+
+def normalize_pre_hooks(
+    hooks: Optional[List[Union[Callable[..., Any], BaseGuardrail, "BaseEval"]]],
+    async_mode: bool = False,
+) -> Optional[List[Callable[..., Any]]]:
+    """Normalize pre-hooks to a list format.
+
+    Args:
+        hooks: List of hook functions, guardrails, or eval instances
+        async_mode: Whether to use async versions of methods
+    """
+    from agno.eval.base import BaseEval
+
+    result_hooks: List[Callable[..., Any]] = []
+
+    if hooks is not None:
+        for hook in hooks:
+            if isinstance(hook, BaseGuardrail):
+                if async_mode:
+                    result_hooks.append(hook.async_check)
+                else:
+                    result_hooks.append(hook.check)
+            elif isinstance(hook, BaseEval):
+                # Extract pre_check method
+                method = hook.async_pre_check if async_mode else hook.pre_check
+
+                from functools import partial
+
+                wrapped = partial(method)
+                wrapped.__name__ = method.__name__  # type: ignore
+                setattr(wrapped, HOOK_RUN_IN_BACKGROUND_ATTR, getattr(hook, "run_in_background", False))
+                result_hooks.append(wrapped)
+            else:
+                # Check if the hook is async and used within sync methods
+                if not async_mode:
+                    import asyncio
+
+                    if asyncio.iscoroutinefunction(hook):
+                        raise ValueError(
+                            f"Cannot use {hook.__name__} (an async hook) with `run()`. Use `arun()` instead."
+                        )
+
+                result_hooks.append(hook)
+    return result_hooks if result_hooks else None
+
+
+def normalize_post_hooks(
+    hooks: Optional[List[Union[Callable[..., Any], BaseGuardrail, "BaseEval"]]],
+    async_mode: bool = False,
+) -> Optional[List[Callable[..., Any]]]:
+    """Normalize post-hooks to a list format.
+
+    Args:
+        hooks: List of hook functions, guardrails, or eval instances
+        async_mode: Whether to use async versions of methods
+    """
+    from agno.eval.base import BaseEval
+
+    result_hooks: List[Callable[..., Any]] = []
+
+    if hooks is not None:
+        for hook in hooks:
+            if isinstance(hook, BaseGuardrail):
+                if async_mode:
+                    result_hooks.append(hook.async_check)
+                else:
+                    result_hooks.append(hook.check)
+            elif isinstance(hook, BaseEval):
+                # Extract post_check method
+                method = hook.async_post_check if async_mode else hook.post_check  # type: ignore[assignment]
+
+                from functools import partial
+
+                wrapped = partial(method)
+                wrapped.__name__ = method.__name__  # type: ignore
+                setattr(wrapped, HOOK_RUN_IN_BACKGROUND_ATTR, getattr(hook, "run_in_background", False))
+                result_hooks.append(wrapped)
+            else:
+                # Check if the hook is async and used within sync methods
+                if not async_mode:
+                    import asyncio
+
+                    if asyncio.iscoroutinefunction(hook):
+                        raise ValueError(
+                            f"Cannot use {hook.__name__} (an async hook) with `run()`. Use `arun()` instead."
+                        )
+
+                result_hooks.append(hook)
+    return result_hooks if result_hooks else None
+
+
+def filter_hook_args(hook: Callable[..., Any], all_args: Dict[str, Any]) -> Dict[str, Any]:
+    """Filter arguments to only include those that the hook function accepts."""
+    import inspect
+
+    try:
+        sig = inspect.signature(hook)
+        accepted_params = set(sig.parameters.keys())
+
+        has_var_keyword = any(param.kind == inspect.Parameter.VAR_KEYWORD for param in sig.parameters.values())
+
+        # If the function has **kwargs, pass all arguments
+        if has_var_keyword:
+            return all_args
+
+        # Otherwise, filter to only include accepted parameters
+        filtered_args = {key: value for key, value in all_args.items() if key in accepted_params}
+
+        return filtered_args
+
+    except Exception as e:
+        log_warning(f"Could not inspect hook signature, passing all arguments: {e}")
+        # If signature inspection fails, pass all arguments as fallback
+        return all_args

agno/utils/http.py

@@ -0,0 +1,185 @@
+import asyncio
+import logging
+from time import sleep
+from typing import Optional
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_BACKOFF_FACTOR = 2  # Exponential backoff: 1, 2, 4, 8...
+
+# Global httpx clients for resource efficiency
+# These are shared across all models to reuse connection pools and avoid resource leaks.
+# Consumers can override these at application startup using set_default_sync_client()
+# and set_default_async_client() to customize limits, timeouts, proxies, etc.
+_global_sync_client: Optional[httpx.Client] = None
+_global_async_client: Optional[httpx.AsyncClient] = None
+
+
+def get_default_sync_client() -> httpx.Client:
+    """Get or create the global synchronous httpx client.
+
+    Returns:
+        A singleton httpx.Client instance with default limits.
+    """
+    global _global_sync_client
+    if _global_sync_client is None or _global_sync_client.is_closed:
+        _global_sync_client = httpx.Client(
+            limits=httpx.Limits(max_connections=1000, max_keepalive_connections=200), http2=True, follow_redirects=True
+        )
+    return _global_sync_client
+
+
+def get_default_async_client() -> httpx.AsyncClient:
+    """Get or create the global asynchronous httpx client.
+
+    Returns:
+        A singleton httpx.AsyncClient instance with default limits.
+    """
+    global _global_async_client
+    if _global_async_client is None or _global_async_client.is_closed:
+        _global_async_client = httpx.AsyncClient(
+            limits=httpx.Limits(max_connections=1000, max_keepalive_connections=200), http2=True, follow_redirects=True
+        )
+    return _global_async_client
+
+
+def close_sync_client() -> None:
+    """Closes the global sync httpx client.
+
+    Should be called during application shutdown.
+    """
+    global _global_sync_client
+    if _global_sync_client is not None and not _global_sync_client.is_closed:
+        _global_sync_client.close()
+
+
+async def aclose_default_clients() -> None:
+    """Asynchronously close the global httpx clients.
+
+    Should be called during application shutdown in async contexts.
+    """
+    global _global_sync_client, _global_async_client
+    if _global_sync_client is not None and not _global_sync_client.is_closed:
+        _global_sync_client.close()
+    if _global_async_client is not None and not _global_async_client.is_closed:
+        await _global_async_client.aclose()
+
+
+def set_default_sync_client(client: httpx.Client) -> None:
+    """Set the global synchronous httpx client.
+
+    IMPORTANT: Call before creating any model instances. Models cache clients on first use.
+
+    Allows consumers to override the default httpx client with custom configuration
+    (e.g., custom limits, timeouts, proxies, SSL verification, etc.).
+    This is useful at application startup to customize how all models connect.
+
+    Example:
+        >>> import httpx
+        >>> from agno.utils.http import set_default_sync_client
+        >>> custom_client = httpx.Client(
+        ...     limits=httpx.Limits(max_connections=500),
+        ...     timeout=httpx.Timeout(30.0),
+        ...     verify=False  # for dev environments
+        ... )
+        >>> set_default_sync_client(custom_client)
+        >>> # All models will now use this custom client
+
+    Args:
+        client: An httpx.Client instance to use as the global sync client.
+    """
+    global _global_sync_client
+    _global_sync_client = client
+
+
+def set_default_async_client(client: httpx.AsyncClient) -> None:
+    """Set the global asynchronous httpx client.
+
+    IMPORTANT: Call before creating any model instances. Models cache clients on first use.
+
+    Allows consumers to override the default async httpx client with custom configuration
+    (e.g., custom limits, timeouts, proxies, SSL verification, etc.).
+    This is useful at application startup to customize how all models connect.
+
+    Example:
+        >>> import httpx
+        >>> from agno.utils.http import set_default_async_client
+        >>> custom_client = httpx.AsyncClient(
+        ...     limits=httpx.Limits(max_connections=500),
+        ...     timeout=httpx.Timeout(30.0),
+        ...     verify=False  # for dev environments
+        ... )
+        >>> set_default_async_client(custom_client)
+        >>> # All models will now use this custom client
+
+    Args:
+        client: An httpx.AsyncClient instance to use as the global async client.
+    """
+    global _global_async_client
+    _global_async_client = client
+
+
+def fetch_with_retry(
+    url: str,
+    max_retries: int = DEFAULT_MAX_RETRIES,
+    backoff_factor: int = DEFAULT_BACKOFF_FACTOR,
+    proxy: Optional[str] = None,
+) -> httpx.Response:
+    """Synchronous HTTP GET with retry logic."""
+
+    for attempt in range(max_retries):
+        try:
+            response = httpx.get(url, proxy=proxy) if proxy else httpx.get(url)
+            response.raise_for_status()
+            return response
+        except httpx.RequestError as e:
+            if attempt == max_retries - 1:
+                logger.error(f"Failed to fetch {url} after {max_retries} attempts: {e}")
+                raise
+            wait_time = backoff_factor**attempt
+            logger.warning("Connection error.")
+            sleep(wait_time)
+        except httpx.HTTPStatusError as e:
+            logger.error(f"HTTP error for {url}: {e.response.status_code} - {e.response.text}")
+            raise
+
+    raise httpx.RequestError(f"Failed to fetch {url} after {max_retries} attempts")
+
+
+async def async_fetch_with_retry(
+    url: str,
+    client: Optional[httpx.AsyncClient] = None,
+    max_retries: int = DEFAULT_MAX_RETRIES,
+    backoff_factor: int = DEFAULT_BACKOFF_FACTOR,
+    proxy: Optional[str] = None,
+) -> httpx.Response:
+    """Asynchronous HTTP GET with retry logic."""
+
+    async def _fetch():
+        if client is None:
+            client_args = {"proxy": proxy} if proxy else {}
+            async with httpx.AsyncClient(**client_args) as local_client:  # type: ignore
+                return await local_client.get(url)
+        else:
+            return await client.get(url)
+
+    for attempt in range(max_retries):
+        try:
+            response = await _fetch()
+            response.raise_for_status()
+            return response
+        except httpx.RequestError as e:
+            if attempt == max_retries - 1:
+                logger.error(f"Failed to fetch {url} after {max_retries} attempts: {e}")
+                raise
+            wait_time = backoff_factor**attempt
+            logger.warning("Connection error.")
+            await asyncio.sleep(wait_time)
+        except httpx.HTTPStatusError as e:
+            logger.error(f"HTTP error for {url}: {e.response.status_code} - {e.response.text}")
+            raise
+
+    raise httpx.RequestError(f"Failed to fetch {url} after {max_retries} attempts")

agno/utils/json_schema.py

@@ -1,15 +1,29 @@
+from enum import Enum
 from typing import Any, Dict, Optional, Union, get_args, get_origin
 
+from pydantic import BaseModel
+
 from agno.utils.log import logger
 
 
+def is_origin_union_type(origin: Any) -> bool:
+    import sys
+
+    if sys.version_info.minor >= 10:
+        from types import UnionType  # type: ignore
+
+        return origin in [Union, UnionType]
+
+    return origin is Union
+
+
 def get_json_type_for_py_type(arg: str) -> str:
     """
     Get the JSON schema type for a given type.
     :param arg: The type to get the JSON schema type for.
     :return: The JSON schema type.
     """
-    # logger.info(f"Getting JSON type for: {arg}")
+    # log_info(f"Getting JSON type for: {arg}")
     if arg in ("int", "float", "complex", "Decimal"):
         return "number"
     elif arg in ("str", "string"):
@@ -27,13 +41,86 @@ def get_json_type_for_py_type(arg: str) -> str:
     return "object"
 
 
-def get_json_schema_for_arg(t: Any) -> Optional[Dict[str, Any]]:
-    # logger.info(f"Getting JSON schema for arg: {t}")
-    type_args = get_args(t)
-    # logger.info(f"Type args: {type_args}")
-    type_origin = get_origin(t)
-    # logger.info(f"Type origin: {type_origin}")
+def inline_pydantic_schema(schema: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Recursively inline Pydantic model schemas by replacing $ref with actual schema.
+    """
+    if not isinstance(schema, dict):
+        return schema
+
+    def resolve_ref(ref: str, defs: Dict[str, Any]) -> Dict[str, Any]:
+        """Resolve a $ref to its actual schema."""
+        if not ref.startswith("#/$defs/"):
+            return {"type": "object"}  # Fallback for external refs
+
+        def_name = ref.split("/")[-1]
+        if def_name in defs:
+            return defs[def_name]
+        return {"type": "object"}  # Fallback if definition not found
+
+    def process_schema(s: Dict[str, Any], defs: Dict[str, Any]) -> Dict[str, Any]:
+        """Process a schema dictionary, resolving all references."""
+        if not isinstance(s, dict):
+            return s
+
+        # Handle $ref
+        if "$ref" in s:
+            return resolve_ref(s["$ref"], defs)
+
+        # Create a new dict to avoid modifying the input
+        result = s.copy()
+
+        # Handle arrays
+        if "items" in result:
+            result["items"] = process_schema(result["items"], defs)
+
+        # Handle object properties
+        if "properties" in result:
+            for prop_name, prop_schema in result["properties"].items():
+                result["properties"][prop_name] = process_schema(prop_schema, defs)
+
+        # Handle anyOf (for Union types)
+        if "anyOf" in result:
+            result["anyOf"] = [process_schema(sub_schema, defs) for sub_schema in result["anyOf"]]
+
+        # Handle allOf (for inheritance)
+        if "allOf" in result:
+            result["allOf"] = [process_schema(sub_schema, defs) for sub_schema in result["allOf"]]
 
+        # Handle additionalProperties
+        if "additionalProperties" in result:
+            result["additionalProperties"] = process_schema(result["additionalProperties"], defs)
+
+        # Handle propertyNames
+        if "propertyNames" in result:
+            result["propertyNames"] = process_schema(result["propertyNames"], defs)
+
+        return result
+
+    # Store definitions for later use
+    definitions = schema.pop("$defs", {})
+
+    # First, resolve any nested references in definitions
+    resolved_definitions = {}
+    for def_name, def_schema in definitions.items():
+        resolved_definitions[def_name] = process_schema(def_schema, definitions)
+
+    # Process the main schema with resolved definitions
+    result = process_schema(schema, resolved_definitions)
+
+    # Remove any remaining definitions
+    if "$defs" in result:
+        del result["$defs"]
+
+    return result
+
+
+def get_json_schema_for_arg(type_hint: Any) -> Optional[Dict[str, Any]]:
+    # log_info(f"Getting JSON schema for arg: {t}")
+    type_args = get_args(type_hint)
+    # log_info(f"Type args: {type_args}")
+    type_origin = get_origin(type_hint)
+    # log_info(f"Type origin: {type_origin}")
     if type_origin is not None:
         if type_origin in (list, tuple, set, frozenset):
             json_schema_for_items = get_json_schema_for_arg(type_args[0]) if type_args else {"type": "string"}
@@ -43,19 +130,61 @@ def get_json_schema_for_arg(t: Any) -> Optional[Dict[str, Any]]:
             key_schema = get_json_schema_for_arg(type_args[0]) if type_args else {"type": "string"}
             value_schema = get_json_schema_for_arg(type_args[1]) if len(type_args) > 1 else {"type": "string"}
             return {"type": "object", "propertyNames": key_schema, "additionalProperties": value_schema}
-        elif type_origin is Union:
+        elif is_origin_union_type(type_origin):
             types = []
             for arg in type_args:
-                if arg is not type(None):
-                    try:
-                        schema = get_json_schema_for_arg(arg)
-                        if schema:
-                            types.append(schema)
-                    except Exception:
-                        continue
+                try:
+                    schema = get_json_schema_for_arg(arg)
+                    if schema:
+                        types.append(schema)
+                except Exception:
+                    continue
             return {"anyOf": types} if types else None
 
-    return {"type": get_json_type_for_py_type(t.__name__)}
+    if isinstance(type_hint, type) and issubclass(type_hint, Enum):
+        enum_values = [member.value for member in type_hint]
+        return {"type": "string", "enum": enum_values}
+
+    if isinstance(type_hint, type) and issubclass(type_hint, BaseModel):
+        # Get the schema and inline it
+        schema = type_hint.model_json_schema()
+        return inline_pydantic_schema(schema)  # type: ignore
+
+    if hasattr(type_hint, "__dataclass_fields__"):
+        # Convert dataclass to JSON schema
+        properties = {}
+        required = []
+
+        for field_name, field in type_hint.__dataclass_fields__.items():
+            field_type = field.type
+            field_schema = get_json_schema_for_arg(field_type)
+
+            if (
+                field_schema
+                and "anyOf" in field_schema
+                and any(schema["type"] == "null" for schema in field_schema["anyOf"])
+            ):
+                field_schema["type"] = next(
+                    schema["type"] for schema in field_schema["anyOf"] if schema["type"] != "null"
+                )
+                field_schema.pop("anyOf")
+            else:
+                required.append(field_name)
+
+            if field_schema:
+                properties[field_name] = field_schema
+
+        arg_json_schema = {"type": "object", "properties": properties, "additionalProperties": False}
+
+        if required:
+            arg_json_schema["required"] = required
+        return arg_json_schema
+
+    json_schema: Dict[str, Any] = {"type": get_json_type_for_py_type(type_hint.__name__)}
+    if json_schema["type"] == "object":
+        json_schema["properties"] = {}
+        json_schema["additionalProperties"] = False
+    return json_schema
 
 
 def get_json_schema(
@@ -68,45 +197,38 @@ def get_json_schema(
     if strict:
         json_schema["additionalProperties"] = False
 
-    for k, v in type_hints.items():
-        # logger.info(f"Parsing arg: {k} | {v}")
-        if k == "return":
+    # We only include the fields in the type_hints dict
+    for parameter_name, type_hint in type_hints.items():
+        # log_info(f"Parsing arg: {k} | {v}")
+        if parameter_name == "return":
             continue
 
         try:
             # Check if type is Optional (Union with NoneType)
-            type_origin = get_origin(v)
-            type_args = get_args(v)
+            type_origin = get_origin(type_hint)
+            type_args = get_args(type_hint)
             is_optional = type_origin is Union and len(type_args) == 2 and any(arg is type(None) for arg in type_args)
 
             # Get the actual type if it's Optional
             if is_optional:
-                v = next(arg for arg in type_args if arg is not type(None))
+                type_hint = next(arg for arg in type_args if arg is not type(None))
 
-            # Handle cases with no type hint
-            if v:
-                arg_json_schema = get_json_schema_for_arg(v)
+            if type_hint:
+                arg_json_schema = get_json_schema_for_arg(type_hint)
             else:
                 arg_json_schema = {}
 
             if arg_json_schema is not None:
-                if is_optional:
-                    # Handle null type for optional fields
-                    if isinstance(arg_json_schema["type"], list):
-                        arg_json_schema["type"].append("null")
-                    else:
-                        arg_json_schema["type"] = [arg_json_schema["type"], "null"]
-
                 # Add description
-                if param_descriptions and k in param_descriptions and param_descriptions[k]:
-                    arg_json_schema["description"] = param_descriptions[k]
+                if param_descriptions and parameter_name in param_descriptions and param_descriptions[parameter_name]:
+                    arg_json_schema["description"] = param_descriptions[parameter_name]
 
-                json_schema["properties"][k] = arg_json_schema
+                json_schema["properties"][parameter_name] = arg_json_schema
 
             else:
-                logger.warning(f"Could not parse argument {k} of type {v}")
+                logger.warning(f"Could not parse argument {parameter_name} of type {type_hint}")
         except Exception as e:
-            logger.error(f"Error processing argument {k}: {str(e)}")
+            logger.error(f"Error processing argument {parameter_name}: {str(e)}")
             continue
 
     return json_schema

agno/utils/knowledge.py

@@ -0,0 +1,36 @@
+from typing import Any, Dict, List, Optional, Union
+
+from agno.filters import FilterExpr
+from agno.utils.log import log_info
+
+
+def get_agentic_or_user_search_filters(
+    filters: Optional[Dict[str, Any]], effective_filters: Optional[Union[Dict[str, Any], List[FilterExpr]]]
+) -> Dict[str, Any]:
+    """Helper function to determine the final filters to use for the search.
+
+    Args:
+        filters: Filters passed by the agent.
+        effective_filters: Filters passed by user.
+
+    Returns:
+        Dict[str, Any]: The final filters to use for the search.
+    """
+    search_filters = None
+
+    # If agentic filters exist and manual filters (passed by user) do not, use agentic filters
+    if filters and not effective_filters:
+        search_filters = filters
+
+    # If both agentic filters exist and manual filters (passed by user) exist, use manual filters (give priority to user and override)
+    if filters and effective_filters:
+        if isinstance(effective_filters, dict):
+            search_filters = effective_filters
+        elif isinstance(effective_filters, list):
+            # If effective_filters is a list (likely List[FilterExpr]), convert both filters and effective_filters to a dict if possible, otherwise raise
+            raise ValueError(
+                "Merging dict and list of filters is not supported; effective_filters should be a dict for search compatibility."
+            )
+
+    log_info(f"Filters used by Agent: {search_filters}")
+    return search_filters or {}

agno/utils/location.py

@@ -0,0 +1,19 @@
+from typing import Any, Dict
+
+import requests
+
+from agno.utils.log import log_warning
+
+
+def get_location() -> Dict[str, Any]:
+    """Get approximate location using IP geolocation."""
+    try:
+        response = requests.get("https://api.ipify.org?format=json", timeout=5)
+        ip = response.json()["ip"]
+        response = requests.get(f"http://ip-api.com/json/{ip}", timeout=5)
+        if response.status_code == 200:
+            data = response.json()
+            return {"city": data.get("city"), "region": data.get("region"), "country": data.get("country")}
+    except Exception as e:
+        log_warning(f"Failed to get location: {e}")
+    return {}