hdsp-jupyter-extension 2.0.5__py3-none-any.whl → 2.0.7__py3-none-any.whl

agent_server/langchain/prompts.py

@@ -0,0 +1,119 @@
+"""
+Prompt templates for LangChain agent.
+
+Contains system prompts, JSON schema for fallback tool calling,
+and middleware-specific prompts.
+"""
+
+DEFAULT_SYSTEM_PROMPT = """You are an expert Python data scientist and Jupyter notebook assistant.
+Your role is to help users with data analysis, visualization, and Python coding tasks in Jupyter notebooks. You can use only Korean
+
+## ⚠️ CRITICAL RULE: NEVER produce an empty response
+
+You MUST ALWAYS call a tool in every response. After any tool result, you MUST:
+1. Check your todo list - are there pending or in_progress items?
+2. If YES → call the next appropriate tool (jupyter_cell_tool, markdown_tool, etc.)
+3. When you suggest next steps for todo item '다음 단계 제시', you MUST create next steps in json format matching this schema:
+{
+  "next_items": [
+    {
+        "subject": "<subject for next step>",
+        "description": "<detailed description for the next step>"
+    }, ...
+  ]
+}
+4. If ALL todos are completed → call final_answer_tool with a summary
+
+NEVER end your turn without calling a tool. NEVER produce an empty response.
+
+## 🔴 MANDATORY: Resource Check Before Data Hanlding
+**ALWAYS call check_resource_tool FIRST** when the task involves:
+- Loading files: .csv, .parquet, .json, .xlsx, .pickle, .h5, .feather
+- Handling datasets(dataframe) with pandas, polars, dask, or similar libraries
+- Training ML models on data files
+
+## Mandatory Workflow
+1. After EVERY tool result, immediately call the next tool
+2. Continue until ALL todos show status: "completed"
+3. ONLY THEN call final_answer_tool to summarize
+4. Only use jupyter_cell_tool for Python code or when the user explicitly asks to run in a notebook cell
+5. For plots and charts, use English text only.
+
+## ❌ FORBIDDEN (will break the workflow)
+- Producing an empty response (no tool call, no content)
+- Stopping after any tool without calling the next tool
+- Ending without calling final_answer_tool
+- Leaving todos in "in_progress" or "pending" state without continuing
+
+## 🚫 execute_command_tool Rules
+**NEVER run long-running commands** with execute_command_tool (e.g., servers, daemons, watch processes).
+- ✅ Allowed: Quick commands like `ls`, `cat`, `grep`, `git status`
+- ❌ Forbidden: `jupyter lab`, `npm start`, `python app.py`, `watch`, background processes
+- For long tasks: Use jupyter_cell_tool instead or inform the user to run manually
+"""
+
+JSON_TOOL_SCHEMA = """You MUST respond with ONLY valid JSON matching this schema:
+{
+  "tool": "<tool_name>",
+  "arguments": {"arg1": "value1", ...}
+}
+
+Available tools:
+- jupyter_cell_tool: Execute Python code. Arguments: {"code": "<python_code>"}
+- markdown_tool: Add markdown cell. Arguments: {"content": "<markdown>"}
+- final_answer_tool: Complete task. Arguments: {"answer": "<summary>"}
+- write_todos: Update task list. Arguments: {"todos": [{"content": "...", "status": "pending|in_progress|completed"}]}
+- read_file_tool: Read file. Arguments: {"path": "<file_path>"}
+- write_file_tool: Write file. Arguments: {"path": "<path>", "content": "<content>", "overwrite": false}
+- list_files_tool: List directory. Arguments: {"path": ".", "recursive": false}
+- search_workspace_tool: Search files. Arguments: {"pattern": "<regex>", "file_types": ["py"], "path": "."}
+- search_notebook_cells_tool: Search notebook cells. Arguments: {"pattern": "<regex>"}
+- execute_command_tool: Execute shell command. Arguments: {"command": "<command>", "stdin": "<input_for_prompts>"}
+- check_resource_tool: Check resources before data processing. Arguments: {"files": ["<path>"], "dataframes": ["<var_name>"]}
+
+Output ONLY the JSON object, no markdown, no explanation."""
+
+TODO_LIST_SYSTEM_PROMPT = """
+## CRITICAL WORKFLOW RULES - MUST FOLLOW:
+1. NEVER stop after calling write_todos - ALWAYS make another tool call immediately
+2. write_todos is ONLY for tracking progress - it does NOT complete any work
+3. After EVERY write_todos call, you MUST call another tool (jupyter_cell_tool, markdown_tool, or final_answer_tool)
+
+## Todo List Management:
+- Before complex tasks, use write_todos to create a task list
+- Update todos as you complete each step (mark 'in_progress' → 'completed')
+- Each todo item should be specific and descriptive (30-60 characters)
+- All todo items must be written in Korean
+- ALWAYS include "다음 단계 제시" as the LAST item
+
+## Task Completion Flow:
+1. When current task is done → mark it 'completed' with write_todos
+2. IMMEDIATELY call the next tool (jupyter_cell_tool for code, markdown_tool for text)
+3. For "다음 단계 제시" → mark completed, then call final_answer_tool with suggestions
+4. NEVER end your turn after write_todos - you MUST continue with actual work
+
+## FORBIDDEN PATTERNS:
+❌ Calling write_todos and then stopping
+❌ Updating todo status without doing the actual work
+❌ Ending turn without calling final_answer_tool when all tasks are done
+"""
+
+TODO_LIST_TOOL_DESCRIPTION = """Update the task list for tracking progress.
+⚠️ CRITICAL: This tool is ONLY for tracking - it does NOT do any actual work.
+After calling this tool, you MUST IMMEDIATELY call another tool (jupyter_cell_tool, markdown_tool, or final_answer_tool).
+NEVER end your response after calling write_todos - always continue with the next action tool."""
+
+# Non-HITL tools that execute immediately without user approval
+NON_HITL_TOOLS = {
+    "markdown_tool",
+    "markdown",
+    "read_file_tool",
+    "read_file",
+    "list_files_tool",
+    "list_files",
+    "search_workspace_tool",
+    "search_workspace",
+    "search_notebook_cells_tool",
+    "search_notebook_cells",
+    "write_todos",
+}

