Several hotfixes (#130)

* fix: prevent project failing to start when cannot talk to github - fixes #128 * improve ollama documentation - see #127 * chore: update esperanto library to enable gpt-5 - see #107; update podcast-creator library to enable TTS_BATCH_SIZE - fixes #125 * add info on ollama env variables * chore: ignore dev logs * chore: bump
2025-09-14 10:58:16 -03:00 · 2025-09-14 10:58:16 -03:00 · fa27fe561a
commit fa27fe561a
parent dcef3751cc
7 changed files with 2449 additions and 1496 deletions
--- a/.gitignore
+++ b/.gitignore
@ -122,4 +122,4 @@ desktop.ini

 .quarentena

-.claude/logs
+**/claude-logs
--- a/docs/features/ai-models.md
+++ b/docs/features/ai-models.md
@ -25,7 +25,7 @@ export OPENAI_API_KEY=your_key_here
 # Environment variables
 export OPENAI_API_KEY=your_key
 export GEMINI_API_KEY=your_key
-export OLLAMA_BASE_URL=http://localhost:11434
+export OLLAMA_API_BASE=http://localhost:11434

 # Recommended configuration in settings covered below
 ```
@ -180,8 +180,8 @@ export ANTHROPIC_API_KEY=your_api_key_here
 # Install Ollama locally
 curl -fsSL https://ollama.ai/install.sh | sh

-# Set base URL (if running remotely)
-export OLLAMA_BASE_URL=http://localhost:11434
+# Set API base (if running remotely)
+export OLLAMA_API_BASE=http://localhost:11434
 ```

 **Recommended Models**
@ -199,6 +199,8 @@ export OLLAMA_BASE_URL=http://localhost:11434
 - Limited model variety compared to cloud providers
 - No TTS/STT capabilities

+> **📖 Need detailed Ollama setup help?** Check our comprehensive [Ollama Setup Guide](ollama.md) for network configuration, Docker deployment, troubleshooting, and optimization tips.
+
 ---

 ### 🎤 ElevenLabs
@ -390,7 +392,7 @@ Open Notebook fully supports **reasoning models** that show their transparent th
 # Environment Variables
 export OPENAI_API_KEY=your_key
 export GEMINI_API_KEY=your_key
-export OLLAMA_BASE_URL=http://localhost:11434
+export OLLAMA_API_BASE=http://localhost:11434
 ```

 | Model Default | Recommended Model | Provider |
@ -413,7 +415,7 @@ export OLLAMA_BASE_URL=http://localhost:11434
 ```bash
 # Environment Variables
 export OPENAI_API_KEY=your_key  # For STT/TTS only
-export OLLAMA_BASE_URL=http://localhost:11434
+export OLLAMA_API_BASE=http://localhost:11434
 ```

 | Model Default | Recommended Model | Provider |
@ -503,7 +505,7 @@ export ELEVENLABS_API_KEY=your_key
 export VOYAGE_API_KEY=your_key

 # Local/Cloud Infrastructure
-export OLLAMA_BASE_URL=http://localhost:11434
+export OLLAMA_API_BASE=http://localhost:11434

 # Azure OpenAI
 export AZURE_OPENAI_API_KEY=your_key
@ -581,8 +583,8 @@ curl -fsSL https://ollama.ai/install.sh | sh
 ollama pull qwen3
 ollama pull mxbai-embed-large

-# Set base URL if remote
-export OLLAMA_BASE_URL=http://your-server:11434
+# Set API base if remote
+export OLLAMA_API_BASE=http://your-server:11434
 ```

 #### ElevenLabs
--- a/docs/features/ollama.md
+++ b/docs/features/ollama.md
@ -0,0 +1,588 @@
+# Ollama Setup Guide
+
+Ollama provides free, local AI models that run on your own hardware. This guide covers everything you need to know about setting up Ollama with Open Notebook, including different deployment scenarios and network configurations.
+
+## Why Choose Ollama?
+
+- **🆓 Completely Free**: No API costs after initial setup
+- **🔒 Full Privacy**: Your data never leaves your local network
+- **📱 Offline Capable**: Works without internet connection
+- **🚀 Fast**: Local inference with no network latency
+- **🧠 Reasoning Models**: Support for advanced reasoning models like DeepSeek-R1
+- **💾 Model Variety**: Access to hundreds of open-source models
+
+## Quick Start
+
+### 1. Install Ollama
+
+**Linux/macOS:**
+```bash
+curl -fsSL https://ollama.ai/install.sh | sh
+```
+
+**Windows:**
+Download and install from [ollama.ai](https://ollama.ai/download)
+
+### 2. Pull Required Models
+
+```bash
+# Language models (choose one or more)
+ollama pull qwen3              # Excellent general purpose, 7B parameters
+ollama pull gemma3            # Google's model, good performance
+ollama pull deepseek-r1       # Advanced reasoning model
+ollama pull phi4              # Microsoft's efficient model
+
+# Embedding model (required for search)
+ollama pull mxbai-embed-large  # Best embedding model for Ollama
+```
+
+### 3. Configure Open Notebook
+
+**For local installation:**
+```bash
+export OLLAMA_API_BASE=http://localhost:11434
+```
+
+**For Docker installation:**
+```bash
+export OLLAMA_API_BASE=http://host.docker.internal:11434
+```
+
+## Network Configuration Guide
+
+The `OLLAMA_API_BASE` environment variable tells Open Notebook where to find your Ollama server. The correct value depends on your deployment scenario:
+
+### Scenario 1: Local Installation (Same Machine)
+
+When both Open Notebook and Ollama run directly on your machine:
+
+```bash
+export OLLAMA_API_BASE=http://localhost:11434
+# or
+export OLLAMA_API_BASE=http://127.0.0.1:11434
+```
+
+**Use `localhost` vs `127.0.0.1`:**
+- **localhost**: Recommended, works with most configurations
+- **127.0.0.1**: Use if you have DNS resolution issues with localhost
+
+### Scenario 2: Open Notebook in Docker, Ollama on Host
+
+When Open Notebook runs in Docker but Ollama runs on your host machine:
+
+```bash
+export OLLAMA_API_BASE=http://host.docker.internal:11434
+```
+
+**⚠️ CRITICAL: Ollama must accept external connections:**
+```bash
+# Start Ollama with external access enabled
+export OLLAMA_HOST=0.0.0.0:11434
+ollama serve
+```
+
+**Why `host.docker.internal`?**
+- Docker containers can't reach `localhost` on the host
+- `host.docker.internal` is Docker's special hostname for the host machine
+- Available on Docker Desktop for Mac/Windows and recent Linux versions
+
+**Why `OLLAMA_HOST=0.0.0.0:11434`?**
+- By default, Ollama only binds to localhost and rejects external connections
+- Docker containers are considered "external" even when running on the same machine
+- Setting `OLLAMA_HOST=0.0.0.0:11434` allows connections from Docker containers
+
+### Scenario 3: Both in Docker (Same Compose)
+
+When both Open Notebook and Ollama run in the same Docker Compose stack:
+
+```bash
+export OLLAMA_API_BASE=http://ollama:11434
+```
+
+**Docker Compose Example:**
+
+```yaml
+version: '3.8'
+services:
+  open-notebook:
+    image: lfnovo/open_notebook:latest-single
+    ports:
+      - "8502:8502"
+      - "5055:5055"
+    environment:
+      - OLLAMA_API_BASE=http://ollama:11434
+    volumes:
+      - ./notebook_data:/app/data
+      - ./surreal_data:/mydata
+    depends_on:
+      - ollama
+
+  ollama:
+    image: ollama/ollama:latest
+    ports:
+      - "11434:11434"
+    volumes:
+      - ollama_data:/root/.ollama
+    # Optional: GPU support
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
+
+volumes:
+  ollama_data:
+```
+
+### Scenario 4: Remote Ollama Server
+
+When Ollama runs on a different machine in your network:
+
+```bash
+export OLLAMA_API_BASE=http://192.168.1.100:11434
+# Replace 192.168.1.100 with your Ollama server's IP address
+```
+
+**Security Note:** Only use this in trusted networks. Ollama doesn't have built-in authentication.
+
+### Scenario 5: Ollama with Custom Port
+
+If you've configured Ollama to use a different port:
+
+```bash
+# Start Ollama on custom port
+OLLAMA_HOST=0.0.0.0:8080 ollama serve
+
+# Configure Open Notebook
+export OLLAMA_API_BASE=http://localhost:8080
+```
+
+## Model Recommendations
+
+### Language Models
+
+| Model | Size | Best For | Quality | Speed |
+|-------|------|----------|---------|-------|
+| **qwen3** | 7B | General purpose, coding | Excellent | Fast |
+| **deepseek-r1** | 7B | Reasoning, problem-solving | Exceptional | Medium |
+| **gemma3** | 7B | Balanced performance | Very Good | Fast |
+| **phi4** | 14B | Efficiency on small hardware | Good | Very Fast |
+| **llama3** | 8B | General purpose | Very Good | Medium |
+
+### Embedding Models
+
+| Model | Best For | Performance |
+|-------|----------|-------------|
+| **mxbai-embed-large** | General search | Excellent |
+| **nomic-embed-text** | Document similarity | Good |
+| **all-minilm** | Lightweight option | Fair |
+
+### Installation Commands
+
+```bash
+# Essential models
+ollama pull qwen3                 # Primary language model
+ollama pull mxbai-embed-large     # Search embeddings
+
+# Optional reasoning model
+ollama pull deepseek-r1           # Advanced reasoning
+
+# Alternative language models
+ollama pull gemma3                # Google's model
+ollama pull phi4                  # Microsoft's efficient model
+```
+
+## Hardware Requirements
+
+### Minimum Requirements
+- **RAM**: 8GB (for 7B models)
+- **Storage**: 10GB free space per model
+- **CPU**: Modern multi-core processor
+
+### Recommended Setup
+- **RAM**: 16GB+ (for multiple models)
+- **Storage**: SSD with 50GB+ free space
+- **GPU**: NVIDIA GPU with 8GB+ VRAM (optional but faster)
+
+### GPU Acceleration
+
+**NVIDIA GPU (CUDA):**
+```bash
+# Install NVIDIA Container Toolkit for Docker
+# Then use the Docker Compose example above with GPU support
+
+# For local installation, Ollama auto-detects CUDA
+ollama pull qwen3
+```
+
+**Apple Silicon (M1/M2/M3):**
+```bash
+# Ollama automatically uses Metal acceleration
+# No additional setup required
+ollama pull qwen3
+```
+
+**AMD GPUs:**
+```bash
+# ROCm support varies by model and system
+# Check Ollama documentation for latest compatibility
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**1. "Ollama unavailable" in Open Notebook**
+
+**Check Ollama is running:**
+```bash
+curl http://localhost:11434/api/tags
+```
+
+**Verify environment variable:**
+```bash
+echo $OLLAMA_API_BASE
+```
+
+**⚠️ IMPORTANT: Enable external connections (most common fix):**
+```bash
+# If Open Notebook runs in Docker or on a different machine,
+# Ollama must bind to all interfaces, not just localhost
+export OLLAMA_HOST=0.0.0.0:11434
+ollama serve
+```
+> **Why this is needed:** By default, Ollama only accepts connections from `localhost` (127.0.0.1). When Open Notebook runs in Docker or on a different machine, it can't reach Ollama unless you configure `OLLAMA_HOST=0.0.0.0:11434` to accept external connections.
+
+**Restart Ollama:**
+```bash
+# Linux/macOS
+sudo systemctl restart ollama
+# or
+ollama serve
+
+# Windows
+# Restart from system tray or Services
+```
+
+**2. Docker networking issues**
+
+**From inside Open Notebook container, test Ollama:**
+```bash
+# Get into container
+docker exec -it open-notebook bash
+
+# Test connection
+curl http://host.docker.internal:11434/api/tags
+```
+
+**3. Models not downloading**
+
+**Check disk space:**
+```bash
+df -h
+```
+
+**Manual model pull:**
+```bash
+ollama pull qwen3 --verbose
+```
+
+**Clear failed downloads:**
+```bash
+ollama rm qwen3
+ollama pull qwen3
+```
+
+**4. Slow performance**
+
+**Check model size vs available RAM:**
+```bash
+ollama ps  # Show running models
+free -h    # Check available memory
+```
+
+**Use smaller models:**
+```bash
+ollama pull phi4         # Instead of larger models
+ollama pull gemma3:2b   # 2B parameter variant
+```
+
+**5. Port conflicts**
+
+**Check what's using port 11434:**
+```bash
+lsof -i :11434
+netstat -tulpn | grep 11434
+```
+
+**Use custom port:**
+```bash
+OLLAMA_HOST=0.0.0.0:8080 ollama serve
+export OLLAMA_API_BASE=http://localhost:8080
+```
+
+### Docker-Specific Troubleshooting
+
+**1. Host networking on Linux:**
+```bash
+# Use host networking if host.docker.internal doesn't work
+docker run --network host lfnovo/open_notebook:latest-single
+export OLLAMA_API_BASE=http://localhost:11434
+```
+
+**2. Custom bridge network:**
+```yaml
+version: '3.8'
+networks:
+  ollama_network:
+    driver: bridge
+
+services:
+  open-notebook:
+    networks:
+      - ollama_network
+    environment:
+      - OLLAMA_API_BASE=http://ollama:11434
+
+  ollama:
+    networks:
+      - ollama_network
+```
+
+**3. Firewall issues:**
+```bash
+# Allow Ollama port through firewall
+sudo ufw allow 11434
+# or
+sudo firewall-cmd --add-port=11434/tcp --permanent
+```
+
+## Performance Optimization
+
+### Model Management
+
+**List installed models:**
+```bash
+ollama list
+```
+
+**Remove unused models:**
+```bash
+ollama rm model_name
+```
+
+**Show running models:**
+```bash
+ollama ps
+```
+
+**Preload models for faster startup:**
+```bash
+# Keep model in memory
+curl http://localhost:11434/api/generate -d '{
+  "model": "qwen3",
+  "prompt": "test",
+  "keep_alive": -1
+}'
+```
+
+### System Optimization
+
+**Linux: Increase file limits:**
+```bash
+echo "* soft nofile 65536" >> /etc/security/limits.conf
+echo "* hard nofile 65536" >> /etc/security/limits.conf
+```
+
+**macOS: Increase memory limits:**
+```bash
+# Add to ~/.zshrc or ~/.bash_profile
+export OLLAMA_MAX_LOADED_MODELS=2
+export OLLAMA_NUM_PARALLEL=4
+```
+
+**Docker: Resource allocation:**
+```yaml
+services:
+  ollama:
+    deploy:
+      resources:
+        limits:
+          memory: 8G
+          cpus: '4'
+```
+
+## Advanced Configuration
+
+### Environment Variables
+
+```bash
+# Ollama server configuration
+export OLLAMA_HOST=0.0.0.0:11434      # Bind to all interfaces
+export OLLAMA_KEEP_ALIVE=5m            # Keep models in memory
+export OLLAMA_MAX_LOADED_MODELS=3      # Max concurrent models
+export OLLAMA_MAX_QUEUE=512            # Request queue size
+export OLLAMA_NUM_PARALLEL=4           # Parallel request handling
+export OLLAMA_FLASH_ATTENTION=1        # Enable flash attention (if supported)
+
+# Open Notebook configuration
+export OLLAMA_API_BASE=http://localhost:11434
+```
+
+### Custom Model Imports
+
+**Import custom models:**
+```bash
+# Create Modelfile
+cat > Modelfile << EOF
+FROM qwen3
+PARAMETER temperature 0.7
+PARAMETER top_p 0.9
+SYSTEM "You are a helpful research assistant."
+EOF
+
+# Create custom model
+ollama create my-research-model -f Modelfile
+```
+
+**Use in Open Notebook:**
+1. Go to Settings → Models
+2. Add new model: `my-research-model`
+3. Set as default for specific tasks
+
+### Monitoring and Logging
+
+**Monitor Ollama logs:**
+```bash
+# Linux (systemd)
+journalctl -u ollama -f
+
+# Docker
+docker logs -f ollama
+
+# Manual run with verbose logging
+OLLAMA_DEBUG=1 ollama serve
+```
+
+**Resource monitoring:**
+```bash
+# CPU and memory usage
+htop
+
+# GPU usage (NVIDIA)
+nvidia-smi -l 1
+
+# Model-specific metrics
+ollama ps
+```
+
+## Integration Examples
+
+### Python Script Integration
+
+```python
+import requests
+import os
+
+# Test Ollama connection
+ollama_base = os.environ.get('OLLAMA_API_BASE', 'http://localhost:11434')
+response = requests.get(f'{ollama_base}/api/tags')
+print(f"Available models: {response.json()}")
+
+# Generate text
+payload = {
+    "model": "qwen3",
+    "prompt": "Explain quantum computing",
+    "stream": False
+}
+response = requests.post(f'{ollama_base}/api/generate', json=payload)
+print(response.json()['response'])
+```
+
+### Health Check Script
+
+```bash
+#!/bin/bash
+# ollama-health-check.sh
+
+OLLAMA_API_BASE=${OLLAMA_API_BASE:-"http://localhost:11434"}
+
+echo "Checking Ollama health..."
+if curl -s "${OLLAMA_API_BASE}/api/tags" > /dev/null; then
+    echo "✅ Ollama is running"
+    echo "Available models:"
+    curl -s "${OLLAMA_API_BASE}/api/tags" | jq -r '.models[].name'
+else
+    echo "❌ Ollama is not accessible at ${OLLAMA_API_BASE}"
+    exit 1
+fi
+```
+
+## Migration from Other Providers
+
+### Coming from OpenAI
+
+**Similar performance models:**
+- GPT-4 → `qwen3` or `deepseek-r1`
+- GPT-3.5 → `gemma3` or `phi4`
+- text-embedding-ada-002 → `mxbai-embed-large`
+
+**Cost comparison:**
+- OpenAI: $0.01-0.06 per 1K tokens
+- Ollama: $0 after hardware investment
+
+### Coming from Anthropic
+
+**Claude replacement suggestions:**
+- Claude 3.5 Sonnet → `deepseek-r1` (reasoning)
+- Claude 3 Haiku → `phi4` (speed)
+
+## Best Practices
+
+### Security
+
+1. **Network Security:**
+   - Run Ollama only on trusted networks
+   - Use firewall rules to limit access
+   - Consider VPN for remote access
+
+2. **Model Verification:**
+   - Only pull models from trusted sources
+   - Verify model checksums when possible
+
+3. **Resource Limits:**
+   - Set memory and CPU limits in production
+   - Monitor resource usage regularly
+
+### Performance
+
+1. **Model Selection:**
+   - Use appropriate model size for your hardware
+   - Smaller models for simple tasks
+   - Reasoning models only when needed
+
+2. **Resource Management:**
+   - Preload frequently used models
+   - Remove unused models regularly
+   - Monitor system resources
+
+3. **Network Optimization:**
+   - Use local networks for better latency
+   - Consider SSD storage for faster model loading
+
+## Getting Help
+
+**Community Resources:**
+- [Ollama GitHub](https://github.com/jmorganca/ollama) - Official repository
+- [Ollama Discord](https://discord.gg/ollama) - Community support
+- [Open Notebook Discord](https://discord.gg/37XJPXfz2w) - Integration help
+
+**Debugging Resources:**
+- Check Ollama logs for error messages
+- Test connection with curl commands
+- Verify environment variables
+- Monitor system resources
+
+This comprehensive guide should help you successfully deploy and optimize Ollama with Open Notebook. Start with the Quick Start section and refer to specific scenarios as needed.
--- a/open_notebook/utils.py
+++ b/open_notebook/utils.py
@ -135,8 +135,8 @@ def get_version_from_github(repo_url: str, branch: str = "main") -> str:
        f"https://raw.githubusercontent.com/{owner}/{repo}/{branch}/pyproject.toml"
    )

-    # Fetch the file
-    response = requests.get(raw_url)
+    # Fetch the file with timeout
+    response = requests.get(raw_url, timeout=10)
    response.raise_for_status()

    # Parse TOML content
--- a/pages/stream_app/utils.py
+++ b/pages/stream_app/utils.py
@ -21,6 +21,7 @@ from open_notebook.utils import (

 def version_sidebar():
    with st.sidebar:
+        # Get current version
        try:
            current_version = get_installed_version("open-notebook")
        except Exception:
@ -31,14 +32,29 @@ def version_sidebar():
                pyproject = tomli.load(f)
                current_version = pyproject["project"]["version"]

-        latest_version = get_version_from_github(
-            "https://www.github.com/lfnovo/open-notebook", "main"
-        )
        st.write(f"Open Notebook: {current_version}")
-        if compare_versions(current_version, latest_version) < 0:
-            st.warning(
-                f"New version {latest_version} available. [Click here for upgrade instructions](https://github.com/lfnovo/open-notebook/blob/main/docs/SETUP.md#upgrading-open-notebook)"
-            )
+
+        # Try to get latest version, but don't fail if unavailable
+        try:
+            # Use session state cache to avoid repeated checks
+            if 'latest_version' not in st.session_state or 'version_check_failed' not in st.session_state:
+                latest_version = get_version_from_github(
+                    "https://www.github.com/lfnovo/open-notebook", "main"
+                )
+                st.session_state.latest_version = latest_version
+                st.session_state.version_check_failed = False
+            else:
+                latest_version = st.session_state.latest_version
+
+            if not st.session_state.version_check_failed and compare_versions(current_version, latest_version) < 0:
+                st.warning(
+                    f"New version {latest_version} available. [Click here for upgrade instructions](https://github.com/lfnovo/open-notebook/blob/main/docs/SETUP.md#upgrading-open-notebook)"
+                )
+        except Exception:
+            # Cache the fact that version check failed to avoid repeated attempts
+            st.session_state.version_check_failed = True
+            # Optionally show a subtle message about failed update check
+            st.caption("⚠️ Could not check for updates (offline or GitHub unavailable)")


 def create_session_for_notebook(notebook_id: str, session_name: str = None):
--- a/pyproject.toml
+++ b/pyproject.toml
@ -1,6 +1,6 @@
 [project]
 name = "open-notebook"
-version = "0.3.2"
+version = "0.3.3"
 description = "An open source implementation of a research assistant, inspired by Google Notebook LM"
 authors = [
    {name = "Luis Novo", email = "lfnovo@gmail.com"}
@ -30,7 +30,7 @@ dependencies = [
    "langchain-openai>=0.2.3",
    "langchain-anthropic>=0.2.3",
    "langchain-ollama>=0.2.0",
-    "langchain-google-genai>=2.0.1",
+    "langchain-google-genai>=2.1.10",
    "langchain-groq>=0.2.1",
    "langchain_mistralai>=0.2.1",
    "langchain_deepseek>=0.1.3",
@ -41,11 +41,11 @@ dependencies = [
    "nest-asyncio>=1.6.0",
    "content-core>=1.0.2",
    "ai-prompter>=0.3",
-    "esperanto>=2.3.4",
-    "langchain-google-vertexai>=2.0.10",
+    "esperanto>=2.4.1",
+    "langchain-google-vertexai>=2.0.28",
    "surrealdb>=1.0.4",
    "surreal-commands>=1.0.13",
-    "podcast-creator>=0.2.6",
+    "podcast-creator>=0.7.0",
 ]

 [tool.setuptools]
--- a/uv.lock
+++ b/uv.lock