deepagents 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

deepagents-cli/deepagents_cli/README.md

@@ -1,196 +0,0 @@
-# DeepAgents CLI
-
-Interactive command-line interface for DeepAgents - an AI coding assistant with file operations, web search, and shell command execution.
-
-## Architecture
-
-The CLI is organized into focused modules:
-
-```
-cli/
-├── __init__.py      # Package exports
-├── __main__.py      # Entry point for `python -m deepagents.cli`
-├── main.py          # CLI loop, argument parsing, main orchestration
-├── config.py        # Configuration, constants, colors, model creation
-├── tools.py         # Custom tools (http_request, web_search)
-├── ui.py            # Display logic, TokenTracker, help screens
-├── input.py         # Input handling, completers, prompt session
-├── commands.py      # Slash command and bash command handlers
-├── execution.py     # Task execution, streaming, HITL approval
-└── agent.py         # Agent creation, management, listing, reset
-```
-
-## Module Responsibilities
-
-### `main.py` - Entry Point & Main Loop
-- **Purpose**: CLI entry point, argument parsing, main interactive loop
-- **Key Functions**:
-  - `cli_main()` - Console script entry point (called when you run `deepagents`)
-  - `main()` - Async main function that orchestrates agent creation and CLI
-  - `simple_cli()` - Main interactive loop handling user input
-  - `parse_args()` - Command-line argument parsing
-  - `check_cli_dependencies()` - Validates required packages are installed
-
-### `config.py` - Configuration & Constants
-- **Purpose**: Centralized configuration, constants, and model creation
-- **Key Exports**:
-  - `COLORS` - Color scheme for terminal output
-  - `DEEP_AGENTS_ASCII` - ASCII art banner
-  - `COMMANDS` - Available slash commands
-  - `console` - Rich Console instance
-  - `create_model()` - Creates OpenAI or Anthropic model based on API keys
-  - `get_default_coding_instructions()` - Loads default agent prompt
-
-### `tools.py` - Custom Agent Tools
-- **Purpose**: Additional tools for the agent beyond built-in filesystem operations
-- **Tools**:
-  - `http_request()` - Make HTTP requests to APIs
-  - `web_search()` - Search the web using Tavily API
-  - `tavily_client` - Initialized Tavily client (if API key available)
-
-### `ui.py` - Display & Rendering
-- **Purpose**: All UI rendering and display logic
-- **Key Components**:
-  - `TokenTracker` - Track and display token usage across the session
-  - `render_todo_list()` - Render todo list with checkboxes
-  - `show_interactive_help()` - Display available commands during session
-  - `show_help()` - Full help screen
-  - `format_tool_message_content()` - Format tool messages for display
-  - `truncate_value()` - Truncate long values for readable display
-
-### `input.py` - Input Handling
-- **Purpose**: User input, completers, and prompt session configuration
-- **Key Components**:
-  - `FilePathCompleter` - Autocomplete for `@file` mentions
-  - `CommandCompleter` - Autocomplete for `/commands`
-  - `BashCompleter` - Autocomplete for `!bash` commands
-  - `parse_file_mentions()` - Extract `@file` mentions and inject content
-  - `create_prompt_session()` - Configure prompt_toolkit session with:
-    - Multi-line input (Alt+Enter for newlines, Enter to submit)
-    - Command history
-    - File/command autocomplete
-    - External editor support (Ctrl+E)
-
-### `commands.py` - Command Handlers
-- **Purpose**: Handle slash commands (`/help`, `/clear`, etc.) and bash execution
-- **Key Functions**:
-  - `handle_command()` - Route and execute slash commands
-  - `execute_bash_command()` - Execute bash commands prefixed with `!`
-
-### `execution.py` - Task Execution & Streaming
-- **Purpose**: Core execution logic, streaming responses, HITL (Human-in-the-Loop)
-- **Key Functions**:
-  - `execute_task()` - Main execution function that:
-    - Parses file mentions
-    - Streams agent responses
-    - Displays tool calls with icons
-    - Renders todo list updates
-    - Tracks token usage
-    - Handles Ctrl+C interruptions
-  - `prompt_for_shell_approval()` - Interactive shell command approval with arrow keys
-- **Features**:
-  - Dual-stream mode (messages + updates) for HITL support
-  - Real-time todo list rendering
-  - Spinner with status updates
-  - Token tracking integration
-
-### `agent.py` - Agent Management
-- **Purpose**: Agent creation, configuration, and management commands
-- **Key Functions**:
-  - `create_agent_with_config()` - Create agent with:
-    - Filesystem backends (working directory + agent directory)
-    - Long-term memory middleware
-    - Shell execution with HITL approval
-    - Custom system prompt
-  - `list_agents()` - List all agents in `~/.deepagents/`
-  - `reset_agent()` - Reset agent to default or copy from another agent
-
-## Data Flow
-
-```
-User Input
-    ↓
-main.py (simple_cli)
-    ↓
-input.py (parse_file_mentions, completers)
-    ↓
-execution.py (execute_task)
-    ↓
-agent.py (agent created with tools from tools.py)
-    ↓
-Stream responses → ui.py (render todos, display tool calls)
-                 → execution.py (HITL approval if needed)
-    ↓
-Display output via ui.py (TokenTracker, console)
-```
-
-## Key Features
-
-### File Context Injection
-Type `@filename` and press Tab to autocomplete and inject file content into your prompt.
-
-### Interactive Commands
-- `/help` - Show help
-- `/clear` - Clear screen and reset conversation
-- `/tokens` - Show token usage
-- `/quit` or `/exit` - Exit the CLI
-
-### Bash Commands
-Type `!command` to execute bash commands directly (e.g., `!ls`, `!git status`)
-
-### Todo List Tracking
-The agent can create and update a visual todo list for multi-step tasks.
-
-### File Operation Summaries & Diff Viewer
-- File reads now show a concise summary with the number of lines streamed (e.g., `⏺ Read(example.py)` followed by `⎿  Read 44 lines (lines 1-44)`).
-- Writes and edits capture before/after snapshots, reporting lines added or removed plus bytes written.
-- A Rich-powered unified diff renders in-line with syntax highlighting so you can review every proposed change before confirming.
-- Diff output truncates gracefully for very large edits while still surfacing a summary.
-- When Human-in-the-Loop approval is required, the proposed diff is shown *before* you choose Approve/Reject.
-
-### Human-in-the-Loop Shell Approval
-Shell commands require user approval with an interactive arrow-key menu.
-
-### Multi-line Input
-- **Enter** - Submit (or accept completion if menu is open)
-- **Alt+Enter** - Insert newline (Option+Enter on Mac, or ESC then Enter)
-- **Ctrl+E** - Open in external editor (nano by default)
-
-## Agent Storage
-
-Each agent stores its state in `~/.deepagents/AGENT_NAME/`:
-- `agent.md` - Agent's custom instructions (long-term memory)
-- `memories/` - Additional context files
-- `history` - Command history
-
-## Development
-
-To modify the CLI:
-
-1. **UI changes** → Edit `ui.py` or `input.py`
-2. **Add new tools** → Edit `tools.py`
-3. **Change execution flow** → Edit `execution.py`
-4. **Add commands** → Edit `commands.py`
-5. **Agent configuration** → Edit `agent.py`
-6. **Constants/colors** → Edit `config.py`
-
-## Running During Development
-
-```bash
-# From project root
-uv run python -m deepagents.cli
-
-# Or install in editable mode
-uv pip install -e .
-deepagents
-```
-
-## Entry Point
-
-The CLI is registered in `pyproject.toml` as:
-```toml
-[project.scripts]
-deepagents = "deepagents.cli:cli_main"
-```
-
-This means when users install the package, they can run `deepagents` directly.

