agent-framework-lib 0.6.3__tar.gz → 0.6.3.post3__tar.gz

{agent_framework_lib-0.6.3/agent_framework_lib.egg-info → agent_framework_lib-0.6.3.post3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-lib
-Version: 0.6.3
+Version: 0.6.3.post3
 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>
@@ -53,6 +53,8 @@ Requires-Dist: markdown>=3.5
 Requires-Dist: playwright>=1.56.0
 Requires-Dist: elasticsearch<9.0.0,>=8.11.0
 Requires-Dist: ddgs>=9.9.3
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: beautifulsoup4>=4.12.0
 Requires-Dist: llama-index>=0.14.16
 Requires-Dist: llama-index-core>=0.14.16
 Requires-Dist: llama-index-workflows>=2.16.0

{agent_framework_lib-0.6.3 → agent_framework_lib-0.6.3.post3}/agent_framework/__init__.py

@@ -88,7 +88,7 @@ def _auto_setup_dependencies() -> None:
 # Track if auto-setup has been done
 _AUTO_SETUP_DONE = False
 
-__version__ = "0.6.3"
+__version__ = "0.6.3post3"
 __author__ = "Cinco AI Team"
 __license__ = "MIT"
 __email__ = "sebastian@cinco.ai"

agent_framework_lib-0.6.3.post3/agent_framework/capabilities/__init__.py

@@ -0,0 +1,10 @@
+"""Capability resolution for token-based access control."""
+
+from .resolver import CapabilityResolverError, CapabilityResolver, CapabilitySet
+
+
+__all__ = [
+    "CapabilitySet",
+    "CapabilityResolver",
+    "CapabilityResolverError",
+]

agent_framework_lib-0.6.3.post3/agent_framework/capabilities/resolver.py

@@ -0,0 +1,175 @@
+"""
+CapabilitySet and CapabilityResolver — token-based capability resolution.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import os
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class CapabilitySet:
+    """Set of capabilities authorized for a session."""
+
+    skill_ids: list[str] = field(default_factory=list)
+    native_tools: list[str] = field(default_factory=list)
+    max_subagent_depth: int = 0
+    env_overrides: dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def empty(cls) -> "CapabilitySet":
+        """Return an empty CapabilitySet (no capabilities authorized)."""
+        return cls()
+
+
+class CapabilityResolverError(Exception):
+    """Raised when the capability source is unreachable or invalid."""
+
+
+class CapabilityResolver:
+    """Resolves authorized capabilities from a token.
+
+    Sources are checked in priority order:
+    1. CAPABILITY_MAP environment variable (JSON inline)
+    2. Local JSON file (json_path)
+    3. HTTP endpoint (http_url)
+    """
+
+    def __init__(
+        self,
+        json_path: Path | None = None,
+        http_url: str | None = None,
+    ) -> None:
+        """Initialize CapabilityResolver.
+
+        Args:
+            json_path: Optional path to a local JSON capability map.
+            http_url: Optional HTTP URL to fetch capabilities from.
+        """
+        self._json_path = json_path
+        self._http_url = http_url
+
+    def resolve(self, api_token: str) -> CapabilitySet:
+        """Return the CapabilitySet authorized for api_token.
+
+        Unknown tokens return CapabilitySet.empty().
+
+        Args:
+            api_token: The API token to resolve.
+
+        Returns:
+            CapabilitySet for the token.
+
+        Raises:
+            CapabilityResolverError: If the configured source is unreachable or invalid.
+        """
+        capability_map = self._load_map()
+        data = capability_map.get(api_token)
+        if data is None:
+            return CapabilitySet.empty()
+        return self._parse_capability_set(data)
+
+    @contextlib.contextmanager
+    def apply_env_overrides(self, capability_set: CapabilitySet) -> Iterator[None]:
+        """Context manager that injects env_overrides into os.environ.
+
+        Keys that were absent before the block are removed on exit.
+        Keys that existed before are restored to their original value.
+
+        Args:
+            capability_set: CapabilitySet whose env_overrides to apply.
+        """
+        overrides = capability_set.env_overrides
+        previous: dict[str, str | None] = {}
+        for key in overrides:
+            previous[key] = os.environ.get(key)
+            os.environ[key] = overrides[key]
+        try:
+            yield
+        finally:
+            for key, old_value in previous.items():
+                if old_value is None:
+                    os.environ.pop(key, None)
+                else:
+                    os.environ[key] = old_value
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _load_map(self) -> dict[str, Any]:
+        """Load the capability map from the highest-priority source."""
+        env_json = os.environ.get("CAPABILITY_MAP")
+        if env_json:
+            try:
+                data = json.loads(env_json)
+                if not isinstance(data, dict):
+                    raise CapabilityResolverError(
+                        "CAPABILITY_MAP must be a JSON object"
+                    )
+                return data
+            except json.JSONDecodeError as exc:
+                raise CapabilityResolverError(
+                    f"Invalid JSON in CAPABILITY_MAP: {exc}"
+                ) from exc
+
+        if self._json_path is not None:
+            try:
+                raw = Path(self._json_path).read_text(encoding="utf-8")
+                data = json.loads(raw)
+                if not isinstance(data, dict):
+                    raise CapabilityResolverError(
+                        f"JSON file must contain an object: {self._json_path}"
+                    )
+                return data
+            except (OSError, json.JSONDecodeError) as exc:
+                raise CapabilityResolverError(
+                    f"Cannot load capability map from {self._json_path}: {exc}"
+                ) from exc
+
+        if self._http_url is not None:
+            try:
+                import httpx
+
+                resp = httpx.get(self._http_url, timeout=10)
+                resp.raise_for_status()
+                data = resp.json()
+                if not isinstance(data, dict):
+                    raise CapabilityResolverError(
+                        f"HTTP response must be a JSON object: {self._http_url}"
+                    )
+                return data
+            except Exception as exc:
+                raise CapabilityResolverError(
+                    f"Cannot reach capability source at {self._http_url}: {exc}"
+                ) from exc
+
+        return {}
+
+    @staticmethod
+    def _parse_capability_set(data: Any) -> CapabilitySet:
+        if not isinstance(data, dict):
+            return CapabilitySet.empty()
+        return CapabilitySet(
+            skill_ids=list(data.get("skill_ids") or []),
+            native_tools=list(data.get("native_tools") or []),
+            max_subagent_depth=int(data.get("max_subagent_depth") or 0),
+            env_overrides=dict(data.get("env_overrides") or {}),
+        )
+
+
+__all__ = [
+    "CapabilitySet",
+    "CapabilityResolver",
+    "CapabilityResolverError",
+]

{agent_framework_lib-0.6.3 → agent_framework_lib-0.6.3.post3}/agent_framework/core/scratchpad_compressor.py

@@ -29,6 +29,11 @@ logger = logging.getLogger(__name__)
 
 TRUNCATION_MARKER = "\n\n[... contenu tronqué ...]\n\n"
 
+# OpenAI enforces a 10 485 760 character limit per message content.
+# We use a conservative 8M limit to leave headroom for JSON serialization
+# overhead, tool_call metadata, and other wrapper text added by the SDK.
+MAX_MESSAGE_CONTENT_CHARS = 8_000_000
+
 
 class ScratchpadCompressor:
     """Compresse le scratchpad de la boucle d'outils pour respecter le budget."""
@@ -106,22 +111,100 @@ class ScratchpadCompressor:
         # Pas de paire trouvée, tout est considéré comme dernière paire
         return [], list(scratchpad)
 
+    @staticmethod
+    def _flatten_message_content(message: ChatMessage) -> str:
+        """Aplatit tous les blocks d'un message en une seule chaîne de texte.
+
+        LlamaIndex stocke le contenu des messages dans des blocks typés
+        (TextBlock, ToolCallBlock, ToolResultBlock, etc.). La propriété
+        .content ne retourne que le texte des TextBlock. Cette méthode
+        sérialise TOUS les blocks pour que la troncature opère sur le
+        contenu réel envoyé à l'API.
+
+        Args:
+            message: ChatMessage à aplatir.
+
+        Returns:
+            Texte complet incluant tous les blocks.
+        """
+        if not hasattr(message, "blocks") or not message.blocks:
+            return message.content or ""
+
+        parts: list[str] = []
+        for block in message.blocks:
+            block_type = type(block).__name__
+            if hasattr(block, "text"):
+                parts.append(block.text or "")
+            elif hasattr(block, "tool_kwargs"):
+                tool_name = getattr(block, "tool_name", "") or ""
+                kwargs = getattr(block, "tool_kwargs", None)
+                if kwargs:
+                    import json as _json
+                    try:
+                        kwargs_str = _json.dumps(kwargs) if isinstance(kwargs, dict) else str(kwargs)
+                    except (TypeError, ValueError):
+                        kwargs_str = str(kwargs)
+                    parts.append(f"[tool_call: {tool_name}({kwargs_str})]")
+                else:
+                    parts.append(f"[tool_call: {tool_name}()]")
+            elif hasattr(block, "tool_output"):
+                output = str(getattr(block, "tool_output", "") or "")
+                parts.append(output)
+            elif block_type == "ImageBlock":
+                parts.append("[image]")
+            else:
+                try:
+                    block_str = str(block)
+                    if len(block_str) > 10:
+                        parts.append(block_str)
+                except Exception:
+                    parts.append("[block non sérialisable]")
+
+        return "\n".join(parts)
+
     def _truncate_single_result(
         self, message: ChatMessage, target_tokens: int
     ) -> ChatMessage:
         """Tronque le contenu d'un tool_result en gardant début + marqueur + fin.
 
+        Aplatit d'abord tous les blocks en texte brut pour que la troncature
+        opère sur le contenu réel (pas seulement .content/TextBlock).
+
+        Applique deux niveaux de troncature :
+        1. Par tokens (budget du context window)
+        2. Par caractères bruts (limite API OpenAI de 10M chars par message)
+
         Args:
             message: Message tool_result à tronquer.
             target_tokens: Nombre cible de tokens pour le message tronqué.
 
         Returns:
-            Nouveau ChatMessage avec le contenu tronqué.
+            Nouveau ChatMessage avec le contenu tronqué (blocks nettoyés).
         """
-        content = message.content or ""
+        content = self._flatten_message_content(message)
+
+        # Garde-fou caractères bruts : tronquer d'abord si on dépasse la
+        # limite API (10M chars) pour éviter un 400 même si le budget
+        # tokens semble OK.
+        content = self._enforce_char_limit(content)
+
         current_tokens = self._token_counter.count_tokens(content).count
 
+        # Nettoyer additional_kwargs pour ne pas conserver les blocks originaux
+        # qui seraient re-sérialisés par LlamaIndex en plus du content tronqué.
+        clean_kwargs = {
+            k: v
+            for k, v in (message.additional_kwargs or {}).items()
+            if k not in ("tool_calls",)
+        }
+
         if current_tokens <= target_tokens or target_tokens <= 0:
+            if content != (message.content or ""):
+                return ChatMessage(
+                    role=message.role,
+                    content=content,
+                    additional_kwargs=clean_kwargs,
+                )
             return message
 
         # Réserver des tokens pour le marqueur de troncature
@@ -142,6 +225,12 @@ class ScratchpadCompressor:
         end_chars = max(0, int(end_tokens * chars_per_token))
 
         if begin_chars + end_chars >= len(content):
+            if content != (message.content or ""):
+                return ChatMessage(
+                    role=message.role,
+                    content=content,
+                    additional_kwargs=clean_kwargs,
+                )
             return message
 
         begin_part = content[:begin_chars]
@@ -151,9 +240,40 @@ class ScratchpadCompressor:
         return ChatMessage(
             role=message.role,
             content=truncated_content,
-            additional_kwargs=message.additional_kwargs,
+            additional_kwargs=clean_kwargs,
         )
 
+    @staticmethod
+    def _enforce_char_limit(content: str, limit: int = MAX_MESSAGE_CONTENT_CHARS) -> str:
+        """Tronque le contenu si sa longueur dépasse la limite en caractères.
+
+        Garde 60% du début et 40% de la fin pour préserver le contexte.
+
+        Args:
+            content: Texte brut du message.
+            limit: Limite en caractères (défaut : MAX_MESSAGE_CONTENT_CHARS).
+
+        Returns:
+            Contenu tronqué si nécessaire, sinon inchangé.
+        """
+        if len(content) <= limit:
+            return content
+
+        marker_len = len(TRUNCATION_MARKER)
+        available = max(0, limit - marker_len)
+        begin_chars = int(available * 0.6)
+        end_chars = available - begin_chars
+
+        logger.warning(
+            "Message content exceeds char limit (%d > %d), truncating",
+            len(content),
+            limit,
+        )
+
+        begin_part = content[:begin_chars]
+        end_part = content[-end_chars:] if end_chars > 0 else ""
+        return begin_part + TRUNCATION_MARKER + end_part
+
     async def compress(
         self,
         scratchpad: list[ChatMessage],
@@ -316,7 +436,7 @@ class ScratchpadCompressor:
         result = list(old_entries)
         while result and total > target_tokens:
             removed = result.pop(0)
-            total -= self._token_counter.count_tokens(removed.content or "").count
+            total -= self._count_tokens([removed])
         return result
 
     def _truncate_last_pair(
@@ -326,6 +446,9 @@ class ScratchpadCompressor:
     ) -> list[ChatMessage]:
         """Tronque le tool_result dans la dernière paire pour respecter le budget.
 
+        Utilise _count_tokens (blocks-aware) pour compter les tokens du
+        message ASSISTANT, pas seulement .content.
+
         Args:
             last_pair: Dernière paire de messages (tool_call + tool_result).
             available_tokens: Tokens disponibles pour toute la paire.
@@ -341,7 +464,7 @@ class ScratchpadCompressor:
                 remaining = max(0, available_tokens - tokens_used)
                 result.append(self._truncate_single_result(msg, remaining))
             else:
-                tokens_used += self._token_counter.count_tokens(msg.content or "").count
+                tokens_used += self._count_tokens([msg])
                 result.append(msg)
 
         return result

{agent_framework_lib-0.6.3 → agent_framework_lib-0.6.3.post3}/agent_framework/implementations/budget_aware_agent.py

@@ -20,6 +20,7 @@ from llama_index.core.workflow import Context
 
 from agent_framework.core.knowledge_state import ToolCallSignature
 from agent_framework.core.loop_detector import LoopDetector
+from agent_framework.core.scratchpad_compressor import MAX_MESSAGE_CONTENT_CHARS
 
 if TYPE_CHECKING:
     from agent_framework.core.context_budget import ContextBudgetManager
@@ -176,14 +177,66 @@ class BudgetAwareFunctionAgent(FunctionAgent):
                     "Compressing scratchpad: usage %.1f%% >= 80%% threshold",
                     usage_percent,
                 )
-                compressed_scratchpad = await self._scratchpad_compressor.compress(
-                    scratchpad=scratchpad,
-                    llm_input=llm_input,
-                    context_window=context_window,
-                    sacred_zone_tokens=sacred_zone_tokens,
-                    model_name=getattr(self.llm, "model", None),
-                )
-                await ctx.store.set(self.scratchpad_key, compressed_scratchpad)
+
+                # Boucle de compression : re-vérifier après chaque passe
+                # car la première compression peut ne pas suffire (ex: blocks
+                # non aplatis, écart de tokenisation).
+                max_compression_passes = 3
+                for compression_pass in range(max_compression_passes):
+                    compressed_scratchpad = await self._scratchpad_compressor.compress(
+                        scratchpad=scratchpad,
+                        llm_input=llm_input,
+                        context_window=context_window,
+                        sacred_zone_tokens=sacred_zone_tokens,
+                        model_name=getattr(self.llm, "model", None),
+                    )
+                    await ctx.store.set(self.scratchpad_key, compressed_scratchpad)
+
+                    # Recalculer le total après compression
+                    new_scratchpad_tokens = self._count_total_tokens([], compressed_scratchpad)
+                    new_total = sacred_zone_tokens + llm_input_tokens + new_scratchpad_tokens
+                    new_usage = new_total / context_window * 100 if context_window > 0 else 0.0
+
+                    logger.info(
+                        "Post-compression pass %d: %d/%d tokens (%.1f%%), scratchpad=%d",
+                        compression_pass + 1,
+                        new_total,
+                        context_window,
+                        new_usage,
+                        new_scratchpad_tokens,
+                    )
+
+                    if new_usage < 80:
+                        break
+
+                    # Préparer la prochaine passe avec le scratchpad compressé
+                    scratchpad = compressed_scratchpad
+
+                    if compression_pass == max_compression_passes - 1:
+                        logger.error(
+                            "Scratchpad still at %.1f%% after %d compression passes",
+                            new_usage,
+                            max_compression_passes,
+                        )
+
+        # Garde-fou caractères bruts : même après compression en tokens,
+        # un message peut dépasser la limite API (10M chars). On tronque
+        # chaque message du scratchpad qui dépasse avant l'appel LLM.
+        if self._scratchpad_compressor:
+            scratchpad = await ctx.store.get(self.scratchpad_key, default=[])
+            patched = False
+            for i, msg in enumerate(scratchpad):
+                content = msg.content or ""
+                if len(content) > MAX_MESSAGE_CONTENT_CHARS:
+                    from agent_framework.core.scratchpad_compressor import ScratchpadCompressor
+                    scratchpad[i] = ChatMessage(
+                        role=msg.role,
+                        content=ScratchpadCompressor._enforce_char_limit(content),
+                        additional_kwargs=msg.additional_kwargs,
+                    )
+                    patched = True
+            if patched:
+                await ctx.store.set(self.scratchpad_key, scratchpad)
 
         return await super().take_step(ctx, llm_input, tools, memory)
 

{agent_framework_lib-0.6.3 → agent_framework_lib-0.6.3.post3}/agent_framework/implementations/llamaindex_agent.py

@@ -61,9 +61,18 @@ logger = logging.getLogger(__name__)
 
 
 def _detect_is_error(tool_output: str) -> bool:
-    """Return True if tool_output contains an error marker (case-insensitive)."""
+    """Return True if tool_output contains an error marker (case-insensitive).
+
+    Excludes false positives like 'isError=False' or 'is_error: false' where
+    the word 'error' appears only as part of a negative flag.
+    """
+    import re
+
     lowered = tool_output.lower()
-    return any(marker in lowered for marker in ("error", "exception", "failed"))
+    # Strip patterns like "iserror=false", "is_error=false", "iserror: false"
+    # before checking for error markers to avoid false positives from MCP tool output.
+    cleaned = re.sub(r"is_?error\s*[=:]\s*false", "", lowered)
+    return any(marker in cleaned for marker in ("error", "exception", "failed"))
 
 
 class _StreamingActivityAccumulator:
@@ -1104,8 +1113,12 @@ class LlamaIndexAgent(BaseAgent):
                 tool_name = getattr(event, "tool_name", "unknown_tool")
                 tool_kwargs = getattr(event, "tool_kwargs", {}) or {}
                 call_id = getattr(event, "call_id", None) or "unknown"
-                tool_output = str(getattr(event, "tool_output", ""))
-                is_error = _detect_is_error(tool_output)
+                raw_tool_output = getattr(event, "tool_output", "")
+                tool_output = str(raw_tool_output)
+                # Prefer the structured is_error flag from ToolOutput when available,
+                # fall back to text-based heuristic detection.
+                native_is_error = getattr(raw_tool_output, "is_error", None)
+                is_error = native_is_error if isinstance(native_is_error, bool) else _detect_is_error(tool_output)
                 ts = datetime.now(timezone.utc).isoformat()
 
                 self._pending_events.append({

{agent_framework_lib-0.6.3 → agent_framework_lib-0.6.3.post3}/agent_framework/skills/agent_mixin.py

@@ -28,6 +28,7 @@ The mixin provides:
 
 import logging
 from collections.abc import Callable
+from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 
@@ -126,23 +127,21 @@ class SkillsMixin:
         self._skill_registry.unload(name)
         logger.info(f"Unloaded skill '{name}' for agent '{getattr(self, 'agent_id', 'unknown')}'")
 
-    def register_builtin_skills(self) -> None:
-        """
-        Register all built-in skills with this agent.
+    def register_builtin_skills(self, source: str = "python") -> None:
+        """Register all built-in skills with this agent.
 
-        This method registers all pre-built skills from the builtin module,
-        making them available for discovery and loading.
-        
-        Note: Skills that are already registered will be skipped to avoid
-        duplicate registration.
+        Args:
+            source: Loading strategy passed to ``get_all_builtin_skills``.
+                Use ``"python"`` (default) for Python factory functions or
+                ``"markdown"`` to load from SKILL.md files.
+                Skills already registered are skipped.
         """
         from .builtin import get_all_builtin_skills
 
-        builtin_skills = get_all_builtin_skills()
+        builtin_skills = get_all_builtin_skills(source=source)  # type: ignore[call-arg]
         registered_count = 0
-        
+
         for skill in builtin_skills:
-            # Skip if already registered
             if self._skill_registry.get(skill.metadata.name) is not None:
                 continue
             self.register_skill(skill)
@@ -151,7 +150,7 @@ class SkillsMixin:
         if registered_count > 0:
             logger.info(
                 f"Registered {registered_count} built-in skills "
-                f"for agent '{getattr(self, 'agent_id', 'unknown')}'"
+                f"for agent '{getattr(self, 'agent_id', 'unknown')}' (source={source!r})"
             )
         elif builtin_skills:
             logger.debug(
@@ -328,6 +327,59 @@ class SkillsMixin:
         logger.info(f"🔧 Configured context for {configured_count} skill tools")
 
 
+    def register_skills_from_dir(self, skills_dir: Path) -> None:
+        """Load all SKILL.md files from a directory and register them.
+
+        Native tools (ShellTool, WebFetchTool) are attached to each loaded skill
+        if not already present.
+
+        Args:
+            skills_dir: Directory containing SKILL.md files.
+
+        Raises:
+            ValueError: If the directory does not exist.
+        """
+        from agent_framework.skills.markdown_loader import MarkdownSkillLoader
+        from agent_framework.tools.shell_tool import ShellTool
+        from agent_framework.tools.web_fetch_tool import WebFetchTool
+
+        skills_dir = Path(skills_dir)
+        if not skills_dir.exists() or not skills_dir.is_dir():
+            raise ValueError(f"Skills directory not found: {skills_dir}")
+
+        loader = MarkdownSkillLoader()
+        skills = loader.load_from_dir(skills_dir)
+
+        for skill in skills:
+            existing_types = {type(t) for t in skill.tools}
+            if ShellTool not in existing_types:
+                skill.tools.append(ShellTool())
+            if WebFetchTool not in existing_types:
+                skill.tools.append(WebFetchTool())
+            try:
+                self._skill_registry.register(skill)
+                logger.debug("Registered SKILL.md skill '%s'", skill.metadata.name)
+            except Exception as exc:
+                logger.warning(
+                    "Could not register skill '%s': %s", skill.metadata.name, exc
+                )
+
+    def apply_capability_set(self, capability_set: "Any") -> None:
+        """Filter the SkillRegistry to only keep skills in capability_set.skill_ids.
+
+        This method is idempotent: applying the same CapabilitySet twice produces
+        the same registry state.
+
+        Args:
+            capability_set: A CapabilitySet instance with a skill_ids attribute.
+        """
+        allowed = set(capability_set.skill_ids)
+        all_names = [m.name for m in self._skill_registry.list_all()]
+        for name in all_names:
+            if name not in allowed:
+                self._skill_registry.unregister(name)
+
+
 __all__ = [
     "SkillsMixin",
 ]

{agent_framework_lib-0.6.3 → agent_framework_lib-0.6.3.post3}/agent_framework/skills/base.py

@@ -52,6 +52,10 @@ class SkillMetadata(BaseModel):
         default="general", description="Category: document, data, web, visualization, etc."
     )
     version: str = Field(default="1.0.0", description="Skill version")
+    requires_bins: list[str] = Field(default_factory=list, description="Required system binaries")
+    requires_env: list[str] = Field(
+        default_factory=list, description="Required environment variables"
+    )
 
     def matches_query(self, query: str) -> bool:
         """