kweaver-dolphin 0.1.0__py3-none-any.whl

dolphin/cli/ui/stream_renderer.py

@@ -0,0 +1,302 @@
+"""
+Stream Renderer - CLI Layer for Live Markdown Rendering
+
+This module provides the CLI-layer rendering logic for LLM streaming output.
+It is completely separate from the SDK core, allowing the SDK to remain
+agnostic to terminal rendering concerns.
+
+Usage:
+    renderer = LiveStreamRenderer()
+    renderer.start()
+    async for item in llm_chat_stream(..., on_stream_chunk=renderer.on_chunk):
+        ...
+    renderer.stop()
+"""
+
+from typing import Optional, Callable
+
+
+def _is_fixed_layout_active() -> bool:
+    """Check if we're using the fixed bottom layout (scroll region is active).
+    
+    When fixed layout is active, Rich Live is incompatible and should be disabled.
+    """
+    try:
+        from dolphin.cli.ui.console import _active_status_bar
+        # If there's an active status bar with a fixed_row, we're in fixed layout mode
+        if _active_status_bar and hasattr(_active_status_bar, 'fixed_row'):
+            return _active_status_bar.fixed_row is not None
+    except ImportError:
+        pass
+    return False
+
+
+class LiveStreamRenderer:
+    """
+    Live Markdown renderer for LLM streaming output.
+    
+    This class manages Rich's Live component to provide real-time
+    Markdown rendering of LLM responses. If Rich is not available,
+    or if fixed layout mode is active, it falls back to simple console output.
+    
+    IMPORTANT: Rich Live is DISABLED when fixed bottom layout is active,
+    because Rich Live and ANSI scroll regions are fundamentally incompatible.
+    Rich Live takes over terminal control and breaks our scroll region setup.
+    """
+    
+    def __init__(self, verbose: bool = True):
+        self._live = None
+        self._Markdown = None
+        self._verbose = verbose
+        self._started = False
+        self._rich_available = False
+        self._use_simple_mode = False  # True when Rich Live is disabled
+        self._paused_status_bar = None  # Track paused status bar for resume
+        self._has_output = False  # Track if we've actually output something
+        
+    def start(self) -> "LiveStreamRenderer":
+        """
+        Start the Live renderer context.
+        
+        Returns self for method chaining:
+            renderer = LiveStreamRenderer().start()
+        """
+        if not self._verbose:
+            return self
+        
+        # Pause the status bar to avoid conflicts with streaming output
+        try:
+            from dolphin.cli.ui.console import _pause_active_status_bar
+            self._paused_status_bar = _pause_active_status_bar()
+        except ImportError:
+            self._paused_status_bar = None
+        
+        # ALWAYS use simple mode in CLI
+        # Rich Live is INCOMPATIBLE with scroll regions and terminal layouts
+        # because it takes over terminal control and breaks cursor positioning
+        import sys
+        if sys.stdout.isatty():
+            self._use_simple_mode = True
+            self._started = True
+            return self
+        
+        # Non-TTY fallback: try Rich Live (for notebooks, etc.)
+        try:
+            from rich.live import Live
+            from rich.markdown import Markdown
+            
+            self._Markdown = Markdown
+            self._live = Live(
+                Markdown(""),
+                auto_refresh=True,
+                refresh_per_second=10,
+                vertical_overflow="visible",
+            )
+            self._live.start()
+            self._rich_available = True
+            self._started = True
+        except ImportError:
+            self._rich_available = False
+            self._started = True
+            
+        return self
+    
+    def on_chunk(self, chunk_text: str, full_text: str, is_final: bool = False) -> None:
+        """
+        Callback for each streaming chunk.
+        
+        Args:
+            chunk_text: The new text in this chunk (delta)
+            full_text: The complete accumulated text so far
+            is_final: Whether this is the final chunk
+        """
+        if not self._verbose:
+            return
+        
+        if self._use_simple_mode:
+            # Line-buffered output with manual ANSI highlighting
+            # This provides basic Markdown formatting without Rich Live
+            if not hasattr(self, '_line_buffer'):
+                self._line_buffer = ""
+            
+            self._line_buffer += chunk_text
+            
+            # Process complete lines
+            while '\n' in self._line_buffer:
+                line, self._line_buffer = self._line_buffer.split('\n', 1)
+                self._print_highlighted_line(line)
+                self._has_output = True  # Track that we've output something
+                
+        elif self._rich_available and self._live and self._Markdown:
+            # Rich Live mode: update with full Markdown
+            self._live.update(self._Markdown(full_text))
+        else:
+            # Fallback: print incremental text
+            print(chunk_text, end="", flush=True)
+    
+    def _print_highlighted_line(self, line: str) -> None:
+        """Print a line with simple ANSI Markdown highlighting."""
+        # ANSI codes
+        BOLD = "\033[1m"
+        RESET = "\033[0m"
+        CYAN = "\033[36m"
+        GREEN = "\033[32m"
+        YELLOW = "\033[33m"
+        MAGENTA = "\033[35m"
+        BLUE = "\033[34m"
+        WHITE = "\033[37m"
+        DIM = "\033[2m"
+        BG_GRAY = "\033[48;5;236m"  # Dark gray background for code
+        
+        stripped = line.lstrip()
+        indent = line[:len(line) - len(stripped)]
+        
+        # Track code block state
+        if not hasattr(self, '_in_code_block'):
+            self._in_code_block = False
+            self._code_lang = ""
+        
+        # Code block start/end markers
+        if stripped.startswith('```'):
+            if not self._in_code_block:
+                # Starting a code block
+                self._in_code_block = True
+                self._code_lang = stripped[3:].strip()
+                lang_display = f" {self._code_lang}" if self._code_lang else ""
+                print(f"{indent}{DIM}╭───{lang_display}{'─' * max(0, 40 - len(lang_display))}╮{RESET}")
+            else:
+                # Ending a code block
+                self._in_code_block = False
+                self._code_lang = ""
+                print(f"{indent}{DIM}╰{'─' * 44}╯{RESET}")
+            return
+        
+        # Inside code block - render code with special formatting
+        if self._in_code_block:
+            print(f"{indent}{DIM}│{RESET} {GREEN}{stripped}{RESET}")
+            return
+        
+        # Headers (H1-H6) - check longer prefixes first, remove # prefix for cleaner output
+        if stripped.startswith('###### '):
+            title = stripped[7:]  # Remove '###### '
+            print(f"{indent}{DIM}{title}{RESET}")
+        elif stripped.startswith('##### '):
+            title = stripped[6:]  # Remove '##### '
+            print(f"{indent}{WHITE}{title}{RESET}")
+        elif stripped.startswith('#### '):
+            title = stripped[5:]  # Remove '#### '
+            print(f"{indent}{BLUE}{BOLD}{title}{RESET}")
+        elif stripped.startswith('### '):
+            title = stripped[4:]  # Remove '### '
+            print(f"{indent}{MAGENTA}{BOLD}{title}{RESET}")
+        elif stripped.startswith('## '):
+            title = stripped[3:]  # Remove '## '
+            print(f"{indent}{CYAN}{BOLD}{title}{RESET}")
+        elif stripped.startswith('# '):
+            title = stripped[2:]  # Remove '# '
+            print(f"{indent}{YELLOW}{BOLD}{title}{RESET}")
+        # Markdown tables - detect lines with | delimiters
+        elif stripped.startswith('|') and stripped.endswith('|'):
+            # Check if it's a separator row (|---|---|)
+            inner = stripped[1:-1]
+            if all(c in '-|: ' for c in inner):
+                # Table separator row - render as horizontal line
+                cells = inner.split('|')
+                rendered_cells = [DIM + '─' * max(3, len(cell.strip())) + RESET for cell in cells]
+                print(f"{indent}{DIM}├{'┼'.join(rendered_cells)}┤{RESET}")
+            else:
+                # Table data row - render with nice borders
+                cells = inner.split('|')
+                rendered_cells = [self._highlight_inline(cell.strip()) for cell in cells]
+                print(f"{indent}{DIM}│{RESET} {f' {DIM}│{RESET} '.join(rendered_cells)} {DIM}│{RESET}")
+        # Lists
+        elif stripped.startswith('- ') or stripped.startswith('* '):
+            bullet = stripped[0]
+            content = stripped[2:]
+            # Handle inline formatting in content
+            content = self._highlight_inline(content)
+            print(f"{indent}{GREEN}•{RESET} {content}")
+        # Numbered lists
+        elif len(stripped) > 2 and stripped[0].isdigit() and stripped[1] in '.:)':
+            num = stripped[0]
+            content = stripped[2:].lstrip()
+            content = self._highlight_inline(content)
+            print(f"{indent}{GREEN}{num}.{RESET} {content}")
+        # Regular text with inline formatting
+        else:
+            print(f"{indent}{self._highlight_inline(stripped)}")
+    
+    def _highlight_inline(self, text: str) -> str:
+        """Highlight inline Markdown: **bold**, `code`, etc."""
+        import re
+        BOLD = "\033[1m"
+        RESET = "\033[0m"
+        CYAN = "\033[36m"
+        DIM = "\033[2m"
+        
+        # Replace **text** with bold
+        text = re.sub(r'\*\*(.+?)\*\*', f'{BOLD}\\1{RESET}', text)
+        # Replace `code` with cyan
+        text = re.sub(r'`([^`]+)`', f'{CYAN}\\1{RESET}', text)
+        return text
+    
+    def _highlight_inline_bold(self, text: str) -> str:
+        """Highlight **bold** text with ANSI codes. (Legacy, use _highlight_inline instead)"""
+        return self._highlight_inline(text)
+    
+    def stop(self) -> None:
+        """Stop the Live renderer and clean up."""
+        # Flush any remaining buffer in simple mode
+        if self._use_simple_mode and self._started:
+            if hasattr(self, '_line_buffer') and self._line_buffer:
+                # Print remaining content (may not end with newline)
+                self._print_highlighted_line(self._line_buffer)
+                self._line_buffer = ""
+            # Only add newline if we actually output something
+            elif hasattr(self, '_has_output') and self._has_output:
+                print()  # End the streaming output with a newline
+
+        if self._live and self._started and not self._use_simple_mode:
+            try:
+                self._live.stop()
+            except Exception:
+                pass
+        self._started = False
+        self._use_simple_mode = False
+        self._has_output = False  # Reset for next use
+        
+        # Resume the status bar that was paused during streaming
+        if hasattr(self, '_paused_status_bar') and self._paused_status_bar:
+            try:
+                from dolphin.cli.ui.console import _resume_status_bar
+                _resume_status_bar(self._paused_status_bar)
+            except ImportError:
+                pass
+            self._paused_status_bar = None
+        
+    def __enter__(self) -> "LiveStreamRenderer":
+        """Context manager support."""
+        return self.start()
+        
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Context manager cleanup."""
+        self.stop()
+
+
+# Convenience function for getting a renderer callback
+def create_stream_renderer(verbose: bool = True) -> tuple:
+    """
+    Create a stream renderer and return (renderer, callback).
+    
+    Usage:
+        renderer, on_chunk = create_stream_renderer()
+        renderer.start()
+        async for item in llm_chat_stream(..., on_stream_chunk=on_chunk):
+            ...
+        renderer.stop()
+    
+    Returns:
+        Tuple of (LiveStreamRenderer instance, on_chunk callback)
+    """
+    renderer = LiveStreamRenderer(verbose=verbose)
+    return renderer, renderer.on_chunk

dolphin/cli/utils/__init__.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""Utils 模块 - CLI 工具"""
+
+from dolphin.cli.utils.version import getVersion
+
+__all__ = [
+    "getVersion",
+]

