aiecs 1.7.6__py3-none-any.whl → 1.8.4__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.8.4"
 __author__ = "AIECS Team"
 __email__ = "iretbl@gmail.com"
 

aiecs/application/knowledge_graph/extractors/llm_entity_extractor.py

@@ -162,7 +162,7 @@ class LLMEntityExtractor(EntityExtractor):
         Args:
             text: Input text to extract entities from
             entity_types: Optional filter for specific entity types
-            **kwargs: Additional parameters (e.g., custom prompt, examples)
+            **kwargs: Additional parameters (e.g., custom prompt, examples, context)
 
         Returns:
             List of extracted Entity objects
@@ -174,6 +174,9 @@ class LLMEntityExtractor(EntityExtractor):
         if not text or not text.strip():
             raise ValueError("Input text cannot be empty")
 
+        # Extract context from kwargs if provided
+        context = kwargs.get("context")
+
         # Build extraction prompt
         prompt = self._build_extraction_prompt(text, entity_types)
 
@@ -189,6 +192,7 @@ class LLMEntityExtractor(EntityExtractor):
                     model=self.model,
                     temperature=self.temperature,
                     max_tokens=self.max_tokens,
+                    context=context,
                 )
             # Otherwise use LLM manager with provider
             else:

aiecs/application/knowledge_graph/retrieval/query_intent_classifier.py

@@ -6,7 +6,7 @@ Uses a lightweight LLM to determine the best retrieval approach based on query c
 """
 
 import logging
-from typing import Optional, Dict, TYPE_CHECKING
+from typing import Optional, Dict, Any, TYPE_CHECKING
 from aiecs.application.knowledge_graph.retrieval.strategy_types import RetrievalStrategy
 
 if TYPE_CHECKING:
@@ -58,12 +58,13 @@ class QueryIntentClassifier:
         self.enable_caching = enable_caching
         self._cache: Dict[str, RetrievalStrategy] = {}
 
-    async def classify_intent(self, query: str) -> RetrievalStrategy:
+    async def classify_intent(self, query: str, context: Optional[Dict[str, Any]] = None) -> RetrievalStrategy:
         """
         Classify query intent and return optimal retrieval strategy.
 
         Args:
             query: Query string to classify
+            context: Optional context dictionary for tracking/observability
 
         Returns:
             RetrievalStrategy enum value
@@ -82,7 +83,7 @@ class QueryIntentClassifier:
         # Use LLM classification if client is available
         if self.llm_client is not None:
             try:
-                strategy = await self._classify_with_llm(query)
+                strategy = await self._classify_with_llm(query, context)
             except Exception as e:
                 logger.warning(f"LLM classification failed: {e}, falling back to rule-based")
                 strategy = self._classify_with_rules(query)
@@ -96,7 +97,7 @@ class QueryIntentClassifier:
 
         return strategy
 
-    async def _classify_with_llm(self, query: str) -> RetrievalStrategy:
+    async def _classify_with_llm(self, query: str, context: Optional[Dict[str, Any]] = None) -> RetrievalStrategy:
         """
         Classify query using LLM.
 
@@ -127,11 +128,12 @@ Respond with ONLY the strategy name (e.g., "MULTI_HOP"). No explanation needed."
         if self.llm_client is None:
             # Fallback to rule-based classification if no LLM client
             return self._classify_with_rules(query)
-        
+
         response = await self.llm_client.generate_text(
             messages=messages,
             temperature=0.0,  # Deterministic classification
             max_tokens=20,  # Short response
+            context=context,
         )
 
         # Parse response

aiecs/config/config.py

@@ -47,6 +47,9 @@ class Settings(BaseSettings):
     google_cse_id: str = Field(default="", alias="GOOGLE_CSE_ID")
     xai_api_key: str = Field(default="", alias="XAI_API_KEY")
     grok_api_key: str = Field(default="", alias="GROK_API_KEY")  # Backward compatibility
+    openrouter_api_key: str = Field(default="", alias="OPENROUTER_API_KEY")
+    openrouter_http_referer: str = Field(default="", alias="OPENROUTER_HTTP_REFERER")
+    openrouter_x_title: str = Field(default="", alias="OPENROUTER_X_TITLE")
 
     # LLM Models Configuration
     llm_models_config_path: str = Field(

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]),