agent-framework-lib 0.7.1__tar.gz → 0.8.0__tar.gz

{agent_framework_lib-0.7.1/agent_framework_lib.egg-info → agent_framework_lib-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-lib
-Version: 0.7.1
+Version: 0.8.0
 Summary: A comprehensive Python framework for building and serving conversational AI agents with FastAPI
 Author-email: Sebastian Pavel <sebastian@cinco.ai>, Elliott Girard <elliott.girard@icloud.com>
 Maintainer-email: Sebastian Pavel <sebastian@cinco.ai>
@@ -999,7 +999,7 @@ class MySkillsAgent(LlamaIndexAgent):
 5. Agent executes via `shell_exec` → script generates the chart
 6. Optionally calls `unload_skill("chart")` when done
 
-**More info:** See [Creating Agents Guide](docs/CREATING_AGENTS.md#skills-integration) and [skills_demo_agent.py](examples/skills_demo_agent.py)
+**More info:** See [Custom Skills Guide](docs/CUSTOM_SKILLS_GUIDE.md), [Creating Agents Guide](docs/CREATING_AGENTS.md#skills-integration) and [skills_demo_agent.py](examples/skills_demo_agent.py)
 
 ## 📝 Rich Content Capabilities (Automatic)
 

{agent_framework_lib-0.7.1 → agent_framework_lib-0.8.0}/README.md

@@ -853,7 +853,7 @@ class MySkillsAgent(LlamaIndexAgent):
 5. Agent executes via `shell_exec` → script generates the chart
 6. Optionally calls `unload_skill("chart")` when done
 
-**More info:** See [Creating Agents Guide](docs/CREATING_AGENTS.md#skills-integration) and [skills_demo_agent.py](examples/skills_demo_agent.py)
+**More info:** See [Custom Skills Guide](docs/CUSTOM_SKILLS_GUIDE.md), [Creating Agents Guide](docs/CREATING_AGENTS.md#skills-integration) and [skills_demo_agent.py](examples/skills_demo_agent.py)
 
 ## 📝 Rich Content Capabilities (Automatic)
 

{agent_framework_lib-0.7.1 → agent_framework_lib-0.8.0}/agent_framework/__init__.py

@@ -32,7 +32,7 @@ Example Usage:
     create_basic_agent_server(MyAgent, port=8000)
     ```
 
-Version: 0.7.1
+Version: 0.7.2
 Author: Cinco AI Team
 License: MIT
 """
@@ -88,7 +88,7 @@ def _auto_setup_dependencies() -> None:
 # Track if auto-setup has been done
 _AUTO_SETUP_DONE = False
 
-__version__ = "0.7.1"
+__version__ = "0.7.2"
 __author__ = "Cinco AI Team"
 __license__ = "MIT"
 __email__ = "sebastian@cinco.ai"

{agent_framework_lib-0.7.1 → agent_framework_lib-0.8.0}/agent_framework/core/base_agent.py

@@ -22,7 +22,13 @@ import time
 from abc import abstractmethod
 from collections.abc import AsyncGenerator
 from datetime import datetime, timezone
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..capabilities.resolver import CapabilitySet
+    from ..subagents.executor import SubagentExecutor
+    from ..subagents.message_queue import SessionMessageQueue
+    from ..subagents.spawn_tool import SubagentSpawnTool
 
 from ..monitoring.streaming_latency_tracer import get_streaming_latency_tracer
 from ..utils.special_blocks import parse_special_blocks_from_text
@@ -231,6 +237,15 @@ class BaseAgent(SkillsMixin, MemoryMixin, AgentInterface):
         self._agent_built: bool = False
         self._state_ctx: Any | None = None
 
+        # Subagent execution support (optional, injected post-init)
+        self._subagent_executor: SubagentExecutor | None = None
+        self._capability_set: CapabilitySet | None = None
+        self._message_queue: SessionMessageQueue | None = None
+        self._current_session_id: str | None = None
+        self._current_user_id: str | None = None
+        self._current_spawn_depth: int = 0
+        self._file_storage_session_id: str | None = None
+
         # Initialize parent classes (including SkillsMixin and MemoryMixin if available)
         super().__init__()
 
@@ -334,6 +349,43 @@ class BaseAgent(SkillsMixin, MemoryMixin, AgentInterface):
         """
         return None
 
+    def set_subagent_executor(self, executor: "SubagentExecutor | None") -> None:
+        """Inject or remove the shared SubagentExecutor.
+
+        Automatically extracts the SessionMessageQueue from the executor's
+        MessageInjector when an executor is provided.
+        """
+        self._subagent_executor = executor
+        if executor is not None:
+            self._message_queue = executor._message_injector.get_queue()
+        else:
+            self._message_queue = None
+
+    def _create_subagent_spawn_tool(self) -> "SubagentSpawnTool | None":
+        """Create the SubagentSpawnTool if all conditions are met.
+
+        Returns None when the executor, capability_set, or the
+        'subagent:spawn' capability is absent.
+        """
+        if self._subagent_executor is None:
+            return None
+        if self._capability_set is None:
+            return None
+        if "subagent:spawn" not in self._capability_set.native_tools:
+            return None
+
+        from ..subagents.spawn_tool import SubagentSpawnTool
+
+        return SubagentSpawnTool(
+            capability_set=self._capability_set,
+            current_depth=self._current_spawn_depth,
+            activity_callback=getattr(self, "_activity_callback", None),
+            executor=self._subagent_executor,
+            parent_session_id=self._current_session_id or "",
+            parent_user_id=self._current_user_id or "",
+            agent_class=type(self),
+        )
+
     async def process_streaming_event(self, event: Any) -> dict[str, Any] | None:
         """
         Convert framework-specific streaming events to unified format.
@@ -528,21 +580,16 @@ class BaseAgent(SkillsMixin, MemoryMixin, AgentInterface):
 
     async def _get_all_tools(self) -> list[callable]:
         """
-        Get all tools including agent-defined tools, skill tools, and memory tools.
-
-        When skills are enabled, ALL registered skill tools are included automatically.
-        This ensures tools are available immediately without requiring load_skill() first.
+        Get all tools including agent-defined tools, skill management, memory, and spawn tools.
 
         Tool Loading Order:
         1. Agent's custom tools (from get_agent_tools())
         2. Skill management tools (list_skills, load_skill, unload_skill)
-        3. ALL registered skill tools (chart, mermaid, pdf, etc.)
-        4. Memory tools (if memory is configured)
-
-        This order ensures no conflicts and proper tool availability.
+        3. Memory tools (if memory is configured)
+        4. SubagentSpawnTool (if executor + capability_set configured)
 
         Returns:
-            Combined list of agent tools, skill management tools, skill tools, and memory tools
+            Combined list of all available tools for this agent.
         """
         # 1. Get base tools from agent implementation
         tools = self.get_agent_tools()
@@ -557,14 +604,18 @@ class BaseAgent(SkillsMixin, MemoryMixin, AgentInterface):
                     f"🎯 Added {len(skill_mgmt_tools)} skill management tools to agent {self.agent_id}"
                 )
 
-            # 3. Add tools from ALL registered skills (not just loaded ones)
-            # This is the key fix: tools must be available before load_skill() is called
-            all_skill_tools = self.get_all_registered_skill_tools()
-            if all_skill_tools:
-                tools = tools + all_skill_tools
-                logger.info(f"🔧 Added {len(all_skill_tools)} skill tools to agent {self.agent_id}")
+            # 2b. Add native skill tools (shell_exec, web_fetch, etc.)
+            try:
+                skill_tools = self.get_all_registered_skill_tools()
+                if skill_tools:
+                    tools = tools + skill_tools
+                    logger.info(
+                        f"🔧 Added {len(skill_tools)} skill tools to agent {self.agent_id}"
+                    )
+            except Exception as e:
+                logger.warning(f"Failed to collect skill tools: {e}")
 
-        # 4. Add memory tools if memory is configured (AFTER skill tools)
+        # 3. Add memory tools if memory is configured
         if MEMORY_AVAILABLE and hasattr(self, "_ensure_memory_initialized"):
             try:
                 # Initialize memory if configured (this is async)
@@ -579,6 +630,15 @@ class BaseAgent(SkillsMixin, MemoryMixin, AgentInterface):
             except Exception as e:
                 logger.warning(f"Failed to add memory tools: {e}")
 
+        # 4. Add subagent spawn tool if configured
+        try:
+            spawn_tool = self._create_subagent_spawn_tool()
+            if spawn_tool is not None:
+                tools = tools + [spawn_tool.get_tool_function()]
+                logger.info(f"🤖 Added SubagentSpawnTool to agent {self.agent_id}")
+        except Exception as e:
+            logger.warning(f"Failed to create SubagentSpawnTool: {e}")
+
         logger.debug(f"📊 Total tools for agent {self.agent_id}: {len(tools)}")
         return tools
 
@@ -627,6 +687,21 @@ class BaseAgent(SkillsMixin, MemoryMixin, AgentInterface):
         if "model_name" in session_configuration:
             self._session_model_name = session_configuration["model_name"]
 
+        if "capability_set" in session_configuration:
+            self._capability_set = session_configuration["capability_set"]
+        if "session_id" in session_configuration:
+            self._current_session_id = session_configuration["session_id"]
+        if "user_id" in session_configuration:
+            self._current_user_id = session_configuration["user_id"]
+        if "spawn_depth" in session_configuration:
+            self._current_spawn_depth = session_configuration["spawn_depth"]
+
+        # Use parent's session_id for file storage if configured (subagent file sharing)
+        if "file_storage_session_id" in session_configuration:
+            self._file_storage_session_id = session_configuration["file_storage_session_id"]
+        else:
+            self._file_storage_session_id = None
+
         # --- Automatic personalization injection ---
         # Activated when PERSONALIZATION_ENABLED=true (default) AND memory is available.
         # If the prompt contains {{native_user_preferences}}, it is replaced with the user's facts.
@@ -846,6 +921,18 @@ class BaseAgent(SkillsMixin, MemoryMixin, AgentInterface):
         # Build full query including file content from parts
         full_query = self._build_full_query(agent_input)
 
+        # Drain pending subagent messages and prepend to query
+        if hasattr(self, '_message_queue') and self._message_queue is not None:
+            try:
+                pending = await self._message_queue.drain(session_id)
+                if pending:
+                    injected = "\n\n".join(
+                        f"[Résultat sous-agent]\n{msg}" for msg in pending
+                    )
+                    full_query = f"{injected}\n\n{full_query}"
+            except Exception:
+                logger.warning("Failed to drain subagent message queue", exc_info=True)
+
         # === PASSIVE MEMORY INJECTION ===
         # Inject memory context if memory is enabled and passive injection is configured
         if MEMORY_AVAILABLE and hasattr(self, "memory_enabled") and self.memory_enabled:
@@ -930,7 +1017,7 @@ class BaseAgent(SkillsMixin, MemoryMixin, AgentInterface):
         try:
             from ..processing.rich_content_validation import validate_rich_content
 
-            cleaned = validate_rich_content(cleaned)
+            cleaned = await validate_rich_content(cleaned)
             logger.debug("Rich content validation completed")
         except ImportError:
             logger.debug("Rich content validation module not available, skipping")
@@ -1105,6 +1192,18 @@ class BaseAgent(SkillsMixin, MemoryMixin, AgentInterface):
                 logger.warning(f"Failed to inject memory context (streaming): {e}")
                 # Continue without memory context - don't fail the message
 
+        # Drain pending subagent messages and prepend to query
+        if hasattr(self, '_message_queue') and self._message_queue is not None:
+            try:
+                pending = await self._message_queue.drain(session_id)
+                if pending:
+                    injected = "\n\n".join(
+                        f"[Résultat sous-agent]\n{msg}" for msg in pending
+                    )
+                    full_query = f"{injected}\n\n{full_query}"
+            except Exception:
+                logger.warning("Failed to drain subagent message queue", exc_info=True)
+
         # Use run_agent in streaming mode
         stream_generator = await self.run_agent(full_query, ctx, stream=True)
 
@@ -1310,7 +1409,7 @@ class BaseAgent(SkillsMixin, MemoryMixin, AgentInterface):
         try:
             from ..processing.rich_content_validation import validate_rich_content
 
-            cleaned = validate_rich_content(cleaned)
+            cleaned = await validate_rich_content(cleaned)
             logger.debug("Rich content validation completed")
         except ImportError:
             logger.debug("Rich content validation module not available, skipping")

agent_framework_lib-0.8.0/agent_framework/notifications/__init__.py

@@ -0,0 +1,7 @@
+"""Notification pub/sub components for real-time SSE event distribution."""
+
+from agent_framework.notifications.hub import NotificationHub
+
+__all__ = [
+    "NotificationHub",
+]

agent_framework_lib-0.8.0/agent_framework/notifications/hub.py

@@ -0,0 +1,78 @@
+"""In-memory pub/sub component for per-session SSE notifications."""
+
+import asyncio
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class NotificationHub:
+    """Per-session event pub/sub for SSE notifications.
+
+    Manages subscriber queues per session and distributes events
+    to all active subscribers using non-blocking put operations.
+    """
+
+    def __init__(self) -> None:
+        self._subscriptions: dict[str, set[asyncio.Queue[dict[str, Any]]]] = {}
+        self._lock = asyncio.Lock()
+
+    async def subscribe(self, session_id: str) -> asyncio.Queue[dict[str, Any]]:
+        """Register a new subscriber for a session.
+
+        Args:
+            session_id: The session to subscribe to.
+
+        Returns:
+            A queue to await events from. Bounded to 100 items.
+        """
+        queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue(maxsize=100)
+        async with self._lock:
+            if session_id not in self._subscriptions:
+                self._subscriptions[session_id] = set()
+            self._subscriptions[session_id].add(queue)
+        return queue
+
+    async def unsubscribe(self, session_id: str, queue: asyncio.Queue[dict[str, Any]]) -> None:
+        """Remove a subscriber's queue from a session.
+
+        No-op if the queue was already removed or the session has no subscribers.
+
+        Args:
+            session_id: The session to unsubscribe from.
+            queue: The subscriber queue to remove.
+        """
+        async with self._lock:
+            subscribers = self._subscriptions.get(session_id)
+            if subscribers is None:
+                return
+            subscribers.discard(queue)
+            if not subscribers:
+                del self._subscriptions[session_id]
+
+    async def publish(self, session_id: str, event: dict[str, Any]) -> None:
+        """Distribute an event to all active subscribers for a session.
+
+        Non-blocking, best-effort delivery. If a subscriber's queue is full,
+        the event is dropped for that subscriber only.
+
+        Args:
+            session_id: The target session.
+            event: The event dict to distribute.
+        """
+        async with self._lock:
+            subscribers = self._subscriptions.get(session_id)
+            if subscribers is None:
+                return
+            # Snapshot to avoid mutation during iteration
+            queues = list(subscribers)
+
+        for queue in queues:
+            try:
+                queue.put_nowait(event)
+            except asyncio.QueueFull:
+                logger.warning(
+                    "Dropping notification event for session %s: subscriber queue full",
+                    session_id,
+                )