Upload 25 files

.dockerignore

@@ -0,0 +1,63 @@
+notebooks/
+data/
+.uploads/
+.venv/
+.env
+sqlite-db/
+temp/
+google-credentials.json
+docker-compose*
+.docker_data/
+docs/
+surreal_data/
+surreal-data/
+notebook_data/
+temp/
+*.env
+.git/
+.github/
+
+# Frontend build artifacts and dependencies
+frontend/node_modules/
+frontend/.next/
+frontend/.env.local
+
+# Cache directories (recursive patterns)
+**/__pycache__/
+**/.mypy_cache/
+**/.ruff_cache/
+**/.pytest_cache/
+**/*.pyc
+**/*.pyo
+**/*.pyd
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+.cache/
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+
+# IDE and editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+
+.quarentena/
+surreal_single_data/

.env.example

@@ -0,0 +1,171 @@
+
+# API CONFIGURATION
+# URL where the API can be accessed by the browser
+# This setting allows the frontend to connect to the API at runtime (no rebuild needed!)
+#
+# IMPORTANT: Do NOT include /api at the end - it will be added automatically!
+#
+# Common scenarios:
+# - Docker on localhost: http://localhost:5055 (default, works for most cases)
+# - Docker on LAN/remote server: http://192.168.1.100:5055 or http://your-server-ip:5055
+# - Behind reverse proxy with custom domain: https://your-domain.com
+# - Behind reverse proxy with subdomain: https://api.your-domain.com
+#
+# Examples for reverse proxy users:
+# - API_URL=https://notebook.example.com  (frontend will call https://notebook.example.com/api/*)
+# - API_URL=https://api.example.com       (frontend will call https://api.example.com/api/*)
+#
+# Note: If not set, the system will auto-detect based on the incoming request.
+# Only set this if you need to override the auto-detection (e.g., reverse proxy scenarios).
+API_URL=http://localhost:5055
+
+# INTERNAL API URL (Server-Side)
+# URL where Next.js server-side should proxy API requests (via rewrites)
+# This is DIFFERENT from API_URL which is used by the browser client
+#
+# INTERNAL_API_URL is used by Next.js rewrites to forward /api/* requests to the FastAPI backend
+# API_URL is used by the browser to know where to make API calls
+#
+# Default: http://localhost:5055 (single-container deployment - both services on same host)
+# Override for multi-container: INTERNAL_API_URL=http://api-service:5055
+#
+# Common scenarios:
+# - Single container (default): Don't set - defaults to http://localhost:5055
+# - Multi-container Docker Compose: INTERNAL_API_URL=http://api:5055 (use service name)
+# - Kubernetes/advanced networking: INTERNAL_API_URL=http://api-service.namespace.svc.cluster.local:5055
+#
+# Why two variables?
+# - API_URL: External/public URL that browsers use (can be https://your-domain.com)
+# - INTERNAL_API_URL: Internal container networking URL (usually http://localhost:5055 or service name)
+#
+# INTERNAL_API_URL=http://localhost:5055
+
+# API CLIENT TIMEOUT (in seconds)
+# Controls how long the frontend/Streamlit UI waits for API responses
+# Increase this if you're using slow AI providers or hardware (Ollama on CPU, remote LM Studio, etc.)
+# Default: 300 seconds (5 minutes) - sufficient for most transformation/insight operations
+#
+# Common scenarios:
+# - Fast cloud APIs (OpenAI, Anthropic): 300 seconds is more than enough
+# - Local Ollama on GPU: 300 seconds should work fine
+# - Local Ollama on CPU: Consider 600 seconds (10 minutes) or more
+# - Remote LM Studio over slow network: Consider 900 seconds (15 minutes)
+# - Very large documents: May need 900+ seconds
+#
+# API_CLIENT_TIMEOUT=300
+
+# ESPERANTO LLM TIMEOUT (in seconds)
+# Controls the timeout for AI model API calls at the Esperanto library level
+# This is separate from API_CLIENT_TIMEOUT and applies to the actual LLM provider requests
+# Only increase this if you're experiencing timeouts during model inference itself
+# Default: 60 seconds (built into Esperanto)
+#
+# Important: This should generally be LOWER than API_CLIENT_TIMEOUT to allow proper error handling
+#
+# Common scenarios:
+# - Fast cloud APIs (OpenAI, Anthropic, Groq): 60 seconds is sufficient
+# - Local Ollama with small models: 120-180 seconds may help
+# - Local Ollama with large models on CPU: 300+ seconds
+# - Remote or self-hosted LLMs: 180-300 seconds depending on hardware
+#
+# Note: If transformations complete but you see timeout errors, increase API_CLIENT_TIMEOUT first.
+# Only increase ESPERANTO_LLM_TIMEOUT if the model itself is timing out during inference.
+#
+# ESPERANTO_LLM_TIMEOUT=60
+
+# SECURITY
+# Set this to protect your Open Notebook instance with a password (for public hosting)
+# OPEN_NOTEBOOK_PASSWORD=
+
+# OPENAI
+# OPENAI_API_KEY=
+
+
+# ANTHROPIC
+# ANTHROPIC_API_KEY=
+
+# GEMINI
+# this is the best model for long context and podcast generation
+# GOOGLE_API_KEY=
+# GEMINI_API_BASE_URL=  # Optional: Override default endpoint (for Vertex AI, proxies, etc.)
+
+# VERTEXAI
+# VERTEX_PROJECT=my-google-cloud-project-name
+# GOOGLE_APPLICATION_CREDENTIALS=./google-credentials.json
+# VERTEX_LOCATION=us-east5
+
+# MISTRAL
+# MISTRAL_API_KEY=
+
+# DEEPSEEK
+# DEEPSEEK_API_KEY=
+
+# OLLAMA
+# OLLAMA_API_BASE="http://10.20.30.20:11434"
+
+# OPEN ROUTER
+# OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"
+# OPENROUTER_API_KEY=
+
+# GROQ
+# GROQ_API_KEY=
+
+# XAI
+# XAI_API_KEY=
+
+# ELEVENLABS
+# Used only by the podcast feature
+# ELEVENLABS_API_KEY=
+
+# TTS BATCH SIZE
+# Controls concurrent TTS requests for podcast generation (default: 5)
+# Lower values reduce provider load but increase generation time
+# Recommended: OpenAI=5, ElevenLabs=2, Google=4, Custom=1
+# TTS_BATCH_SIZE=2
+
+# VOYAGE AI
+# VOYAGE_API_KEY=
+
+# OPENAI COMPATIBLE ENDPOINTS
+# Generic configuration (applies to all modalities: language, embedding, STT, TTS)
+# OPENAI_COMPATIBLE_BASE_URL=http://localhost:1234/v1
+# OPENAI_COMPATIBLE_API_KEY=
+
+# Mode-specific configuration (overrides generic if set)
+# Use these when you want different endpoints for different capabilities
+# OPENAI_COMPATIBLE_BASE_URL_LLM=http://localhost:1234/v1
+# OPENAI_COMPATIBLE_API_KEY_LLM=
+# OPENAI_COMPATIBLE_BASE_URL_EMBEDDING=http://localhost:8080/v1
+# OPENAI_COMPATIBLE_API_KEY_EMBEDDING=
+# OPENAI_COMPATIBLE_BASE_URL_STT=http://localhost:9000/v1
+# OPENAI_COMPATIBLE_API_KEY_STT=
+# OPENAI_COMPATIBLE_BASE_URL_TTS=http://localhost:9000/v1
+# OPENAI_COMPATIBLE_API_KEY_TTS=
+
+# AZURE OPENAI
+# AZURE_OPENAI_API_KEY=
+# AZURE_OPENAI_ENDPOINT=
+# AZURE_OPENAI_API_VERSION="2024-12-01-preview"
+# AZURE_OPENAI_DEPLOYMENT_NAME=
+
+# USE THIS IF YOU WANT TO DEBUG THE APP ON LANGSMITH
+# LANGCHAIN_TRACING_V2=true
+# LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"
+# LANGCHAIN_API_KEY=
+# LANGCHAIN_PROJECT="Open Notebook"
+
+# CONNECTION DETAILS FOR YOUR SURREAL DB
+# New format (preferred) - WebSocket URL
+SURREAL_URL="ws://surrealdb/rpc:8000"
+SURREAL_USER="root"
+SURREAL_PASSWORD="root"
+SURREAL_NAMESPACE="open_notebook"
+SURREAL_DATABASE="staging"
+
+# OPEN_NOTEBOOK_PASSWORD=
+
+# FIRECRAWL - Get a key at https://firecrawl.dev/
+FIRECRAWL_API_KEY=
+
+# JINA - Get a key at https://jina.ai/
+JINA_API_KEY=

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+logo.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,136 @@
+.env
+prompts/patterns/user/
+/notebooks/
+data/
+.uploads/
+sqlite-db/
+surreal-data/
+docker.env
+!setup_guide/docker.env
+notebook_data/
+# Python-specific
+*.py[cod]
+__pycache__/
+*.so
+todo.md
+temp/
+google-credentials.json
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+/lib/
+/lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# PyCharm
+.idea/
+
+# VS Code
+.vscode/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# macOS
+.DS_Store
+
+# Windows
+Thumbs.db
+ehthumbs.db
+desktop.ini
+
+# Linux
+*~
+
+# Log files
+*.log
+
+# Database files
+*.db
+*.sqlite3
+
+.quarentena
+
+claude-logs/
+.claude/sessions
+**/claude-logs
+
+
+docs/custom_gpt
+doc_exports/
+
+specs/
+.claude
+
+.playwright-mcp/

.python-version

@@ -0,0 +1 @@
+3.12

CLAUDE.md

@@ -0,0 +1,3 @@
+
+We have a good amount of documentation on this project on the ./docs folder. Please read through them when necessary, and always review the docs/index.md file before starting a new feature so you know at least which docs are available. 
+

CONFIGURATION.md

