agent-framework-lib 0.8.5__tar.gz → 0.8.6__tar.gz

{agent_framework_lib-0.8.5/agent_framework_lib.egg-info → agent_framework_lib-0.8.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-lib
-Version: 0.8.5
+Version: 0.8.6
 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>

{agent_framework_lib-0.8.5 → agent_framework_lib-0.8.6}/agent_framework/__init__.py

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

{agent_framework_lib-0.8.5 → agent_framework_lib-0.8.6}/agent_framework/core/agent_interface.py

@@ -860,6 +860,38 @@ class AgentInterface(abc.ABC):
         """
         pass
 
+    def get_cancellation_refs(self) -> dict[str, Any]:
+        """
+        Return framework-specific references the server uses to wire up
+        graceful cancellation for the in-flight turn.
+
+        The returned dict may contain any of:
+        - ``handler``: the live workflow handler (e.g. LlamaIndex's
+          ``WorkflowHandler``) that the server will pass to
+          ``ExecutionController.set_handler`` so an external cancel can call
+          ``handler.cancel_run()``.
+        - ``ctx``: the agent's working context (used for scratchpad commit on
+          cancel).
+        - ``memory``: the chat memory buffer (used for scratchpad replay).
+        - ``memory_adapter``: the memory adapter (used to invalidate caches
+          after the scratchpad is committed).
+
+        The default implementation returns all keys set to ``None``. Agents
+        that participate in cancellation (BaseAgent + LlamaIndex-style
+        agents) should override this method. The server treats every key as
+        optional and only wires what is present.
+
+        Exposing these refs through a single public method keeps the server
+        framework-agnostic — it never has to touch private agent attributes
+        like ``_current_handler`` or ``_current_ctx``.
+        """
+        return {
+            "handler": None,
+            "ctx": None,
+            "memory": None,
+            "memory_adapter": None,
+        }
+
     def get_custom_tool_display_info(self) -> dict[str, Any]:
         """
         Returns custom display info for agent-specific tools (e.g., MCP tools).

{agent_framework_lib-0.8.5 → agent_framework_lib-0.8.6}/agent_framework/core/base_agent.py

@@ -388,6 +388,23 @@ class BaseAgent(SkillsMixin, MemoryMixin, AgentInterface):
         else:
             self._message_queue = None
 
+    def get_cancellation_refs(self) -> dict[str, Any]:
+        """Expose private cancellation hooks through a single public method.
+
+        Returns the live framework objects (workflow handler, agent context,
+        memory, memory adapter) that the FastAPI server registers with the
+        ``ExecutionController`` so a user-issued cancel can commit the
+        scratchpad and abort the in-flight handler. Keeping this behind a
+        single interface method lets the server stay framework-agnostic
+        instead of poking at private attributes like ``_current_handler``.
+        """
+        return {
+            "handler": getattr(self, "_current_handler", None),
+            "ctx": getattr(self, "_current_ctx", None),
+            "memory": getattr(self, "_current_memory", None),
+            "memory_adapter": getattr(self, "_memory_adapter", None),
+        }
+
     def _create_subagent_spawn_tool(self) -> SubagentSpawnTool | None:
         """Create the SubagentSpawnTool if all conditions are met.
 
@@ -910,51 +927,21 @@ class BaseAgent(SkillsMixin, MemoryMixin, AgentInterface):
         except Exception as e:
             logger.warning("Personalization injection skipped: %s", e)
 
-    async def get_system_prompt(self) -> str | None:
-        """
-        Return the current system prompt with skills discovery capabilities.
-
-        If skills are enabled (default), automatically combines the agent's
-        custom prompt with skills discovery instructions that teach the agent
-        how to discover and load skills on-demand.
+    def _has_shell_tool(self) -> bool:
+        """Check whether a shell tool is available."""
+        return self._live_shell_tool is not None
 