agent_server/langchain/state.py

@@ -6,7 +6,7 @@ This state is passed through the agent execution and updated by middleware.
 """
 
 from dataclasses import dataclass
-from typing import Annotated, Any, Dict, List, Optional, TypedDict
+from typing import Annotated, Any, Dict, List, Optional, TypedDict, Union
 
 from langchain_core.messages import BaseMessage
 from langgraph.graph.message import add_messages
@@ -14,6 +14,7 @@ from langgraph.graph.message import add_messages
 
 class NotebookContext(TypedDict, total=False):
     """Current notebook context"""
+
     notebook_path: str
     cell_count: int
     imported_libraries: List[str]
@@ -24,6 +25,7 @@ class NotebookContext(TypedDict, total=False):
 
 class ExecutionResult(TypedDict, total=False):
     """Result of code execution"""
+
     success: bool
     output: str
     error_type: Optional[str]
@@ -35,6 +37,7 @@ class ExecutionResult(TypedDict, total=False):
 
 class SearchResult(TypedDict, total=False):
     """Result of code search"""
+
     file_path: str
     cell_index: Optional[int]
     line_number: Optional[int]
@@ -51,6 +54,7 @@ class AgentState(TypedDict, total=False):
     - Tool executions (execution results, search results)
     - Agent decisions (current step, plan updates)
     """
+
     # Message history - uses add_messages reducer to accumulate messages
     messages: Annotated[List[BaseMessage], add_messages]
 
@@ -87,6 +91,9 @@ class AgentState(TypedDict, total=False):
     # Detected libraries for knowledge injection
     detected_libraries: List[str]
 