deepagents-cli/deepagents_cli/__init__.py

@@ -1,5 +0,0 @@
-"""DeepAgents CLI - Interactive AI coding assistant."""
-
-from .main import cli_main
-
-__all__ = ["cli_main"]

deepagents-cli/deepagents_cli/__main__.py

@@ -1,6 +0,0 @@
-"""Allow running the CLI as: python -m deepagents.cli"""
-
-from .main import cli_main
-
-if __name__ == "__main__":
-    cli_main()

deepagents-cli/deepagents_cli/agent.py

@@ -1,278 +0,0 @@
-"""Agent management and creation for the CLI."""
-
-import os
-import shutil
-from pathlib import Path
-
-from deepagents import create_deep_agent
-from deepagents.backends import CompositeBackend
-from deepagents.backends.filesystem import FilesystemBackend
-from deepagents.middleware.resumable_shell import ResumableShellToolMiddleware
-from langchain.agents.middleware import HostExecutionPolicy
-from langgraph.checkpoint.memory import InMemorySaver
-
-from .agent_memory import AgentMemoryMiddleware
-from .config import COLORS, config, console, get_default_coding_instructions
-
-
-def list_agents():
-    """List all available agents."""
-    agents_dir = Path.home() / ".deepagents"
-
-    if not agents_dir.exists() or not any(agents_dir.iterdir()):
-        console.print("[yellow]No agents found.[/yellow]")
-        console.print(
-            "[dim]Agents will be created in ~/.deepagents/ when you first use them.[/dim]",
-            style=COLORS["dim"],
-        )
-        return
-
-    console.print("\n[bold]Available Agents:[/bold]\n", style=COLORS["primary"])
-
-    for agent_path in sorted(agents_dir.iterdir()):
-        if agent_path.is_dir():
-            agent_name = agent_path.name
-            agent_md = agent_path / "agent.md"
-
-            if agent_md.exists():
-                console.print(f"  • [bold]{agent_name}[/bold]", style=COLORS["primary"])
-                console.print(f"    {agent_path}", style=COLORS["dim"])
-            else:
-                console.print(
-                    f"  • [bold]{agent_name}[/bold] [dim](incomplete)[/dim]", style=COLORS["tool"]
-                )
-                console.print(f"    {agent_path}", style=COLORS["dim"])
-
-    console.print()
-
-
-def reset_agent(agent_name: str, source_agent: str = None):
-    """Reset an agent to default or copy from another agent."""
-    agents_dir = Path.home() / ".deepagents"
-    agent_dir = agents_dir / agent_name
-
-    if source_agent:
-        source_dir = agents_dir / source_agent
-        source_md = source_dir / "agent.md"
-
-        if not source_md.exists():
-            console.print(
-                f"[bold red]Error:[/bold red] Source agent '{source_agent}' not found or has no agent.md"
-            )
-            return
-
-        source_content = source_md.read_text()
-        action_desc = f"contents of agent '{source_agent}'"
-    else:
-        source_content = get_default_coding_instructions()
-        action_desc = "default"
-
-    if agent_dir.exists():
-        shutil.rmtree(agent_dir)
-        console.print(f"Removed existing agent directory: {agent_dir}", style=COLORS["tool"])
-
-    agent_dir.mkdir(parents=True, exist_ok=True)
-    agent_md = agent_dir / "agent.md"
-    agent_md.write_text(source_content)
-
-    console.print(f"✓ Agent '{agent_name}' reset to {action_desc}", style=COLORS["primary"])
-    console.print(f"Location: {agent_dir}\n", style=COLORS["dim"])
-
-
-def get_system_prompt() -> str:
-    """Get the base system prompt for the agent.
-
-    Returns:
-        The system prompt string (without agent.md content)
-    """
-    return f"""### Current Working Directory
-
-The filesystem backend is currently operating in: `{Path.cwd()}`
-
-### Memory System Reminder
-
-Your long-term memory is stored in /memories/ and persists across sessions.
-
-**IMPORTANT - Check memories before answering:**
-- When asked "what do you know about X?" → Run `ls /memories/` FIRST, then read relevant files
-- When starting a task → Check if you have guides or examples in /memories/
-- At the beginning of new sessions → Consider checking `ls /memories/` to see what context you have
-
-Base your answers on saved knowledge (from /memories/) when available, supplemented by general knowledge.
-
-### Human-in-the-Loop Tool Approval
-
-Some tool calls require user approval before execution. When a tool call is rejected by the user:
-1. Accept their decision immediately - do NOT retry the same command
-2. Explain that you understand they rejected the action
-3. Suggest an alternative approach or ask for clarification
-4. Never attempt the exact same rejected command again
-
-Respect the user's decisions and work with them collaboratively.
-
-### Web Search Tool Usage
-
-When you use the web_search tool:
-1. The tool will return search results with titles, URLs, and content excerpts
-2. You MUST read and process these results, then respond naturally to the user
-3. NEVER show raw JSON or tool results directly to the user
-4. Synthesize the information from multiple sources into a coherent answer
-5. Cite your sources by mentioning page titles or URLs when relevant
-6. If the search doesn't find what you need, explain what you found and ask clarifying questions
-
-The user only sees your text responses - not tool results. Always provide a complete, natural language answer after using web_search.
-
-### Todo List Management
-
-When using the write_todos tool:
-1. Keep the todo list MINIMAL - aim for 3-6 items maximum
-2. Only create todos for complex, multi-step tasks that truly need tracking
-3. Break down work into clear, actionable items without over-fragmenting
-4. For simple tasks (1-2 steps), just do them directly without creating todos
-5. When first creating a todo list for a task, ALWAYS ask the user if the plan looks good before starting work
-   - Create the todos, let them render, then ask: "Does this plan look good?" or similar
-   - Wait for the user's response before marking the first todo as in_progress
-   - If they want changes, adjust the plan accordingly
-6. Update todo status promptly as you complete each item
-
-The todo list is a planning tool - use it judiciously to avoid overwhelming the user with excessive task tracking."""
-
-
-def create_agent_with_config(model, assistant_id: str, tools: list):
-    """Create and configure an agent with the specified model and tools."""
-    shell_middleware = ResumableShellToolMiddleware(
-        workspace_root=os.getcwd(), execution_policy=HostExecutionPolicy()
-    )
-
-    # For long-term memory, point to ~/.deepagents/AGENT_NAME/ with /memories/ prefix
-    agent_dir = Path.home() / ".deepagents" / assistant_id
-    agent_dir.mkdir(parents=True, exist_ok=True)
-    agent_md = agent_dir / "agent.md"
-    if not agent_md.exists():
-        source_content = get_default_coding_instructions()
-        agent_md.write_text(source_content)
-
-    # Long-term backend - rooted at agent directory
-    # This handles both /memories/ files and /agent.md
-    long_term_backend = FilesystemBackend(root_dir=agent_dir, virtual_mode=True)
-
-    # Composite backend: current working directory for default, agent directory for /memories/
-    backend = CompositeBackend(
-        default=FilesystemBackend(), routes={"/memories/": long_term_backend}
-    )
-
-    # Use the same backend for agent memory middleware
-    agent_middleware = [
-        AgentMemoryMiddleware(backend=long_term_backend, memory_path="/memories/"),
-        shell_middleware,
-    ]
-
-    # Get the system prompt
-    system_prompt = get_system_prompt()
-
-    # Helper functions for formatting tool descriptions in HITL prompts
-    def format_write_file_description(tool_call: dict) -> str:
-        """Format write_file tool call for approval prompt."""
-        args = tool_call.get("args", {})
-        file_path = args.get("file_path", "unknown")
-        content = args.get("content", "")
-
-        action = "Overwrite" if os.path.exists(file_path) else "Create"
-        line_count = len(content.splitlines())
-        size = len(content.encode("utf-8"))
-
-        return f"File: {file_path}\nAction: {action} file\nLines: {line_count} · Bytes: {size}"
-
-    def format_edit_file_description(tool_call: dict) -> str:
-        """Format edit_file tool call for approval prompt."""
-        args = tool_call.get("args", {})
-        file_path = args.get("file_path", "unknown")
-        old_string = args.get("old_string", "")
-        new_string = args.get("new_string", "")
-        replace_all = bool(args.get("replace_all", False))
-
-        delta = len(new_string) - len(old_string)
-
-        return (
-            f"File: {file_path}\n"
-            f"Action: Replace text ({'all occurrences' if replace_all else 'single occurrence'})\n"
-            f"Snippet delta: {delta:+} characters"
-        )
-
-    def format_web_search_description(tool_call: dict) -> str:
-        """Format web_search tool call for approval prompt."""
-        args = tool_call.get("args", {})
-        query = args.get("query", "unknown")
-        max_results = args.get("max_results", 5)
-
-        return f"Query: {query}\nMax results: {max_results}\n\n⚠️  This will use Tavily API credits"
-
-    def format_task_description(tool_call: dict) -> str:
-        """Format task (subagent) tool call for approval prompt."""
-        args = tool_call.get("args", {})
-        description = args.get("description", "unknown")
-        prompt = args.get("prompt", "")
-
-        # Truncate prompt if too long
-        prompt_preview = prompt[:300]
-        if len(prompt) > 300:
-            prompt_preview += "..."
-
-        return (
-            f"Task: {description}\n\n"
-            f"Instructions to subagent:\n"
-            f"{'─' * 40}\n"
-            f"{prompt_preview}\n"
-            f"{'─' * 40}\n\n"
-            f"⚠️  Subagent will have access to file operations and shell commands"
-        )
-
-    # Configure human-in-the-loop for potentially destructive tools
-    from langchain.agents.middleware import InterruptOnConfig
-
-    shell_interrupt_config: InterruptOnConfig = {
-        "allowed_decisions": ["approve", "reject"],
-        "description": lambda tool_call, state, runtime: (
-            f"Shell Command: {tool_call['args'].get('command', 'N/A')}\n"
-            f"Working Directory: {os.getcwd()}"
-        ),
-    }
-
-    write_file_interrupt_config: InterruptOnConfig = {
-        "allowed_decisions": ["approve", "reject"],
-        "description": lambda tool_call, state, runtime: format_write_file_description(tool_call),
-    }
-
-    edit_file_interrupt_config: InterruptOnConfig = {
-        "allowed_decisions": ["approve", "reject"],
-        "description": lambda tool_call, state, runtime: format_edit_file_description(tool_call),
-    }
-
-    web_search_interrupt_config: InterruptOnConfig = {
-        "allowed_decisions": ["approve", "reject"],
-        "description": lambda tool_call, state, runtime: format_web_search_description(tool_call),
-    }
-
-    task_interrupt_config: InterruptOnConfig = {
-        "allowed_decisions": ["approve", "reject"],
-        "description": lambda tool_call, state, runtime: format_task_description(tool_call),
-    }
-
-    agent = create_deep_agent(
-        model=model,
-        system_prompt=system_prompt,
-        tools=tools,
-        backend=backend,
-        middleware=agent_middleware,
-        interrupt_on={
-            "shell": shell_interrupt_config,
-            "write_file": write_file_interrupt_config,
-            "edit_file": edit_file_interrupt_config,
-            "web_search": web_search_interrupt_config,
-            "task": task_interrupt_config,
-        },
-    ).with_config(config)
-
-    agent.checkpointer = InMemorySaver()
-
-    return agent