kweaver-dolphin 0.1.0__py3-none-any.whl

dolphin/core/runtime/runtime_instance.py

@@ -0,0 +1,446 @@
+from enum import Enum
+import time
+from typing import List, Optional, TYPE_CHECKING
+import uuid
+
+from dolphin.core.common.enums import Messages, SkillInfo, Status, TypeStage
+from dolphin.core.common.constants import estimate_tokens_from_chars
+
+if TYPE_CHECKING:
+    from dolphin.core.agent.base_agent import BaseAgent
+    from dolphin.core.code_block.basic_code_block import BasicCodeBlock
+
+
+class TypeRuntimeInstance(Enum):
+    AGENT = "agent"
+    BLOCK = "block"
+    PROGRESS = "progress"
+    STAGE = "stage"
+
+
+class RuntimeInstance:
+    def __init__(self, type: TypeRuntimeInstance):
+        self.type = type
+        self.id = str(uuid.uuid4())
+        self.parent: RuntimeInstance = None
+        self.children: List[RuntimeInstance] = []
+        # Provide time fields uniformly for all instances to avoid missing attributes when accessing RuntimeGraph
+        self.start_time = time.time()
+        self.end_time = None
+
+    def set_parent(self, parent: "RuntimeInstance"):
+        self.parent = parent
+        parent.children.append(self)
+
+    def get_parent(self):
+        return self.parent
+
+    def get_children(self):
+        return self.children
+
+    def get_type(self):
+        return self.type
+
+
+class AgentInstance(RuntimeInstance):
+    def __init__(self, name: str, agent: "BaseAgent"):
+        super().__init__(type=TypeRuntimeInstance.AGENT)
+        self.name = name
+        self.agent = agent
+
+
+class BlockInstance(RuntimeInstance):
+    def __init__(self, name: str, block: "BasicCodeBlock"):
+        super().__init__(type=TypeRuntimeInstance.BLOCK)
+        self.name = name
+        self.block = block
+
+
+class LLMInput:
+    def __init__(
+        self, content: Optional[str] = None, messages: Optional[Messages] = None
+    ) -> None:
+        self.content = content
+        self.messages = messages
+
+
+class LLMOutput:
+    def __init__(
+        self,
+        raw_output: Optional[str] = None,
+        answer: Optional[str] = None,
+        think: Optional[str] = None,
+        block_answer: Optional[str] = None,
+    ) -> None:
+        self.raw_output = raw_output
+        self.answer = answer
+        self.think = think
+        self.block_answer = block_answer
+
+
+class StageInstance(RuntimeInstance):
+    def __init__(
+        self,
+        agent_name: str = "",
+        stage: TypeStage = TypeStage.LLM,
+        answer: Optional[str] = None,
+        think: Optional[str] = None,
+        raw_output: Optional[str] = None,
+        status: Status = Status.PROCESSING,
+        skill_info: Optional[SkillInfo] = None,
+        block_answer: Optional[str] = None,
+        input_content: Optional[str] = None,
+        input_messages: Optional[Messages] = None,
+        interrupted: bool = False,
+        flags: str = "",
+    ):
+        super().__init__(type=TypeRuntimeInstance.STAGE)
+
+        self.agent_name = agent_name
+        self.stage = stage
+        self.input = LLMInput(
+            content=input_content,
+            messages=input_messages.copy() if input_messages is not None else None,
+        )
+
+        if not self.input.content and self.input.messages:
+            self.input.content = self.input.messages[-1].content
+
+        self.output = LLMOutput(
+            answer=answer, think=think, raw_output=raw_output, block_answer=block_answer
+        )
+        self.status = status
+        self.skill_info = skill_info
+        self.interrupted = interrupted
+        self.flags = flags
+
+        self.start_time = time.time()
+        self.end_time = self.start_time
+
+        self.token_usage = {}
+
+    def get_agent_name(self):
+        return self.agent_name
+
+    def get_answer(self):
+        return self.output.answer
+
+    def get_think(self):
+        return self.output.think
+
+    def get_raw_output(self):
+        return self.output.raw_output
+
+    def get_block_answer(self):
+        return self.output.block_answer
+
+    def set_end_time(self):
+        self.end_time = time.time()
+
+    def get_estimated_input_tokens(self):
+        if self.stage != TypeStage.LLM:
+            return 0
+
+        # First try to get from whole_messages
+        if self.input.messages:
+            return self.input.messages.estimated_tokens()
+        return 0
+
+    def get_estimated_output_tokens(self):
+        if self.stage != TypeStage.LLM:
+            return 0
+
+        if self.output.raw_output:
+            tokens = estimate_tokens_from_chars(self.output.raw_output)
+            return tokens if tokens is not None else 0
+
+        return 0
+
+    def get_estimated_ratio_tokens(self) -> float:
+        if self.stage != TypeStage.LLM or self.input.messages is None:
+            return 0
+
+        total_tokens = (
+            self.get_estimated_input_tokens() + self.get_estimated_output_tokens()
+        )
+        return (
+            (float)(total_tokens) / (float)(self.input.messages.get_max_tokens())
+            if self.input.messages.get_max_tokens() > 0
+            else 0
+        )
+
+    def update(
+        self,
+        stage: Optional[TypeStage] = None,
+        answer: Optional[str] = None,
+        think: Optional[str] = None,
+        raw_output: Optional[str] = None,
+        status: Optional[str] = None,
+        skill_info: Optional[SkillInfo] = None,
+        block_answer: Optional[str] = None,
+        input_messages: Optional[Messages] = None,
+        **kwargs,
+    ):
+        if stage is not None:
+            self.stage = stage
+        if answer is not None:
+            self.output.answer = answer
+        if think is not None:
+            self.output.think = think
+        if raw_output is not None:
+            self.output.raw_output = raw_output
+        if status is not None:
+            self.status = status
+        if skill_info is not None:
+            self.skill_info = skill_info
+        if block_answer is not None:
+            self.output.block_answer = block_answer
+        if input_messages is not None:
+            self.input.messages = input_messages.copy()
+
+        if kwargs:
+            for key, value in kwargs.items():
+                if key not in [
+                    "stage",
+                    "answer",
+                    "think",
+                    "raw_output",
+                    "status",
+                    "skill_info",
+                    "block_answer",
+                    "input_messages",
+                ]:
+                    setattr(self, key, value)
+
+    def get_traditional_dict(self):
+        # Safe access to enum values with fallback
+        stage_value = (
+            self.stage.value if hasattr(self.stage, "value") else str(self.stage)
+        )
+        status_value = (
+            self.status.value
+            if self.status and hasattr(self.status, "value")
+            else str(self.status)
+        )
+
+        # Unified answer field: prefer block_answer if answer is empty
+        # This ensures answer field always contains the streaming text output
+        # while maintaining backward compatibility with block_answer field
+        answer_value = self.output.answer
+        if not answer_value and self.output.block_answer:
+            answer_value = self.output.block_answer
+
+        return {
+            "id": self.id,
+            "agent_name": self.agent_name,
+            "stage": stage_value,
+            "answer": answer_value,  # Unified streaming text output
+            "think": self.output.think,
+            "status": status_value,
+            "skill_info": self.skill_info.to_dict() if self.skill_info else None,
+            "block_answer": self.output.block_answer,  # Kept for backward compatibility (deprecated)
+            "input_message": self.input.content,
+            "interrupted": self.interrupted,
+            "flags": self.flags,
+            "start_time": self.start_time,
+            "end_time": self.end_time,
+            "estimated_input_tokens": self.get_estimated_input_tokens(),
+            "estimated_output_tokens": self.get_estimated_output_tokens(),
+            "estimated_ratio_tokens": self.get_estimated_ratio_tokens(),
+            "token_usage": self.token_usage,
+        }
+
+    def get_triditional_dict(self):
+        """Deprecated: Use get_traditional_dict() instead.
+
+        This method is kept for backward compatibility and will be removed in v3.0.
+        The method name was a typo ('triditional' instead of 'traditional').
+
+        .. deprecated:: 2.1
+            Use :meth:`get_traditional_dict` instead.
+        """
+        import warnings
+        warnings.warn(
+            "get_triditional_dict() is deprecated due to typo. "
+            "Use get_traditional_dict() instead. "
+            "This method will be removed in v3.0.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        return self.get_traditional_dict()
+
+    def llm_empty_answer(self):
+        return (
+            self.stage == TypeStage.LLM
+            and not self.output.answer
+            and not self.output.think
+            and not self.output.block_answer
+        )
+
+    def empty_answer(self):
+        return (
+            not self.output.answer
+            and not self.output.think
+            and not self.output.block_answer
+        )
+
+
+class ProgressInstance(RuntimeInstance):
+    def __init__(self, context, parent: Optional["ProgressInstance"] = None, flags=""):
+        super().__init__(type=TypeRuntimeInstance.PROGRESS)
+
+        self.context = context
+        self.stages: List[StageInstance] = []
+        self.flags = flags
+
+    def add_stage(
+        self,
+        agent_name: str = "",
+        stage: TypeStage = TypeStage.LLM,
+        answer: str = "",
+        think: str = "",
+        raw_output: str = "",
+        status: Status = Status.PROCESSING,
+        skill_info: Optional[SkillInfo] = None,
+        block_answer: str = "",
+        input_content: str = "",
+        input_messages: Optional[Messages] = None,
+        interrupted: bool = False,
+    ):
+        pop_last_stage = False
+        if len(self.stages) > 0 and self.stages[-1].llm_empty_answer():
+            pop_last_stage = True
+
+        stage_instance = StageInstance(
+            agent_name=agent_name,
+            stage=stage,
+            answer=answer,
+            think=think,
+            raw_output=raw_output,
+            status=status,
+            skill_info=skill_info,
+            block_answer=block_answer,
+            input_content=input_content,
+            input_messages=input_messages,
+            interrupted=interrupted,
+            flags=self.flags,
+        )
+        self.add_stage_instance(stage_instance, pop_last_stage)
+
+    def add_stage_instance(
+        self, stage_instance: StageInstance, pop_last_stage: bool = False
+    ):
+        stage_instance.set_parent(self)
+        if pop_last_stage:
+            self.stages.pop()
+        self.stages.append(stage_instance)
+
+        # Register stage instance to runtime_graph if available
+        if (
+            self.context
+            and hasattr(self.context, "runtime_graph")
+            and self.context.runtime_graph
+        ):
+            self.context.runtime_graph.set_stage(stage_instance, pop_last_stage)
+
+        self.set_variable()
+
+    def set_last_stage(
+        self,
+        stage: Optional[TypeStage] = None,
+        answer: Optional[str] = None,
+        think: Optional[str] = None,
+        raw_output: Optional[str] = None,
+        status: Status = Status.PROCESSING,
+        skill_info: Optional[SkillInfo] = None,
+        block_answer: Optional[str] = None,
+        input_messages: Optional[Messages] = None,
+        **kwargs,
+    ):
+        # If no stages exist, create a new one
+        if len(self.stages) == 0:
+            # If stage is None and we have no stages, default to LLM
+            default_stage = stage if stage is not None else TypeStage.LLM
+            self.add_stage(
+                stage=default_stage,
+                answer=answer,
+                think=think,
+                raw_output=raw_output,
+                status=status,
+                skill_info=skill_info,
+                block_answer=block_answer,
+                input_messages=input_messages,
+            )
+            return
+
+        # Check if we need to create a new stage (when stage type changes)
+        last_stage = self.stages[-1]
+
+        # Create new stage if stage type is changing (and it's not None)
+        if stage is not None and stage != last_stage.stage:
+            self.add_stage(
+                stage=stage,
+                answer=answer,
+                think=think,
+                raw_output=raw_output,
+                status=status,
+                skill_info=skill_info,
+                block_answer=block_answer,
+                input_messages=input_messages,
+            )
+            return
+
+        last_stage.update(
+            stage=stage,
+            answer=answer,
+            think=think,
+            raw_output=raw_output,
+            status=status,
+            skill_info=skill_info,
+            block_answer=block_answer,
+            input_messages=input_messages,
+            **kwargs,
+        )
+        last_stage.set_end_time()
+        self.set_variable()
+
+    def get_last_stage(self):
+        return self.stages[-1] if len(self.stages) > 0 else None
+
+    def get_last_answer(self) -> dict:
+        return self.stages[-1].get_traditional_dict()
+
+    def get_step_answers(self):
+        last_stage = self.get_last_stage()
+        if last_stage is None:
+            return ""
+
+        last_answer = last_stage.get_answer()
+        if isinstance(last_answer, str) and len(last_answer.strip()) != 0:
+            return last_answer
+        elif not isinstance(last_answer, str):
+            return last_answer
+        else:
+            block_answer = last_stage.get_block_answer()
+            think = last_stage.get_think()
+            answer = last_stage.get_answer()
+            return str(block_answer) + "\n\n" + str(think) + "\n\n" + str(answer)
+
+    def get(self):
+        """
+        Get stages as serializable dictionaries instead of raw objects
+        This ensures compatibility when stages are used as variable values
+        """
+        return [stage.get_traditional_dict() for stage in self.stages]
+
+    def get_raw_stages(self):
+        """
+        Get raw StageInstance objects for internal use
+        Use this method when you need direct access to StageInstance objects
+        """
+        return self.stages
+
+    def set_variable(self):
+        self.context.set_variable(
+            "_progress", [stage.get_traditional_dict() for stage in self.stages]
+        )

dolphin/core/skill/__init__.py

@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+"""Skill 模块 - Skill 核心"""
+
+from dolphin.core.skill.skillkit import Skillkit
+from dolphin.core.skill.skillset import Skillset
+from dolphin.core.skill.skill_function import SkillFunction
+from dolphin.core.skill.skill_matcher import SkillMatcher
+
+__all__ = [
+    "Skillkit",
+    "Skillset",
+    "SkillFunction",
+    "SkillMatcher",
+]

dolphin/core/skill/context_retention.py

@@ -0,0 +1,157 @@
+from abc import ABC, abstractmethod
+from typing import Any, Optional, List, Dict
+from dataclasses import dataclass
+from enum import Enum
+
+class ContextRetentionMode(Enum):
+    """Context retention mode for skill results"""
+    SUMMARY = "summary"      # Keep head and tail, truncate middle
+    FULL = "full"           # Keep everything, no processing (default)
+    PIN = "pin"             # Keep full, skip compression, persist to history
+    REFERENCE = "reference" # Keep only reference_id, fetch full via cache
+
+
+@dataclass
+class SkillContextRetention:
+    """Skill context retention configuration"""
+    mode: ContextRetentionMode = ContextRetentionMode.FULL
+    max_length: int = 2000  # Only used by SUMMARY mode
+    summary_prompt: Optional[str] = None
+    ttl_turns: int = -1
+    reference_hint: Optional[str] = None  # Hint text for REFERENCE mode
+
+
+class ContextRetentionStrategy(ABC):
+    """Base class for context retention strategies"""
+    
+    @abstractmethod
+    def process(self, result: str, config: SkillContextRetention, 
+                reference_id: str = None) -> str:
+        """Process result and return content for context
+        
+        Args:
+            result: Original result
+            config: Retention configuration
+            reference_id: Result reference ID (for REFERENCE mode)
+        """
+        pass
+
+
+class SummaryContextStrategy(ContextRetentionStrategy):
+    """Summary strategy - keep head and tail, truncate middle"""
+    
+    def process(self, result: str, config: SkillContextRetention,
+                reference_id: str = None) -> str:
+        if len(result) <= config.max_length:
+            return result
+        
+        # Keep head and tail, truncate middle
+        head_ratio = 0.6
+        tail_ratio = 0.2
+        head_chars = int(config.max_length * head_ratio)
+        tail_chars = int(config.max_length * tail_ratio)
+        
+        # Provide reference_id so LLM can fetch full content if needed
+        ref_hint = ""
+        if reference_id:
+            ref_hint = f"\n[For full content, call _get_result_detail('{reference_id}')]"
+        
+        omitted = len(result) - head_chars - tail_chars
+        # Ensure we don't have negative omission if rounding puts us over
+        if omitted <= 0:
+            return result
+            
+        return (f"{result[:head_chars]}\n"
+                f"... ({omitted} chars omitted) ...\n"
+                f"{result[-tail_chars:]}"
+                f"{ref_hint}")
+
+
+class FullContextStrategy(ContextRetentionStrategy):
+    """Full strategy - keep everything without any processing
+    
+    Note: This strategy does NOT truncate. If the result is too large,
+    it will be handled by the Compression Strategy at LLM call time.
+    """
+    
+    def process(self, result: str, config: SkillContextRetention,
+                reference_id: str = None) -> str:
+        # No processing, return as-is
+        # Compression Strategy will handle if context is too large
+        return result
+
+
+class PinContextStrategy(ContextRetentionStrategy):
+    """Pin strategy - keep full, mark as non-compressible, persist to history"""
+    
+    def process(self, result: str, config: SkillContextRetention,
+                reference_id: str = None) -> str:
+        # Keep full, compression behavior controlled by metadata
+        # PIN_MARKER is recognized by _update_history_and_cleanup
+        from dolphin.core.common.constants import PIN_MARKER
+        # If result already has PIN_MARKER, don't add it again
+        if PIN_MARKER in result:
+            return result
+        return f"{PIN_MARKER}{result}"
+
+
+class ReferenceContextStrategy(ContextRetentionStrategy):
+    """Reference strategy - keep only reference_id, fetch full via cache
+    
+    Use cases:
+    - Very large results (datasets, full web pages)
+    - Results that may need to be fetched later via reference_id
+    - Minimize context usage as much as possible
+    """
+    
+    def process(self, result: str, config: SkillContextRetention,
+                reference_id: str = None) -> str:
+        if not reference_id:
+            # Fallback to SUMMARY if no reference_id
+            return SummaryContextStrategy().process(result, config, reference_id)
+        
+        # Build short reference info with fetch instructions
+        hint = config.reference_hint or "Full result stored"
+        return (f"[{hint}]\n"
+                f"Original length: {len(result)} chars\n"
+                f"Get full content: _get_result_detail('{reference_id}')\n"
+                f"Get range: _get_result_detail('{reference_id}', offset=0, limit=2000)")
+
+
+# Strategy mapping
+CONTEXT_RETENTION_STRATEGIES: Dict[ContextRetentionMode, ContextRetentionStrategy] = {
+    ContextRetentionMode.SUMMARY: SummaryContextStrategy(),
+    ContextRetentionMode.FULL: FullContextStrategy(),
+    ContextRetentionMode.PIN: PinContextStrategy(),
+    ContextRetentionMode.REFERENCE: ReferenceContextStrategy(),
+}
+
+
+def get_context_retention_strategy(mode: ContextRetentionMode) -> ContextRetentionStrategy:
+    """Get context retention strategy"""
+    return CONTEXT_RETENTION_STRATEGIES.get(mode, FullContextStrategy())
+
+
+def context_retention(
+    mode: str = "full",
+    max_length: int = 2000,
+    summary_prompt: str = None,
+    ttl_turns: int = -1,
+    reference_hint: str = None,
+):
+    """Skill context retention strategy decorator"""
+    def decorator(func):
+        try:
+            retention_mode = ContextRetentionMode(mode)
+        except ValueError:
+            retention_mode = ContextRetentionMode.FULL
+            
+        func._context_retention = SkillContextRetention(
+            mode=retention_mode,
+            max_length=max_length,
+            summary_prompt=summary_prompt,
+            ttl_turns=ttl_turns,
+            reference_hint=reference_hint,
+        )
+        return func
+    return decorator