+    # Resource usage context (legacy, use check_resource_tool instead)
+    resource_context: Optional[Union[Dict[str, Any], str]]
+
     # Final answer
     final_answer: Optional[str]
     is_complete: bool
@@ -96,9 +103,10 @@ class AgentState(TypedDict, total=False):
 class AgentRuntime:
     """
     Runtime context passed to middleware.
-    
+
     Contains references to executors and services needed by middleware.
     """
+
     jupyter_executor: Any = None
     notebook_searcher: Any = None
     rag_manager: Any = None
@@ -107,7 +115,7 @@ class AgentRuntime:
     workspace_root: str = "."
 
     # Execution mode
-    embedded_mode: bool = True
+    embedded_mode: bool = False
 
     # Configuration
     max_retries: int = 3
@@ -123,19 +131,20 @@ def create_initial_state(
 ) -> AgentState:
     """
     Create initial agent state from user request.
-    
+
     Args:
         user_request: Natural language request from user
         notebook_context: Current notebook state
         llm_config: LLM configuration
-        
+
     Returns:
         Initialized AgentState
     """
     return AgentState(
         messages=[],
         user_request=user_request,
-        notebook_context=notebook_context or NotebookContext(
+        notebook_context=notebook_context
+        or NotebookContext(
             notebook_path="",
             cell_count=0,
             imported_libraries=[],
@@ -154,6 +163,7 @@ def create_initial_state(
         recovery_strategy=None,
         llm_config=llm_config or {},
         detected_libraries=[],
+        resource_context=None,
         final_answer=None,
         is_complete=False,
     )

agent_server/langchain/tools/__init__.py

@@ -10,6 +10,8 @@ Tools available:
 - list_files: List directory contents
 - search_workspace: Search files in workspace
 - search_notebook_cells: Search cells in notebooks
+- execute_command_tool: Run shell commands (client-executed)
+- check_resource_tool: Check resources before data processing (client-executed)
 """
 
 from agent_server.langchain.tools.file_tools import (
@@ -22,10 +24,12 @@ from agent_server.langchain.tools.jupyter_tools import (
     jupyter_cell_tool,
     markdown_tool,
 )
+from agent_server.langchain.tools.resource_tools import check_resource_tool
 from agent_server.langchain.tools.search_tools import (
     search_notebook_cells_tool,
     search_workspace_tool,
 )
+from agent_server.langchain.tools.shell_tools import execute_command_tool
 
 __all__ = [
     "jupyter_cell_tool",
@@ -36,4 +40,6 @@ __all__ = [
     "list_files_tool",
     "search_workspace_tool",
     "search_notebook_cells_tool",
+    "execute_command_tool",
+    "check_resource_tool",
 ]

agent_server/langchain/tools/file_tools.py

@@ -8,7 +8,7 @@ Provides tools for file system operations:
 """
 
 import os
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, Optional
 
 from langchain_core.tools import tool
 from pydantic import BaseModel, Field
@@ -16,31 +16,54 @@ from pydantic import BaseModel, Field
 
 class ReadFileInput(BaseModel):
     """Input schema for read_file tool"""
+
     path: str = Field(description="Relative path to the file to read")
     encoding: str = Field(default="utf-8", description="File encoding")
+    max_lines: Optional[int] = Field(
+        default=None,
+        description="Maximum number of lines to read",
+    )
+    execution_result: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Optional execution result payload from the client",
+    )
 
 
 class WriteFileInput(BaseModel):
     """Input schema for write_file tool"""
+
     path: str = Field(description="Relative path to the file to write")
     content: str = Field(description="Content to write to the file")
     encoding: str = Field(default="utf-8", description="File encoding")
+    overwrite: bool = Field(
+        default=False,
+        description="Whether to overwrite an existing file (default: false)",
+    )
+    execution_result: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Optional execution result payload from the client",
+    )
 
 
 class ListFilesInput(BaseModel):
     """Input schema for list_files tool"""
+
     path: str = Field(default=".", description="Directory path to list")
     recursive: bool = Field(default=False, description="Whether to list recursively")
     pattern: Optional[str] = Field(
         default=None,
-        description="Glob pattern to filter files (e.g., '*.py', '*.ipynb')"
+        description="Glob pattern to filter files (e.g., '*.py', '*.ipynb')",
+    )
+    execution_result: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Optional execution result payload from the client",
     )
 
 
 def _validate_path(path: str, workspace_root: str = ".") -> str:
     """
     Validate and resolve file path.
-    
+
     Security checks:
     - No absolute paths allowed
     - No parent directory traversal (..)
@@ -70,93 +93,88 @@ def _validate_path(path: str, workspace_root: str = ".") -> str:
 def read_file_tool(
     path: str,
     encoding: str = "utf-8",
-    workspace_root: str = "."
+    max_lines: Optional[int] = None,
+    execution_result: Optional[Dict[str, Any]] = None,
+    workspace_root: str = ".",
 ) -> Dict[str, Any]:
     """
     Read content from a file.
