agent-framework-lib 0.6.1__tar.gz → 0.6.2__tar.gz

{agent_framework_lib-0.6.1/agent_framework_lib.egg-info → agent_framework_lib-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-lib
-Version: 0.6.1
+Version: 0.6.2
 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.6.1 → agent_framework_lib-0.6.2}/agent_framework/__init__.py

@@ -32,7 +32,7 @@ Example Usage:
     create_basic_agent_server(MyAgent, port=8000)
     ```
 
-Version: 0.6.1
+Version: 0.6.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.6.1"
+__version__ = "0.6.2"
 __author__ = "Cinco AI Team"
 __license__ = "MIT"
 __email__ = "sebastian@cinco.ai"

{agent_framework_lib-0.6.1 → agent_framework_lib-0.6.2}/agent_framework/core/context_budget.py

@@ -10,6 +10,8 @@ import logging
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
+from agent_framework.core.provider_calibration import ProviderCalibrationRegistry
+
 if TYPE_CHECKING:
     from llama_index.core.llms import ChatMessage
 
@@ -102,6 +104,9 @@ class BudgetSnapshot:
     usage_percent: float
     compression_triggered: bool
     model_name: str
+    tool_definition_multiplier: float = 1.0
+    raw_tool_tokens: int = 0
+    estimated_tool_tokens: int = 0
 
 
 class ContextBudgetManager:
@@ -133,6 +138,8 @@ class ContextBudgetManager:
         self._sacred_zone_tokens = 0
         self._prompt_tokens = 0
         self._tool_definition_tokens = 0
+        self._raw_tool_tokens = 0
+        self._tool_definition_multiplier = 1.0
 
         # Resolution order: explicit parameter > env var > class constant
         def _resolve(param, env_key, default):
@@ -251,8 +258,8 @@ class ContextBudgetManager:
         """Compte et enregistre les tokens de la Zone Sacrée.
 
         Le system prompt est compté tel quel (tiktoken est fiable pour du texte).
-        Les tool definitions reçoivent un multiplicateur car les providers
-        (Anthropic notamment) les sérialisent avec un wrapping lourd.
+        Les tool definitions reçoivent un multiplicateur calibré par provider car
+        les providers sérialisent les définitions avec un wrapping lourd.
 
         Args:
             system_prompt: Prompt système complet (agent + skills + mémoire passive).
@@ -262,15 +269,20 @@ class ContextBudgetManager:
             Nombre total estimé de tokens de la Zone Sacrée.
         """
         self._prompt_tokens = self._token_counter.count_tokens(system_prompt).count
-        raw_tool_tokens = self._token_counter.count_tokens(tool_definitions).count
-        self._tool_definition_tokens = raw_tool_tokens * self.TOOL_DEFINITION_MULTIPLIER
+        self._raw_tool_tokens = self._token_counter.count_tokens(tool_definitions).count
+        self._tool_definition_multiplier = ProviderCalibrationRegistry.get_multiplier(
+            self._model_name
+        )
+        self._tool_definition_tokens = int(
+            self._raw_tool_tokens * self._tool_definition_multiplier
+        )
         self._sacred_zone_tokens = self._prompt_tokens + self._tool_definition_tokens
         logger.info(
-            "Sacred zone: %d tokens (prompt=%d, tools=%d raw * %dx = %d)",
+            "Sacred zone: %d tokens (prompt=%d, tools=%d raw * %.1fx = %d)",
             self._sacred_zone_tokens,
             self._prompt_tokens,
-            raw_tool_tokens,
-            self.TOOL_DEFINITION_MULTIPLIER,
+            self._raw_tool_tokens,
+            self._tool_definition_multiplier,
             self._tool_definition_tokens,
         )
         if self._sacred_zone_tokens > 0.65 * self._context_window:
@@ -340,6 +352,9 @@ class ContextBudgetManager:
             usage_percent=usage,
             compression_triggered=False,
             model_name=self._model_name,
+            tool_definition_multiplier=self._tool_definition_multiplier,
+            raw_tool_tokens=self._raw_tool_tokens,
+            estimated_tool_tokens=int(self._raw_tool_tokens * self._tool_definition_multiplier),
         )
 
     async def enforce_budget(
@@ -576,6 +591,9 @@ class ContextBudgetManager:
             usage_percent=usage,
             compression_triggered=True,
             model_name=self._model_name,
+            tool_definition_multiplier=self._tool_definition_multiplier,
+            raw_tool_tokens=self._raw_tool_tokens,
+            estimated_tool_tokens=int(self._raw_tool_tokens * self._tool_definition_multiplier),
         )
 
     async def truncate_query_if_needed(

agent_framework_lib-0.6.2/agent_framework/core/knowledge_state.py

@@ -0,0 +1,228 @@
+"""Knowledge state tracking for scratchpad compression.
+
+Captures and structures knowledge acquired from tool calls,
+preserving it across successive compressions.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from agent_framework.monitoring.token_counter import TokenCounter
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ToolCallSignature:
+    """Unique identifier for a tool call based on name and argument hash."""
+
+    tool_name: str
+    args_hash: str
+
+    @classmethod
+    def from_tool_call(
+        cls, tool_name: str, tool_kwargs: dict[str, Any]
+    ) -> ToolCallSignature:
+        """Compute a deterministic signature from tool name and arguments.
+
+        Uses canonical JSON serialization (sorted keys, compact separators)
+        for the hash. Falls back to str() if JSON serialization fails.
+
+        Args:
+            tool_name: Name of the tool.
+            tool_kwargs: Dictionary of tool arguments.
+
+        Returns:
+            A ToolCallSignature with a SHA-256 hash of the arguments.
+        """
+        try:
+            canonical = json.dumps(tool_kwargs, sort_keys=True, separators=(",", ":"))
+        except (TypeError, ValueError):
+            logger.warning(
+                "JSON serialization failed for tool '%s' args, falling back to str()",
+                tool_name,
+            )
+            canonical = str(tool_kwargs)
+
+        args_hash = hashlib.sha256(canonical.encode()).hexdigest()
+        return cls(tool_name=tool_name, args_hash=args_hash)
+
+    def __hash__(self) -> int:
+        return hash((self.tool_name, self.args_hash))
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, ToolCallSignature):
+            return NotImplemented
+        return self.tool_name == other.tool_name and self.args_hash == other.args_hash
+
+
+@dataclass
+class ToolResultEntry:
+    """Structured result of a tool call."""
+
+    signature: ToolCallSignature
+    tool_name: str
+    arguments: dict[str, Any]
+    status: Literal["success", "error", "truncated"]
+    key_data: dict[str, Any]
+    numeric_values: dict[str, Any]
+    raw_excerpt: str
+    timestamp: float
+
+
+class KnowledgeState:
+    """Accumulated knowledge state, persisted across compressions."""
+
+    def __init__(self) -> None:
+        self._entries: dict[ToolCallSignature, ToolResultEntry] = {}
+
+    def add_entry(self, entry: ToolResultEntry) -> None:
+        """Add or update an entry in the registry.
+
+        Args:
+            entry: The tool result entry to store.
+        """
+        self._entries[entry.signature] = entry
+
+    def get_entry(self, signature: ToolCallSignature) -> ToolResultEntry | None:
+        """Retrieve an entry by its signature.
+
+        Args:
+            signature: The tool call signature to look up.
+
+        Returns:
+            The matching entry, or None if not found.
+        """
+        return self._entries.get(signature)
+
+    def has_signature(self, signature: ToolCallSignature) -> bool:
+        """Check whether a signature is already registered.
+
+        Args:
+            signature: The tool call signature to check.
+
+        Returns:
+            True if the signature exists in the registry.
+        """
+        return signature in self._entries
+
+    def get_all_entries(self) -> list[ToolResultEntry]:
+        """Return all entries in insertion order.
+
+        Returns:
+            List of all stored tool result entries.
+        """
+        return list(self._entries.values())
+
+    def get_entries_by_tool(self, tool_name: str) -> list[ToolResultEntry]:
+        """Return entries filtered by tool name.
+
+        Args:
+            tool_name: Name of the tool to filter by.
+
+        Returns:
+            List of entries matching the given tool name.
+        """
+        return [e for e in self._entries.values() if e.tool_name == tool_name]
+
+    def to_structured_text(self) -> str:
+        """Serialize the full knowledge state as structured text.
+
+        Produces a human-readable representation with sections per tool call
+        and tabular format for numeric data.
+
+        Returns:
+            Structured text representation of all entries.
+        """
+        if not self._entries:
+            return ""
+
+        sections: list[str] = []
+        for entry in self._entries.values():
+            lines: list[str] = []
+            lines.append(f"[{entry.tool_name}] status={entry.status}")
+
+            if entry.arguments:
+                args_str = ", ".join(
+                    f"{k}={v!r}" for k, v in entry.arguments.items()
+                )
+                lines.append(f"  args: {args_str}")
+
+            if entry.numeric_values:
+                lines.append("  numeric_data:")
+                for k, v in entry.numeric_values.items():
+                    lines.append(f"    {k}: {v}")
+
+            if entry.key_data:
+                lines.append("  key_data:")
+                for k, v in entry.key_data.items():
+                    lines.append(f"    {k}: {v}")
+
+            if entry.raw_excerpt:
+                lines.append(f"  excerpt: {entry.raw_excerpt}")
+
+            sections.append("\n".join(lines))
+
+        return "\n\n".join(sections)
+
+    def to_compact_text(self, max_tokens: int, token_counter: TokenCounter) -> str:
+        """Serialize a compact version that fits within a token budget.
+
+        Prioritizes numeric data in tabular form (key: value).
+        Progressively adds content until the budget is reached.
+
+        Args:
+            max_tokens: Maximum number of tokens allowed in the output.
+            token_counter: Token counter instance for measuring output size.
+
+        Returns:
+            Compact text representation respecting the token budget.
+        """
+        if not self._entries or max_tokens <= 0:
+            return ""
+
+        # Phase 1: collect numeric lines (highest priority)
+        numeric_lines: list[str] = []
+        for entry in self._entries.values():
+            if entry.numeric_values:
+                for k, v in entry.numeric_values.items():
+                    numeric_lines.append(f"{k}: {v}")
+
+        # Phase 2: collect tool status headers
+        header_lines: list[str] = []
+        for entry in self._entries.values():
+            header_lines.append(f"[{entry.tool_name}] status={entry.status}")
+
+        # Phase 3: collect key_data lines
+        key_data_lines: list[str] = []
+        for entry in self._entries.values():
+            if entry.key_data:
+                for k, v in entry.key_data.items():
+                    key_data_lines.append(f"{k}: {v}")
+
+        # Phase 4: collect excerpt lines
+        excerpt_lines: list[str] = []
+        for entry in self._entries.values():
+            if entry.raw_excerpt:
+                excerpt_lines.append(f"excerpt: {entry.raw_excerpt}")
+
+        # Build output incrementally, respecting the budget
+        result_lines: list[str] = []
+
+        for line_group in [numeric_lines, header_lines, key_data_lines, excerpt_lines]:
+            for line in line_group:
+                candidate = "\n".join(result_lines + [line]) if result_lines else line
+                count = token_counter.count_tokens(candidate).count
+                if count <= max_tokens:
+                    result_lines.append(line)
+                else:
+                    # Budget exhausted — return what we have
+                    return "\n".join(result_lines)
+
+        return "\n".join(result_lines)

agent_framework_lib-0.6.2/agent_framework/core/loop_detector.py

@@ -0,0 +1,148 @@
+"""Loop detection for repeated tool calls in the scratchpad.
+
+Identifies when the agent is re-executing identical tool calls by
+tracking deterministic signatures and flagging duplicates above a
+configurable threshold.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import Counter
+from dataclasses import dataclass, field
+
+from llama_index.core.llms import ChatMessage, MessageRole
+
+from agent_framework.core.knowledge_state import ToolCallSignature
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class LoopDetectionResult:
+    """Result of a loop detection analysis on the scratchpad."""
+
+    is_loop: bool
+    duplicate_signatures: list[tuple[ToolCallSignature, int]] = field(
+        default_factory=list
+    )
+    total_duplicates: int = 0
+
+
+class LoopDetector:
+    """Detects tool call loops in the scratchpad.
+
+    Traverses ASSISTANT messages containing tool calls, computes a
+    ToolCallSignature for each call, and flags signatures that appear
+    at or above the duplicate threshold.
+    """
+
+    DUPLICATE_THRESHOLD: int = 2
+
+    def detect(self, scratchpad: list[ChatMessage]) -> LoopDetectionResult:
+        """Analyse the scratchpad and detect duplicated tool call signatures.
+
+        Args:
+            scratchpad: List of ChatMessage from the tool loop.
+
+        Returns:
+            A LoopDetectionResult indicating whether a loop was found.
+        """
+        signatures = self._extract_signatures(scratchpad)
+
+        if not signatures:
+            return LoopDetectionResult(is_loop=False)
+
+        counts: Counter[ToolCallSignature] = Counter(signatures)
+
+        duplicate_signatures = [
+            (sig, count)
+            for sig, count in counts.items()
+            if count >= self.DUPLICATE_THRESHOLD
+        ]
+
+        total_duplicates = sum(count for _, count in duplicate_signatures)
+
+        if duplicate_signatures:
+            for sig, count in duplicate_signatures:
+                logger.warning(
+                    "Duplicate tool call detected: tool='%s' args_hash='%s' repeated %d times",
+                    sig.tool_name,
+                    sig.args_hash,
+                    count,
+                )
+
+        return LoopDetectionResult(
+            is_loop=len(duplicate_signatures) > 0,
+            duplicate_signatures=duplicate_signatures,
+            total_duplicates=total_duplicates,
+        )
+
+    def _extract_signatures(
+        self, scratchpad: list[ChatMessage]
+    ) -> list[ToolCallSignature]:
+        """Extract all ToolCallSignatures from ASSISTANT messages.
+
+        Handles both dict-based tool calls in additional_kwargs and
+        ToolCallBlock objects in message blocks.
+
+        Args:
+            scratchpad: List of ChatMessage to scan.
+
+        Returns:
+            List of ToolCallSignature found in the scratchpad.
+        """
+        signatures: list[ToolCallSignature] = []
+
+        for msg in scratchpad:
+            if msg.role != MessageRole.ASSISTANT:
+                continue
+
+            # Dict-based tool calls from additional_kwargs
+            kwargs = msg.additional_kwargs or {}
+            for tc in kwargs.get("tool_calls", []):
+                if isinstance(tc, dict):
+                    name = tc.get("name") or (tc.get("function") or {}).get(
+                        "name", ""
+                    )
+                    arguments = tc.get("arguments") or (
+                        tc.get("function") or {}
+                    ).get("arguments", {})
+
+                    if not name:
+                        continue
+
+                    # arguments may be a JSON string or a dict
+                    if isinstance(arguments, str):
+                        try:
+                            import json
+
+                            arguments = json.loads(arguments)
+                        except (ValueError, TypeError):
+                            arguments = {"_raw": arguments}
+
+                    if not isinstance(arguments, dict):
+                        arguments = {"_raw": str(arguments)}
+
+                    signatures.append(
+                        ToolCallSignature.from_tool_call(name, arguments)
+                    )
+
+            # Block-based tool calls
+            if hasattr(msg, "blocks"):
+                for block in msg.blocks or []:
+                    if type(block).__name__ == "ToolCallBlock":
+                        name = getattr(block, "tool_name", "")
+                        tool_kwargs = getattr(block, "tool_kwargs", {})
+
+                        if not name:
+                            continue
+
+                        if not isinstance(tool_kwargs, dict):
+                            tool_kwargs = {}
+
+                        signatures.append(
+                            ToolCallSignature.from_tool_call(name, tool_kwargs)
+                        )
+
+        return signatures

agent_framework_lib-0.6.2/agent_framework/core/provider_calibration.py

@@ -0,0 +1,126 @@
+"""Provider-specific token calibration for tool definition multipliers.
+
+Provides empirically measured multipliers that account for the overhead
+each LLM provider adds when serializing tool definitions (XML wrapping,
+JSON function-calling format, etc.).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ProviderCalibration:
+    """Calibration factors for an LLM provider's tool definition overhead."""
+
+    provider_name: str
+    tool_definition_multiplier: float
+    source: str
+    measured_date: str
+    notes: str = ""
+
+
+class ProviderCalibrationRegistry:
+    """Registry of per-provider token calibration data.
+
+    Resolves the appropriate tool-definition multiplier for a given model
+    by detecting the provider from the model name.
+    """
+
+    CALIBRATIONS: dict[str, ProviderCalibration] = {
+        "anthropic": ProviderCalibration(
+            provider_name="anthropic",
+            tool_definition_multiplier=15.0,
+            source="empirical_measurement_2025-01",
+            measured_date="2025-01",
+            notes="Heavy XML/JSON wrapping for Anthropic tool definitions",
+        ),
+        "openai": ProviderCalibration(
+            provider_name="openai",
+            tool_definition_multiplier=3.0,
+            source="empirical_measurement_2025-01",
+            measured_date="2025-01",
+            notes="OpenAI function-calling format, moderate overhead",
+        ),
+        "google": ProviderCalibration(
+            provider_name="google",
+            tool_definition_multiplier=4.0,
+            source="empirical_measurement_2025-01",
+            measured_date="2025-01",
+            notes="Gemini tool-use format, overhead similar to OpenAI",
+        ),
+    }
+
+    DEFAULT_MULTIPLIER: float = 5.0
+
+    # Prefix-to-provider mapping for model name detection
+    _PROVIDER_PREFIXES: dict[str, str] = {
+        "claude": "anthropic",
+        "gpt": "openai",
+        "o1": "openai",
+        "o3": "openai",
+        "o4": "openai",
+        "gemini": "google",
+    }
+
+    @classmethod
+    def detect_provider(cls, model_name: str) -> str | None:
+        """Detect the provider from a model name.
+
+        Checks if the model name starts with or contains known prefixes.
+
+        Args:
+            model_name: Name of the LLM model.
+
+        Returns:
+            Provider name (e.g. "anthropic") or None if unrecognized.
+        """
+        lower = model_name.lower()
+        # Check longest prefixes first to avoid false positives
+        for prefix in sorted(cls._PROVIDER_PREFIXES, key=len, reverse=True):
+            if lower.startswith(prefix):
+                return cls._PROVIDER_PREFIXES[prefix]
+        return None
+
+    @classmethod
+    def get_calibration(cls, model_name: str) -> ProviderCalibration | None:
+        """Return the full calibration for a model, or None if unknown.
+
+        Args:
+            model_name: Name of the LLM model.
+
+        Returns:
+            ProviderCalibration if the provider is recognized, else None.
+        """
+        provider = cls.detect_provider(model_name)
+        if provider is None:
+            return None
+        return cls.CALIBRATIONS.get(provider)
+
+    @classmethod
+    def get_multiplier(cls, model_name: str) -> float:
+        """Resolve the tool-definition multiplier for a model.
+
+        Falls back to DEFAULT_MULTIPLIER (5.0) and logs INFO when the
+        provider is not recognized.
+
+        Args:
+            model_name: Name of the LLM model.
+
+        Returns:
+            The provider-specific multiplier, or the default.
+        """
+        calibration = cls.get_calibration(model_name)
+        if calibration is not None:
+            return calibration.tool_definition_multiplier
+
+        logger.info(
+            "No calibration for model '%s', using default multiplier %.1f",
+            model_name,
+            cls.DEFAULT_MULTIPLIER,
+        )
+        return cls.DEFAULT_MULTIPLIER