# Main Dependencies for Open Notebook: Complete Python Stack Guide

> Discover the main dependencies for Open Notebook: FastAPI, LangChain, LangGraph, SurrealDB, and Esperanto. Explore this complete Python stack guide to understand the core components powering this project.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: getting-started
- Published: 2026-06-13

---

**Open Notebook relies on FastAPI for the web layer, LangChain and LangGraph for AI orchestration, SurrealDB for graph persistence, and Esperanto for unified multi-provider LLM access, with all versions pinned in [`pyproject.toml`](https://github.com/lfnovo/open-notebook/blob/main/pyproject.toml).**

Open Notebook is an AI-powered notebook application that orchestrates multiple language models through a modern Python architecture. Understanding the main dependencies for Open Notebook reveals how the project handles asynchronous web serving, stateful AI workflows, and vector database persistence. All package requirements are declared in the repository's root [`pyproject.toml`](https://github.com/lfnovo/open-notebook/blob/main/pyproject.toml), which pins specific versions to ensure compatibility across the FastAPI server, LangChain ecosystem, and SurrealDB drivers.

## Web Framework and Server Infrastructure

The application exposes REST endpoints through a high-performance async stack.

### FastAPI and Uvicorn

**FastAPI** (≥0.104.0) serves as the primary web framework, powering all HTTP endpoints defined in [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py). The application runs on **Uvicorn** (≥0.24.0) as the ASGI server, enabling asynchronous request handling critical for AI-intensive operations.

```python
from fastapi import APIRouter, Depends
from pydantic import BaseModel

router = APIRouter()

class NotebookCreate(BaseModel):
    title: str
    description: str | None = None

@router.post("/notebooks")
async def create_notebook(
    payload: NotebookCreate,
    db = Depends(get_surrealdb),
):
    await db.create("notebook", payload.dict())
    return {"status": "created"}

```

### Data Validation and Logging

**Pydantic** (≥2.9.2) handles request validation and settings management through strict type checking, while **Loguru** (≥0.7.2) provides structured, colorized logging throughout the codebase, replacing standard library logging for better observability.

## AI Orchestration and LLM Integration

The core AI functionality depends on the LangChain ecosystem and a unified provider abstraction layer.

### LangChain Ecosystem and Graph Workflows

**LangChain** (≥1.2.0) provides the base abstractions for model calls and prompt management, while **LangGraph** (≥1.0.5) drives the notebook's state machines and multi-step workflows. The project uses **langgraph-checkpoint-sqlite** (≥3.0.1) to persist graph execution states durably, particularly in `open_notebook/graphs/`. **langchain-community** (≥0.4.1) supplies additional integrations for vector stores and Elasticsearch.

```python
from open_notebook.graphs.source import source_graph

result = await source_graph.ainvoke(
    {"url": "https://example.com/paper.pdf"},
    config={"recursion_limit": 5},
)
print(result["embedding_id"])

```

### Multi-Provider LLM Support via Esperanto

Rather than managing separate SDKs directly, Open Notebook uses **Esperanto** (≥2.20.0,<3) as a unified interface to eight providers: OpenAI, Anthropic, Google, Groq, Ollama, Mistral, DeepSeek, and xAI. This abstraction sits in [`open_notebook/ai/provision.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/provision.py) and returns LangChain-compatible models.

```python
from open_notebook.ai.provision import provision_langchain_model

model = provision_langchain_model(
    provider="openai",
    model_name="gpt-4o-mini",
    temperature=0.7,
)
response = await model.ainvoke("Explain the Open Notebook architecture.")

```

### Provider-Specific LangChain Packages

The project includes specific LangChain provider packages for direct API access when needed:

- **langchain-openai** (≥1.1.14)
- **langchain-anthropic** (≥1.3.0)
- **langchain-ollama** (≥1.0.1)
- **langchain-google-genai** (≥4.1.2)
- **langchain-groq** (≥1.1.1)
- **langchain-mistralai** (≥1.1.1)
- **langchain-deepseek** (≥1.0.0)

**Tiktoken** (≥0.12.0) provides fast token counting specifically for OpenAI-compatible models, enabling accurate context window management.

## Database and Persistence Layer

### SurrealDB and Async Commands

**SurrealDB** (≥1.0.4) serves as the primary graph database, storing notebooks, sources, and embeddings in a relational-graph hybrid model. The **surreal-commands** (≥1.3.1,<2) package provides a command-queue abstraction on top of SurrealDB for handling async background jobs like podcast rendering.

```python
from surrealdb import Surreal

async def store_embedding(db: Surreal, embedding: list[float], source_id: str):
    await db.create("embedding", {
        "vector": embedding,
        "source": source_id,
    })

```

## Content Processing and Media Generation

### Document Extraction and Prompt Templating

**content-core** (≥1.14.1,<2) handles extraction of text from PDFs, images, and videos, while **ai-prompter** (≥0.4,<1) manages Jinja-style prompt templating for LLM calls.

### Podcast Generation

**podcast-creator** (≥0.12.0,<1) converts AI-generated scripts into audio podcasts, orchestrated through [`api/podcast_service.py`](https://github.com/lfnovo/open-notebook/blob/main/api/podcast_service.py).

```python
from podcast_creator import PodcastCreator

creator = PodcastCreator(api_key="YOUR_API_KEY")
audio_path = await creator.create_from_text(
    script="Welcome to the Open Notebook podcast...",
    voice="en_us_female"
)

```

## Configuration and Networking Utilities

### Environment and Config Parsing

**python-dotenv** (≥1.2.2) loads `.env` files for secret management, while **tomli** (≥2.0.2) parses TOML configuration files.

### HTTP Client and Scientific Computing

**httpx[socks]** (≥0.27.0) provides an async HTTP client with SOCKS proxy support for content extraction and provider SDKs. **Numpy** (≥2.4.1) supports numeric operations in embedding handling and vector mathematics.

### Internationalization

**pycountry** (≥26.2.16) supplies ISO country and language metadata for UI localization, complemented by **babel** (≥2.18.0) for date and number formatting utilities.

## Summary

- **FastAPI**, **Uvicorn**, and **Pydantic** form the async web layer handling all HTTP traffic and validation in [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py).
- **LangChain**, **LangGraph**, and **Esperanto** provide the AI orchestration stack supporting eight different LLM providers through a unified interface.
- **SurrealDB** and **surreal-commands** persist notebook data, embeddings, and async job queues.
- **content-core** and **podcast-creator** handle multimedia processing and audio generation.
- **python-dotenv**, **httpx**, and **tiktoken** supply essential utilities for configuration, networking, and token counting.

## Frequently Asked Questions

### What is the minimum Python version required for Open Notebook?

Open Notebook requires Python 3.10 or higher to support the modern async/await syntax used with FastAPI and SurrealDB, along with the union type syntax (`|`) seen in Pydantic models throughout [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py).

### Can I use Open Notebook without installing all LLM provider packages?

Yes, the modular design allows you to install only the specific **langchain-*** provider packages you need for your configuration. However, **Esperanto** remains a required dependency as it provides the unified abstraction layer in [`open_notebook/ai/provision.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/ai/provision.py) that the rest of the application expects.

### How does Open Notebook handle database migrations?

The project uses **SurrealDB** (≥1.0.4) with schemaless document-graph storage, eliminating traditional migration scripts. The **surreal-commands** package manages async job queues for background processing tasks like podcast generation, but schema definitions are handled through SurrealDB's native live schema functionality.

### Why does the project use both LangChain and Esperanto?

**LangChain** provides the foundational abstractions for chains and prompts, while **Esperanto** (≥2.20.0) acts as a factory that instantiates LangChain-compatible models across multiple providers (OpenAI, Anthropic, Groq, etc.) using a consistent configuration interface. This dual-layer approach allows Open Notebook to support new providers without modifying core workflow code in `open_notebook/graphs/`.