-    
+
     Only relative paths within the workspace are allowed.
     Absolute paths and parent directory traversal (..) are blocked.
-    
+
     Args:
         path: Relative path to the file
         encoding: File encoding (default: utf-8)
-        
+
     Returns:
         Dict with file content or error
     """
-    try:
-        resolved_path = _validate_path(path, workspace_root)
-
-        if not os.path.exists(resolved_path):
-            return {
-                "tool": "read_file",
-                "success": False,
-                "error": f"File not found: {path}",
-                "path": path,
-            }
-
-        if not os.path.isfile(resolved_path):
-            return {
-                "tool": "read_file",
-                "success": False,
-                "error": f"Not a file: {path}",
-                "path": path,
-            }
-
-        with open(resolved_path, "r", encoding=encoding) as f:
-            content = f.read()
-
-        return {
-            "tool": "read_file",
-            "success": True,
-            "path": path,
-            "content": content,
-            "size": len(content),
-        }
-
-    except ValueError as e:
+    if os.path.isabs(path):
         return {
-            "tool": "read_file",
+            "tool": "read_file_tool",
             "success": False,
-            "error": str(e),
+            "error": f"Absolute paths not allowed: {path}",
             "path": path,
         }
-    except Exception as e:
+    if ".." in path:
         return {
-            "tool": "read_file",
+            "tool": "read_file_tool",
             "success": False,
-            "error": f"Failed to read file: {str(e)}",
+            "error": f"Parent directory traversal not allowed: {path}",
             "path": path,
         }
 
+    response: Dict[str, Any] = {
+        "tool": "read_file_tool",
+        "parameters": {
+            "path": path,
+            "encoding": encoding,
+            "max_lines": max_lines,
+        },
+        "status": "pending_execution",
+        "message": "File read queued for execution by client",
+    }
+    if execution_result is not None:
+        response["execution_result"] = execution_result
+        response["status"] = "complete"
+        response["message"] = "File read executed with client-reported results"
+    return response
+
 
 @tool(args_schema=WriteFileInput)
 def write_file_tool(
     path: str,
     content: str,
     encoding: str = "utf-8",
-    workspace_root: str = "."
+    overwrite: bool = False,
+    execution_result: Optional[Dict[str, Any]] = None,
+    workspace_root: str = ".",
 ) -> Dict[str, Any]:
     """
     Write content to a file.
-    
+
     This operation requires user approval before execution.
     Only relative paths within the workspace are allowed.
-    
+
     Args:
         path: Relative path to the file
         content: Content to write
         encoding: File encoding (default: utf-8)
