agno 2.2.11__py3-none-any.whl → 2.2.12__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/knowledge/knowledge.py

@@ -13,6 +13,7 @@ from httpx import AsyncClient
 
 from agno.db.base import AsyncBaseDb, BaseDb
 from agno.db.schemas.knowledge import KnowledgeRow
+from agno.filters import FilterExpr
 from agno.knowledge.content import Content, ContentAuth, ContentStatus, FileData
 from agno.knowledge.document import Document
 from agno.knowledge.reader import Reader, ReaderFactory
@@ -403,7 +404,7 @@ class Knowledge:
 
         if path.is_file():
             if self._should_include_file(str(path), include, exclude):
-                log_info(f"Adding file {path} due to include/exclude filters")
+                log_debug(f"Adding file {path} due to include/exclude filters")
 
                 await self._add_to_contents_db(content)
                 if self._should_skip(content.content_hash, skip_if_exists):  # type: ignore[arg-type]
@@ -1392,7 +1393,7 @@ class Knowledge:
         self,
         query: str,
         max_results: Optional[int] = None,
-        filters: Optional[Dict[str, Any]] = None,
+        filters: Optional[Union[Dict[str, Any], List[FilterExpr]]] = None,
         search_type: Optional[str] = None,
     ) -> List[Document]:
         """Returns relevant documents matching a query"""
@@ -1423,7 +1424,7 @@ class Knowledge:
         self,
         query: str,
         max_results: Optional[int] = None,
-        filters: Optional[Dict[str, Any]] = None,
+        filters: Optional[Union[Dict[str, Any], List[FilterExpr]]] = None,
         search_type: Optional[str] = None,
     ) -> List[Document]:
         """Returns relevant documents matching a query"""
@@ -1465,38 +1466,58 @@ class Knowledge:
         self.valid_metadata_filters.update(await self._aget_filters_from_db())
         return self.valid_metadata_filters
 
-    def _validate_filters(self, filters: Optional[Dict[str, Any]]) -> Tuple[Dict[str, Any], List[str]]:
+    def _validate_filters(self, filters: Optional[Union[Dict[str, Any], List[FilterExpr]]]) -> Tuple[Any, List[str]]:
+        """Internal method to validate filters against known metadata keys."""
         if not filters:
-            return {}, []
+            return None, []
 
-        valid_filters: Dict[str, Any] = {}
+        valid_filters: Optional[Dict[str, Any]] = None
         invalid_keys = []
 
-        # If no metadata filters tracked yet, all keys are considered invalid
-        if self.valid_metadata_filters is None:
-            invalid_keys = list(filters.keys())
-            log_debug(f"No valid metadata filters tracked yet. All filter keys considered invalid: {invalid_keys}")
-            return {}, invalid_keys
-
-        for key, value in filters.items():
-            # Handle both normal keys and prefixed keys like meta_data.key
-            base_key = key.split(".")[-1] if "." in key else key
-            if base_key in self.valid_metadata_filters or key in self.valid_metadata_filters:
-                valid_filters[key] = value
-            else:
-                invalid_keys.append(key)
-                log_debug(f"Invalid filter key: {key} - not present in knowledge base")
+        if isinstance(filters, dict):
+            # If no metadata filters tracked yet, all keys are considered invalid
+            if self.valid_metadata_filters is None:
+                invalid_keys = list(filters.keys())
+                log_debug(f"No valid metadata filters tracked yet. All filter keys considered invalid: {invalid_keys}")
+                return None, invalid_keys
+
+            valid_filters = {}
+            for key, value in filters.items():
+                # Handle both normal keys and prefixed keys like meta_data.key
+                base_key = key.split(".")[-1] if "." in key else key
+                if base_key in self.valid_metadata_filters or key in self.valid_metadata_filters:
+                    valid_filters[key] = value
+                else:
+                    invalid_keys.append(key)
+                    log_debug(f"Invalid filter key: {key} - not present in knowledge base")
+
+        elif isinstance(filters, List):
+            # Validate that list contains FilterExpr instances
+            for i, filter_item in enumerate(filters):
+                if not isinstance(filter_item, FilterExpr):
+                    log_warning(
+                        f"Invalid filter at index {i}: expected FilterExpr instance, "
+                        f"got {type(filter_item).__name__}. "
+                        f"Use filter expressions like EQ('key', 'value'), IN('key', [values]), "
+                        f"AND(...), OR(...), NOT(...) from agno.filters"
+                    )
+
+            # Filter expressions are already validated, return empty dict/list
+            # The actual filtering happens in the vector_db layer
+            return filters, []
 
         return valid_filters, invalid_keys
 