-        Returns:
-            Combined system prompt with skills discovery capabilities, or base prompt if disabled
-        """
-        base_prompt = self._session_system_prompt or ""
-
-        if not base_prompt:
-            logger.warning("Agent has no base prompt defined")
-            if self._enable_skills and SKILLS_AVAILABLE:
-                # Import here to avoid circular dependencies
-                try:
-                    from ..skills.discovery_prompt import get_skills_discovery_prompt
-
-                    return get_skills_discovery_prompt()
-                except ImportError as e:
-                    logger.error(f"Failed to import skills discovery prompt: {e}")
-                    logger.warning("Skills discovery capabilities unavailable, using empty prompt")
-                    return ""
-            return ""
-
-        if not self._enable_skills or not SKILLS_AVAILABLE:
-            logger.debug("Skills disabled, returning base prompt only")
-            return base_prompt
-
-        # Import here to avoid circular dependencies
-        try:
-            from ..skills.discovery_prompt import get_skills_discovery_prompt
-
-            skills_prompt = get_skills_discovery_prompt()
-            combined = f"{base_prompt}\n\n{skills_prompt}"
-            logger.debug(
-                f"Combined prompt length: {len(combined)} chars (base: {len(base_prompt)}, skills: {len(skills_prompt)})"
-            )
-            return combined
-        except ImportError as e:
-            logger.error(f"Failed to import skills discovery prompt: {e}")
-            logger.warning("Skills discovery capabilities unavailable, using base prompt only")
-            return base_prompt
+    async def get_system_prompt(self) -> str | None:
+        """Assemble le system prompt via PromptBuilder."""
+        from .prompt_builder import PromptBuilder
+
+        builder = PromptBuilder(
+            agent_prompt=self._session_system_prompt or "",
+            has_shell_tool=self._has_shell_tool(),
+            has_workspace=self._workspace_context is not None,
+            skills_enabled=self._enable_skills and SKILLS_AVAILABLE,
+        )
+        return builder.build()
 
     async def get_current_model(self, session_id: str) -> str | None:
         """Return the current model name."""

{agent_framework_lib-0.8.5 → agent_framework_lib-0.8.6}/agent_framework/core/execution_controller.py

@@ -40,6 +40,11 @@ class ExecutionContext:
     # MessageData on cancel, so the /cancel endpoint skips its own persist
     # and we don't write duplicate entries.
     stream_persisted_partial: bool = False
+    # Serializes concurrent cancel_execution / end_execution calls for this
+    # session. Without this, two awaiters can both pass the ``state == RUNNING``
+    # check before either sets state=IDLE, and both will commit the scratchpad
+    # + return True (cf. test_exactly_one_cancel_succeeds).
+    lock: asyncio.Lock = field(default_factory=asyncio.Lock)
 
 
 class InvalidStateTransitionError(Exception):
@@ -284,70 +289,82 @@ class ExecutionController:
         8. return True
         """
         ctx = self._sessions.get(session_id)
-        if not ctx or ctx.state != ExecutionState.RUNNING:
+        if not ctx:
             return False
 