dolphin/cli/utils/helpers.py

@@ -0,0 +1,135 @@
+"""
+Utility functions for Dolphin CLI
+
+This module contains helper functions used by the CLI.
+"""
+
+import json
+import sys
+from typing import Any, Dict, List
+
+from dolphin.core.common.constants import (
+    DOLPHIN_VARIABLES_OUTPUT_START,
+    DOLPHIN_VARIABLES_OUTPUT_END,
+)
+from dolphin.core.logging.logger import console
+
+from dolphin.cli.args.parser import Args
+
+
+def readFile(filePath: str) -> str:
+    """Read content from file
+    
+    Args:
+        filePath: Path to the file
+        
+    Returns:
+        File content as string
+    """
+    try:
+        with open(filePath, "r", encoding="utf-8") as file:
+            return file.read()
+    except FileNotFoundError:
+        console(f"Error: File not found: {filePath}")
+        sys.exit(1)
+    except Exception as e:
+        console(f"Error reading file {filePath}: {e}")
+        sys.exit(1)
+
+
+def buildVariables(args: Args) -> Dict[str, Any]:
+    """Build variables dictionary from arguments
+    
+    Args:
+        args: Parsed CLI arguments
+        
+    Returns:
+        Dictionary of variables to pass to the agent
+    """
+    variables = {}
+    
+    if args.query is not None:
+        variables["query"] = args.query
+    
+    if args.userId is not None:
+        variables["user_id"] = args.userId
+    
+    if args.runArgs:
+        variables.update(args.runArgs)
+    
+    return variables
+
+
+def outputVariablesToJson(context, variableNames: List[str]) -> None:
+    """Output specified variables in JSON format
+    
+    Args:
+        context: Dolphin context object
+        variableNames: List of variable names to output (empty = all)
+    """
+    if not variableNames:
+        allVariables = context.get_all_variables_values()
+    else:
+        allVariables = {}
+        for varName in variableNames:
+            try:
+                varValue = context.get_var_path_value(varName)
+                if varValue is not None:
+                    allVariables[varName] = varValue
+            except Exception:
+                allVariables[varName] = None
+    
+    if "_all_stages" not in allVariables:
+        allVariables["_all_stages"] = context.get_runtime_graph().get_all_stages()
+    
+    variablesJson = json.dumps(
+        allVariables, ensure_ascii=False, default=str, indent=2
+    )
+    console(f"\n{DOLPHIN_VARIABLES_OUTPUT_START}")
+    console(variablesJson)
+    console(f"{DOLPHIN_VARIABLES_OUTPUT_END}\n")
+
+
+def validateArgs(args: Args) -> None:
+    """Validate CLI arguments before execution
+    
+    Args:
+        args: Parsed CLI arguments
+        
+    Raises:
+        SystemExit: If validation fails
+    """
+    import os
+    
+    if args.folder and not os.path.exists(args.folder):
+        console(f"Error: Folder not found: {args.folder}")
+        sys.exit(1)
+    
+    if args.skillFolder and not os.path.exists(args.skillFolder):
+        console(f"Error: Skill folder not found: {args.skillFolder}")
+        sys.exit(1)
+
+
+def setupFlagsFromArgs(args: Args) -> None:
+    """Set feature flags from CLI arguments
+    
+    Args:
+        args: Parsed CLI arguments
+    """
+    from dolphin.core import flags
+    
+    if not args.flagsOverrides:
+        return
+    
+    for flagName, flagValue in args.flagsOverrides.items():
+        # Convert string "true"/"false" to boolean, handle boolean directly
+        if isinstance(flagValue, str):
+            boolValue = flagValue.lower() in ('true', '1', 'yes', 'on', 'True')
+        else:
+            boolValue = bool(flagValue)
+        
+        flags.set_flag(flagName, boolValue)
+        # Cleaner flag output
+        state = "Enabled" if boolValue else "Disabled"
+        console(f"[Flag] {flagName}: {state}")
+

