kweaver-dolphin 0.1.0__py3-none-any.whl

dolphin/lib/skill_results/result_processor.py

@@ -0,0 +1,181 @@
+"""Result Processor Module
+Responsible for processing tool execution results, including caching, reference management, and policy application
+"""
+
+import uuid
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from dolphin.lib.skill_results.cache_backend import (
+    CacheBackend,
+    CacheEntry,
+)
+from dolphin.lib.skill_results.result_reference import ResultReference
+from dolphin.lib.skill_results.strategy_registry import StrategyRegistry
+
+from dolphin.core.logging.logger import get_logger
+
+logger = get_logger("skill_results")
+
+
+class ResultProcessor:
+    """Result Processor
+        Responsible for receiving raw tool results, writing to cache, and returning references
+    """
+
+    def __init__(
+        self, cache_backend: CacheBackend, strategy_registry: StrategyRegistry
+    ):
+        self.cache_backend = cache_backend
+        self.strategy_registry = strategy_registry
+
+    def process_result(
+        self,
+        tool_name: str,
+        result: Any,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> ResultReference:
+        """Process tool execution results
+
+        Args:
+            tool_name: Tool name
+            result: Tool execution result
+            metadata: Metadata
+
+        Returns:
+            ResultReference: Result reference object
+        """
+        try:
+            # Generate unique reference ID
+            reference_id = str(uuid.uuid4())
+
+            # Preparing metadata
+            if metadata is None:
+                metadata = {}
+
+            metadata.update(
+                {
+                    "tool_name": tool_name,
+                    "processed_at": datetime.now().isoformat(),
+                    "result_type": type(result).__name__,
+                }
+            )
+
+            # Calculate result size
+            result_size = len(str(result)) if result else 0
+
+            # Create cache entry
+            cache_entry = CacheEntry(
+                reference_id=reference_id,
+                full_result=result,
+                metadata=metadata,
+                created_at=datetime.now(),
+                tool_name=tool_name,
+                size=result_size,
+            )
+
+            # Store in cache
+            self.cache_backend.store(cache_entry)
+
+            logger.debug(
+                f"结果处理完成: tool={tool_name}, id={reference_id}, size={result_size}"
+            )
+
+            # Return result reference
+            return ResultReference(
+                reference_id=reference_id,
+                cache_backend=self.cache_backend,
+                strategy_registry=self.strategy_registry,
+            )
+
+        except Exception as e:
+            logger.error(f"结果处理failed: tool={tool_name}, error={e}")
+            raise
+
+    def get_result_reference(self, reference_id: str) -> Optional[ResultReference]:
+        """Get result reference object by reference ID
+
+        Args:
+            reference_id: Reference ID
+
+        Returns:
+            ResultReference: Result reference object, returns None if not exists
+        """
+        try:
+            if not self.cache_backend.exists(reference_id):
+                return None
+
+            return ResultReference(
+                reference_id=reference_id,
+                cache_backend=self.cache_backend,
+                strategy_registry=self.strategy_registry,
+            )
+
+        except Exception as e:
+            logger.error(f"Get结果引用failed: id={reference_id}, error={e}")
+            return None
+
+    def delete_result(self, reference_id: str) -> bool:
+        """Delete the cached result of the specified reference
+
+        Args:
+            reference_id: Reference ID
+
+        Returns:
+            bool: Whether the deletion was successful
+        """
+        try:
+            success = self.cache_backend.delete(reference_id)
+            if success:
+                logger.info(f"结果删除successful: id={reference_id}")
+            else:
+                logger.warning(f"结果删除failed: id={reference_id}")
+            return success
+
+        except Exception as e:
+            logger.error(f"结果删除异常: id={reference_id}, error={e}")
+            return False
+
+    def cleanup_expired(self, max_age_hours: int = 24) -> int:
+        """Clean expired cache
+
+        Args:
+            max_age_hours: Maximum retention time (in hours)
+
+        Returns:
+            int: Number of items cleaned
+        """
+        try:
+            cleaned_count = self.cache_backend.cleanup(max_age_hours)
+            logger.info(
+                f"过期缓存清理完成: count={cleaned_count}, max_age={max_age_hours}h"
+            )
+            return cleaned_count
+
+        except Exception as e:
+            logger.error(f"过期缓存清理failed: error={e}")
+            return 0
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get cache statistics
+
+        Returns:
+            Dict: Dictionary of statistics
+        """
+        try:
+            cache_stats = self.cache_backend.get_stats()
+            strategy_stats = self.strategy_registry.get_stats()
+
+            return {
+                "cache": cache_stats,
+                "strategies": strategy_stats,
+                "processor": {
+                    "type": "ResultProcessor",
+                    "cache_backend": type(self.cache_backend).__name__,
+                    "strategy_registry": type(self.strategy_registry).__name__,
+                },
+            }
+
+        except Exception as e:
+            logger.error(f"Get统计信息failed: error={e}")
+            return {"error": str(e)}

dolphin/lib/skill_results/result_reference.py

@@ -0,0 +1,179 @@
+"""Result reference module
+Provides functions for referencing, caching, and handling strategies for result data
+"""
+
+from typing import Any, Dict, Optional, TYPE_CHECKING
+from datetime import datetime, timedelta
+
+from dolphin.lib.skill_results.cache_backend import CacheBackend, CacheEntry
+
+if TYPE_CHECKING:
+    from dolphin.lib.skill_results.strategy_registry import StrategyRegistry
+
+from dolphin.core.logging.logger import get_logger
+
+logger = get_logger("skill_results")
+
+
+class ResultReference:
+    """Result reference class, providing reference access to cached results"""
+
+    def __init__(
+        self,
+        reference_id: str,
+        cache_backend: CacheBackend,
+        strategy_registry: "StrategyRegistry",
+    ):
+        self.reference_id = reference_id
+        self.cache_backend = cache_backend
+        self._strategy_registry = strategy_registry
+        self._cached_entry: Optional[CacheEntry] = None
+
+    def get_full_result(self) -> Optional[Any]:
+        """Get complete results"""
+        try:
+            if self._cached_entry is None:
+                self._cached_entry = self.cache_backend.get(self.reference_id)
+
+            if self._cached_entry:
+                return self._cached_entry.full_result
+            return None
+        except Exception as e:
+            logger.error(f"Failed to get full result for {self.reference_id}: {e}")
+            return None
+
+    def get_metadata(self) -> Optional[Dict[str, Any]]:
+        """Get metadata"""
+        try:
+            if self._cached_entry is None:
+                self._cached_entry = self.cache_backend.get(self.reference_id)
+
+            if self._cached_entry:
+                return self._cached_entry.metadata
+            return None
+        except Exception as e:
+            logger.error(f"Failed to get metadata for {self.reference_id}: {e}")
+            return None
+
+    # === Unified Entry: Retrieval Based on Category ===
+    def get_for_category(
+        self, category: str, strategy_name: str = "default", **kwargs
+    ) -> Optional[Any]:
+        """Get processed data based on category (e.g., category='llm' or 'frontend')"""
+        try:
+            strategy = self._strategy_registry.get_strategy(strategy_name, category)
+            if strategy is None:
+                logger.warning(f"策略不存在: {category}:{strategy_name}")
+                return None
+
+            if not strategy.supports(category):
+                logger.warning(f"策略不支持 category: {category}")
+                return None
+
+            return strategy.process(self, **kwargs)
+        except Exception as e:
+            logger.error(f"策略处理failed: {category}:{strategy_name}, 错误: {e}")
+            return None
+
+    def get(self, strategy_spec: str = "", **kwargs) -> Any:
+        """Unified acquisition: supports 'llm:summary' / 'app/pagination' / 'summary' (auto-detected)."""
+        if not strategy_spec:
+            # Channel not specified:优先尝试 llm，再尝试 app
+            result = self.get_for_category("llm", "default", **kwargs)
+            if result is not None:
+                return result
+            return self.get_for_category("app", strategy_name="default", **kwargs)
+
+        # Parsing strategy specifications
+        if ":" in strategy_spec:
+            category, name = strategy_spec.split(":", 1)
+            return self.get_for_category(category, name, **kwargs)
+        elif "/" in strategy_spec:
+            category, name = strategy_spec.split("/", 1)
+            return self.get_for_category(category, name, **kwargs)
+        else:
+            # Unknown channel: try common categories
+            for k in ("llm", "app"):
+                result = self.get_for_category(k, strategy_spec, **kwargs)
+                if result is not None:
+                    return result
+            # Try another category
+            for k in self._strategy_registry.list_strategies().keys():
+                if k in ("llm", "app"):
+                    continue
+                result = self.get_for_category(k, strategy_spec, **kwargs)
+                if result is not None:
+                    return result
+            return None
+
+    def exists(self) -> bool:
+        """Check if reference exists"""
+        return self.cache_backend.exists(self.reference_id)
+
+    def get_info(self) -> Dict[str, Any]:
+        """Get reference information"""
+        try:
+            if self._cached_entry is None:
+                self._cached_entry = self.cache_backend.get(self.reference_id)
+
+            if self._cached_entry:
+                return {
+                    "reference_id": self.reference_id,
+                    "tool_name": self._cached_entry.tool_name,
+                    "size": self._cached_entry.size,
+                    "created_at": self._cached_entry.created_at.isoformat(),
+                    "metadata": self._cached_entry.metadata,
+                }
+            return {"reference_id": self.reference_id, "exists": False}
+        except Exception as e:
+            logger.error(f"Failed to get info for {self.reference_id}: {e}")
+            return {"reference_id": self.reference_id, "error": str(e)}
+
+    def delete(self) -> bool:
+        """Delete reference"""
+        try:
+            success = self.cache_backend.delete(self.reference_id)
+            if success:
+                self._cached_entry = None
+            return success
+        except Exception as e:
+            logger.error(f"Failed to delete reference {self.reference_id}: {e}")
+            return False
+
+    def set_data(self, data: Any) -> None:
+        """Set result data"""
+        self._data = data
+
+    def set_metadata(self, metadata: Dict[str, Any]) -> None:
+        """Set metadata"""
+        self._metadata = metadata.copy()
+
+    def update_metadata(self, updates: Dict[str, Any]) -> None:
+        """Update metadata"""
+        self._metadata.update(updates)
+
+    def is_expired(self) -> bool:
+        """Check if expired"""
+        if self._cache_ttl is None:
+            return False
+        return datetime.now() - self._created_at > timedelta(seconds=self._cache_ttl)
+
+    def get_age(self) -> float:
+        """Get data age (seconds)"""
+        return (datetime.now() - self._created_at).total_seconds()
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary"""
+        return {
+            "reference_id": self.reference_id,
+            "data": self._data,
+            "metadata": self._metadata,
+            "created_at": self._created_at.isoformat(),
+            "cache_ttl": self._cache_ttl,
+        }
+
+    def __str__(self) -> str:
+        return f"ResultReference(id={self.reference_id}, data_type={type(self._data).__name__})"
+
+    def __repr__(self) -> str:
+        return self.__str__()

dolphin/lib/skill_results/skillkit_hook.py

@@ -0,0 +1,324 @@
+"""SkillKit Hook Module
+Provides hook functions and utility methods for processing skill results.
+
+Main Features:
+- Before returning to LLM: get_for_llm -> generates understandable data based on strategy
+- Before returning to APP: get_for_app -> generates displayable data based on strategy
+- Result caching: unified management of result lifecycle
+"""
+
+from typing import Dict, Any, Optional
+
+from dolphin.lib.skill_results.result_processor import ResultProcessor
+from dolphin.lib.skill_results.result_reference import ResultReference
+from dolphin.lib.skill_results.strategy_registry import StrategyRegistry
+from dolphin.lib.skill_results.cache_backend import (
+    CacheBackend,
+    MemoryCacheBackend,
+)
+from dolphin.core.skill.skill_function import SkillFunction, DynamicAPISkillFunction
+
+from dolphin.core.logging.logger import get_logger
+
+logger = get_logger("skill_results")
+
+
+class SkillkitHook:
+    """Skillkit Result Processing Hooks.
+
+    - Provides a unified interface for result retrieval and processing
+    - Supports data transformation with different strategies
+    - Manages result caching and lifecycle
+    """
+
+    def __init__(
+        self,
+        cache_backend: Optional[CacheBackend] = None,
+        strategy_registry: Optional[StrategyRegistry] = None,
+    ) -> None:
+        self._processor = ResultProcessor(
+            cache_backend=cache_backend or MemoryCacheBackend(),
+            strategy_registry=strategy_registry or StrategyRegistry(),
+        )
+
+    # === Hook: After tool execution ===
+    def on_tool_after_execute(
+        self, tool_name: str, result: Any, metadata: Optional[Dict[str, Any]] = None
+    ) -> ResultReference:
+        """Alias: equivalent to process_result."""
+        return self.process_result(
+            tool_name=tool_name, result=result, metadata=metadata
+        )
+
+    # === Hook: After tool execution ===
+    def process_result(
+        self,
+        tool_name: str,
+        result: Any,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> ResultReference:
+        """Called after the tool execution is completed, saves the result and returns a reference.
+        The returned reference ID can be recorded in the context for subsequent frontend/LLM to retrieve data as needed.
+        """
+        return self._processor.process_result(
+            tool_name=tool_name, result=result, metadata=metadata
+        )
+
+    # === Hook: Before returning LLM ===
+    def on_before_send_to_llm(
+        self,
+        reference_id: str,
+        strategy_name: str = None,
+        skill: SkillFunction = None,
+        **kwargs,
+    ) -> Optional[str]:
+        """Alias: equivalent to get_for_llm. Uses the default strategy by default.
+
+        Special handling for dynamic tool responses:
+        - If the result contains _dynamic_tools marker, returns a user-friendly message
+        - Otherwise, processes the result using the normal strategy
+        """
+
+        # Check if this is a dynamic tool response
+        ref = self._get_result_reference(reference_id)
+
+        if ref:
+            full_result = ref.get_full_result()
+
+            if isinstance(full_result, dict):
+                # Check for _dynamic_tools at multiple levels
+                dynamic_tools = None
+                message = ""
+                
+                # Level 1: Check if _dynamic_tools is directly in full_result
+                if "_dynamic_tools" in full_result:
+                    dynamic_tools = full_result.get("_dynamic_tools", [])
+                    message = full_result.get("message", "") or full_result.get("answer", "")
+                    if isinstance(message, dict):
+                        message = message.get("message", "") or message.get("answer", "")
+                
+                # Level 2: Check if _dynamic_tools is in full_result["answer"]
+                elif "answer" in full_result:
+                    answer = full_result["answer"]
+                    if isinstance(answer, dict) and "_dynamic_tools" in answer:
+                        dynamic_tools = answer.get("_dynamic_tools", [])
+                        message = answer.get("message", "")
+                
+                # If we found dynamic tools, process them
+                if dynamic_tools is not None:
+                    tool_names = []
+                    if isinstance(dynamic_tools, list):
+                        for tool in dynamic_tools:
+                            if isinstance(tool, dict) and "name" in tool:
+                                tool_names.append(tool["name"])
+
+                    # Build the response message
+                    if not message and tool_names:
+                        message = f"Successfully loaded {len(tool_names)} tools: {', '.join(tool_names)}"
+                    elif not message:
+                        message = "Successfully loaded dynamic tools"
+                    
+                    logger.debug(
+                        f"[Dynamic Tool] Returning for LLM - message: {message}, tools: {tool_names}"
+                    )
+                    return message
+
+        # Normal processing
+        if strategy_name is None and skill is not None:
+            strategy_name = skill.get_first_valid_llm_strategy()
+
+        strategy_name = strategy_name if strategy_name else "default"
+
+        return self.get_for_llm(
+            reference_id=reference_id, strategy_name=strategy_name, **kwargs
+        )
+
+    def on_before_reply_app(
+        self,
+        reference_id: str,
+        strategy_name: str = "default",
+        skill: SkillFunction = None,
+        **kwargs,
+    ) -> Dict[str, Any]:
+        """Alias: equivalent to get_for_app. Uses the default strategy by default.
+        
+        Special handling for dynamic tool responses:
+        - If the result contains _dynamic_tools marker, returns structured data with message
+        - Otherwise, processes the result using the normal strategy
+        """
+        # Check if this is a dynamic API tool response
+        ref = self._get_result_reference(reference_id)
+
+        if ref and skill and isinstance(skill, DynamicAPISkillFunction):
+            full_result = ref.get_full_result()
+            return {"answer": full_result}
+        
+        # Normal processing
+        try:
+            strategy_name = skill.get_first_valid_app_strategy()
+            if not strategy_name:
+                return {"error": "未找到有效的APP策略"}
+
+            return self.get_for_app(reference_id, strategy_name=strategy_name, **kwargs)
+        except Exception as e:
+            logger.error(f"APP回复前处理failed: {e}")
+            return {"error": f"数据处理failed: {str(e)}"}
+
+    def on_before_send_to_context(
+        self,
+        reference_id: str,
+        skill: SkillFunction,
+        skillkit_name: str,
+        resource_skill_path: Optional[str] = None,
+    ) -> tuple[str, Dict[str, Any]]:
+        """Hook called before sending result to context (SCRATCHPAD message).
+
+        This hook applies context retention strategies to optimize how much
+        content is stored in the context window.
+
+        Args:
+            reference_id: The result reference ID
+            skill: The executed skill function
+            skillkit_name: Name of the skillkit
+            resource_skill_path: Optional path to resource skill
+
+        Returns:
+            tuple[str, dict]: (processed_content, metadata)
+        """
+        from dolphin.core.skill.context_retention import (
+            SkillContextRetention,
+            get_context_retention_strategy,
+            ContextRetentionMode,
+        )
+
+        ref = self._get_result_reference(reference_id)
+        if not ref:
+            return "", {}
+
+        full_result = ref.get_full_result()
+        if not isinstance(full_result, str):
+            full_result = str(full_result)
+
+        # Get decorator config or default
+        config = getattr(skill.func, '_context_retention', None)
+        if not config:
+            config = SkillContextRetention()  # Default FULL mode
+
+        # Apply strategy
+        strategy = get_context_retention_strategy(config.mode)
+        processed_result = strategy.process(full_result, config, reference_id)
+
+        # Build metadata
+        metadata = {
+            "original_length": len(full_result),
+            "processed_length": len(processed_result),
+            "retention_mode": config.mode.value,
+            "pinned": config.mode == ContextRetentionMode.PIN,
+        }
+
+        # Use update() to merge with existing metadata
+        existing_metadata = ref.get_metadata()
+        if existing_metadata:
+            metadata.update(existing_metadata)
+
+        return processed_result, metadata
+
+    def get_for_llm(
+        self, reference_id: str, strategy_name: str = "default", **kwargs
+    ) -> str:
+        """Get data suitable for LLM
+        - Generate data in a format understandable by LLM according to the strategy
+        - Support strategies such as 'llm:summary', 'llm:truncate', etc.
+        """
+        try:
+            ref = self._get_result_reference(reference_id)
+            if ref is None:
+                return "结果引用不存在"
+
+            return ref.get_for_category("llm", strategy_name, **kwargs)
+        except Exception as e:
+            logger.error(f"GetLLM数据failed: {e}")
+            return f"数据Getfailed: {str(e)}"
+
+    def get_for_app(
+        self, reference_id: str, strategy_name: str = "default", **kwargs
+    ) -> Dict[str, Any]:
+        """Get data suitable for APP
+        - Generate a displayable data format according to the strategy
+        - Support strategies such as 'app:pagination', 'app:preview', etc.
+        """
+        try:
+            ref = self._get_result_reference(reference_id)
+            if ref is None:
+                return {"error": "结果引用不存在"}
+
+            return ref.get_for_category("app", strategy_name=strategy_name, **kwargs)
+        except Exception as e:
+            logger.error(f"GetAPP数据failed: {e}")
+            return {"error": f"数据Getfailed: {str(e)}"}
+
+    def get_for_category(
+        self, reference_id: str, category: str, strategy_name: str = "default", **kwargs
+    ) -> Any:
+        """Get data based on category
+        - Supports strategy processing for any category
+        - Provides unified error handling
+        """
+        try:
+            ref = self._get_result_reference(reference_id)
+            if ref is None:
+                if category == "llm":
+                    return "结果引用不存在"
+                else:
+                    return {"error": "结果引用不存在"}
+
+            return ref.get_for_category(category, strategy_name=strategy_name, **kwargs)
+        except Exception as e:
+            logger.error(f"Get{category}数据failed: {e}")
+            if category == "llm":
+                return f"数据Getfailed: {str(e)}"
+            else:
+                return {"error": f"数据Getfailed: {str(e)}"}
+
+    def get_raw_result(self, reference_id: str) -> Any:
+        """Get original result data (not processed by strategy)"""
+        try:
+            ref = self._get_result_reference(reference_id)
+            if ref is None:
+                return None
+            return ref.get_full_result()
+        except Exception as e:
+            logger.error(f"Get原始结果failed: {e}")
+            return None
+
+    def get_result_metadata(self, reference_id: str) -> Optional[Dict[str, Any]]:
+        """Get result metadata"""
+        try:
+            ref = self._get_result_reference(reference_id)
+            if ref is None:
+                return None
+            return ref.get_metadata()
+        except Exception as e:
+            logger.error(f"Get结果元数据failed: {e}")
+            return None
+
+    def _get_result_reference(self, reference_id: str) -> Optional[ResultReference]:
+        """Get result reference"""
+        try:
+            """Get ResultReference by reference ID."""
+            return self._processor.get_result_reference(reference_id)
+        except Exception as e:
+            logger.error(f"Get结果引用failed: {e}")
+            return None
+
+    def delete_result(self, reference_id: str) -> bool:
+        """Delete the cached result of the specified reference."""
+        return self._processor.delete_result(reference_id)
+
+    def cleanup_expired(self, max_age_hours: int = 24) -> int:
+        """Clean up expired cache and return the number of items cleaned."""
+        return self._processor.cleanup_expired(max_age_hours=max_age_hours)
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get the statistics information of the cache and policy system."""
+        return self._processor.get_stats()