hdsp-jupyter-extension 2.0.1__py3-none-any.whl → 2.0.3__py3-none-any.whl

agent_server/langchain/tools/file_tools.py

@@ -0,0 +1,279 @@
+"""
+File Tools for LangChain Agent
+
+Provides tools for file system operations:
+- read_file: Read file content
+- write_file: Write content to file (requires approval)
+- list_files: List directory contents
+"""
+
+import os
+from typing import Any, Dict, List, Optional
+
+from langchain_core.tools import tool
+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")
+
+
+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")
+
+
+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')"
+    )
+
+
+def _validate_path(path: str, workspace_root: str = ".") -> str:
+    """
+    Validate and resolve file path.
+    
+    Security checks:
+    - No absolute paths allowed
+    - No parent directory traversal (..)
+    - Must be within workspace root
+    """
+    # Block absolute paths
+    if os.path.isabs(path):
+        raise ValueError(f"Absolute paths not allowed: {path}")
+
+    # Block parent directory traversal
+    if ".." in path:
+        raise ValueError(f"Parent directory traversal not allowed: {path}")
+
+    # Resolve to absolute path within workspace
+    normalized_path = path or "."
+    resolved_abs = os.path.abspath(os.path.join(workspace_root, normalized_path))
+    workspace_abs = os.path.abspath(workspace_root)
+
+    # Ensure resolved path is within workspace
+    if os.path.commonpath([workspace_abs, resolved_abs]) != workspace_abs:
+        raise ValueError(f"Path escapes workspace: {path}")
+
+    return resolved_abs
+
+
+@tool(args_schema=ReadFileInput)
+def read_file_tool(
+    path: str,
+    encoding: str = "utf-8",
+    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:
+        return {
+            "tool": "read_file",
+            "success": False,
+            "error": str(e),
+            "path": path,
+        }
+    except Exception as e:
+        return {
+            "tool": "read_file",
+            "success": False,
+            "error": f"Failed to read file: {str(e)}",
+            "path": path,
+        }
+
+
+@tool(args_schema=WriteFileInput)
+def write_file_tool(
+    path: str,
+    content: str,
+    encoding: str = "utf-8",
+    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",
+            "status": "pending_approval",
+            "path": path,
+            "resolved_path": resolved_path,
+            "content_preview": content[:200] + "..." if len(content) > 200 else content,
+            "content_length": len(content),
+            "message": "File write operation requires user approval",
+        }
+
+    except ValueError as e:
+        return {
+            "tool": "write_file",
+            "success": False,
+            "error": str(e),
+            "path": path,
+        }
+
+
+@tool(args_schema=ListFilesInput)
+def list_files_tool(
+    path: str = ".",
+    recursive: bool = False,
+    pattern: Optional[str] = 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,
+            "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,
+        }
+
+
+# Export all tools
+FILE_TOOLS = [
+    read_file_tool,
+    write_file_tool,
+    list_files_tool,
+]

agent_server/langchain/tools/jupyter_tools.py

@@ -0,0 +1,143 @@
+"""
+Jupyter Tools for LangChain Agent
+
+Provides tools for interacting with Jupyter notebooks:
+- jupyter_cell: Execute Python code in a new cell
+- markdown: Add a markdown cell
+- final_answer: Complete the task with a summary
+"""
+
+from typing import Any, Dict, Optional
+
+from langchain_core.tools import tool
+from pydantic import BaseModel, Field
+
+
+class JupyterCellInput(BaseModel):
+    """Input schema for jupyter_cell tool"""
+    code: str = Field(description="Python code to execute in the notebook cell")
+    description: Optional[str] = Field(
+        default=None,
+        description="Optional description of what this code does"
+    )
+    execution_result: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Optional execution result payload from the client"
+    )
+
+
+class MarkdownInput(BaseModel):
+    """Input schema for markdown tool"""
+    content: str = Field(description="Markdown content to add to the notebook")
+
+
+class FinalAnswerInput(BaseModel):
+    """Input schema for final_answer tool"""
+    answer: str = Field(description="Final answer/summary to present to the user")
+    summary: Optional[str] = Field(
+        default=None,
+        description="Optional brief summary of what was accomplished"
+    )
+
+
+@tool(args_schema=JupyterCellInput)
+def jupyter_cell_tool(
+    code: str,
+    description: Optional[str] = None,
+    execution_result: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """
+    Execute Python code in a new Jupyter notebook cell.
+    
+    This tool adds a new code cell at the end of the notebook and executes it.
+    The execution is handled by JupyterExecutionMiddleware.
+    
+    Args:
+        code: Python code to execute
+        description: Optional description of the code's purpose
+        
+    Returns:
+        Dict containing execution request (actual execution by middleware)
+    """
+    # Clean code: remove markdown code block wrappers if present
+    cleaned_code = code.strip()
+    if cleaned_code.startswith("```python"):
+        cleaned_code = cleaned_code[9:]
+    elif cleaned_code.startswith("```"):
+        cleaned_code = cleaned_code[3:]
+    if cleaned_code.endswith("```"):
+        cleaned_code = cleaned_code[:-3]
+    cleaned_code = cleaned_code.strip()
+
+    response: Dict[str, Any] = {
+        "tool": "jupyter_cell",
+        "parameters": {
+            "code": cleaned_code,
+            "description": description,
+        },
+        "status": "pending_execution",
+        "message": "Code cell queued for execution by JupyterExecutionMiddleware"
+    }
+    if execution_result is not None:
+        response["execution_result"] = execution_result
+        response["status"] = "complete"
+        response["message"] = "Code cell executed with client-reported results"
+    return response
+
+
+@tool(args_schema=MarkdownInput)
+def markdown_tool(content: str) -> Dict[str, Any]:
+    """
+    Add a markdown cell to the Jupyter notebook.
+    
+    This tool adds a new markdown cell at the end of the notebook.
+    Useful for adding explanations, documentation, or section headers.
+    
+    Args:
+        content: Markdown content to add
+        
+    Returns:
+        Dict containing the markdown addition request
+    """
+    return {
+        "tool": "markdown",
+        "parameters": {
+            "content": content,
+        },
+        "status": "completed",
+        "message": "Markdown cell added successfully. Continue with the next task."
+    }
+
+
+@tool(args_schema=FinalAnswerInput)
+def final_answer_tool(answer: str, summary: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Complete the task and provide final answer to the user.
+    
+    Use this tool when you have successfully completed the user's request.
+    Provide a clear summary of what was accomplished.
+    
+    Args:
+        answer: Final answer/message to the user
+        summary: Optional brief summary
+        
+    Returns:
+        Dict marking task completion
+    """
+    return {
+        "tool": "final_answer",
+        "parameters": {
+            "answer": answer,
+            "summary": summary,
+        },
+        "status": "complete",
+        "message": "Task completed successfully"
+    }
+
+
+# Export all tools
+JUPYTER_TOOLS = [
+    jupyter_cell_tool,
+    markdown_tool,
+    final_answer_tool,
+]