How datalayer/jupyter-ai-agents works
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.