Main Dependencies for Open Notebook: Complete Python Stack Guide

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.

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, 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. The application runs on Uvicorn (≥0.24.0) as the ASGI server, enabling asynchronous request handling critical for AI-intensive operations.

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.

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 and returns LangChain-compatible models.

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.

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.

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.
• 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.

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 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/.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}