aiecs 1.7.6__py3-none-any.whl → 1.7.17__py3-none-any.whl

aiecs/__init__.py

@@ -5,7 +5,7 @@ A powerful Python middleware framework for building AI-powered applications
 with tool orchestration, task execution, and multi-provider LLM support.
 """
 
-__version__ = "1.7.6"
+__version__ = "1.7.17"
 __author__ = "AIECS Team"
 __email__ = "iretbl@gmail.com"
 

aiecs/config/tool_config.py

@@ -212,21 +212,51 @@ class ToolConfigLoader:
                 logger.warning(f"Failed to load {global_config_path}: {e}. Skipping.")
 
         # Load tool-specific config (higher precedence)
+        # Try multiple locations:
+        # 1. config/tools/{tool_name}.yaml (standard location)
+        # 2. config/{tool_name}.yaml (direct in config_dir, for custom paths)
         tools_dir = config_dir / "tools"
+        search_dirs = []
         if tools_dir.exists() and tools_dir.is_dir():
-            tool_config_path = tools_dir / f"{tool_name}.yaml"
-            if tool_config_path.exists():
-                try:
-                    with open(tool_config_path, "r", encoding="utf-8") as f:
-                        tool_data = yaml.safe_load(f)
-                        if tool_data:
-                            # Merge tool-specific config (overrides global)
-                            merged_config.update(tool_data)
-                            logger.debug(f"Loaded tool-specific config from {tool_config_path}")
-                except yaml.YAMLError as e:
-                    logger.warning(f"Invalid YAML in {tool_config_path}: {e}. Skipping.")
-                except Exception as e:
-                    logger.warning(f"Failed to load {tool_config_path}: {e}. Skipping.")
+            search_dirs.append(tools_dir)
+        # Also search directly in config_dir for custom path structures
+        search_dirs.append(config_dir)
+        
+        # Try multiple naming conventions for tool config files
+        # 1. {tool_name}.yaml (e.g., image.yaml)
+        # 2. {tool_name}_tool.yaml (e.g., image_tool.yaml)
+        # 3. {ToolName}.yaml (e.g., ImageTool.yaml)
+        possible_names = [
+            f"{tool_name}.yaml",
+            f"{tool_name}_tool.yaml",
+        ]
+        # Also try with capitalized class name if tool_name is lowercase
+        if tool_name.islower():
+            class_name = tool_name.replace("_", "").title() + "Tool"
+            possible_names.append(f"{class_name}.yaml")
+        
+        tool_config_path = None
+        for search_dir in search_dirs:
+            for name in possible_names:
+                candidate_path = search_dir / name
+                if candidate_path.exists():
+                    tool_config_path = candidate_path
+                    break
+            if tool_config_path:
+                break
+        
+        if tool_config_path:
+            try:
+                with open(tool_config_path, "r", encoding="utf-8") as f:
+                    tool_data = yaml.safe_load(f)
+                    if tool_data:
+                        # Merge tool-specific config (overrides global)
+                        merged_config.update(tool_data)
+                        logger.debug(f"Loaded tool-specific config from {tool_config_path}")
+            except yaml.YAMLError as e:
+                logger.warning(f"Invalid YAML in {tool_config_path}: {e}. Skipping.")
+            except Exception as e:
+                logger.warning(f"Failed to load {tool_config_path}: {e}. Skipping.")
 
         return merged_config
 
@@ -362,17 +392,23 @@ class ToolConfigLoader:
             logger.debug(f"Loaded config for {tool_name}: {len(merged_config)} keys")
             return merged_config
 
-    def set_config_path(self, path: Union[str, Path]) -> None:
+    def set_config_path(self, path: Optional[Union[str, Path]] = None) -> None:
         """
         Set custom config path.
 
         Args:
-            path: Path to config directory or file
+            path: Path to config directory or file. If None, resets to auto-discovery.
         """
-        self._config_path = Path(path)
-        # Clear cached config directory to force re-discovery
-        self._cached_config_dir = None
-        logger.info(f"Set custom config path: {self._config_path}")
+        if path is None:
+            self._config_path = None
+            # Clear cached config directory to force re-discovery
+            self._cached_config_dir = None
+            logger.info("Reset config path to auto-discovery")
+        else:
+            self._config_path = Path(path)
+            # Clear cached config directory to force re-discovery
+            self._cached_config_dir = None
+            logger.info(f"Set custom config path: {self._config_path}")
 
     def get_config_path(self) -> Optional[Path]:
         """

aiecs/domain/agent/base_agent.py

