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

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

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

@@ -107,6 +107,7 @@ class BudgetSnapshot:
     tool_definition_multiplier: float = 1.0
     raw_tool_tokens: int = 0
     estimated_tool_tokens: int = 0
+    tool_fixed_overhead: int = 0
 
 
 class ContextBudgetManager:
@@ -140,6 +141,7 @@ class ContextBudgetManager:
         self._tool_definition_tokens = 0
         self._raw_tool_tokens = 0
         self._tool_definition_multiplier = 1.0
+        self._tool_fixed_overhead = 0
 
         # Resolution order: explicit parameter > env var > class constant
         def _resolve(param, env_key, default):
@@ -248,18 +250,19 @@ class ContextBudgetManager:
             total = self._token_counter.count_tokens(message.content or "").count
         return total
 
-    # Anthropic (et d'autres providers) sérialisent les tool definitions avec un
-    # wrapping XML/JSON lourd qui multiplie le coût en tokens par rapport à ce que
-    # tiktoken estime sur le JSON brut. Empiriquement, le ratio est ~14x pour
-    # Anthropic. On utilise 15x comme marge de sécurité.
-    TOOL_DEFINITION_MULTIPLIER = 15
+    # Les providers sérialisent les tool definitions avec un wrapping qui ajoute
+    # un overhead par rapport au JSON brut. Le modèle de calibration utilise :
+    # estimated_tokens = raw_tokens * multiplier + fixed_overhead
+    # Voir provider_calibration.py pour les valeurs par provider.
+    TOOL_DEFINITION_MULTIPLIER = 1.4  # Anthropic default, overridden per-provider
 
     def set_sacred_zone(self, system_prompt: str, tool_definitions: str) -> int:
         """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 calibré par provider car
-        les providers sérialisent les définitions avec un wrapping lourd.
+        Les tool definitions reçoivent un multiplicateur calibré par provider
+        (wrapping XML/JSON) plus un overhead fixe (system prompt tool-use injecté
+        par le provider).
 
         Args:
             system_prompt: Prompt système complet (agent + skills + mémoire passive).
@@ -273,16 +276,25 @@ class ContextBudgetManager:
         self._tool_definition_multiplier = ProviderCalibrationRegistry.get_multiplier(
             self._model_name
         )
-        self._tool_definition_tokens = int(
-            self._raw_tool_tokens * self._tool_definition_multiplier
+        self._tool_fixed_overhead = ProviderCalibrationRegistry.get_fixed_overhead(
+            self._model_name
         )
+        # estimated = raw * multiplier + fixed_overhead (only if tools are present)
+        if self._raw_tool_tokens > 0:
+            self._tool_definition_tokens = (
+                int(self._raw_tool_tokens * self._tool_definition_multiplier)
+                + self._tool_fixed_overhead
+            )
+        else:
+            self._tool_definition_tokens = 0
         self._sacred_zone_tokens = self._prompt_tokens + self._tool_definition_tokens
         logger.info(
-            "Sacred zone: %d tokens (prompt=%d, tools=%d raw * %.1fx = %d)",
+            "Sacred zone: %d tokens (prompt=%d, tools=%d raw * %.1fx + %d overhead = %d)",
             self._sacred_zone_tokens,
             self._prompt_tokens,
             self._raw_tool_tokens,
             self._tool_definition_multiplier,
+            self._tool_fixed_overhead if self._raw_tool_tokens > 0 else 0,
             self._tool_definition_tokens,
         )
         if self._sacred_zone_tokens > 0.65 * self._context_window:
@@ -354,7 +366,8 @@ class ContextBudgetManager:
             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),
+            estimated_tool_tokens=self._tool_definition_tokens,
+            tool_fixed_overhead=self._tool_fixed_overhead,
         )
 
     async def enforce_budget(
@@ -593,7 +606,8 @@ class ContextBudgetManager:
             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),
+            estimated_tool_tokens=self._tool_definition_tokens,
+            tool_fixed_overhead=self._tool_fixed_overhead,
         )
 
     async def truncate_query_if_needed(

{agent_framework_lib-0.6.2 → agent_framework_lib-0.6.2.post2}/agent_framework/core/provider_calibration.py

@@ -1,8 +1,16 @@
-"""Provider-specific token calibration for tool definition multipliers.
+"""Provider-specific token calibration for tool definition overhead.
 
-Provides empirically measured multipliers that account for the overhead
-each LLM provider adds when serializing tool definitions (XML wrapping,
-JSON function-calling format, etc.).
+Provides calibration factors that account for the overhead each LLM provider
+adds when serializing tool definitions. The model uses a fixed overhead
+(provider system prompt for tool-use) plus a multiplier on the raw tool
+definition tokens (XML/JSON wrapping per tool).
+
+Previous calibration (2025-01) used a single 15x multiplier for Anthropic,
+which was based on per-tool count_tokens calls that double-counted the shared
+system overhead. See: https://www.async-let.com/posts/claude-code-mcp-token-reporting
+
+Current calibration (2026-03) uses overhead + multiplier, measured against
+Anthropic's batch count_tokens endpoint and OpenAI's tiktoken validation.
 """
 
 from __future__ import annotations
