agno 2.3.25__py3-none-any.whl → 2.4.0__py3-none-any.whl

agno/knowledge/utils.py

@@ -49,26 +49,28 @@ def _import_class(module_name: str, class_name: str):
 
 
 def get_reader_info(reader_key: str) -> Dict:
-    """Get information about a reader without instantiating it."""
-    # Try to create the reader to get its info, but don't cache it
+    """Get information about a reader without instantiating it.
+
+    Uses class methods and static metadata from ReaderFactory to avoid
+    the overhead of creating reader instances.
+    """
     try:
-        reader_factory_method = ReaderFactory._get_reader_method(reader_key)
+        # Get the reader CLASS without instantiation
+        reader_class = ReaderFactory.get_reader_class(reader_key)
 
-        # Create an instance to get the class, then call class methods
-        reader_instance = reader_factory_method()
-        reader_class = reader_instance.__class__
+        # Get metadata from static registry (no instantiation needed)
+        metadata = ReaderFactory.READER_METADATA.get(reader_key, {})
 
-        supported_strategies = reader_class.get_supported_chunking_strategies()
-        supported_content_types = reader_class.get_supported_content_types()
+        # Call class methods directly (no instance needed)
+        supported_strategies = reader_class.get_supported_chunking_strategies()  # type: ignore[attr-defined]
+        supported_content_types = reader_class.get_supported_content_types()  # type: ignore[attr-defined]
 
         return {
             "id": reader_key,
-            "name": "".join(word.capitalize() for word in reader_key.split("_")) + "Reader",
-            "description": reader_instance.description,
-            "chunking_strategies": [
-                strategy.value for strategy in supported_strategies
-            ],  # Convert enums to string values
-            "content_types": [ct.value for ct in supported_content_types],  # Convert enums to string values
+            "name": metadata.get("name", reader_class.__name__),
+            "description": metadata.get("description", f"{reader_class.__name__} reader"),
+            "chunking_strategies": [strategy.value for strategy in supported_strategies],
+            "content_types": [ct.value for ct in supported_content_types],
         }
     except ImportError as e:
         # Skip readers with missing dependencies
@@ -98,38 +100,44 @@ def get_reader_info_from_instance(reader: Reader, reader_id: str) -> Dict:
 def get_all_readers_info(knowledge_instance: Optional[Any] = None) -> List[Dict]:
     """Get information about all available readers, including custom readers from a Knowledge instance.
 
+    Custom readers are added first and take precedence over factory readers with the same ID.
+
     Args:
         knowledge_instance: Optional Knowledge instance to include custom readers from.
 
     Returns:
-        List of reader info dictionaries.
+        List of reader info dictionaries (custom readers first, then factory readers).
     """
     readers_info = []
-    keys = ReaderFactory.get_all_reader_keys()
-    for key in keys:
-        try:
-            reader_info = get_reader_info(key)
-            readers_info.append(reader_info)
-        except ValueError as e:
-            # Skip readers with missing dependencies or other issues
-            # Log the error but don't fail the entire request
-            log_debug(f"Skipping reader '{key}': {e}")
-            continue
+    seen_ids: set = set()
 
-    # Add custom readers from knowledge instance if provided
+    # 1. Add custom readers FIRST (they take precedence over factory readers)
     if knowledge_instance is not None:
         custom_readers = knowledge_instance.get_readers()
         if isinstance(custom_readers, dict):
             for reader_id, reader in custom_readers.items():
                 try:
                     reader_info = get_reader_info_from_instance(reader, reader_id)
-                    # Only add if not already present (custom readers take precedence)
-                    if not any(r["id"] == reader_id for r in readers_info):
-                        readers_info.append(reader_info)
+                    readers_info.append(reader_info)
+                    seen_ids.add(reader_id)
                 except ValueError as e:
                     log_debug(f"Skipping custom reader '{reader_id}': {e}")
                     continue
 
+    # 2. Add factory readers (skip if custom reader with same ID already exists)
+    keys = ReaderFactory.get_all_reader_keys()
+    for key in keys:
+        if key in seen_ids:
+            # Custom reader with this ID already added, skip factory version
+            continue
+        try:
+            reader_info = get_reader_info(key)
+            readers_info.append(reader_info)
+        except ValueError as e:
+            # Skip readers with missing dependencies or other issues
+            log_debug(f"Skipping reader '{key}': {e}")
+            continue
+
     return readers_info
 
 

agno/learn/__init__.py