@@ -0,0 +1,108 @@
+# Configuration Guide
+
+## API Connection Configuration
+
+Starting from version 1.0.0-alpha, Open Notebook uses a simplified API connection system that automatically configures itself based on your deployment environment.
+
+### How It Works
+
+The frontend automatically discovers the API location at runtime by analyzing the incoming HTTP request. This eliminates the need for complex network configurations and works for both Docker deployment modes:
+- Multi-container (docker-compose with separate SurrealDB)
+- Single-container (all services in one container)
+
+**Auto-detection logic:**
+1. If `API_URL` environment variable is set → use it (explicit override)
+2. Otherwise, detect from the HTTP request:
+   - Uses the same hostname you're accessing the frontend from
+   - Automatically changes port to 5055 (API port)
+   - Respects `X-Forwarded-Proto` header for reverse proxy setups
+3. Falls back to `http://localhost:5055` if detection fails
+
+**Examples:**
+- Access frontend at `http://localhost:8502` → API at `http://localhost:5055` ✅
+- Access frontend at `http://10.20.30.20:8502` → API at `http://10.20.30.20:5055` ✅
+- Access frontend at `http://my-server:8502` → API at `http://my-server:5055` ✅
+
+**No configuration needed** for most deployments!
+
+### Custom Configuration
+
+If you need to change the API URL (e.g., running on a different host, port, or domain), you can configure it using the `API_URL` environment variable.
+
+#### Option 1: Using docker-compose (Recommended)
+
+Edit your `docker.env` file:
+
+```env
+API_URL=http://your-server-ip:5055
+```
+
+Or add it to your `docker-compose.yml`:
+
+```yaml
+services:
+  open_notebook:
+    image: lfnovo/open_notebook:v1-latest
+    ports:
+      - "8502:8502"
+      - "5055:5055"  # API port must be exposed
+    environment:
+      - API_URL=http://your-server-ip:5055
+```
+
+#### Option 2: Using docker run
+
+```bash
+docker run -e API_URL=http://your-server-ip:5055 \
+  -p 8502:8502 \
+  -p 5055:5055 \
+  lfnovo/open_notebook:v1-latest-single
+```
+
+### Important Notes
+
+1. **Port 5055 must be exposed**: The browser needs direct access to the API, so port 5055 must be mapped in your Docker configuration.
+
+2. **Use the externally accessible URL**: The `API_URL` should be the URL that a browser can reach, not internal Docker networking addresses.
+
+3. **Protocol matters**: Use `http://` for local deployments, `https://` if you've set up SSL.
+
+### Examples
+
+#### Running on a different host
+```env
+API_URL=http://192.168.1.100:5055
+```
+
+#### Running on a custom domain with SSL
+```env
+API_URL=https://notebook.example.com/api
+```
+
+#### Running on a custom port
+```env
+API_URL=http://localhost:3055
+```
+(Remember to update the port mapping in docker-compose accordingly)
+
+### Troubleshooting
+
+**"Unable to connect to server" error on login:**
+1. Verify port 5055 is exposed in your Docker configuration
+2. Check that `API_URL` matches the URL your browser can access
+3. Try accessing `http://localhost:5055/health` directly in your browser
+4. If that fails, the API isn't running or port isn't exposed
+
+**API works but frontend doesn't connect:**
+1. Check browser console for CORS errors
+2. Verify `API_URL` is set correctly
+3. Make sure you're using the same protocol (http/https) throughout
+
+### Migration from Previous Versions
+
+If you were previously exposing port 5055 manually or had custom configurations, you may need to:
+1. Update your `docker.env` or environment variables to include `API_URL`
+2. Ensure port 5055 is exposed in your docker-compose.yml (it's now required)
+3. Remove any custom Next.js configuration or environment variables you may have added
+
+The default configuration will work for most users without any changes.

CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing to Open Notebook
+
+First off, thank you for considering contributing to Open Notebook! What makes open source great is the fact that we can work together and accomplish things we would never do on our own. All suggestions are welcome. 
+
+## Code of Conduct
+
+By participating in this project, you are expected to uphold our Code of Conduct (to be created separately).
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+- Ensure the bug was not already reported by searching on GitHub under [Issues](https://github.com/yourusername/open-notebook/issues).
+- If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/yourusername/open-notebook/issues/new). Be sure to include a title and clear description, as much relevant information as possible, and a code sample or an executable test case demonstrating the expected behavior that is not occurring.
+
+### Suggesting Enhancements
+
+- Open a new issue with a clear title and detailed description of the suggested enhancement.
+- Provide any relevant examples or mockups if applicable.
+
+### Pull Requests
+
+1. Fork the repo and create your branch from `main`.
+2. If you've added code that should be tested, add tests.
+3. Ensure the test suite passes.
+4. Make sure your code lints.
+5. Issue that pull request!
+
+## Styleguides
+
+### Git Commit Messages
+
+- Use the present tense ("Add feature" not "Added feature")
+- Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
+- Limit the first line to 72 characters or less
+- Reference issues and pull requests liberally after the first line
+
+### Python Styleguide
+
+- Follow PEP 8 guidelines
+- Use type hints where possible
+- Write docstrings for all functions, classes, and modules
+
+### Documentation Styleguide
+
+- Use Markdown for documentation files
+- Reference functions and classes appropriately
+
+## Additional Notes
+
+
+Thank you for contributing to Open Notebook!

Dockerfile

@@ -0,0 +1,95 @@
+# Build stage
+FROM python:3.12-slim-bookworm AS builder
+
+# Install uv using the official method
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+# Install system dependencies required for building certain Python packages
+# Add Node.js 20.x LTS for building frontend
+RUN apt-get update && apt-get upgrade -y && apt-get install -y \
+    gcc g++ git make \
+    curl \
+    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set build optimization environment variables
+ENV MAKEFLAGS="-j$(nproc)"
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV UV_COMPILE_BYTECODE=1
+ENV UV_LINK_MODE=copy
+
+# Set the working directory in the container to /app
+WORKDIR /app
+
+# Copy dependency files and minimal package structure first for better layer caching
+COPY pyproject.toml uv.lock ./
+COPY open_notebook/__init__.py ./open_notebook/__init__.py
+
+# Install dependencies with optimizations (this layer will be cached unless dependencies change)
+RUN uv sync --frozen --no-dev
+
+# Copy the rest of the application code
+COPY . /app
+
+# Install frontend dependencies and build
+WORKDIR /app/frontend
+RUN npm ci
+RUN npm run build
+
+# Return to app root
+WORKDIR /app
+
+# Runtime stage
+FROM python:3.12-slim-bookworm AS runtime
+
+# Install only runtime system dependencies (no build tools)
+# Add Node.js 20.x LTS for running frontend
+RUN apt-get update && apt-get upgrade -y && apt-get install -y \
+    ffmpeg \
+    supervisor \
+    curl \
+    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv using the official method
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+# Set the working directory in the container to /app
+WORKDIR /app
+
+# Copy the virtual environment from builder stage
+COPY --from=builder /app/.venv /app/.venv
+
+# Copy the application code
+COPY --from=builder /app /app
+
+# Copy built frontend from builder stage
+COPY --from=builder /app/frontend/.next/standalone /app/frontend/
+COPY --from=builder /app/frontend/.next/static /app/frontend/.next/static
+COPY --from=builder /app/frontend/public /app/frontend/public
+
+# Expose ports for Frontend and API
+EXPOSE 8502 5055
+
+RUN mkdir -p /app/data
+
+# Copy supervisord configuration
+COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf
+
+# Create log directories
+RUN mkdir -p /var/log/supervisor
+
+# Runtime API URL Configuration
+# The API_URL environment variable can be set at container runtime to configure
+# where the frontend should connect to the API. This allows the same Docker image
+# to work in different deployment scenarios without rebuilding.
+#
+# If not set, the system will auto-detect based on incoming requests.
+# Set API_URL when using reverse proxies or custom domains.
+#
+# Example: docker run -e API_URL=https://your-domain.com/api ...
+
+CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]

Dockerfile.single

@@ -0,0 +1,99 @@
+# Build stage
+FROM python:3.12-slim-bookworm AS builder
+
+# Install uv using the official method
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+# Install system dependencies required for building certain Python packages
+# Add Node.js 20.x LTS for building frontend
+RUN apt-get update && apt-get upgrade -y && apt-get install -y \
+    gcc g++ git make \
+    curl \
+    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set build optimization environment variables
+ENV MAKEFLAGS="-j$(nproc)"
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV UV_COMPILE_BYTECODE=1
+ENV UV_LINK_MODE=copy
+
+# Set the working directory in the container to /app
+WORKDIR /app
+
+# Copy dependency files and minimal package structure first for better layer caching
+COPY pyproject.toml uv.lock ./
+COPY open_notebook/__init__.py ./open_notebook/__init__.py
+
+# Install dependencies with optimizations (this layer will be cached unless dependencies change)
+RUN uv sync --frozen --no-dev
+
+# Copy the rest of the application code
+COPY . /app
+
+# Install frontend dependencies and build
+WORKDIR /app/frontend
+RUN npm ci
+RUN npm run build
+
+# Return to app root
+WORKDIR /app
+
+# Runtime stage
+FROM python:3.12-slim-bookworm AS runtime
+
+# Install runtime system dependencies including curl for SurrealDB installation
+# Add Node.js 20.x LTS for running frontend
+RUN apt-get update && apt-get upgrade -y && apt-get install -y \
+    ffmpeg \
+    supervisor \
+    curl \
+    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install SurrealDB
+RUN curl --proto '=https' --tlsv1.2 -sSf https://install.surrealdb.com | sh
+
+# Install uv using the official method
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+# Set the working directory in the container to /app
+WORKDIR /app
+
+# Copy the virtual environment from builder stage
+COPY --from=builder /app/.venv /app/.venv
+
+# Copy the application code
+COPY --from=builder /app /app
+
+# Copy built frontend from builder stage
+COPY --from=builder /app/frontend/.next/standalone /app/frontend/
+COPY --from=builder /app/frontend/.next/static /app/frontend/.next/static
+COPY --from=builder /app/frontend/public /app/frontend/public
+
+# Create directories for data persistence
+RUN mkdir -p /app/data /mydata
+
+# Expose ports for Frontend and API
+EXPOSE 8502 5055
+
+# Copy single-container supervisord configuration
+COPY supervisord.single.conf /etc/supervisor/conf.d/supervisord.conf
+
+# Create log directories
+RUN mkdir -p /var/log/supervisor
+
+# Runtime API URL Configuration
+# The API_URL environment variable can be set at container runtime to configure
+# where the frontend should connect to the API. This allows the same Docker image
+# to work in different deployment scenarios without rebuilding.
+#
+# If not set, the system will auto-detect based on incoming requests.
+# Set API_URL when using reverse proxies or custom domains.
+#
+# Example: docker run -e API_URL=https://your-domain.com/api ...
+
+CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]

LICENSE

@@ -0,0 +1,17 @@
+MIT License
+Copyright (c) 2024 Luis Novo
+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.

MIGRATION.md