@@ -19,6 +27,7 @@ class ProviderCalibration:
 
     provider_name: str
     tool_definition_multiplier: float
+    fixed_overhead_tokens: int
     source: str
     measured_date: str
     notes: str = ""
@@ -27,35 +36,46 @@ class ProviderCalibration:
 class ProviderCalibrationRegistry:
     """Registry of per-provider token calibration data.
 
-    Resolves the appropriate tool-definition multiplier for a given model
+    Resolves the appropriate tool-definition overhead for a given model
     by detecting the provider from the model name.
+
+    The total estimated tool tokens = raw_tokens * multiplier + fixed_overhead.
     """
 
     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",
+            tool_definition_multiplier=1.4,
+            fixed_overhead_tokens=350,
+            source="batch_count_tokens_measurement_2026-03",
+            measured_date="2026-03",
+            notes=(
+                "Anthropic injects a hidden tool-use system prompt (~350 tokens) "
+                "and wraps each tool in XML. The 1.4x multiplier accounts for "
+                "XML wrapping overhead on the raw JSON schema. Previous 15x was "
+                "based on per-tool counting that repeated the system overhead."
+            ),
         ),
         "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",
+            tool_definition_multiplier=1.1,
+            fixed_overhead_tokens=100,
+            source="tiktoken_validation_2026-03",
+            measured_date="2026-03",
+            notes="OpenAI function-calling format, minimal overhead over JSON schema",
         ),
         "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",
+            tool_definition_multiplier=1.2,
+            fixed_overhead_tokens=150,
+            source="estimated_2026-03",
+            measured_date="2026-03",
+            notes="Gemini tool-use format, similar to OpenAI with slight extra wrapping",
         ),
     }
 
-    DEFAULT_MULTIPLIER: float = 5.0
+    DEFAULT_MULTIPLIER: float = 1.5
+    DEFAULT_FIXED_OVERHEAD: int = 200
 
     # Prefix-to-provider mapping for model name detection
     _PROVIDER_PREFIXES: dict[str, str] = {
@@ -105,7 +125,7 @@ class ProviderCalibrationRegistry:
     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
+        Falls back to DEFAULT_MULTIPLIER and logs INFO when the
         provider is not recognized.
 
         Args:
@@ -124,3 +144,21 @@ class ProviderCalibrationRegistry:
             cls.DEFAULT_MULTIPLIER,
         )
         return cls.DEFAULT_MULTIPLIER
+
+    @classmethod
+    def get_fixed_overhead(cls, model_name: str) -> int:
+        """Resolve the fixed tool-use overhead tokens for a model.
+
+        This accounts for the hidden system prompt that providers inject
+        when tools are present (e.g. Anthropic's tool-use preamble).
+
+        Args:
+            model_name: Name of the LLM model.
+
+        Returns:
+            Fixed overhead in tokens, or the default.
+        """
+        calibration = cls.get_calibration(model_name)
+        if calibration is not None:
+            return calibration.fixed_overhead_tokens
+        return cls.DEFAULT_FIXED_OVERHEAD

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-lib
-Version: 0.6.2
+Version: 0.6.2.post2
 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.2 → agent_framework_lib-0.6.2.post2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-framework-lib"
-version = "0.6.2"
+version = "0.6.2post2"
 description = "A comprehensive Python framework for building and serving conversational AI agents with FastAPI"
 readme = {file = "README.md", content-type = "text/markdown"}
 license = {text = "MIT"}