@@ -11,6 +11,7 @@ Main Components:
 """
 
 from agno.learn.config import (
+    DecisionLogConfig,
     EntityMemoryConfig,
     LearnedKnowledgeConfig,
     LearningMode,
@@ -21,6 +22,7 @@ from agno.learn.config import (
 )
 from agno.learn.machine import LearningMachine
 from agno.learn.schemas import (
+    DecisionLog,
     EntityMemory,
     LearnedKnowledge,
     Memories,
@@ -28,6 +30,7 @@ from agno.learn.schemas import (
     UserProfile,
 )
 from agno.learn.stores import (
+    DecisionLogStore,
     EntityMemoryStore,
     LearnedKnowledgeStore,
     LearningStore,
@@ -48,12 +51,14 @@ __all__ = [
     "EntityMemoryConfig",
     "SessionContextConfig",
     "LearnedKnowledgeConfig",
+    "DecisionLogConfig",  # Phase 2
     # Schemas
     "UserProfile",
     "Memories",
     "EntityMemory",
     "SessionContext",
     "LearnedKnowledge",
+    "DecisionLog",  # Phase 2
     # Stores
     "LearningStore",
     "UserProfileStore",
@@ -62,4 +67,5 @@ __all__ = [
     "SessionContextStore",
     "LearnedKnowledgeStore",
     "EntityMemoryStore",
+    "DecisionLogStore",  # Phase 2
 ]

agno/learn/machine.py

@@ -17,6 +17,7 @@ from os import getenv
 from typing import Any, Callable, Dict, List, Optional, Union
 
 from agno.learn.config import (
+    DecisionLogConfig,
     EntityMemoryConfig,
     LearnedKnowledgeConfig,
     LearningMode,
@@ -45,6 +46,7 @@ UserMemoryInput = Union[bool, UserMemoryConfig, LearningStore, None]
 EntityMemoryInput = Union[bool, EntityMemoryConfig, LearningStore, None]
 SessionContextInput = Union[bool, SessionContextConfig, LearningStore, None]
 LearnedKnowledgeInput = Union[bool, LearnedKnowledgeConfig, LearningStore, None]
+DecisionLogInput = Union[bool, DecisionLogConfig, LearningStore, None]
 
 
 @dataclass
@@ -80,6 +82,7 @@ class LearningMachine:
     session_context: SessionContextInput = False
     entity_memory: EntityMemoryInput = False
     learned_knowledge: LearnedKnowledgeInput = False
+    decision_log: DecisionLogInput = False  # Phase 2
 
     # Namespace for entity_memory and learned_knowledge
     namespace: str = "global"
@@ -144,6 +147,13 @@ class LearningMachine:
                 store_type="learned_knowledge",
             )
 
+        # Decision Log (Phase 2)
+        if self.decision_log:
+            self._stores["decision_log"] = self._resolve_store(
+                input_value=self.decision_log,
+                store_type="decision_log",
+            )
+
         # Custom stores
         if self.custom_stores:
             for name, store in self.custom_stores.items():
@@ -180,6 +190,8 @@ class LearningMachine:
             return self._create_entity_memory_store(config=input_value)
         elif store_type == "learned_knowledge":
             return self._create_learned_knowledge_store(config=input_value)
+        elif store_type == "decision_log":
+            return self._create_decision_log_store(config=input_value)
         else:
             raise ValueError(f"Unknown store type: {store_type}")
 
@@ -274,6 +286,24 @@ class LearningMachine:
 
         return LearnedKnowledgeStore(config=config, debug_mode=self.debug_mode)
 
+    def _create_decision_log_store(self, config: Any) -> LearningStore:
+        """Create DecisionLogStore with resolved config."""
+        from agno.learn.stores import DecisionLogStore
+
+        if isinstance(config, DecisionLogConfig):
+            if config.db is None:
+                config.db = self.db
+            if config.model is None:
+                config.model = self.model
+        else:
+            config = DecisionLogConfig(
+                db=self.db,
+                model=self.model,
+                mode=LearningMode.AGENTIC,  # Default to AGENTIC for explicit logging
+            )
+
+        return DecisionLogStore(config=config, debug_mode=self.debug_mode)
+
     # =========================================================================
     # Store Accessors (Type-Safe)
     # =========================================================================
@@ -303,6 +333,11 @@ class LearningMachine:
         """Get learned knowledge store if enabled."""
         return self.stores.get("learned_knowledge")
 
+    @property
+    def decision_log_store(self) -> Optional[LearningStore]:
+        """Get decision log store if enabled."""
+        return self.stores.get("decision_log")
+
     @property
     def was_updated(self) -> bool:
         """True if any store was updated in the last operation."""

agno/learn/schemas.py

@@ -893,22 +893,72 @@ class SessionPlanningExtractionResponse:
 
 
 @dataclass
-class Decision:
-    """Schema for Decision Logs. (Phase 2)
+class DecisionLog:
+    """Schema for Decision Logs.
 
     Records decisions made by the agent with reasoning and context.
+    Useful for:
+    - Auditing agent behavior
+    - Learning from past decisions
+    - Debugging unexpected outcomes
+    - Building feedback loops
+
+    Example:
+        DecisionLog(
+            id="dec_abc123",
+            decision="Used web search instead of knowledge base",
+            reasoning="User asked about current events which require fresh data",
+            decision_type="tool_selection",
+            context="User query: 'What happened in the news today?'",
+            alternatives=["search_knowledge_base", "ask_for_clarification"],
+            confidence=0.85,
+        )
+
+    Attributes:
+        id: Unique identifier for this decision.
+        decision: What was decided (the choice made).
+        reasoning: Why this decision was made.
+        decision_type: Category of decision (tool_selection, response_style, etc).
+        context: The situation that required a decision.
+        alternatives: Other options that were considered.
+        confidence: How confident the agent was (0.0 to 1.0).
+        outcome: What happened as a result (can be updated later).
+        outcome_quality: Was the outcome good/bad/neutral.
+        tags: Categories for organization.
+        session_id: Which session this decision was made in.
+        user_id: Which user this decision was for.
+        agent_id: Which agent made this decision.
+        team_id: Which team context.
+        created_at: When the decision was made.
+        updated_at: When the outcome was recorded.
     """
 