-    def validate_filters(self, filters: Optional[Dict[str, Any]]) -> Tuple[Dict[str, Any], List[str]]:
+    def validate_filters(self, filters: Optional[Union[Dict[str, Any], List[FilterExpr]]]) -> Tuple[Any, List[str]]:
         if self.valid_metadata_filters is None:
             self.valid_metadata_filters = set()
         self.valid_metadata_filters.update(self._get_filters_from_db())
 
         return self._validate_filters(filters)
 
-    async def async_validate_filters(self, filters: Optional[Dict[str, Any]]) -> Tuple[Dict[str, Any], List[str]]:
+    async def async_validate_filters(
+        self, filters: Optional[Union[Dict[str, Any], List[FilterExpr]]]
+    ) -> Tuple[Any, List[str]]:
         if self.valid_metadata_filters is None:
             self.valid_metadata_filters = set()
         self.valid_metadata_filters.update(await self._aget_filters_from_db())

agno/os/interfaces/slack/router.py

@@ -1,4 +1,4 @@
-from typing import Optional
+from typing import Optional, Union
 
 from fastapi import APIRouter, BackgroundTasks, HTTPException, Request
 from pydantic import BaseModel, Field
@@ -24,7 +24,11 @@ class SlackChallengeResponse(BaseModel):
 
 
 def attach_routes(
-    router: APIRouter, agent: Optional[Agent] = None, team: Optional[Team] = None, workflow: Optional[Workflow] = None
+    router: APIRouter,
+    agent: Optional[Agent] = None,
+    team: Optional[Team] = None,
+    workflow: Optional[Workflow] = None,
+    reply_to_mentions_only: bool = True,
 ) -> APIRouter:
     # Determine entity type for documentation
     entity_type = "agent" if agent else "team" if team else "workflow" if workflow else "unknown"