dolphin/cli/utils/version.py

@@ -0,0 +1,49 @@
+"""
+Version management for Dolphin CLI
+
+Reads version from VERSION file to avoid hardcoding.
+"""
+
+import os
+from functools import lru_cache
+
+
+@lru_cache(maxsize=1)
+def getVersion() -> str:
+    """
+    Get version from VERSION file.
+    
+    Returns:
+        Version string (e.g., "0.3.3")
+    """
+    # Try multiple paths to find VERSION file
+    possiblePaths = [
+        # When running from project root
+        os.path.join(os.getcwd(), "VERSION"),
+        # When running from bin/
+        os.path.join(os.path.dirname(__file__), "..", "..", "..", "..", "VERSION"),
+        # Fallback: relative to this file
+        os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..", "..", "VERSION"),
+    ]
+    
+    for versionPath in possiblePaths:
+        normalizedPath = os.path.normpath(versionPath)
+        if os.path.exists(normalizedPath):
+            try:
+                with open(normalizedPath, "r", encoding="utf-8") as f:
+                    return f.read().strip()
+            except Exception:
+                continue
+    
+    return "unknown"
+
+
+def getFullVersion() -> str:
+    """
+    Get full version string for display.
+    
+    Returns:
+        Full version string (e.g., "Dolphin Language v0.3.3")
+    """
+    return f"Dolphin Language v{getVersion()}"
+