@@ -1296,6 +1296,67 @@ class BaseAIAgent(ABC):
 
         self._metrics.updated_at = datetime.utcnow()
 
+    def update_cache_metrics(
+        self,
+        cache_read_tokens: Optional[int] = None,
+        cache_creation_tokens: Optional[int] = None,
+        cache_hit: Optional[bool] = None,
+    ) -> None:
+        """
+        Update prompt cache metrics from LLM response.
+
+        This method tracks provider-level prompt caching statistics to monitor
+        cache hit rates and token savings.
+
+        Args:
+            cache_read_tokens: Tokens read from cache (indicates cache hit)
+            cache_creation_tokens: Tokens used to create a new cache entry
+            cache_hit: Whether the request hit a cached prompt prefix
+
+        Example:
+            # After receiving LLM response
+            agent.update_cache_metrics(
+                cache_read_tokens=response.cache_read_tokens,
+                cache_creation_tokens=response.cache_creation_tokens,
+                cache_hit=response.cache_hit
+            )
+        """
+        # Track LLM request count
+        self._metrics.total_llm_requests += 1
+
+        # Track cache hit/miss
+        if cache_hit is True:
+            self._metrics.cache_hits += 1
+        elif cache_hit is False:
+            self._metrics.cache_misses += 1
+        elif cache_read_tokens is not None and cache_read_tokens > 0:
+            # Infer cache hit from tokens
+            self._metrics.cache_hits += 1
+        elif cache_creation_tokens is not None and cache_creation_tokens > 0:
+            # Infer cache miss from creation tokens
+            self._metrics.cache_misses += 1
+
+        # Update cache hit rate
+        total_cache_requests = self._metrics.cache_hits + self._metrics.cache_misses
+        if total_cache_requests > 0:
+            self._metrics.cache_hit_rate = self._metrics.cache_hits / total_cache_requests
+
+        # Track cache tokens
+        if cache_read_tokens is not None and cache_read_tokens > 0:
+            self._metrics.total_cache_read_tokens += cache_read_tokens
+            # Provider-level caching saves ~90% of token cost for cached tokens
+            self._metrics.estimated_cache_savings_tokens += int(cache_read_tokens * 0.9)
+
+        if cache_creation_tokens is not None and cache_creation_tokens > 0:
+            self._metrics.total_cache_creation_tokens += cache_creation_tokens
+
+        self._metrics.updated_at = datetime.utcnow()
+        logger.debug(
+            f"Agent {self.agent_id} cache metrics updated: "
+            f"hit_rate={self._metrics.cache_hit_rate:.2%}, "
+            f"read_tokens={cache_read_tokens}, creation_tokens={cache_creation_tokens}"
+        )
+
     def update_session_metrics(
         self,
         session_status: str,
@@ -1518,6 +1579,18 @@ class BaseAIAgent(ABC):
             "p95_operation_time": self._metrics.p95_operation_time,
             "p99_operation_time": self._metrics.p99_operation_time,
             "recent_operations": self._metrics.operation_history[-10:],  # Last 10 operations
+            # Prompt cache metrics
+            "prompt_cache": {
+                "total_llm_requests": self._metrics.total_llm_requests,
+                "cache_hits": self._metrics.cache_hits,
+                "cache_misses": self._metrics.cache_misses,
+                "cache_hit_rate": self._metrics.cache_hit_rate,
+                "cache_hit_rate_pct": f"{self._metrics.cache_hit_rate * 100:.1f}%",
+                "total_cache_read_tokens": self._metrics.total_cache_read_tokens,
+                "total_cache_creation_tokens": self._metrics.total_cache_creation_tokens,
+                "estimated_cache_savings_tokens": self._metrics.estimated_cache_savings_tokens,
+                "estimated_cache_savings_cost": self._metrics.estimated_cache_savings_cost,
+            },
         }
 
     def get_health_status(self) -> Dict[str, Any]:
@@ -1658,6 +1731,12 @@ class BaseAIAgent(ABC):
                 # Error tracking
                 "error_count": self._metrics.error_count,
                 "error_types": self._metrics.error_types,
+                # Prompt cache metrics
+                "cache_hit_rate": self._metrics.cache_hit_rate,
+                "cache_hits": self._metrics.cache_hits,
+                "cache_misses": self._metrics.cache_misses,
+                "total_cache_read_tokens": self._metrics.total_cache_read_tokens,
+                "estimated_cache_savings_tokens": self._metrics.estimated_cache_savings_tokens,
             },
             "capabilities": [cap.capability_type for cap in self.get_capabilities()],
             "active_goals": len([g for g in self._goals.values() if g.status == GoalStatus.IN_PROGRESS]),