@@ -34,7 +38,7 @@ def attach_routes(
         operation_id=f"slack_events_{entity_type}",
         name="slack_events",
         description="Process incoming Slack events",
-        response_model=SlackEventResponse,
+        response_model=Union[SlackChallengeResponse, SlackEventResponse],
         response_model_exclude_none=True,
         responses={
             200: {"description": "Event processed successfully"},
@@ -71,36 +75,52 @@ def attach_routes(
         return SlackEventResponse(status="ok")
 
     async def _process_slack_event(event: dict):
-        if event.get("type") == "message":
-            user = None
-            message_text = event.get("text", "")
-            channel_id = event.get("channel", "")
-            user = event.get("user")
-            if event.get("thread_ts"):
-                ts = event.get("thread_ts", "")
-            else:
-                ts = event.get("ts", "")
-
-            # Use the timestamp as the session id, so that each thread is a separate session
-            session_id = ts
-
-            if agent:
-                response = await agent.arun(message_text, user_id=user if user else None, session_id=session_id)
-            elif team:
-                response = await team.arun(message_text, user_id=user if user else None, session_id=session_id)  # type: ignore
-            elif workflow:
-                response = await workflow.arun(message_text, user_id=user if user else None, session_id=session_id)  # type: ignore
-
-            if response:
-                if hasattr(response, "reasoning_content") and response.reasoning_content:
-                    _send_slack_message(
-                        channel=channel_id,
-                        message=f"Reasoning: \n{response.reasoning_content}",
-                        thread_ts=ts,
-                        italics=True,
-                    )
-
-                _send_slack_message(channel=channel_id, message=response.content or "", thread_ts=ts)
+        event_type = event.get("type")
+
+        # Only handle app_mention and message events
+        if event_type not in ("app_mention", "message"):
+            return
+
+        channel_type = event.get("channel_type", "")
+
+        # Handle duplicate replies
+        if not reply_to_mentions_only and event_type == "app_mention":
+            return
+
+        # If reply_to_mentions_only is True, ignore every message that is not a DM
+        if reply_to_mentions_only and event_type == "message" and channel_type != "im":
+            return
+
+        # Extract event data
+        user = None
+        message_text = event.get("text", "")
+        channel_id = event.get("channel", "")
+        user = event.get("user")
+        if event.get("thread_ts"):
+            ts = event.get("thread_ts", "")
+        else:
+            ts = event.get("ts", "")
+
+        # Use the timestamp as the session id, so that each thread is a separate session
+        session_id = ts
+
+        if agent:
+            response = await agent.arun(message_text, user_id=user, session_id=session_id)
+        elif team:
+            response = await team.arun(message_text, user_id=user, session_id=session_id)  # type: ignore
+        elif workflow:
+            response = await workflow.arun(message_text, user_id=user, session_id=session_id)  # type: ignore
+
+        if response:
+            if hasattr(response, "reasoning_content") and response.reasoning_content:
+                _send_slack_message(
+                    channel=channel_id,
+                    message=f"Reasoning: \n{response.reasoning_content}",
+                    thread_ts=ts,
+                    italics=True,
+                )
+
+            _send_slack_message(channel=channel_id, message=response.content or "", thread_ts=ts)
 
     def _send_slack_message(channel: str, thread_ts: str, message: str, italics: bool = False):
         if len(message) <= 40000:

agno/os/interfaces/slack/slack.py

@@ -21,12 +21,14 @@ class Slack(BaseInterface):
         workflow: Optional[Workflow] = None,
         prefix: str = "/slack",
         tags: Optional[List[str]] = None,
+        reply_to_mentions_only: bool = True,
     ):
         self.agent = agent
         self.team = team
         self.workflow = workflow
         self.prefix = prefix
         self.tags = tags or ["Slack"]
+        self.reply_to_mentions_only = reply_to_mentions_only
 
         if not (self.agent or self.team or self.workflow):
             raise ValueError("Slack requires an agent, team or workflow")
@@ -34,6 +36,12 @@ class Slack(BaseInterface):
     def get_router(self) -> APIRouter:
         self.router = APIRouter(prefix=self.prefix, tags=self.tags)  # type: ignore
 
-        self.router = attach_routes(router=self.router, agent=self.agent, team=self.team, workflow=self.workflow)
+        self.router = attach_routes(
+            router=self.router,
+            agent=self.agent,
+            team=self.team,
+            workflow=self.workflow,
+            reply_to_mentions_only=self.reply_to_mentions_only,
+        )
 
         return self.router

agno/os/router.py

@@ -106,10 +106,34 @@ async def _get_request_kwargs(request: Request, endpoint_func: Callable) -> Dict
         try:
             if isinstance(knowledge_filters, str):
                 knowledge_filters_dict = json.loads(knowledge_filters)  # type: ignore
-                kwargs["knowledge_filters"] = knowledge_filters_dict
+
+                # Try to deserialize FilterExpr objects
+                from agno.filters import from_dict
+
+                # Check if it's a single FilterExpr dict or a list of FilterExpr dicts
+                if isinstance(knowledge_filters_dict, dict) and "op" in knowledge_filters_dict:
+                    # Single FilterExpr - convert to list format
+                    kwargs["knowledge_filters"] = [from_dict(knowledge_filters_dict)]
+                elif isinstance(knowledge_filters_dict, list):
+                    # List of FilterExprs or mixed content
+                    deserialized = []
+                    for item in knowledge_filters_dict:
+                        if isinstance(item, dict) and "op" in item:
+                            deserialized.append(from_dict(item))
+                        else:
+                            # Keep non-FilterExpr items as-is
+                            deserialized.append(item)
+                    kwargs["knowledge_filters"] = deserialized
+                else:
+                    # Regular dict filter
+                    kwargs["knowledge_filters"] = knowledge_filters_dict
         except json.JSONDecodeError:
             kwargs.pop("knowledge_filters")
             log_warning(f"Invalid knowledge_filters parameter couldn't be loaded: {knowledge_filters}")
+        except ValueError as e:
+            # Filter deserialization failed
+            kwargs.pop("knowledge_filters")
+            log_warning(f"Invalid FilterExpr in knowledge_filters: {e}")
 
     # Parse boolean and null values
     for key, value in kwargs.items():

agno/run/base.py

@@ -1,9 +1,10 @@
 from dataclasses import asdict, dataclass
 from enum import Enum
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional, Union
 
 from pydantic import BaseModel
 
+from agno.filters import FilterExpr
 from agno.media import Audio, Image, Video
 from agno.models.message import Citations, Message, MessageReferences
 from agno.models.metrics import Metrics
@@ -18,7 +19,7 @@ class RunContext:
     user_id: Optional[str] = None
 
     dependencies: Optional[Dict[str, Any]] = None
-    knowledge_filters: Optional[Dict[str, Any]] = None
+    knowledge_filters: Optional[Union[Dict[str, Any], List[FilterExpr]]] = None
     metadata: Optional[Dict[str, Any]] = None
     session_state: Optional[Dict[str, Any]] = None