-        
+
     Returns:
         Dict with operation status (pending approval)
     """
     try:
         resolved_path = _validate_path(path, workspace_root)
 
-        return {
-            "tool": "write_file",
+        response: Dict[str, Any] = {
+            "tool": "write_file_tool",
+            "parameters": {
+                "path": path,
+                "encoding": encoding,
+                "overwrite": overwrite,
+            },
             "status": "pending_approval",
             "path": path,
             "resolved_path": resolved_path,
@@ -164,10 +182,15 @@ def write_file_tool(
             "content_length": len(content),
             "message": "File write operation requires user approval",
         }
+        if execution_result is not None:
+            response["execution_result"] = execution_result
+            response["status"] = "complete"
+            response["message"] = "File write executed with client-reported results"
+        return response
 
     except ValueError as e:
         return {
-            "tool": "write_file",
+            "tool": "write_file_tool",
             "success": False,
             "error": str(e),
             "path": path,
@@ -179,96 +202,35 @@ def list_files_tool(
     path: str = ".",
     recursive: bool = False,
     pattern: Optional[str] = None,
-    workspace_root: str = "."
+    execution_result: Optional[Dict[str, Any]] = None,
+    workspace_root: str = ".",
 ) -> Dict[str, Any]:
     """
     List files and directories.
-    
+
     Args:
         path: Directory path to list (default: current directory)
         recursive: Whether to list recursively
         pattern: Optional glob pattern to filter (e.g., '*.py')
-        
+
     Returns:
         Dict with list of files and directories
     """
-    import fnmatch
-
-    try:
-        resolved_path = _validate_path(path, workspace_root)
-
-        if not os.path.exists(resolved_path):
-            return {
-                "tool": "list_files",
-                "success": False,
-                "error": f"Directory not found: {path}",
-                "path": path,
-            }
-
-        if not os.path.isdir(resolved_path):
-            return {
-                "tool": "list_files",
-                "success": False,
-                "error": f"Not a directory: {path}",
-                "path": path,
-            }
-
-        files: List[Dict[str, Any]] = []
-        dirs: List[str] = []
-
-        if recursive:
-            for root, dirnames, filenames in os.walk(resolved_path):
-                rel_root = os.path.relpath(root, resolved_path)
-                for dirname in dirnames:
-                    dir_path = os.path.join(rel_root, dirname) if rel_root != "." else dirname
-                    dirs.append(dir_path)
-                for filename in filenames:
-                    if pattern and not fnmatch.fnmatch(filename, pattern):
-                        continue
-                    file_path = os.path.join(rel_root, filename) if rel_root != "." else filename
-                    full_path = os.path.join(root, filename)
-                    files.append({
-                        "name": filename,
-                        "path": file_path,
-                        "size": os.path.getsize(full_path),
-                    })
-        else:
-            for entry in os.scandir(resolved_path):
-                if entry.is_dir():
-                    dirs.append(entry.name)
-                elif entry.is_file():
-                    if pattern and not fnmatch.fnmatch(entry.name, pattern):
-                        continue
-                    files.append({
-                        "name": entry.name,
-                        "path": entry.name,
-                        "size": entry.stat().st_size,
-                    })
-
-        return {
-            "tool": "list_files",
-            "success": True,
+    response: Dict[str, Any] = {
+        "tool": "list_files_tool",
+        "parameters": {
             "path": path,
-            "directories": sorted(dirs),
-            "files": sorted(files, key=lambda x: x["name"]),
-            "total_dirs": len(dirs),
-            "total_files": len(files),
-        }
-
-    except ValueError as e:
-        return {
-            "tool": "list_files",
-            "success": False,
-            "error": str(e),
-            "path": path,
-        }
-    except Exception as e:
-        return {
-            "tool": "list_files",
-            "success": False,
-            "error": f"Failed to list directory: {str(e)}",
-            "path": path,
-        }
+            "recursive": recursive,
+            "pattern": pattern,
+        },
+        "status": "pending_execution",
+        "message": "File listing queued for execution by client",
+    }
+    if execution_result is not None:
+        response["execution_result"] = execution_result
+        response["status"] = "complete"
+        response["message"] = "File listing executed with client-reported results"
+    return response
 
 
 # Export all tools