Metadata-Version: 2.4
Name: jupyter-deepagents
Version: 0.1.0
Dynamic: Keywords
Summary: JupyterLab extension with chat interface for DeepAgents
Project-URL: Homepage, https://github.com/dkedar7/jupyter-deepagents
Project-URL: Bug Tracker, https://github.com/dkedar7/jupyter-deepagents/issues
Project-URL: Repository, https://github.com/dkedar7/jupyter-deepagents.git
Author: Kedar Dabhadkar
License: MIT License
        
        Copyright (c) 2024 jupyter-deepagents contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Framework :: Jupyter
Classifier: Framework :: Jupyter :: JupyterLab
Classifier: Framework :: Jupyter :: JupyterLab :: 4
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Requires-Dist: deepagents>=0.1.0
Requires-Dist: jupyter-server<3,>=2.0.1
Requires-Dist: langgraph>=0.0.1
Requires-Dist: python-dotenv>=0.19.0
Provides-Extra: dev
Requires-Dist: jupyter-server[test]<3,>=2.0.1; extra == 'dev'
Description-Content-Type: text/markdown

# jupyter-deepagents

A JupyterLab extension that provides an elegant chat interface for AI agents with human-in-the-loop capabilities.

## Features

### Core Functionality
- **Chat Interface**: Clean, accessible sidebar interface for natural conversations with your agent
- **Streaming Responses**: Real-time streaming of agent responses for immediate feedback
- **Thread-based History**: Maintains conversation context across messages with persistent thread IDs
- **Context Awareness**: Automatically sends current directory and focused widget information to the agent

### Human-in-the-Loop
- **Tool Call Approvals**: Review and approve/reject/edit tool calls before execution
- **Minimal Design**: Simple gray UI with one-click approval buttons
- **Flexible Decisions**: Approve, reject, or edit tool arguments inline
- **No Interruptions**: Streamlined workflow without unnecessary prompts

### Developer Experience
- **Tool Call Visibility**: Expandable sections showing tool names and arguments
- **Markdown Rendering**: Compact, elegant formatting for agent responses
- **Agent Health Status**: Visual indicator showing agent connection status
- **Hot Reload**: Reload agent configuration without restarting JupyterLab
- **Clear Chat**: Start fresh conversations with a single click

## Requirements

- JupyterLab >= 4.0.0
- Python >= 3.8

## Installation

```bash
pip install jupyter-deepagents
```

## Usage

### Quick Start

1. **Create your agent** in `my_agent.py`:

```python
from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver

# Create agent with interrupt capability
agent = create_deep_agent(
    backend=FilesystemBackend(root_dir=".", virtual_mode=True),
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={
                "write_file": {"allowed_decisions": ["approve", "reject"]}
            },
            description_prefix="Tool execution pending approval",
        ),
    ],
    checkpointer=MemorySaver()
)
```

2. **Start JupyterLab**:

```bash
jupyter lab
```

3. **Open the chat interface** by clicking the chat icon in the right sidebar

4. **Start chatting** with your agent!

### Using the Interface

**Basic Chat:**
- Type your message in the input field
- Press Enter or click the send arrow (↑) to send
- Watch as the agent streams its response in real-time

**Human-in-the-Loop Approvals:**

When your agent wants to execute a tool:
1. An approval UI appears showing the tool name
2. Click **Approve** to allow execution
3. Click **Reject** to deny the action
4. Click **Edit** to modify tool arguments before execution

No confirmation dialogs or reason prompts - just one click!

**Interface Controls:**
- **⟳ Reload**: Reload your agent without restarting JupyterLab
- **Clear**: Start a new conversation thread
- **Status Indicator**:
  - 🟢 Green: Agent loaded and ready
  - 🟠 Orange: Agent not found or loading
  - 🔴 Red: Agent error

### Agent Configuration

#### Option 1: Default Location (Recommended)

Create `my_agent.py` in your working directory with an `agent` variable:

```python
from langgraph.prebuilt import create_react_agent

agent = create_react_agent(
    model=your_model,
    tools=your_tools,
    checkpointer=MemorySaver()
)
```

#### Option 2: Custom Location

Set the `JUPYTER_AGENT_PATH` environment variable:

```bash
export JUPYTER_AGENT_PATH="path.to.module:variable_name"
jupyter lab
```

**Examples:**
```bash
# Agent in custom_agent.py as 'my_graph'
export JUPYTER_AGENT_PATH="custom_agent:my_graph"

# Agent in package: src/agents/main.py as 'agent'
export JUPYTER_AGENT_PATH="src.agents.main:agent"
```

Format: `module_path:variable_name`
- `module_path`: Python import path (e.g., `my_agent` or `package.module`)
- `variable_name`: Name of the agent variable in the module

See [AGENT_CONFIGURATION.md](AGENT_CONFIGURATION.md) for advanced configuration.


## UI Design Philosophy

The interface follows a minimal, functional aesthetic:

- **Compact Markdown**: Tight line spacing (1.2) and minimal margins for efficient reading
- **Minimal Color Scheme**: Gray, black, and white palette without visual clutter
- **No Rounded Edges**: Clean, professional design
- **One-Click Actions**: Approval buttons submit immediately without confirmation dialogs
- **Elegant Send Button**: Circular arrow button (↑) for a modern look
- **Expandable Tool Calls**: Collapsible sections keep the interface clean

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

## License

MIT License - see [LICENSE](LICENSE) for details.