-        # Phase 1: Commit scratchpad (best-effort, before cancel_event.set)
-        logger.info(
-            "[EC] cancel_execution starting for session %s (interaction %s)",
-            session_id,
-            ctx.interaction_id,
-        )
-        commit_succeeded = False
-        try:
-            commit_succeeded = await asyncio.wait_for(
-                self._commit_scratchpad(ctx),
-                timeout=5.0,
-            )
-        except asyncio.TimeoutError:
-            logger.warning(
-                "[EC] Scratchpad commit timeout (5s) for session %s, proceeding with standard cancel",
-                session_id,
-            )
-        except Exception as exc:
-            logger.warning(
-                "[EC] Scratchpad commit failed for session %s: %s, proceeding with standard cancel",
+        # Serialize concurrent cancel_execution calls for this session. The
+        # state check + commit + state mutation must run atomically — without
+        # the lock, two awaiters both observe RUNNING and both commit + return
+        # True, violating "exactly one cancellation succeeds".
+        async with ctx.lock:
+            if ctx.state != ExecutionState.RUNNING:
+                return False
+
+            # Phase 1: Commit scratchpad (best-effort, before cancel_event.set)
+            logger.info(
+                "[EC] cancel_execution starting for session %s (interaction %s)",
                 session_id,
-                exc,
-                exc_info=True,
+                ctx.interaction_id,
             )
-
-        # Phase 1b: Invalidate cache after successful commit (Requirement 3.1)
-        if commit_succeeded and ctx.memory_adapter is not None:
+            commit_succeeded = False
             try:
-                ctx.memory_adapter.clear_cache(session_id=session_id, user_id=ctx.user_id)
-                logger.info("[EC] Cache invalidated for session %s", session_id)
+                commit_succeeded = await asyncio.wait_for(
+                    self._commit_scratchpad(ctx),
+                    timeout=5.0,
+                )
+            except asyncio.TimeoutError:
+                logger.warning(
+                    "[EC] Scratchpad commit timeout (5s) for session %s, proceeding with standard cancel",
+                    session_id,
+                )
             except Exception as exc:
-                logger.warning("[EC] Cache invalidation failed for session %s: %s", session_id, exc)
+                logger.warning(
+                    "[EC] Scratchpad commit failed for session %s: %s, proceeding with standard cancel",
+                    session_id,
+                    exc,
+                    exc_info=True,
+                )
+
+            # Phase 1b: Invalidate cache after successful commit (Requirement 3.1)
+            if commit_succeeded and ctx.memory_adapter is not None:
+                try:
+                    ctx.memory_adapter.clear_cache(session_id=session_id, user_id=ctx.user_id)
+                    logger.info("[EC] Cache invalidated for session %s", session_id)
+                except Exception as exc:
+                    logger.warning(
+                        "[EC] Cache invalidation failed for session %s: %s", session_id, exc
+                    )
 
-        # Phase 2: Standard cancellation
-        ctx.cancel_event.set()
-        ctx.state = ExecutionState.IDLE
+            # Phase 2: Standard cancellation
+            ctx.cancel_event.set()
+            ctx.state = ExecutionState.IDLE
 
-        # Cancel the LlamaIndex workflow handler if available
-        if ctx.handler is not None:
-            try:
-                cancel_method = getattr(ctx.handler, "cancel_run", None)
-                if cancel_method and asyncio.iscoroutinefunction(cancel_method):
-                    await cancel_method()
-                    logger.info("[EC] Called handler.cancel_run() for session %s", session_id)
-                elif hasattr(ctx.handler, "cancel"):
-                    ctx.handler.cancel()
-                    logger.info("[EC] Called handler.cancel() for session %s", session_id)
-            except Exception as exc:
-                logger.warning("[EC] Error cancelling handler for session %s: %s", session_id, exc)
-            ctx.handler = None
+            # Cancel the LlamaIndex workflow handler if available
+            if ctx.handler is not None:
+                try:
+                    cancel_method = getattr(ctx.handler, "cancel_run", None)
+                    if cancel_method and asyncio.iscoroutinefunction(cancel_method):
+                        await cancel_method()
+                        logger.info("[EC] Called handler.cancel_run() for session %s", session_id)
+                    elif hasattr(ctx.handler, "cancel"):
+                        ctx.handler.cancel()
+                        logger.info("[EC] Called handler.cancel() for session %s", session_id)
+                except Exception as exc:
+                    logger.warning(
+                        "[EC] Error cancelling handler for session %s: %s", session_id, exc
+                    )
+                ctx.handler = None
 
-        # Phase 3: Clean up agent references (Requirement 2.4)
-        # NOTE: keep ``last_scratchpad_activity_parts`` so server.py can read it
-        # right after cancel to build the InterruptionMessage.
-        ctx.agent_ctx = None
-        ctx.memory = None
-        ctx.memory_adapter = None
-        ctx.session_storage = None
-        ctx.user_id = None
+            # Phase 3: Clean up agent references (Requirement 2.4)
+            # NOTE: keep ``last_scratchpad_activity_parts`` so server.py can read it
+            # right after cancel to build the InterruptionMessage.
+            ctx.agent_ctx = None
+            ctx.memory = None
+            ctx.memory_adapter = None
+            ctx.session_storage = None
+            ctx.user_id = None
 
-        return True
+            return True
 
     async def end_execution(self, session_id: str) -> None:
         """Termine normalement une exécution.
@@ -357,7 +374,12 @@ class ExecutionController:
         CancelledError (client disconnect) rather than a clean cancel.
         """
         ctx = self._sessions.get(session_id)
-        if ctx:
+        if not ctx:
+            return
+        # Use the same per-session lock as ``cancel_execution`` so the two
+        # paths cannot race (e.g. cancel mid-stream while the stream is also
+        # ending normally).
+        async with ctx.lock:
             # Best-effort scratchpad commit before cleanup.
             # This covers the GeneratorExit / CancelledError path where
             # cancel_execution() was never called.

agent_framework_lib-0.8.6/agent_framework/core/prompt_builder.py

@@ -0,0 +1,198 @@
+"""Modular prompt assembly system for enhanced system prompts."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+try:
+    from agent_framework.skills.discovery_prompt import SKILLS_DISCOVERY_PROMPT
+except ImportError:
+    SKILLS_DISCOVERY_PROMPT = ""
+
+
+@dataclass
+class PromptSection:
+    """A named, conditionally-included section of the system prompt."""
+
+    name: str
+    content: str
+    order: int
+    prerequisite_met: bool = True
+
+
+BASE_PROMPT_SECTION: str = """## Communication & Efficiency
+
+- Provide concise responses focused on results, not process descriptions.
+- Use structured formatting (bullet points, code blocks, tables) for technical information.
+- State what was done and what the result is. Do not narrate each intermediate step.
+- Do not repeat information already visible in the conversation context.
+- When encountering an error, report it with a diagnosis and proposed next steps — never forward raw error output without interpretation."""
+
+PROACTIVE_SECTION: str = """## Proactive Behavior
+
+- Attempt actions before asking clarifying questions. Use available tools to gather information rather than asking the user for details you can discover yourself.
+- Complete multi-step tasks in a single response when all required information is available or discoverable via tools.
+- When a request is ambiguous, attempt the most likely interpretation and state the assumption made. Only ask for clarification when multiple interpretations would lead to fundamentally different outcomes.
+- Report results concisely without repeating the original request or adding unnecessary preamble."""
+
+SHELL_SECTION: str = """## Shell Usage & Diagnostics
+
+You have access to `shell_exec` for running shell commands. Use it proactively:
+
+**Diagnostics first**: Before reporting a problem to the user, use shell_exec to verify connectivity, test commands, and diagnose the issue yourself. Chain diagnostic commands in a logical sequence (check connectivity → verify credentials → test endpoint).
+
+**Environment discovery**: Read environment variables via shell_exec (`echo $VAR_NAME` or `env | grep PATTERN`) to discover available service endpoints and credentials. Do not ask the user for values that are available in the environment.
+
+**Timeout**: The default timeout is 30 seconds. Use the `timeout` parameter for commands expected to take longer.
+
+**Error interpretation**: Interpret non-zero exit codes and stderr output to diagnose failures. Provide the user with a diagnosis, not raw output.
+
+**Dependency auto-install**: When shell output shows an ImportError or missing client library:
+1. Detect the missing package name from the error message.
+2. Install it with `uv pip install <package>` (never use `pip` directly — always `uv`).
+3. Retry the failed command.
+4. If installation fails, report the specific error to the user.
+5. Install only the specific missing package, not unrelated packages."""
+
+WORKSPACE_SECTION: str = """## Workspace Context
+
+You are operating within a shared workspace. Leverage the workspace context:
+
+**Secrets as env vars**: Workspace entities marked as secrets are available as environment variables in shell_exec. Access them via `$VARIABLE_NAME` in shell commands. NEVER expose secret values in your text responses.
+
+**Service discovery**: Infer available services from entity names (e.g., `ELASTICSEARCH_URL` implies Elasticsearch access, `REDIS_HOST` implies Redis). Test service connectivity via shell_exec using available credentials before reporting access issues.
+
+**Collaboration**: Use workspace member information to personalize interactions and understand the collaboration context."""
+
+
+class PromptBuilder:
+    """Assembles the system prompt from modular, conditional sections."""
+
+    SECTION_SEPARATOR: str = "\n\n"
+
+    def __init__(
+        self,
+        agent_prompt: str,
+        has_shell_tool: bool = False,
+        has_workspace: bool = False,
+        skills_enabled: bool = True,
+    ) -> None:
+        self._agent_prompt = agent_prompt
+        self._has_shell_tool = has_shell_tool
+        self._has_workspace = has_workspace
+        self._skills_enabled = skills_enabled
+
+        self._sections = self._build_sections()
+
+    def _build_sections(self) -> list[PromptSection]:
+        """Create all sections with their prerequisite flags."""
+        return [
+            PromptSection(
+                name="Agent_Prompt",
+                content=self._agent_prompt,
+                order=0,
+                prerequisite_met=True,
+            ),
+            PromptSection(
+                name="Base_Prompt_Section",
+                content=BASE_PROMPT_SECTION,
+                order=1,
+                prerequisite_met=True,
+            ),
+            PromptSection(
+                name="Proactive_Section",
+                content=PROACTIVE_SECTION,
+                order=2,
+                prerequisite_met=True,
+            ),
+            PromptSection(
+                name="Shell_Section",
+                content=SHELL_SECTION,
+                order=3,
+                prerequisite_met=self._has_shell_tool,
+            ),
+            PromptSection(
+                name="Workspace_Section",
+                content=WORKSPACE_SECTION,
+                order=4,
+                prerequisite_met=self._has_workspace,
+            ),
+            PromptSection(
+                name="Skills_Discovery_Section",
+                content=SKILLS_DISCOVERY_PROMPT,
+                order=5,
+                prerequisite_met=self._skills_enabled and bool(SKILLS_DISCOVERY_PROMPT),
+            ),
+        ]
+
+    def build(self) -> str:
+        """Assemble the final prompt from active sections in canonical order."""
+        active = sorted(
+            [s for s in self._sections if s.prerequisite_met],
+            key=lambda s: s.order,
+        )
+        return self.SECTION_SEPARATOR.join(s.content for s in active)
+
+    def get_active_sections(self) -> list[str]:
+        """Return the list of active section names in canonical order."""
+        return [s.name for s in sorted(self._sections, key=lambda s: s.order) if s.prerequisite_met]
+
+    def get_sections(self) -> list[PromptSection]:
+        """Return all registered sections (active and inactive)."""
+        return list(self._sections)
+
+    @staticmethod
+    def parse_sections(assembled_prompt: str) -> list[PromptSection]:
+        """Parse an assembled prompt back into its constituent sections.
+
+        Each section is delimited by a markdown header: ## Section Name
+        The agent prompt (first section) has no header delimiter.
+        """
+        # Split on ## headers while keeping the delimiter
+        parts = re.split(r"(?=^## )", assembled_prompt, flags=re.MULTILINE)
+
+        sections: list[PromptSection] = []
+
+        for i, part in enumerate(parts):
+            if not part:
+                continue
+
+            if i == 0 and not part.startswith("## "):
+                # First part is the agent prompt (no ## header)
+                sections.append(
+                    PromptSection(
+                        name="Agent_Prompt",
+                        content=part.rstrip("\n"),
+                        order=0,
+                    )
+                )
+            else:
+                # Extract section name from the ## header line
+                lines = part.split("\n", 1)
+                header = lines[0]
+                name = header.lstrip("# ").strip()
+                sections.append(
+                    PromptSection(
+                        name=name,
+                        content=part.rstrip("\n"),
+                        order=len(sections),
+                    )
+                )
+
+        return sections
+
+    def get_token_estimate(self) -> int:
+        """Return approximate token count of framework-added sections.
+
+        Excludes agent prompt and skills discovery section.
+        Uses len(text) / 4 as approximation.
+        """
+        framework_sections = [
+            s
+            for s in self._sections
+            if s.prerequisite_met and s.name not in ("Agent_Prompt", "Skills_Discovery_Section")
+        ]
+        total_chars = sum(len(s.content) for s in framework_sections)
+        return int(total_chars / 4)

{agent_framework_lib-0.8.5 → agent_framework_lib-0.8.6}/agent_framework/memory/providers/graphiti_provider.py

@@ -46,6 +46,7 @@ Version: 0.1.0
 
 import logging
 import re
+import unicodedata
 from datetime import datetime
 from typing import Any
 
@@ -58,29 +59,34 @@ logger = logging.getLogger(__name__)
 
 def _sanitize_for_redisearch(text: str) -> str:
     """
-    Sanitize text to avoid RediSearch syntax errors.
-
-    RediSearch has special characters that need escaping or removal:
-    - | (OR operator)
-    - / (path separator, causes issues)
-    - @ (field prefix)
-    - : (field separator)
-    - ( ) (grouping)
-    - [ ] (range)
-    - { } (tag)
-    - " (phrase)
-    - ~ (fuzzy)
-    - * (wildcard)
-    - - (negation)
-    - ' (escape)
-
-    We replace problematic characters with spaces to preserve word boundaries.
+    Sanitize text to avoid RediSearch syntax errors and non-ASCII payloads.
+
+    RediSearch rejects multi-byte UTF-8 sequences in many query contexts and
+    has special syntactic characters that must be removed:
+    - | (OR operator), / (path separator), @ (field prefix), : (field separator)
+    - ( ) (grouping), [ ] (range), { } (tag), " (phrase), ~ (fuzzy)
+    - * (wildcard), - (negation), ' (escape), \\ (escape)
+
+    Pipeline:
+    1. Normalize via NFKD to decompose accented characters
+       (e.g. ``é`` → ``e`` + combining acute accent).
+    2. Drop every combining mark and any character with ``ord >= 128``,
+       producing ASCII-only output (``résumé`` → ``resume``).
+    3. Replace RediSearch-special characters with spaces to preserve
+       word boundaries, then collapse runs of whitespace.
+
+    The transliteration step preserves the semantic intent of the search
+    text. Falling back to ``encode("ascii", "ignore")`` would have stripped
+    the accented characters entirely (``résumé`` → ``rsum``), which is much
+    less useful for keyword search.
     """
-    # Characters that cause RediSearch syntax errors
+    # 1. Decompose accented characters into base + combining marks.
+    decomposed = unicodedata.normalize("NFKD", text)
+    # 2. Drop combining marks and any residual non-ASCII characters.
+    ascii_only = "".join(c for c in decomposed if not unicodedata.combining(c) and ord(c) < 128)
+    # 3. Strip RediSearch special characters and collapse whitespace.
     special_chars = r'[|/@:(){}\[\]"~*\-\'\\/]'
-    # Replace with space to preserve word boundaries
-    sanitized = re.sub(special_chars, " ", text)
-    # Collapse multiple spaces
+    sanitized = re.sub(special_chars, " ", ascii_only)
     sanitized = re.sub(r"\s+", " ", sanitized)
     return sanitized.strip()