dolphin/core/__init__.py

@@ -0,0 +1,107 @@
+# -*- coding: utf-8 -*-
+"""
+Dolphin Core - 核心运行时引擎（内核态）
+
+职责：
+- 执行引擎（Executor）
+- 上下文管理（Context）
+- 上下文工程（Context Engineer）
+- 消息压缩（Message Compressor）
+- 变量池（Variable Pool）
+- 语法解析器（Parser）
+- 协程调度（Coroutine）
+- 代码块执行（Code Block）
+- LLM 调用抽象层
+- Skill 核心（Skillkit、skill_function、skill_matcher）
+- 轨迹记录（Trajectory）
+- Agent 核心定义（BaseAgent、AgentState）
+- Runtime 核心（RuntimeInstance、RuntimeGraph）
+
+依赖规则：
+- dolphin.core 无内部依赖（仅依赖第三方库）
+"""
+
+# Context
+from dolphin.core.context.context import Context
+from dolphin.core.context_engineer.core.context_manager import ContextManager
+from dolphin.core.context.variable_pool import VariablePool
+
+# Executor
+from dolphin.core.executor.executor import Executor
+# DolphinExecutor is available via lazy import from dolphin.core.executor
+from dolphin.core.executor.debug_controller import DebugController
+
+# Runtime
+from dolphin.core.runtime.runtime_instance import RuntimeInstance
+from dolphin.core.runtime.runtime_graph import RuntimeGraph
+
+# Agent
+from dolphin.core.agent.base_agent import BaseAgent
+from dolphin.core.agent.agent_state import AgentState
+
+# 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
+
+# LLM
+from dolphin.core.llm.llm import LLM
+from dolphin.core.llm.llm_client import LLMClient
+from dolphin.core.llm.llm_call import LLMCall
+
+# Config
+from dolphin.core.config.global_config import GlobalConfig
+
+# Common
+from dolphin.core.common.enums import MessageRole, SkillType
+from dolphin.core.common.exceptions import DolphinException
+
+# Logging
+from dolphin.core.logging.logger import get_logger
+
+# Trajectory
+from dolphin.core.trajectory.trajectory import Trajectory
+from dolphin.core.trajectory.recorder import Recorder
+
+# Interfaces
+from dolphin.core.interfaces import IMemoryManager
+
+__all__ = [
+    # Context
+    "Context",
+    "ContextManager",
+    "VariablePool",
+    # Executor
+    "Executor",
+    # DolphinExecutor is available via lazy import
+    "DebugController",
+    # Runtime
+    "RuntimeInstance",
+    "RuntimeGraph",
+    # Agent
+    "BaseAgent",
+    "AgentState",
+    # Skill
+    "Skillkit",
+    "Skillset",
+    "SkillFunction",
+    "SkillMatcher",
+    # LLM
+    "LLM",
+    "LLMClient",
+    "LLMCall",
+    # Config
+    "GlobalConfig",
+    # Common
+    "MessageRole",
+    "SkillType",
+    "DolphinException",
+    # Logging
+    "get_logger",
+    # Trajectory
+    "Trajectory",
+    "Recorder",
+    # Interfaces
+    "IMemoryManager",
+]