@@ -0,0 +1,397 @@
+# Migration Guide: Streamlit to React/Next.js Frontend
+
+**Version**: 1.0.0
+**Last Updated**: October 2025
+
+This guide helps existing Open Notebook users migrate from the legacy Streamlit frontend to the new React/Next.js frontend.
+
+---
+
+## ⚠️ Breaking Changes in v1.0
+
+Open Notebook v1.0 introduces breaking changes that require manual migration. Please read this section carefully before upgrading.
+
+### Docker Tag Changes
+
+**The "latest" tag is now frozen** at the last Streamlit version. Starting with v1.0, we use versioned tags to prevent unexpected breaking changes:
+
+- **`latest`** and **`latest-single`** → FROZEN at Streamlit version (will not update)
+- **`v1-latest`** and **`v1-latest-single`** → NEW tags for v1.x releases (recommended)
+- **`X.Y.Z`** and **`X.Y.Z-single`** → Specific version tags (unchanged)
+
+**Why this change?**
+The v1.0 release brings significant architectural changes (Streamlit → React/Next.js frontend). Freezing the "latest" tag prevents existing deployments from breaking unexpectedly, while the new "v1-latest" tag allows users to explicitly opt into the v1 architecture.
+
+### Quick Migration for Docker Users
+
+If you're currently using `latest` or `latest-single`, you need to:
+
+1. **Update your docker-compose.yml or docker run command**:
+   ```yaml
+   # Before:
+   image: lfnovo/open_notebook:latest-single
+
+   # After (recommended):
+   image: lfnovo/open_notebook:v1-latest-single
+   ```
+
+2. **Expose port 5055** for the API (required in v1):
+   ```yaml
+   ports:
+     - "8502:8502"  # Frontend
+     - "5055:5055"  # API (NEW - required)
+   ```
+
+3. **Verify API connectivity** after upgrade:
+   ```bash
+   curl http://localhost:5055/api/config
+   ```
+
+### API Connectivity (Port 5055)
+
+**Important:** v1.0 requires port 5055 to be exposed to your host machine so the frontend can communicate with the API.
+
+**Auto-Detection:** The Next.js frontend automatically detects the API URL:
+- If you access the frontend at `http://localhost:8502`, it uses `http://localhost:5055`
+- If you access the frontend at `http://192.168.1.100:8502`, it uses `http://192.168.1.100:5055`
+- If you access the frontend at `http://my-server:8502`, it uses `http://my-server:5055`
+
+**Manual Override:** If auto-detection doesn't work (e.g., reverse proxy, complex networking), set the `API_URL` environment variable:
+
+```bash
+# Docker run example
+docker run -d \
+  --name open-notebook \
+  -p 8502:8502 -p 5055:5055 \
+  -e API_URL=http://my-custom-api:5055 \
+  -v ./notebook_data:/app/data \
+  -v ./surreal_data:/mydata \
+  lfnovo/open_notebook:v1-latest-single
+```
+
+```yaml
+# docker-compose.yml example
+services:
+  open_notebook:
+    image: lfnovo/open_notebook:v1-latest-single
+    ports:
+      - "8502:8502"
+      - "5055:5055"
+    environment:
+      - API_URL=http://my-custom-api:5055
+    volumes:
+      - ./notebook_data:/app/data
+      - ./surreal_data:/mydata
+```
+
+### Health Check
+
+Verify your API is accessible with:
+
+```bash
+# Local deployment
+curl http://localhost:5055/api/config
+
+# Remote deployment
+curl http://your-server-ip:5055/api/config
+```
+
+Expected response:
+```json
+{
+  "version": "1.0.0",
+  "latestVersion": "1.0.0",
+  "hasUpdate": false,
+  "dbStatus": "online"
+}
+```
+
+Note: The API URL is now auto-detected by the frontend from the hostname you're accessing, so `/api/config` no longer returns `apiUrl`.
+
+### Troubleshooting
+
+**Problem:** Frontend shows "Cannot connect to API" error
+- **Check:** Is port 5055 exposed? Run `docker ps` and verify port mapping
+- **Check:** Can you reach the API? Run `curl http://localhost:5055/api/config`
+- **Solution:** If using custom networking, set `API_URL` environment variable
+
+**Problem:** Auto-detection uses wrong hostname
+- **Example:** Frontend at `http://internal-hostname:8502` but API should use `http://public-hostname:5055`
+- **Solution:** Set `API_URL=http://public-hostname:5055` environment variable
+
+**Problem:** Still running the old Streamlit version after `docker pull`
+- **Check:** Are you using the "latest" tag? It's frozen at Streamlit version
+- **Solution:** Update to `v1-latest` or `v1-latest-single` tag
+
+---
+
+## What Changed
+
+Open Notebook has migrated from a Streamlit-based frontend to a modern React/Next.js application. This brings significant improvements in performance, user experience, and maintainability.
+
+### Key Changes
+
+| Aspect | Before (Streamlit) | After (React/Next.js) |
+|--------|-------------------|----------------------|
+| **Frontend Framework** | Streamlit | Next.js 15 + React 18 |
+| **UI Components** | Streamlit widgets | shadcn/ui + Radix UI |
+| **Frontend Port** | 8502 | 8502 (unchanged) |
+| **API Port** | 5055 | 5055 (unchanged) |
+| **Navigation** | Sidebar with emoji icons | Clean sidebar navigation |
+| **Performance** | Server-side rendering | Client-side React with API calls |
+| **Customization** | Limited | Highly customizable |
+
+### What Stayed the Same
+
+- **Core functionality**: All features remain available
+- **API backend**: FastAPI backend unchanged
+- **Database**: SurrealDB unchanged
+- **Data format**: No data migration needed
+- **Configuration**: Same environment variables
+- **Docker deployment**: Same ports and setup
+
+## Migration Paths
+
+### Path 1: Docker Users (Recommended)
+
+If you're running Open Notebook via Docker, migration is automatic:
+
+1. **Stop the current version**:
+   ```bash
+   docker-compose down
+   ```
+
+2. **Update to the latest image**:
+   ```bash
+   # Update docker-compose.yml to use v1-latest
+   # Change from:
+   image: lfnovo/open_notebook:latest-single
+   # To:
+   image: lfnovo/open_notebook:v1-latest-single
+   ```
+
+3. **Start the new version**:
+   ```bash
+   docker-compose pull
+   docker-compose up -d
+   ```
+
+4. **Access the new frontend**:
+   - Frontend: http://localhost:8502 (new React UI)
+   - API Docs: http://localhost:5055/docs
+
+**Your data is automatically preserved!** All notebooks, sources, and notes carry over seamlessly.
+
+### Path 2: Source Code Users
+
+If you're running from source code:
+
+1. **Pull the latest code**:
+   ```bash
+   git pull origin main
+   ```
+
+2. **Install frontend dependencies**:
+   ```bash
+   cd frontend
+   npm install
+   cd ..
+   ```
+
+3. **Update Python dependencies**:
+   ```bash
+   uv sync
+   ```
+
+4. **Start services** (3 terminals):
+   ```bash
+   # Terminal 1: Database
+   make database
+
+   # Terminal 2: API
+   uv run python api/main.py
+
+   # Terminal 3: Frontend (NEW)
+   cd frontend && npm run dev
+   ```
+
+5. **Access the application**:
+   - Frontend: http://localhost:8502
+   - API: http://localhost:5055
+
+## Breaking Changes
+
+### Removed Features
+
+The following Streamlit-specific features are no longer available:
+
+- **Streamlit cache**: Replaced with React Query caching
+- **Streamlit session state**: Replaced with React state management
+- **Direct file access via Streamlit**: Use API endpoints instead
+
+### Changed Navigation
+
+Navigation paths have been simplified:
+
+| Old Path | New Path |
+|----------|----------|
+| Settings → Models | Models |
+| Settings → Advanced | Advanced |
+| Other paths | (Same but cleaner navigation) |
+
+### API Changes
+
+**No breaking API changes!** The REST API remains fully backward compatible.
+
+## New Features in React Version
+
+The React frontend brings several improvements:
+
+### Performance
+- **Faster page loads**: Client-side rendering with React
+- **Better caching**: React Query for intelligent data caching
+- **Optimized builds**: Next.js automatic code splitting
+
+### User Experience
+- **Modern UI**: Clean, professional interface with shadcn/ui
+- **Responsive design**: Better mobile and tablet support
+- **Keyboard shortcuts**: Improved keyboard navigation
+- **Real-time updates**: Better WebSocket support
+
+### Developer Experience
+- **TypeScript**: Full type safety
+- **Component library**: Reusable UI components
+- **Hot reload**: Instant updates during development
+- **Testing**: Better test infrastructure
+
+## Troubleshooting
+
+### Issue: Can't access the frontend
+
+**Solution**:
+```bash
+# Check if services are running
+docker-compose ps
+
+# Check logs
+docker-compose logs open_notebook
+
+# Restart services
+docker-compose restart
+```
+
+### Issue: API errors in new frontend
+
+**Solution**:
+The new frontend requires the API to be running. Ensure:
+```bash
+# API should be accessible at
+curl http://localhost:5055/health
+
+# If not, check API logs
+docker-compose logs open_notebook | grep api
+```
+
+### Issue: Missing data after migration
+
+**Solution**:
+Data is preserved automatically. If you don't see your data:
+
+1. Check database volume is mounted correctly:
+   ```bash
+   docker-compose down
+   # Verify volumes in docker-compose.yml:
+   # - ./surreal_data:/mydata  (for multi-container)
+   # - ./surreal_single_data:/mydata (for single-container)
+   docker-compose up -d
+   ```
+
+2. Check SurrealDB is running:
+   ```bash
+   docker-compose logs surrealdb
+   ```
+
+### Issue: Port conflicts
+
+**Solution**:
+If ports 8502 or 5055 are already in use:
+
+```bash
+# Find what's using the port
+lsof -i :8502
+lsof -i :5055
+
+# Stop conflicting service or change Open Notebook ports
+# Edit docker-compose.yml:
+ports:
+  - "8503:8502"  # Change external port
+  - "5056:5055"  # Change external port
+```
+
+## Rollback Instructions
+
+If you need to roll back to the Streamlit version:
+
+### Docker Users
+
+```bash
+# Stop current version
+docker-compose down
+
+# Edit docker-compose.yml to use old image
+# Change to: lfnovo/open_notebook:streamlit-latest
+
+# Start old version
+docker-compose up -d
+```
+
+### Source Code Users
+
+```bash
+# Checkout the last Streamlit version tag
+git checkout tags/streamlit-final
+
+# Install dependencies
+uv sync
+
+# Start Streamlit
+uv run streamlit run app_home.py
+```
+
+## Getting Help
+
+If you encounter issues during migration:
+
+- **Discord**: Join our [Discord community](https://discord.gg/37XJPXfz2w) for real-time help
+- **GitHub Issues**: Report bugs at [github.com/lfnovo/open-notebook/issues](https://github.com/lfnovo/open-notebook/issues)
+- **Documentation**: Check [full documentation](https://github.com/lfnovo/open-notebook/tree/main/docs)
+
+## FAQs
+
+### Will my notebooks and data be lost?
+No! All data is preserved. The database and API backend are unchanged.
+
+### Do I need to update my API integrations?
+No! The REST API remains fully backward compatible.
+
+### Can I use both frontends simultaneously?
+Technically yes, but not recommended. Choose one for consistency.
+
+### What about my custom Streamlit pages?
+Custom Streamlit pages won't work with the React frontend. Consider:
+- Using the REST API to build custom integrations
+- Contributing React components to the project
+- Requesting features in GitHub issues
+
+### Is the Streamlit version still supported?
+The Streamlit version is no longer actively developed. We recommend migrating to the React version for the best experience and latest features.
+
+## Timeline
+
+- **Legacy (Pre-v1.0)**: Streamlit frontend
+- **Current (v1.0+)**: React/Next.js frontend
+- **Future**: Continued React development with new features
+
+---
+
+**Ready to migrate?** Follow the migration path for your deployment method above. The process is straightforward and your data is safe!

Makefile

@@ -0,0 +1,201 @@
+.PHONY: run frontend check ruff database lint api start-all stop-all status clean-cache worker worker-start worker-stop worker-restart
+.PHONY: docker-buildx-prepare docker-buildx-clean docker-buildx-reset
+.PHONY: docker-push docker-push-latest docker-release tag export-docs
+
+# Get version from pyproject.toml
+VERSION := $(shell grep -m1 version pyproject.toml | cut -d'"' -f2)
+
+# Image names for both registries
+DOCKERHUB_IMAGE := lfnovo/open_notebook
+GHCR_IMAGE := ghcr.io/lfnovo/open-notebook
+
+# Build platforms
+PLATFORMS := linux/amd64,linux/arm64
+
+database:
+	docker compose up -d surrealdb
+
+run:
+	@echo "⚠️  Warning: Starting frontend only. For full functionality, use 'make start-all'"
+	cd frontend && npm run dev
+
+frontend:
+	cd frontend && npm run dev
+
+lint:
+	uv run python -m mypy .
+
+ruff:
+	ruff check . --fix
+
+# === Docker Build Setup ===
+docker-buildx-prepare:
+	@docker buildx inspect multi-platform-builder >/dev/null 2>&1 || \
+		docker buildx create --use --name multi-platform-builder --driver docker-container
+	@docker buildx use multi-platform-builder
+
+docker-buildx-clean:
+	@echo "🧹 Cleaning up buildx builders..."
+	@docker buildx rm multi-platform-builder 2>/dev/null || true
+	@docker ps -a | grep buildx_buildkit | awk '{print $$1}' | xargs -r docker rm -f 2>/dev/null || true
+	@echo "✅ Buildx cleanup complete!"
+
+docker-buildx-reset: docker-buildx-clean docker-buildx-prepare
+	@echo "✅ Buildx reset complete!"
+
+# === Docker Build Targets ===
+
+# Build and push version tags ONLY (no latest) for both regular and single images
+docker-push: docker-buildx-prepare
+	@echo "📤 Building and pushing version $(VERSION) to both registries..."
+	@echo "🔨 Building regular image..."
+	docker buildx build --pull \
+		--platform $(PLATFORMS) \
+		--progress=plain \
+		-t $(DOCKERHUB_IMAGE):$(VERSION) \
+		-t $(GHCR_IMAGE):$(VERSION) \
+		--push \
+		.
+	@echo "🔨 Building single-container image..."
+	docker buildx build --pull \
+		--platform $(PLATFORMS) \
+		--progress=plain \
+		-f Dockerfile.single \
+		-t $(DOCKERHUB_IMAGE):$(VERSION)-single \
+		-t $(GHCR_IMAGE):$(VERSION)-single \
+		--push \
+		.
+	@echo "✅ Pushed version $(VERSION) to both registries (latest NOT updated)"
+	@echo "  📦 Docker Hub:"
+	@echo "    - $(DOCKERHUB_IMAGE):$(VERSION)"
+	@echo "    - $(DOCKERHUB_IMAGE):$(VERSION)-single"
+	@echo "  📦 GHCR:"
+	@echo "    - $(GHCR_IMAGE):$(VERSION)"
+	@echo "    - $(GHCR_IMAGE):$(VERSION)-single"
+
+# Update v1-latest tags to current version (both regular and single images)
+docker-push-latest: docker-buildx-prepare
+	@echo "📤 Updating v1-latest tags to version $(VERSION)..."
+	@echo "🔨 Building regular image with latest tag..."
+	docker buildx build --pull \
+		--platform $(PLATFORMS) \
+		--progress=plain \
+		-t $(DOCKERHUB_IMAGE):$(VERSION) \
+		-t $(DOCKERHUB_IMAGE):v1-latest \
+		-t $(GHCR_IMAGE):$(VERSION) \
+		-t $(GHCR_IMAGE):v1-latest \
+		--push \
+		.
+	@echo "🔨 Building single-container image with latest tag..."
+	docker buildx build --pull \
+		--platform $(PLATFORMS) \
+		--progress=plain \
+		-f Dockerfile.single \
+		-t $(DOCKERHUB_IMAGE):$(VERSION)-single \
+		-t $(DOCKERHUB_IMAGE):v1-latest-single \
+		-t $(GHCR_IMAGE):$(VERSION)-single \
+		-t $(GHCR_IMAGE):v1-latest-single \
+		--push \
+		.
+	@echo "✅ Updated v1-latest to version $(VERSION)"
+	@echo "  📦 Docker Hub:"
+	@echo "    - $(DOCKERHUB_IMAGE):$(VERSION) → v1-latest"
+	@echo "    - $(DOCKERHUB_IMAGE):$(VERSION)-single → v1-latest-single"
+	@echo "  📦 GHCR:"
+	@echo "    - $(GHCR_IMAGE):$(VERSION) → v1-latest"
+	@echo "    - $(GHCR_IMAGE):$(VERSION)-single → v1-latest-single"
+
+# Full release: push version AND update latest tags
+docker-release: docker-push-latest
+	@echo "✅ Full release complete for version $(VERSION)"
+
+tag:
+	@version=$$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/'); \
+	echo "Creating tag v$$version"; \
+	git tag "v$$version"; \
+	git push origin "v$$version"
+
+
+dev:
+	docker compose -f docker-compose.dev.yml up --build 
+
+full:
+	docker compose -f docker-compose.full.yml up --build 
+
+
+api:
+	uv run run_api.py
+
+# === Worker Management ===
+.PHONY: worker worker-start worker-stop worker-restart
+
+worker: worker-start
+
+worker-start:
+	@echo "Starting surreal-commands worker..."
+	uv run --env-file .env surreal-commands-worker --import-modules commands
+
+worker-stop:
+	@echo "Stopping surreal-commands worker..."
+	pkill -f "surreal-commands-worker" || true
+
+worker-restart: worker-stop
+	@sleep 2
+	@$(MAKE) worker-start
+
+# === Service Management ===
+start-all:
+	@echo "🚀 Starting Open Notebook (Database + API + Worker + Frontend)..."
+	@echo "📊 Starting SurrealDB..."
+	@docker compose up -d surrealdb
+	@sleep 3
+	@echo "🔧 Starting API backend..."
+	@uv run run_api.py &
+	@sleep 3
+	@echo "⚙️ Starting background worker..."
+	@uv run --env-file .env surreal-commands-worker --import-modules commands &
+	@sleep 2
+	@echo "🌐 Starting Next.js frontend..."
+	@echo "✅ All services started!"
+	@echo "📱 Frontend: http://localhost:3000"
+	@echo "🔗 API: http://localhost:5055"
+	@echo "📚 API Docs: http://localhost:5055/docs"
+	cd frontend && npm run dev
+
+stop-all:
+	@echo "🛑 Stopping all Open Notebook services..."
+	@pkill -f "next dev" || true
+	@pkill -f "surreal-commands-worker" || true
+	@pkill -f "run_api.py" || true
+	@pkill -f "uvicorn api.main:app" || true
+	@docker compose down
+	@echo "✅ All services stopped!"
+
+status:
+	@echo "📊 Open Notebook Service Status:"
+	@echo "Database (SurrealDB):"
+	@docker compose ps surrealdb 2>/dev/null || echo "  ❌ Not running"
+	@echo "API Backend:"
+	@pgrep -f "run_api.py\|uvicorn api.main:app" >/dev/null && echo "  ✅ Running" || echo "  ❌ Not running"
+	@echo "Background Worker:"
+	@pgrep -f "surreal-commands-worker" >/dev/null && echo "  ✅ Running" || echo "  ❌ Not running"
+	@echo "Next.js Frontend:"
+	@pgrep -f "next dev" >/dev/null && echo "  ✅ Running" || echo "  ❌ Not running"
+
+# === Documentation Export ===
+export-docs:
+	@echo "📚 Exporting documentation..."
+	@uv run python scripts/export_docs.py
+	@echo "✅ Documentation export complete!"
+
+# === Cleanup ===
+clean-cache:
+	@echo "🧹 Cleaning cache directories..."
+	@find . -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null || true
+	@find . -name ".mypy_cache" -type d -exec rm -rf {} + 2>/dev/null || true
+	@find . -name ".ruff_cache" -type d -exec rm -rf {} + 2>/dev/null || true
+	@find . -name ".pytest_cache" -type d -exec rm -rf {} + 2>/dev/null || true
+	@find . -name "*.pyc" -type f -delete 2>/dev/null || true
+	@find . -name "*.pyo" -type f -delete 2>/dev/null || true
+	@find . -name "*.pyd" -type f -delete 2>/dev/null || true
+	@echo "✅ Cache directories cleaned!"

PWA_IMPLEMENTATION.md

@@ -0,0 +1,292 @@
+# PWA Implementation Guide for Open Notebook
+
+## What Was Implemented
+
+Open Notebook has been successfully converted into a Progressive Web App (PWA) with the following features:
+
+### Features Added
+
+1. **Installable App**
+   - Users can install Open Notebook to their home screen on mobile and desktop
+   - Works on iOS, Android, Windows, Mac, and Linux
+   - App appears in app launchers just like native apps
+
+2. **Offline Support**
+   - Service worker caching for faster load times
+   - Graceful offline fallback page
+   - API caching with Network-First strategy (5-minute cache)
+
+3. **Smart Caching**
+   - Static assets (JS, CSS, images) cached for 24 hours
+   - Google Fonts cached for optimal performance
+   - Next.js image optimization cached
+
+4. **Install Prompt**
+   - Smart install prompt appears after 30 seconds
+   - Dismissible with 7-day cooldown
+   - Auto-detects if already installed
+
+5. **Mobile Optimized**
+   - Apple Touch Icon support
+   - Proper viewport and theme-color meta tags
+   - App shortcuts for quick actions
+
+## Files Modified/Created
+
+### Modified Files
+- `frontend/next.config.ts` - PWA configuration with caching strategies
+- `frontend/src/app/layout.tsx` - Added PWA meta tags and install prompt
+- `frontend/package.json` - Added next-pwa dependency
+
+### New Files
+- `frontend/public/manifest.json` - Web app manifest with app metadata
+- `frontend/public/offline.html` - Offline fallback page
+- `frontend/src/components/common/InstallPWA.tsx` - Install prompt component
+- `frontend/generate-icons.js` - Icon generation script
+- `frontend/public/icon-*.png` - PWA icons (9 sizes)
+- `frontend/public/apple-touch-icon.png` - iOS home screen icon
+
+## How to Test
+
+### 1. Build and Start the App
+
+```bash
+cd /home/john/opennotebook/frontend
+npm run build
+npm start
+```
+
+Or with Docker:
+```bash
+cd /home/john/opennotebook
+docker compose up --build
+```
+
+### 2. Test on Desktop (Chrome/Edge)
+
+1. Open Chrome/Edge browser
+2. Navigate to your Open Notebook URL (e.g., `http://localhost:8502`)
+3. Look for the install icon in the address bar (⊕ or ⬇️)
+4. Click it and select "Install"
+5. The app will open in its own window
+
+**Alternative:**
+- Open DevTools (F12)
+- Go to "Application" tab
+- Click "Manifest" to verify manifest is loaded
+- Check "Service Workers" to see if worker is active
+- Use "Lighthouse" tab to run PWA audit
+
+### 3. Test on Android
+
+1. Open Chrome browser on Android
+2. Navigate to your Open Notebook URL
+3. Wait 30 seconds for the install prompt to appear
+4. Or tap the menu (⋮) and select "Install app" or "Add to Home Screen"
+5. Tap "Install"
+6. Find the app icon on your home screen
+
+**Testing Tips:**
+- Use Chrome's Device Mode in DevTools to simulate mobile
+- Remote debug using `chrome://inspect` on desktop
+- Check console for any PWA-related errors
+
+### 4. Test on iOS (Safari)
+
+1. Open Safari on iOS
+2. Navigate to your Open Notebook URL
+3. Tap the Share button (square with arrow)
+4. Scroll down and tap "Add to Home Screen"
+5. Customize name if desired and tap "Add"
+6. Find the app icon on your home screen
+
+**Note:** iOS has limited PWA support:
+- No automatic install prompt
+- No background sync
+- Limited push notification support
+
+### 5. Test Offline Functionality
+
+**Desktop:**
+1. Open DevTools (F12)
+2. Go to "Network" tab
+3. Check "Offline" checkbox
+4. Refresh the page
+5. You should see the offline fallback page
+
+**Mobile:**
+1. Enable Airplane mode
+2. Open the installed app
+3. You should see cached content or offline page
+
+### 6. Test PWA Features with Lighthouse
+
+1. Open Chrome DevTools (F12)
+2. Go to "Lighthouse" tab
+3. Select "Progressive Web App" category
+4. Click "Analyze page load"
+5. Review the PWA score (should be 90+)
+
+## PWA Configuration Details
+
+### Caching Strategies
+
+| Resource Type | Strategy | Cache Duration | Notes |
+|--------------|----------|----------------|-------|
+| API Calls | NetworkFirst | 5 minutes | Falls back to cache if network is slow (10s timeout) |
+| Static JS/CSS | StaleWhileRevalidate | 24 hours | Always serves from cache, updates in background |
+| Images | StaleWhileRevalidate | 24 hours | Cached for fast loading |
+| Google Fonts | CacheFirst (webfonts) / StaleWhileRevalidate (CSS) | 365 days / 7 days | Optimal font loading |
+
+### Manifest Features
+
+- **Display Mode:** Standalone (looks like a native app)
+- **Orientation:** Portrait-primary (mobile optimized)
+- **Theme Color:** #000000 (customizable in manifest.json)
+- **Background Color:** #ffffff (customizable in manifest.json)
+- **App Shortcuts:** Quick access to New Notebook and Search
+
+## Customization
+
+### Change Theme Colors
+
+Edit `frontend/public/manifest.json`:
+```json
+{
+  "theme_color": "#667eea",
+  "background_color": "#ffffff"
+}
+```
+
+Also update in `frontend/src/app/layout.tsx`:
+```tsx
+<meta name="theme-color" content="#667eea" />
+```
+
+### Adjust Install Prompt Timing
+
+Edit `frontend/src/components/common/InstallPWA.tsx`:
+```tsx
+// Change from 30 seconds (30000ms) to desired delay
+setTimeout(() => {
+  setShowInstallPrompt(true);
+}, 30000); // Change this value
+```
+
+### Modify Caching Behavior
+
+Edit `frontend/next.config.ts` in the `runtimeCaching` array:
+- Change `handler` types: `NetworkFirst`, `CacheFirst`, `StaleWhileRevalidate`
+- Adjust `maxAgeSeconds` for cache duration
+- Modify `maxEntries` for cache size limits
+
+### Disable PWA in Development
+
+PWA is automatically disabled in development mode. To enable it, edit `next.config.ts`:
+```tsx
+disable: false, // Change from process.env.NODE_ENV === "development"
+```
+
+## Troubleshooting
+
+### Install Button Not Showing
+
+1. Check if already installed (look for standalone display mode)
+2. PWA criteria not met - run Lighthouse audit
+3. HTTPS required (except localhost)
+4. Service worker may not be registered - check DevTools > Application > Service Workers
+
+### Service Worker Not Updating
+
+1. In DevTools > Application > Service Workers
+2. Check "Update on reload"
+3. Click "Unregister" and reload page
+4. Or use "Skip waiting" button
+
+### Icons Not Loading
+
+1. Verify icons exist: `ls frontend/public/icon-*.png`
+2. Regenerate if needed: `node frontend/generate-icons.js`
+3. Check manifest.json paths match icon filenames
+4. Clear cache and reinstall app
+
+### Manifest Not Found
+
+1. Check that manifest.json exists in `frontend/public/`
+2. Verify build output includes public files
+3. Check browser console for 404 errors
+4. Ensure `manifest: "/manifest.json"` in layout.tsx
+
+### App Not Working Offline
+
+1. Service worker must be active (check DevTools)
+2. Visit pages while online first to cache them
+3. API calls require cached responses or fallbacks
+4. Check offline.html is in public directory
+
+## Production Deployment
+
+### Important Considerations
+
+1. **HTTPS Required**
+   - PWAs require HTTPS (except localhost)
+   - Ensure your production server has valid SSL certificate
+
+2. **Cache Updates**
+   - Service worker updates automatically on new deployments
+   - Users get updates when they close and reopen the app
+
+3. **Environment Variables**
+   - `NODE_ENV=production` enables PWA features
+   - `API_URL` must be set correctly for your deployment
+
+4. **Docker Deployment**
+   - PWA files are included in the standalone build
+   - Icons and manifest are served from the public directory
+   - No additional configuration needed
+
+## Next Steps
+
+### Optional Enhancements
+
+1. **Push Notifications**
+   - Add web push notification support
+   - Requires backend integration for push subscriptions
+
+2. **Background Sync**
+   - Queue API requests when offline
+   - Sync when connection is restored
+
+3. **Share Target API**
+   - Allow sharing content to Open Notebook from other apps
+   - Add to manifest.json
+
+4. **App Shortcuts**
+   - Already configured in manifest
+   - Can add more shortcuts for quick actions
+
+5. **Screenshots**
+   - Add app screenshots to manifest
+   - Improves install prompt on some platforms
+
+## Resources
+
+- [PWA Documentation](https://web.dev/progressive-web-apps/)
+- [next-pwa GitHub](https://github.com/shadowwalker/next-pwa)
+- [Workbox Documentation](https://developers.google.com/web/tools/workbox)
+- [Manifest Generator](https://www.simicart.com/manifest-generator.html/)
+- [PWA Testing Tools](https://www.pwabuilder.com/)
+
+## Support
+
+For issues specific to Open Notebook PWA:
+- Check browser console for errors
+- Run Lighthouse audit for PWA compliance
+- Verify service worker is active
+- Test on different devices and browsers
+
+---
+
+**Implementation Date:** October 28, 2025
+**Implemented By:** Claude Code Assistant
+**Status:** ✅ Complete and Ready for Testing

README.md

@@ -1,13 +1,455 @@
+<a id="readme-top"></a>
+
+<!-- [![Contributors][contributors-shield]][contributors-url] -->
+[![Forks][forks-shield]][forks-url]
+[![Stargazers][stars-shield]][stars-url]
+[![Issues][issues-shield]][issues-url]
+[![MIT License][license-shield]][license-url]
+<!-- [![LinkedIn][linkedin-shield]][linkedin-url] -->
+
+
+<!-- PROJECT LOGO -->
+<br />
+<div align="center">
+  <a href="https://github.com/lfnovo/open-notebook">
+    <img src="docs/assets/hero.svg" alt="Logo">
+  </a>
+
+  <h3 align="center">Open Notebook</h3>
+
+  <p align="center">
+    An open source, privacy-focused alternative to Google's Notebook LM!
+    <br /><strong>Join our <a href="https://discord.gg/37XJPXfz2w">Discord server</a> for help, to share workflow ideas, and suggest features!</strong>
+    <br />
+    <a href="https://www.open-notebook.ai"><strong>Checkout our website »</strong></a>
+    <br />
+    <br />
+    <a href="docs/getting-started/index.md">📚 Get Started</a>
+    ·
+    <a href="docs/user-guide/index.md">📖 User Guide</a>
+    ·
+    <a href="docs/features/index.md">✨ Features</a>
+    ·
+    <a href="docs/deployment/index.md">🚀 Deploy</a>
+  </p>
+</div>
+
+<div align="center">
+  <!-- Keep these links. Translations will automatically update with the README. -->
+  <a href="https://zdoc.app/de/lfnovo/open-notebook">Deutsch</a> | 
+  <a href="https://zdoc.app/es/lfnovo/open-notebook">Español</a> | 
+  <a href="https://zdoc.app/fr/lfnovo/open-notebook">français</a> | 
+  <a href="https://zdoc.app/ja/lfnovo/open-notebook">日本語</a> | 
+  <a href="https://zdoc.app/ko/lfnovo/open-notebook">한국어</a> | 
+  <a href="https://zdoc.app/pt/lfnovo/open-notebook">Português</a> | 
+  <a href="https://zdoc.app/ru/lfnovo/open-notebook">Русский</a> | 
+  <a href="https://zdoc.app/zh/lfnovo/open-notebook">中文</a>
+</div>
+
+## A private, multi-model, 100% local, full-featured alternative to Notebook LM
+
+![New Notebook](docs/assets/asset_list.png)
+
+In a world dominated by Artificial Intelligence, having the ability to think 🧠 and acquire new knowledge 💡, is a skill that should not be a privilege for a few, nor restricted to a single provider.
+
+**Open Notebook empowers you to:**
+- 🔒 **Control your data** - Keep your research private and secure
+- 🤖 **Choose your AI models** - Support for 16+ providers including OpenAI, Anthropic, Ollama, LM Studio, and more
+- 📚 **Organize multi-modal content** - PDFs, videos, audio, web pages, and more
+- 🎙️ **Generate professional podcasts** - Advanced multi-speaker podcast generation
+- 🔍 **Search intelligently** - Full-text and vector search across all your content
+- 💬 **Chat with context** - AI conversations powered by your research
+
+Learn more about our project at [https://www.open-notebook.ai](https://www.open-notebook.ai)
+
 ---
-title: OpenNotebook
-emoji: 📚
-colorFrom: red
-colorTo: indigo
-sdk: gradio
-sdk_version: 5.49.1
-app_file: app.py
-pinned: false
-short_description: 'Notebook LM '
+
+## ⚠️ IMPORTANT: v1.0 Breaking Changes
+
+**If you're upgrading from a previous version**, please note:
+
+- 🏷️ **Docker tags have changed**: The `latest` tag is now **frozen** at the last Streamlit version
+- 🆕 **Use `v1-latest` tag** for the new React/Next.js version (recommended)
+- 🔌 **Port 5055 required**: You must expose port 5055 for the API to work
+- 📖 **Read the migration guide**: See [MIGRATION.md](MIGRATION.md) for detailed upgrade instructions
+
+**New users**: You can ignore this notice and proceed with the Quick Start below using the `v1-latest-single` tag.
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## 🆚 Open Notebook vs Google Notebook LM
+
+| Feature | Open Notebook | Google Notebook LM | Advantage |
+|---------|---------------|--------------------|-----------|
+| **Privacy & Control** | Self-hosted, your data | Google cloud only | Complete data sovereignty |
+| **AI Provider Choice** | 16+ providers (OpenAI, Anthropic, Ollama, LM Studio, etc.) | Google models only | Flexibility and cost optimization |
+| **Podcast Speakers** | 1-4 speakers with custom profiles | 2 speakers only | Extreme flexibility |
+| **Context Control** | 3 granular levels | All-or-nothing | Privacy and performance tuning |
+| **Content Transformations** | Custom and built-in | Limited options | Unlimited processing power |
+| **API Access** | Full REST API | No API | Complete automation |
+| **Deployment** | Docker, cloud, or local | Google hosted only | Deploy anywhere |
+| **Citations** | Comprehensive with sources | Basic references | Research integrity |
+| **Customization** | Open source, fully customizable | Closed system | Unlimited extensibility |
+| **Cost** | Pay only for AI usage | Monthly subscription + usage | Transparent and controllable |
+
+**Why Choose Open Notebook?**
+- 🔒 **Privacy First**: Your sensitive research stays completely private
+- 💰 **Cost Control**: Choose cheaper AI providers or run locally with Ollama
+- 🎙️ **Better Podcasts**: Full script control and multi-speaker flexibility vs limited 2-speaker deep-dive format
+- 🔧 **Unlimited Customization**: Modify, extend, and integrate as needed
+- 🌐 **No Vendor Lock-in**: Switch providers, deploy anywhere, own your data
+
+### Built With
+
+[![Python][Python]][Python-url] [![Next.js][Next.js]][Next-url] [![React][React]][React-url] [![SurrealDB][SurrealDB]][SurrealDB-url] [![LangChain][LangChain]][LangChain-url]
+
+## 🚀 Quick Start
+
+**Docker Images Available:**
+- **Docker Hub**: `lfnovo/open_notebook:v1-latest-single`
+- **GitHub Container Registry**: `ghcr.io/lfnovo/open-notebook:v1-latest-single`
+
+Both registries contain identical images - choose whichever you prefer!
+
+### Choose Your Setup:
+
+<table>
+<tr>
+<td width="50%">
+
+#### 🏠 **Local Machine Setup**
+Perfect if Docker runs on the **same computer** where you'll access Open Notebook.
+
+```bash
+mkdir open-notebook && cd open-notebook
+
+docker run -d \
+  --name open-notebook \
+  -p 8502:8502 -p 5055:5055 \
+  -v ./notebook_data:/app/data \
+  -v ./surreal_data:/mydata \
+  -e OPENAI_API_KEY=your_key_here \
+  -e SURREAL_URL="ws://localhost:8000/rpc" \
+  -e SURREAL_USER="root" \
+  -e SURREAL_PASSWORD="root" \
+  -e SURREAL_NAMESPACE="open_notebook" \
+  -e SURREAL_DATABASE="production" \
+  lfnovo/open_notebook:v1-latest-single
+```
+
+**Access at:** http://localhost:8502
+
+</td>
+<td width="50%">
+
+#### 🌐 **Remote Server Setup**
+Use this for servers, Raspberry Pi, NAS, Proxmox, or any remote machine.
+
+```bash
+mkdir open-notebook && cd open-notebook
+
+docker run -d \
+  --name open-notebook \
+  -p 8502:8502 -p 5055:5055 \
+  -v ./notebook_data:/app/data \
+  -v ./surreal_data:/mydata \
+  -e OPENAI_API_KEY=your_key_here \
+  -e API_URL=http://YOUR_SERVER_IP:5055 \
+  -e SURREAL_URL="ws://localhost:8000/rpc" \
+  -e SURREAL_USER="root" \
+  -e SURREAL_PASSWORD="root" \
+  -e SURREAL_NAMESPACE="open_notebook" \
+  -e SURREAL_DATABASE="production" \
+  lfnovo/open_notebook:v1-latest-single
+```
+
+**Replace `YOUR_SERVER_IP`** with your server's IP (e.g., `192.168.1.100`) or domain
+
+**Access at:** http://YOUR_SERVER_IP:8502
+
+</td>
+</tr>
+</table>
+
+> **⚠️ Critical Setup Notes:**
+>
+> **Both ports are required:**
+> - **Port 8502**: Web interface (what you see in your browser)
+> - **Port 5055**: API backend (required for the app to function)
+>
+> **API_URL must match how YOU access the server:**
+> - ✅ Access via `http://192.168.1.100:8502` → set `API_URL=http://192.168.1.100:5055`
+> - ✅ Access via `http://myserver.local:8502` → set `API_URL=http://myserver.local:5055`
+> - ❌ Don't use `localhost` for remote servers - it won't work from other devices!
+
+### Using Docker Compose (Recommended for Easy Management)
+
+Create a `docker-compose.yml` file:
+
+```yaml
+services:
+  open_notebook:
+    image: lfnovo/open_notebook:v1-latest-single
+    # Or use: ghcr.io/lfnovo/open-notebook:v1-latest-single
+    ports:
+      - "8502:8502"  # Web UI
+      - "5055:5055"  # API (required!)
+    environment:
+      - OPENAI_API_KEY=your_key_here
+      # For remote access, uncomment and set your server IP/domain:
+      # - API_URL=http://192.168.1.100:5055
+      # Database connection (required for single-container)
+      - SURREAL_URL=ws://localhost:8000/rpc
+      - SURREAL_USER=root
+      - SURREAL_PASSWORD=root
+      - SURREAL_NAMESPACE=open_notebook
+      - SURREAL_DATABASE=production
+    volumes:
+      - ./notebook_data:/app/data
+      - ./surreal_data:/mydata
+    restart: always
+```
+
+Start with: `docker compose up -d`
+
+**What gets created:**
+```
+open-notebook/
+├── docker-compose.yml # Your configuration
+├── notebook_data/     # Your notebooks and research content
+└── surreal_data/      # Database files
+```
+
+### 🆘 Quick Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| **"Unable to connect to server"** | Set `API_URL` environment variable to match how you access the server (see remote setup above) |
+| **Blank page or errors** | Ensure BOTH ports (8502 and 5055) are exposed in your docker command |
+| **Works on server but not from other computers** | Don't use `localhost` in `API_URL` - use your server's actual IP address |
+| **"404" or "config endpoint" errors** | Don't add `/api` to `API_URL` - use just `http://your-ip:5055` |
+| **Still having issues?** | Check our [5-minute troubleshooting guide](docs/troubleshooting/quick-fixes.md) or [join Discord](https://discord.gg/37XJPXfz2w) |
+
+### How Open Notebook Works
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Your Browser                                           │
+│  Access: http://your-server-ip:8502                     │
+└────────────────┬────────────────────────────────────────┘
+                 │
+                 ▼
+         ┌───────────────┐
+         │   Port 8502   │  ← Next.js Frontend (what you see)
+         │   Frontend    │    Also proxies API requests internally!
+         └───────┬───────┘
+                 │ proxies /api/* requests ↓
+                 ▼
+         ┌───────────────┐
+         │   Port 5055   │  ← FastAPI Backend (handles requests)
+         │     API       │
+         └───────┬───────┘
+                 │
+                 ▼
+         ┌───────────────┐
+         │   SurrealDB   │  ← Database (internal, auto-configured)
+         │   (Port 8000) │
+         └───────────────┘
+```
+
+**Key Points:**
+- **v1.1+**: Next.js automatically proxies `/api/*` requests to the backend, simplifying reverse proxy setup
+- Your browser loads the frontend from port 8502
+- The frontend needs to know where to find the API - when accessing remotely, set: `API_URL=http://your-server-ip:5055`
+- **Behind reverse proxy?** You only need to proxy to port 8502 now! See [Reverse Proxy Guide](docs/deployment/reverse-proxy.md)
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=lfnovo/open-notebook&type=date&legend=top-left)](https://www.star-history.com/#lfnovo/open-notebook&type=date&legend=top-left)
+
+### 🛠️ Full Installation
+For development or customization:
+```bash
+git clone https://github.com/lfnovo/open-notebook
+cd open-notebook
+make start-all
+```
+
+### 📖 Need Help?
+- **🤖 AI Installation Assistant**: We have a [CustomGPT built to help you install Open Notebook](https://chatgpt.com/g/g-68776e2765b48191bd1bae3f30212631-open-notebook-installation-assistant) - it will guide you through each step!
+- **New to Open Notebook?** Start with our [Getting Started Guide](docs/getting-started/index.md)
+- **Need installation help?** Check our [Installation Guide](docs/getting-started/installation.md)
+- **Want to see it in action?** Try our [Quick Start Tutorial](docs/getting-started/quick-start.md)
+
+## Provider Support Matrix
+
+Thanks to the [Esperanto](https://github.com/lfnovo/esperanto) library, we support this providers out of the box!
+
+| Provider     | LLM Support | Embedding Support | Speech-to-Text | Text-to-Speech |
+|--------------|-------------|------------------|----------------|----------------|
+| OpenAI       | ✅          | ✅               | ✅             | ✅             |
+| Anthropic    | ✅          | ❌               | ❌             | ❌             |
+| Groq         | ✅          | ❌               | ✅             | ❌             |
+| Google (GenAI) | ✅          | ✅               | ❌             | ✅             |
+| Vertex AI    | ✅          | ✅               | ❌             | ✅             |
+| Ollama       | ✅          | ✅               | ❌             | ❌             |
+| Perplexity   | ✅          | ❌               | ❌             | ❌             |
+| ElevenLabs   | ❌          | ❌               | ✅             | ✅             |
+| Azure OpenAI | ✅          | ✅               | ❌             | ❌             |
+| Mistral      | ✅          | ✅               | ❌             | ❌             |
+| DeepSeek     | ✅          | ❌               | ❌             | ❌             |
+| Voyage       | ❌          | ✅               | ❌             | ❌             |
+| xAI          | ✅          | ❌               | ❌             | ❌             |
+| OpenRouter   | ✅          | ❌               | ❌             | ❌             |
+| OpenAI Compatible* | ✅          | ❌               | ❌             | ❌             |
+
+*Supports LM Studio and any OpenAI-compatible endpoint
+
+## ✨ Key Features
+
+### Core Capabilities
+- **🔒 Privacy-First**: Your data stays under your control - no cloud dependencies
+- **🎯 Multi-Notebook Organization**: Manage multiple research projects seamlessly
+- **📚 Universal Content Support**: PDFs, videos, audio, web pages, Office docs, and more
+- **🤖 Multi-Model AI Support**: 16+ providers including OpenAI, Anthropic, Ollama, Google, LM Studio, and more
+- **🎙️ Professional Podcast Generation**: Advanced multi-speaker podcasts with Episode Profiles
+- **🔍 Intelligent Search**: Full-text and vector search across all your content
+- **💬 Context-Aware Chat**: AI conversations powered by your research materials
+- **📝 AI-Assisted Notes**: Generate insights or write notes manually
+
+### Advanced Features
+- **⚡ Reasoning Model Support**: Full support for thinking models like DeepSeek-R1 and Qwen3
+- **🔧 Content Transformations**: Powerful customizable actions to summarize and extract insights
+- **🌐 Comprehensive REST API**: Full programmatic access for custom integrations [![API Docs](https://img.shields.io/badge/API-Documentation-blue?style=flat-square)](http://localhost:5055/docs)
+- **🔐 Optional Password Protection**: Secure public deployments with authentication
+- **📊 Fine-Grained Context Control**: Choose exactly what to share with AI models
+- **📎 Citations**: Get answers with proper source citations
+
+### Three-Column Interface
+1. **Sources**: Manage all your research materials
+2. **Notes**: Create manual or AI-generated notes
+3. **Chat**: Converse with AI using your content as context
+
+[![Check out our podcast sample](https://img.youtube.com/vi/D-760MlGwaI/0.jpg)](https://www.youtube.com/watch?v=D-760MlGwaI)
+
+## 📚 Documentation
+
+### Getting Started
+- **[📖 Introduction](docs/getting-started/introduction.md)** - Learn what Open Notebook offers
+- **[⚡ Quick Start](docs/getting-started/quick-start.md)** - Get up and running in 5 minutes
+- **[🔧 Installation](docs/getting-started/installation.md)** - Comprehensive setup guide
+- **[🎯 Your First Notebook](docs/getting-started/first-notebook.md)** - Step-by-step tutorial
+
+### User Guide
+- **[📱 Interface Overview](docs/user-guide/interface-overview.md)** - Understanding the layout
+- **[📚 Notebooks](docs/user-guide/notebooks.md)** - Organizing your research
+- **[📄 Sources](docs/user-guide/sources.md)** - Managing content types
+- **[📝 Notes](docs/user-guide/notes.md)** - Creating and managing notes
+- **[💬 Chat](docs/user-guide/chat.md)** - AI conversations
+- **[🔍 Search](docs/user-guide/search.md)** - Finding information
+
+### Advanced Topics
+- **[🎙️ Podcast Generation](docs/features/podcasts.md)** - Create professional podcasts
+- **[🔧 Content Transformations](docs/features/transformations.md)** - Customize content processing
+- **[🤖 AI Models](docs/features/ai-models.md)** - AI model configuration
+- **[🔧 REST API Reference](docs/development/api-reference.md)** - Complete API documentation
+- **[🔐 Security](docs/deployment/security.md)** - Password protection and privacy
+- **[🚀 Deployment](docs/deployment/index.md)** - Complete deployment guides for all scenarios
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## 🗺️ Roadmap
+
+### Upcoming Features
+- **Live Front-End Updates**: Real-time UI updates for smoother experience
+- **Async Processing**: Faster UI through asynchronous content processing
+- **Cross-Notebook Sources**: Reuse research materials across projects
+- **Bookmark Integration**: Connect with your favorite bookmarking apps
+
+### Recently Completed ✅
+- **Next.js Frontend**: Modern React-based frontend with improved performance
+- **Comprehensive REST API**: Full programmatic access to all functionality
+- **Multi-Model Support**: 16+ AI providers including OpenAI, Anthropic, Ollama, LM Studio
+- **Advanced Podcast Generator**: Professional multi-speaker podcasts with Episode Profiles
+- **Content Transformations**: Powerful customizable actions for content processing
+- **Enhanced Citations**: Improved layout and finer control for source citations
+- **Multiple Chat Sessions**: Manage different conversations within notebooks
+
+See the [open issues](https://github.com/lfnovo/open-notebook/issues) for a full list of proposed features and known issues.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+## 🤝 Community & Contributing
+
+### Join the Community
+- 💬 **[Discord Server](https://discord.gg/37XJPXfz2w)** - Get help, share ideas, and connect with other users
+- 🐛 **[GitHub Issues](https://github.com/lfnovo/open-notebook/issues)** - Report bugs and request features
+- ⭐ **Star this repo** - Show your support and help others discover Open Notebook
+
+### Contributing
+We welcome contributions! We're especially looking for help with:
+- **Frontend Development**: Help improve our modern Next.js/React UI
+- **Testing & Bug Fixes**: Make Open Notebook more robust
+- **Feature Development**: Build the coolest research tool together
+- **Documentation**: Improve guides and tutorials
+
+**Current Tech Stack**: Python, FastAPI, Next.js, React, SurrealDB
+**Future Roadmap**: Real-time updates, enhanced async processing
+
+See our [Contributing Guide](CONTRIBUTING.md) for detailed information on how to get started.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+## 📄 License
+
+Open Notebook is MIT licensed. See the [LICENSE](LICENSE) file for details.
+
+## 📞 Contact
+
+**Luis Novo** - [@lfnovo](https://twitter.com/lfnovo)
+
+**Community Support**:
+- 💬 [Discord Server](https://discord.gg/37XJPXfz2w) - Get help, share ideas, and connect with users
+- 🐛 [GitHub Issues](https://github.com/lfnovo/open-notebook/issues) - Report bugs and request features
+- 🌐 [Website](https://www.open-notebook.ai) - Learn more about the project
+
+## 🙏 Acknowledgments
+
+Open Notebook is built on the shoulders of amazing open-source projects:
+
+* **[Podcast Creator](https://github.com/lfnovo/podcast-creator)** - Advanced podcast generation capabilities
+* **[Surreal Commands](https://github.com/lfnovo/surreal-commands)** - Background job processing
+* **[Content Core](https://github.com/lfnovo/content-core)** - Content processing and management
+* **[Esperanto](https://github.com/lfnovo/esperanto)** - Multi-provider AI model abstraction
+* **[Docling](https://github.com/docling-project/docling)** - Document processing and parsing
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+<!-- MARKDOWN LINKS & IMAGES -->
+<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
+[contributors-shield]: https://img.shields.io/github/contributors/lfnovo/open-notebook.svg?style=for-the-badge
+[contributors-url]: https://github.com/lfnovo/open-notebook/graphs/contributors
+[forks-shield]: https://img.shields.io/github/forks/lfnovo/open-notebook.svg?style=for-the-badge
+[forks-url]: https://github.com/lfnovo/open-notebook/network/members
+[stars-shield]: https://img.shields.io/github/stars/lfnovo/open-notebook.svg?style=for-the-badge
+[stars-url]: https://github.com/lfnovo/open-notebook/stargazers
+[issues-shield]: https://img.shields.io/github/issues/lfnovo/open-notebook.svg?style=for-the-badge
+[issues-url]: https://github.com/lfnovo/open-notebook/issues
+[license-shield]: https://img.shields.io/github/license/lfnovo/open-notebook.svg?style=for-the-badge
+[license-url]: https://github.com/lfnovo/open-notebook/blob/master/LICENSE.txt
+[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
+[linkedin-url]: https://linkedin.com/in/lfnovo
+[product-screenshot]: images/screenshot.png
+[Next.js]: https://img.shields.io/badge/Next.js-000000?style=for-the-badge&logo=next.js&logoColor=white
+[Next-url]: https://nextjs.org/
+[React]: https://img.shields.io/badge/React-61DAFB?style=for-the-badge&logo=react&logoColor=black
+[React-url]: https://reactjs.org/
+[Python]: https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white
+[Python-url]: https://www.python.org/
+[LangChain]: https://img.shields.io/badge/LangChain-3A3A3A?style=for-the-badge&logo=chainlink&logoColor=white
+[LangChain-url]: https://www.langchain.com/
+[SurrealDB]: https://img.shields.io/badge/SurrealDB-FF5E00?style=for-the-badge&logo=databricks&logoColor=white
+[SurrealDB-url]: https://surrealdb.com/

batch_fix_services.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Batch fix service files for mypy errors."""
+import re
+from pathlib import Path
+
+SERVICE_FILES = [
+    'api/notes_service.py',
+    'api/insights_service.py',
+    'api/episode_profiles_service.py',
+    'api/settings_service.py',
+    'api/sources_service.py',
+    'api/podcast_service.py',
+    'api/command_service.py',
+]
+
+BASE_DIR = Path('/Users/luisnovo/dev/projetos/open-notebook/open-notebook')
+
+for service_file in SERVICE_FILES:
+    file_path = BASE_DIR / service_file
+    if not file_path.exists():
+        print(f"Skipping {service_file} - file not found")
+        continue
+
+    content = file_path.read_text()
+    original_content = content
+
+    # Pattern to find: var_name = api_client.method(args)
+    # Followed by: var_name["key"] or var_name.get("key")
+    lines = content.split('\n')
+    new_lines = []
+    i = 0
+
+    while i < len(lines):
+        line = lines[i]
+
+        # Check if this line has an api_client call assignment
+        match = re.match(r'(\s*)(\w+)\s*=\s*api_client\.(\w+)\((.*)\)\s*$', line)
+        if match and 'response = api_client' not in line:
+            indent = match.group(1)
+            var_name = match.group(2)
+            method_name = match.group(3)
+            args = match.group(4)
+
+            # Look ahead to see if this variable is used with dict access
+            has_dict_access = False
+            for j in range(i+1, min(i+15, len(lines))):
+                next_line = lines[j]
+                if f'{var_name}["' in next_line or f"{var_name}['" in next_line or f'{var_name}.get(' in next_line:
+                    has_dict_access = True
+                    break
+                # Stop looking if we hit a blank line, new function, or new assignment
+                if (not next_line.strip() or
+                    next_line.strip().startswith('def ') or
+                    next_line.strip().startswith('class ') or
+                    (re.match(r'\s*\w+\s*=', next_line) and var_name not in next_line)):
+                    break
+
+            if has_dict_access:
+                # Replace with response and isinstance check
+                new_lines.append(f'{indent}response = api_client.{method_name}({args})')
+                new_lines.append(f'{indent}{var_name} = response if isinstance(response, dict) else response[0]')
+                i += 1
+                continue
+
+        new_lines.append(line)
+        i += 1
+
+    new_content = '\n'.join(new_lines)
+
+    # Check if content changed
+    if new_content != original_content:
+        file_path.write_text(new_content)
+        print(f"✓ Fixed {service_file}")
+    else:
+        print(f"- No changes needed for {service_file}")
+
+print("\nDone!")

docker-compose.dev.yml

@@ -0,0 +1,26 @@
+services:
+  surrealdb:
+    image: surrealdb/surrealdb:v2
+    volumes:
+      - ./surreal_data:/mydata
+    environment:
+      - SURREAL_EXPERIMENTAL_GRAPHQL=true
+    command: start --log info --user root --pass root rocksdb:/mydata/mydatabase.db
+    pull_policy: always
+    user: root
+    restart: always
+  open_notebook:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8502:8502"
+      - "5055:5055"
+    env_file:
+      - ./docker.env
+    depends_on:
+      - surrealdb
+    volumes:
+      - ./notebook_data:/app/data
+    restart: always
+    

docker-compose.full.yml

@@ -0,0 +1,25 @@
+services:
+  surrealdb:
+    image: surrealdb/surrealdb:v2
+    volumes:
+      - ./surreal_data:/mydata
+    environment:
+      - SURREAL_EXPERIMENTAL_GRAPHQL=true
+    ports:
+      - "8000:8000"
+    command: start --log info --user root --pass root rocksdb:/mydata/mydatabase.db
+    pull_policy: always
+    user: root
+    restart: always
+  open_notebook:
+    image: lfnovo/open_notebook:v1-latest
+    ports:
+      - "8502:8502"
+      - "5055:5055"
+    env_file:
+      - ./docker.env
+    depends_on:
+      - surrealdb
+    volumes:
+      - ./notebook_data:/app/data
+    restart: always

docker-compose.single.yml

@@ -0,0 +1,20 @@
+services:
+  open_notebook_single:
+    # image: lfnovo/open_notebook:v1-latest-single
+    build:
+      context: .
+      dockerfile: Dockerfile.single
+    ports:
+      - "8502:8502"  # Next.js Frontend
+      - "5055:5055"  # REST API
+    env_file:
+      - ./docker.env
+    volumes:
+      - ./notebook_data:/app/data          # Application data
+      - ./surreal_single_data:/mydata      # SurrealDB data
+    restart: always
+    # Single container includes all services: SurrealDB, API, Worker, and Next.js Frontend
+    # Access:
+    # - Next.js UI: http://localhost:8502
+    # - REST API: http://localhost:5055
+    # - API Documentation: http://localhost:5055/docs

mypy.ini

@@ -0,0 +1,36 @@
+[mypy]
+# Only check for syntax errors, not type errors
+# This allows the codebase to gradually add type hints
+warn_return_any = False
+warn_unused_configs = True
+ignore_missing_imports = True
+no_implicit_optional = False
+check_untyped_defs = False
+check_untyped_defs = True
+explicit_package_bases = True
+mypy_path = .
+
+# Disable type checking for files with many errors
+[mypy-api.client]
+ignore_errors = True
+
+[mypy-api.podcast_api_service]
+ignore_errors = True
+
+[mypy-api.auth]
+ignore_errors = True
+
+[mypy-api.routers.models]
+ignore_errors = True
+
+[mypy-open_notebook.domain.base]
+ignore_errors = True
+
+[mypy-open_notebook.domain.notebook]
+ignore_errors = True
+
+[mypy-open_notebook.graphs.transformation]
+ignore_errors = True
+
+[mypy-open_notebook.graphs.ask]
+ignore_errors = True

pyproject.toml

@@ -0,0 +1,98 @@
+[project]
+name = "open-notebook"
+version = "1.1.1"
+description = "An open source implementation of a research assistant, inspired by Google Notebook LM"
+authors = [
+    {name = "Luis Novo", email = "lfnovo@gmail.com"}
+]
+readme = "README.md"
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+]
+requires-python = ">=3.11,<3.13"
+dependencies = [
+    "fastapi>=0.104.0",
+    "uvicorn>=0.24.0",
+    "pydantic>=2.9.2",
+    "loguru>=0.7.2",
+    "langchain>=0.3.3",
+    "langgraph>=0.2.38",
+    "tiktoken>=0.8.0",
+    "langgraph-checkpoint-sqlite>=2.0.0",
+    "langchain-community>=0.3.3",
+    "langchain-openai>=0.2.3",
+    "langchain-anthropic>=0.2.3",
+    "langchain-ollama>=0.2.0",
+    "langchain-google-genai>=2.1.10",
+    "langchain-groq>=0.2.1",
+    "langchain_mistralai>=0.2.1",
+    "langchain_deepseek>=0.1.3",
+    "tomli>=2.0.2",
+    "groq>=0.12.0",
+    "python-dotenv>=1.0.1",
+    "httpx[socks]>=0.27.0",
+    "content-core>=1.0.2",
+    "ai-prompter>=0.3",
+    "esperanto>=2.4.1",
+    "langchain-google-vertexai>=2.0.28",
+    "surrealdb>=1.0.4",
+    "surreal-commands>=1.0.13",
+    "podcast-creator>=0.7.0",
+]
+
+[tool.setuptools]
+package-dir = {"open_notebook" = "open_notebook"}
+
+
+[project.optional-dependencies]
+dev = [
+    "ipykernel>=6.29.5",
+    "ruff>=0.5.5",
+    "mypy>=1.11.1",
+    "types-requests>=2.32.0.20241016",
+    "ipywidgets>=8.1.5",
+    "pre-commit>=4.0.1",
+    "pytest>=8.0.0",
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.1.0",
+    "pytest-asyncio>=1.2.0",
+    "types-requests>=2.32.4.20250913",
+]
+
+[tool.isort]
+profile = "black"
+line_length = 88
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = [
+    "E501",  # line too long
+    "E402",  # module level import not at top of file (Streamlit requires this pattern)
+    "E722",  # do not use bare except (legacy code pattern)
+    "F401",  # imported but unused (may be used in type hints or re-exports)
+    "F541",  # f-string without placeholders
+    "F841",  # local variable assigned but never used
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Streamlit files need nest_asyncio.apply() before imports
+"app_home.py" = ["E402"]
+"pages/**/*.py" = ["E402"]
+
+[tool.mypy]
+# Exclude Streamlit UI pages from type checking
+[[tool.mypy.overrides]]
+module = "pages.*"
+ignore_errors = true

run_api.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""
+Startup script for Open Notebook API server.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+import uvicorn
+
+# Add the current directory to Python path so imports work
+current_dir = Path(__file__).parent
+sys.path.insert(0, str(current_dir))
+
+if __name__ == "__main__":
+    # Default configuration
+    host = os.getenv("API_HOST", "127.0.0.1")
+    port = int(os.getenv("API_PORT", "5055"))
+    reload = os.getenv("API_RELOAD", "true").lower() == "true"
+
+    print(f"Starting Open Notebook API server on {host}:{port}")
+    print(f"Reload mode: {reload}")
+
+    uvicorn.run(
+        "api.main:app",
+        host=host,
+        port=port,
+        reload=reload,
+        reload_dirs=[str(current_dir)] if reload else None,
+    )

supervisord.conf

@@ -0,0 +1,40 @@
+[supervisord]
+nodaemon=true
+logfile=/dev/stdout
+logfile_maxbytes=0
+pidfile=/tmp/supervisord.pid
+
+[program:api]
+command=uv run uvicorn api.main:app --host 0.0.0.0 --port 5055
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+autorestart=true
+priority=10
+autostart=true
+
+[program:worker]
+command=uv run surreal-commands-worker --import-modules commands
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+autorestart=true
+priority=20
+autostart=true
+startsecs=3
+
+[program:frontend]
+command=bash -c "sleep 5 && npm run start"
+directory=/app/frontend
+environment=NODE_ENV="production",PORT="8502"
+passenv=API_URL,NEXT_PUBLIC_API_URL,INTERNAL_API_URL
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+autorestart=true
+priority=30
+autostart=true
+startsecs=5

supervisord.single.conf

@@ -0,0 +1,52 @@
+[supervisord]
+nodaemon=true
+logfile=/dev/stdout
+logfile_maxbytes=0
+pidfile=/tmp/supervisord.pid
+
+[program:surrealdb]
+command=surreal start --log trace --user root --pass root rocksdb:/mydata/mydatabase.db
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+autorestart=true
+priority=5
+autostart=true
+startsecs=5
+
+[program:api]
+command=uv run uvicorn api.main:app --host 0.0.0.0 --port 5055
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+autorestart=true
+priority=10
+autostart=true
+startsecs=3
+
+[program:worker]
+command=uv run surreal-commands-worker --import-modules commands
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+autorestart=true
+priority=20
+autostart=true
+startsecs=3
+
+[program:frontend]
+command=bash -c "sleep 5 && npm run start"
+directory=/app/frontend
+environment=NODE_ENV="production",PORT="8502"
+passenv=API_URL,NEXT_PUBLIC_API_URL,INTERNAL_API_URL
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+autorestart=true
+priority=30
+autostart=true
+startsecs=5