+    id: str
     decision: str
-    reasoning: Optional[str] = None
-    context: Optional[str] = None
-    outcome: Optional[str] = None
-    agent_id: Optional[str] = None
-    team_id: Optional[str] = None
-    created_at: Optional[str] = None
+    reasoning: Optional[str] = field(default=None, metadata={"description": "Why this decision was made"})
+    decision_type: Optional[str] = field(
+        default=None,
+        metadata={"description": "Category: tool_selection, response_style, clarification, escalation, etc"},
+    )
+    context: Optional[str] = field(default=None, metadata={"description": "The situation that required a decision"})
+    alternatives: Optional[List[str]] = field(
+        default=None, metadata={"description": "Other options that were considered"}
+    )
+    confidence: Optional[float] = field(default=None, metadata={"description": "Confidence level 0.0 to 1.0"})
+    outcome: Optional[str] = field(default=None, metadata={"description": "What happened as a result"})
+    outcome_quality: Optional[str] = field(default=None, metadata={"description": "Was outcome good/bad/neutral"})
+    tags: Optional[List[str]] = field(default=None, metadata={"description": "Categories for organization"})
+
+    # Scope
+    session_id: Optional[str] = field(default=None, metadata={"internal": True})
+    user_id: Optional[str] = field(default=None, metadata={"internal": True})
+    agent_id: Optional[str] = field(default=None, metadata={"internal": True})
+    team_id: Optional[str] = field(default=None, metadata={"internal": True})
+    created_at: Optional[str] = field(default=None, metadata={"internal": True})
+    updated_at: Optional[str] = field(default=None, metadata={"internal": True})
 
     @classmethod
-    def from_dict(cls, data: Any) -> Optional["Decision"]:
+    def from_dict(cls, data: Any) -> Optional["DecisionLog"]:
         """Parse from dict/JSON, returning None on any failure."""
         if data is None:
             return None
@@ -921,8 +971,9 @@ class Decision:
                 log_debug(f"{cls.__name__}.from_dict: _parse_json returned None for data={_truncate_for_log(data)}")
                 return None
 
-            if not parsed.get("decision"):
-                log_debug(f"{cls.__name__}.from_dict: missing required field 'decision'")
+            # id and decision are required
+            if not parsed.get("id") or not parsed.get("decision"):
+                log_debug(f"{cls.__name__}.from_dict: missing required fields 'id' or 'decision'")
                 return None
 
             field_names = {f.name for f in fields(cls)}
@@ -941,6 +992,26 @@ class Decision:
             log_debug(f"{self.__class__.__name__}.to_dict failed: {e}")
             return {}
 
+    def to_text(self) -> str:
+        """Convert to searchable text format."""
+        parts = [f"Decision: {self.decision}"]
+        if self.reasoning:
+            parts.append(f"Reasoning: {self.reasoning}")
+        if self.context:
+            parts.append(f"Context: {self.context}")
+        if self.decision_type:
+            parts.append(f"Type: {self.decision_type}")
+        if self.outcome:
+            parts.append(f"Outcome: {self.outcome}")
+        return "\n".join(parts)
+
+    def __repr__(self) -> str:
+        return f"DecisionLog(id={self.id}, decision={self.decision[:50]}...)"
+
+
+# Backwards compatibility alias
+Decision = DecisionLog
+
 
 @dataclass
 class Feedback:

agno/learn/stores/__init__.py

@@ -15,8 +15,10 @@ Available Stores:
 - SessionContextStore: Current session state
 - LearnedKnowledgeStore: Reusable knowledge/insights
 - EntityMemoryStore: Third-party entity facts
+- DecisionLogStore: Agent decision logging (Phase 2)
 """
 
+from agno.learn.stores.decision_log import DecisionLogStore
 from agno.learn.stores.entity_memory import EntityMemoryStore
 from agno.learn.stores.learned_knowledge import LearnedKnowledgeStore
 from agno.learn.stores.protocol import LearningStore
@@ -32,4 +34,5 @@ __all__ = [
     "SessionContextStore",
     "LearnedKnowledgeStore",
     "EntityMemoryStore",
+    "DecisionLogStore",
 ]