dolphin/core/agent/__init__.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+"""Agent 模块 - Agent 核心定义"""
+
+from dolphin.core.agent.base_agent import BaseAgent
+from dolphin.core.agent.agent_state import AgentState
+
+__all__ = [
+    "BaseAgent",
+    "AgentState",
+]

dolphin/core/agent/agent_state.py

@@ -0,0 +1,69 @@
+"""Agent state enumeration definition"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+
+class AgentState(Enum):
+    """Agent State Enumeration"""
+
+    CREATED = "created"  # Created, not initialized
+    INITIALIZED = "initialized"  # Initialized
+    RUNNING = "running"  # Running
+    PAUSED = "paused"  # Paused
+    COMPLETED = "completed"  # Completed
+    TERMINATED = "terminated"  # Terminated
+    ERROR = "error"  # Error State
+
+
+class PauseType(Enum):
+    """Type of pause that caused agent to enter PAUSED state.
+
+    Values:
+        MANUAL: User explicitly called pause()
+        TOOL_INTERRUPT: Tool requested user input (ToolInterrupt)
+        USER_INTERRUPT: User actively interrupted execution (UserInterrupt)
+    """
+    MANUAL = "manual"
+    TOOL_INTERRUPT = "tool_interrupt"
+    USER_INTERRUPT = "user_interrupt"
+
+
+class AgentEvent(Enum):
+    """Agent Event Enumeration"""
+
+    INIT = "init"  # Initialize event
+    START = "start"  # Start executing event
+    PAUSE = "pause"  # Pause Event
+    RESUME = "resume"  # Recover event
+    TERMINATE = "terminate"  # Termination Event
+    COMPLETE = "complete"  # Completion Event
+    ERROR = "error"  # Error Event
+
+
+class AgentStatus:
+    """Agent State Information Container"""
+
+    def __init__(
+        self,
+        state: AgentState = AgentState.CREATED,
+        message: str = "",
+        data: Any = None,
+    ):
+        self.state = state
+        self.message = message
+        self.data = data
+        self.timestamp: datetime = datetime.now()
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary format"""
+        return {
+            "state": self.state.value,
+            "message": self.message,
+            "data": self.data,
+            "timestamp": self.timestamp.isoformat() if self.timestamp else None,
+        }
+
+    def __str__(self) -> str:
+        return f"AgentStatus(state={self.state.value}, message='{self.message}')"