# datalayer/jupyter-ai-agents architecture

> Architecture diagram of the GitHub repository datalayer/jupyter-ai-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/datalayer/jupyter-ai-agents
- Repository: https://github.com/datalayer/jupyter-ai-agents

## Overview

##### Project type and purpose
- This is an open-source Python library and CLI/server application called **Jupyter AI Agents**.
- Purpose: empower LLM-based agents (via LangChain) to interact with and modify whole Jupyter Notebooks in real time, using JupyterLab’s RTC and kernel clients.

##### File structure
- Top-level scripts/config:
- `cli/` – Click-based commands (`prompt`, `explain-error`, etc.).
- `server/` – FastAPI (or similar) server exposing an API for remote agents.
- `agents/` – LangChain custom agents (`base.py`, `explain_error.py`, `prompt.py`).
- `handlers/` – Handlers for notebook state (agents manager, config, index, etc.).
- `providers/` – Abstractions for LLM endpoints (OpenAI, Anthropic, Azure, Bedrock, Copilot).
- `tools/` – Built-in notebook operations (insert cell, execute cell, etc.).
- `utils.py`, `models.py` – Shared utilities and data models.
- `static/`, `templates/` – Web assets for server UI.
- Config & build: `pyproject.toml`, `Makefile`, GitHub Actions in `.github/workflows`, `pre-commit` hooks.
- Documentation site under `docs/` (Docusaurus config).

##### Dive into the README
– **Jupyter NbModel Client** (notebook CRDT).
– **Jupyter Kernel Client** (execute code).
- Can be run as CLI (“Out-Kernel Stateless”) or as a persistent server backing Datalayer’s online services.
- Uses LangChain Agent Framework to orchestrate model ↔ tools interactions.
- Supports multiple model providers via a uniform interface.

a. Main components
1. **User** – issues commands via CLI or browser UI.
2. **CLI App** (`jupyter-ai-agents prompt|explain-error`)
– loads an Agent, Providers, Tools, Handlers.
3. **Server** (`make server` / FastAPI)
– exposes REST/WebSocket for remote agent sessions.
4. **Agent Core** (LangChain wrapper)
– Decision logic: which tool to call based on LLM output.
5. **Providers Layer**
– Adapters to external LLM APIs (OpenAI, Azure, Anthropic, etc.).
6. **Tools Layer**
– Notebook operations (insert_cell, execute_cell, etc.).
7. **Handlers Layer**
– Manage notebook state via
- **Index Handler** (locate notebook cells)
- **Config Handler**
- **Agent Manager** (session management)
8. **Jupyter Clients**
– **NbModel Client** (CRDT sync over RTC)
– **Kernel Client** (code execution)
9. **JupyterLab Server**
– Hosts the actual notebook and collaboration extension.
10. **External Services**
– Cloud LLM endpoints, Datalayer backend (optional).

b. Relationships & interactions
- User → CLI/Server (CLI flags / HTTP requests)
- CLI/Server ↔ Agent Core (invoke agents)
- Agent Core → Providers (LLM API calls)
- Agent Core → Tools (issue notebook commands)
- Tools → Handlers → Jupyter Clients (CRDT + kernel calls)
- Jupyter Clients ↔ JupyterLab Server (RTC channel & kernel socket)
- JupyterLab ↔ User (real-time UI updates)

c. Architectural patterns & principles
- **Adapter pattern** for Providers layer.
- **Command/Tool pattern** for notebook actions.
- **Handler chain** for notebook state orchestration.
- **LangChain Framework** to centralize agent logic.

d. Key technologies
- Python, Click (CLI), FastAPI (server), LangChain agents.
- jupyter-nbmodel-client (CRDT), jupyter-kernel-client.
- Cloud LLM APIs (OpenAI, Azure, Anthropic, etc.).
- Docusaurus for docs, GitHub Actions for CI/CD.

##### Essential elements
- Versioning note: indicate pluggable providers via config.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interaction Layer
    subgraph "User Interaction"
        direction TB
        User("User")
        CLI("CLI Application"):::blue
        Server("Server (FastAPI)"):::blue
        User -->|CLI Flags| CLI
        User -->|HTTP/WebSocket| Server
    end

    %% Agent Logic Layer
    subgraph "Agent Logic"
        direction TB
        AgentCore("Agent Core (LangChain)"):::blue
        Providers("Providers Layer"):::green
        Tools("Tools Layer"):::blue
        Handlers("Handlers Layer"):::blue

        CLI -->|invoke agent| AgentCore
        Server -->|invoke agent| AgentCore
        AgentCore -->|LLM API calls| Providers
        AgentCore -->|issue tools| Tools
        Tools -->|commands| Handlers
    end

    %% Notebook I/O Layer
    subgraph "Notebook I/O"
        direction TB
        subgraph "Jupyter Clients"
            direction TB
            NbModel("NbModel Client (CRDT)"):::green
            KernelClient("Kernel Client"):::green
        end
        Handlers -->|CRDT ops| NbModel
        Handlers -->|execute code| KernelClient
        NbModel <-->|"RTC channel"| JupyterLabServer
        KernelClient <-->|"Kernel socket"| JupyterLabServer
    end

    %% External Services Layer
    subgraph "External Services"
        direction TB
        LLM("Cloud LLM Endpoints"):::green
    end

    AgentCore -->|HTTP/gRPC| LLM

    JupyterLabServer("JupyterLab Server"):::orange

    %% Click events
    click CLI "https://github.com/datalayer/jupyter-ai-agents/blob/main/jupyter_ai_agents/cli/app.py"
    click Server "https://github.com/datalayer/jupyter-ai-agents/blob/main/jupyter_ai_agents/server/main.py"
    click Server "https://github.com/datalayer/jupyter-ai-agents/tree/main/jupyter_ai_agents/server/api/"
    click AgentCore "https://github.com/datalayer/jupyter-ai-agents/blob/main/jupyter_ai_agents/agents/base.py"
    click Providers "https://github.com/datalayer/jupyter-ai-agents/blob/main/jupyter_ai_agents/providers/openai.py"
    click Tools "https://github.com/datalayer/jupyter-ai-agents/blob/main/jupyter_ai_agents/tools/tools.py"
    click Handlers "https://github.com/datalayer/jupyter-ai-agents/blob/main/jupyter_ai_agents/handlers/base.py"

    %% Styles
    classDef blue fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef green fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef orange fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px;
    class User external
```
