Add Mistral AI backend support with abstraction layer

README.md

@@ -2,7 +2,7 @@
 
 **The AI-powered intelligence layer for your Ratta Supernote.**
 
-This toolkit is a self-hosted implementation of the **Supernote Private Cloud** protocol. While Ratta's official private cloud provides a solid and reliable sync foundation, this project extends that experience with an **AI-driven synthesis engine**—transforming your handwritten notes into structured, searchable knowledge using Google Gemini.
+This toolkit is a self-hosted implementation of the **Supernote Private Cloud** protocol. While Ratta's official private cloud provides a solid and reliable sync foundation, this project extends that experience with an **AI-driven synthesis engine**—transforming your handwritten notes into structured, searchable knowledge using Google Gemini or Mistral AI.
 
 <p align="center">
   <img src="docs/static-assets/hero-overview.jpg" alt="Supernote Overview" width="800">
@@ -26,7 +26,7 @@ This project is designed to be **fully compatible** with the official Supernote
 Beyond simple storage, Supernote provides an active processing pipeline to increase the utility of your notes:
 
 1.  **Sync**: Your device uploads `.note` files using the official Private Cloud protocol.
-2.  **Transcribe**: The server extract pages and use Gemini Vision to OCR your handwriting.
+2.  **Transcribe**: The server extracts pages and uses an AI provider (Gemini or Mistral) to OCR your handwriting.
 3.  **Synthesize**: AI Analyzers review your journals to find tasks, themes, and summaries.
 4.  **Index**: Every word is vectorized, enabling semantic search across your entire library.
 
@@ -43,10 +43,15 @@ The integrated frontend allows you to review your notes and AI insights side-by-
 
 ### 1. Launch the Cloud
 
-The easiest way to start is with the `all` bundle and a Gemini API key:
+The easiest way to start is with the `all` bundle and an AI API key. Choose either Google Gemini or Mistral AI:
 
 ```bash
-export SUPERNOTE_GEMINI_API_KEY="your-api-key"
+# Option A: Google Gemini (default)
+export SUPERNOTE_GEMINI_API_KEY="your-gemini-api-key"
+
+# Option B: Mistral AI
+export SUPERNOTE_MISTRAL_API_KEY="your-mistral-api-key"
+
 pip install "supernote[all]"
 supernote serve
 ```
@@ -130,13 +135,26 @@ The notebook parser is a fork and slightly lighter dependency version of [supern
 
 ### Run with Docker
 
+The pre-built image is published to the GitHub Container Registry:
+
+```bash
+# Pull and run the latest image
+docker run -d \
+  -p 8080:8080 \
+  -p 8001:8001 \
+  -v supernote-data:/data \
+  -e SUPERNOTE_GEMINI_API_KEY="your-api-key" \
+  ghcr.io/allenporter/supernote:latest
+```
+
+Or build from source:
+
 ```bash
-# Build & Run server
 docker build -t supernote .
 docker run -d -p 8080:8080 -v $(pwd)/storage:/storage supernote serve
 ```
 
-See [Server Documentation](https://github.com/allenporter/supernote/blob/main/supernote/server/README.md) for details.
+For a full setup with Docker Compose, see [docker-compose.yml](docker-compose.yml).
 
 ### Developer API
 

docker-compose.yml

@@ -0,0 +1,33 @@
+---
+services:
+  supernote:
+    image: ghcr.io/allenporter/supernote:latest
+    # Alternatively, build from source:
+    # build: .
+    restart: unless-stopped
+    ports:
+      - "8080:8080"   # Main server
+      - "8001:8001"   # MCP server
+    volumes:
+      - supernote-data:/data
+    environment:
+      # AI Provider — set one of the following:
+      SUPERNOTE_GEMINI_API_KEY: ""      # Google Gemini API key
+      # SUPERNOTE_MISTRAL_API_KEY: ""   # Mistral AI API key (alternative)
+
+      # Storage & server
+      SUPERNOTE_STORAGE_DIR: /data
+      SUPERNOTE_CONFIG_DIR: /data/config
+      SUPERNOTE_HOST: 0.0.0.0
+      SUPERNOTE_PORT: "8080"
+      SUPERNOTE_MCP_PORT: "8001"
+
+      # Optional: set the public-facing base URL (e.g. behind a reverse proxy)
+      # SUPERNOTE_BASE_URL: "https://supernote.example.com"
+      # SUPERNOTE_MCP_BASE_URL: "https://mcp.example.com"
+
+      # Optional: enable user self-registration
+      # SUPERNOTE_ENABLE_REGISTRATION: "true"
+
+volumes:
+  supernote-data:

docs/CONTRIBUTING.md

@@ -61,8 +61,9 @@ This script will initialize a virtual environment using `uv`, install dependenci
 For rapid iteration, run an ephemeral server. It starts with a clean state and a pre-configured debug user.
 
 ```bash
-# Enable AI features for development
-export SUPERNOTE_GEMINI_API_KEY="your_api_key"
+# Enable AI features for development (choose one)
+export SUPERNOTE_GEMINI_API_KEY="your-gemini-api-key"     # Google Gemini (default)
+# export SUPERNOTE_MISTRAL_API_KEY="your-mistral-api-key"  # Mistral AI (alternative)
 
 # Start the ephemeral server
 supernote serve --ephemeral

docs/note_processing_design.md

@@ -41,11 +41,11 @@ If we don't want to parse the large "Transcript Summary" every time we need a si
 1.  **Diff Phase**: Parser extracts page streams. Each stream is hashed and compared to the database.
 2.  **Visual Phase**: Generate PNGs for new/changed pages. Assemble full PDF using cached PNGs for unchanged pages.
 3.  **Intelligence Phase**:
-    - Send PNG to Gemini (with retry/backoff) for OCR.
+    - Send PNG to the configured AI provider (with retry/backoff) for OCR.
     - **Chunk Embeddings (Page-indexed)**: Generated per-page from raw OCR text. Ideal for "finding the needle in the haystack."
 4.  **Document Phase**:
     - **Transcript Generation**: Aggregate all page text into a single "OCR Transcript" `SummaryDO`.
-    - **Insight Generation**: Prompt Gemini with the transcript to create an "AI Insights" `SummaryDO`.
+    - **Insight Generation**: Prompt the AI provider with the transcript to create an "AI Insights" `SummaryDO`.
     - **Vector Indexing**:
         - **Chunks**: Generate vectors for each page window. Store in-memory index `(file_id, page_index)`.
         - **Document**: Generate vector for the Insight Summary. Store in-memory index `(file_id)`.
@@ -102,7 +102,7 @@ To maintain a resilient pipeline, modules must follow specific error handling pa
 
 ### 1. Expectations for `process()`
 - **No Internal Try/Except (Mostly)**: Modules should let exceptions bubble up. The base class's `run()` method is the centralized error handler.
-- **Descriptive Exceptions**: Raise specific exceptions (e.g., `FileNotFoundError`, `GeminiAPIError`) so the automated logs are useful.
+- **Descriptive Exceptions**: Raise specific exceptions (e.g., `FileNotFoundError`, `ValueError`) so the automated logs are useful.
 - **Idempotency is Mandatory**: If `process()` fails halfway (e.g., after writing a file but before updating a DB record), the next attempt must be able to resume or overwrite without creating duplicates or corruption.
 
 ### 2. Orchestrator Reaction
@@ -118,5 +118,5 @@ To maintain a resilient pipeline, modules must follow specific error handling pa
 ### Failure Modes & Corner Cases
 
 1.  **Dependency Staleness**: If `PageHashingModule` detects a change, it deletes the `SystemTaskDO` entries for `OCR` and `Embedding`. This causes their `run_if_needed` to return `True` on the next run, forcing a re-poll.
-2.  **Concurrency Limits**: `ProcessorService` limits the number of files processed in parallel. Modules should use internal semaphores (like `GeminiService`) if they have external API rate limits.
+2.  **Concurrency Limits**: `ProcessorService` limits the number of files processed in parallel. AI service implementations (like `GeminiService` and `MistralService`) use internal semaphores to respect external API rate limits.
 3.  **Idempotency Requirement**: If a task fails *after* writing data but *before* updating its status to `COMPLETED`, it will be re-run. `process()` must be safe to call again (e.g., using `UPSERT` or overwriting files).

pyproject.toml

@@ -43,6 +43,7 @@ server = [
   "aiofiles>=25.1.0",
   "aiohttp-remotes>=1.3.0",
   "google-genai>=1.57.0",
+  "mistralai>=2.0.0",
   "mcp>=1.25.0",
   "aiohttp-asgi>=0.6.1",
 ]

supernote/server/README.md

@@ -5,7 +5,7 @@ This package provides a self-hosted implementation of the Supernote Cloud server
 ## Core Features
 
 -   **Seamless Sync**: Implements the native Supernote sync protocol.
--   **AI Synthesis**: Automatically transcribes handwriting and identifies key insights using Google Gemini.
+-   **AI Synthesis**: Automatically transcribes handwriting and identifies key insights using Google Gemini or Mistral AI.
 -   **Knowledge Exploration**: Cross-notebook semantic search and web-based file browsing.
 -   **Private & Local**: Store your notes and metadata on your own infrastructure.
 
@@ -17,7 +17,7 @@ See the main [README.md](../../README.md) for a quick start guide.
 
 -   A Supernote device (Nomad, A5 X, A6 X, etc.)
 -   Python 3.13+ or Docker.
--   (Recommended) **Gemini API Key** for OCR and Summarization.
+-   (Recommended) A **Gemini** or **Mistral AI** API key for OCR and Summarization.
 
 ### Configuration
 
@@ -26,11 +26,37 @@ The server is configured via `config/config.yaml` or environment variables.
 For a comprehensive reference, see the [ServerConfig documentation](https://allenporter.github.io/supernote/supernote/server.html#ServerConfig).
 
 #### AI Configuration
-To enable AI features, set the Gemini API key:
+
+AI features require an API key from either Google Gemini (default) or Mistral AI. Set one of the following:
+
 ```bash
-export SUPERNOTE_GEMINI_API_KEY="your-api-key"
+# Option A: Google Gemini (default)
+export SUPERNOTE_GEMINI_API_KEY="your-gemini-api-key"
+
+# Option B: Mistral AI (takes priority when set)
+export SUPERNOTE_MISTRAL_API_KEY="your-mistral-api-key"
 ```
 
+> **Note on provider switching**: Gemini embeddings are 3072-dimensional while Mistral embeddings are 1024-dimensional. Switching providers after notes have been indexed requires re-processing all files to regenerate embeddings.
+
+Additional Gemini model settings:
+
+| Env var | Default | Description |
+|---|---|---|
+| `SUPERNOTE_GEMINI_OCR_MODEL` | `gemini-3-flash-preview` | Vision model for OCR |
+| `SUPERNOTE_GEMINI_EMBEDDING_MODEL` | `gemini-embedding-001` | Embedding model |
+| `SUPERNOTE_GEMINI_CHAT_MODEL` | `gemini-2.0-flash` | Chat model for summaries |
+| `SUPERNOTE_GEMINI_MAX_CONCURRENCY` | `5` | Max concurrent API calls (minimum 1) |
+
+Additional Mistral model settings:
+
+| Env var | Default | Description |
+|---|---|---|
+| `SUPERNOTE_MISTRAL_OCR_MODEL` | `mistral-ocr-latest` | Dedicated OCR model |
+| `SUPERNOTE_MISTRAL_EMBEDDING_MODEL` | `mistral-embed` | Embedding model |
+| `SUPERNOTE_MISTRAL_CHAT_MODEL` | `mistral-large-latest` | Chat model for summaries |
+| `SUPERNOTE_MISTRAL_MAX_CONCURRENCY` | `5` | Max concurrent API calls (minimum 1) |
+
 ### Running the Server
 
 Start the server using the unified `supernote` CLI:

supernote/server/app.py

@@ -35,13 +35,15 @@
     system,
 )
 from .routes.decorators import public_route
+from .services.ai_service import AIService
 from .services.blob import LocalBlobStorage
 from .services.coordination import SqliteCoordinationService
 from .services.file import FileService
 from .services.gemini import GeminiService
+from .services.mistral import MistralService
 from .services.processor import ProcessorService
-from .services.processor_modules.gemini_embedding import GeminiEmbeddingModule
-from .services.processor_modules.gemini_ocr import GeminiOcrModule
+from .services.processor_modules.embedding import EmbeddingModule
+from .services.processor_modules.ocr import OcrModule
 from .services.processor_modules.page_hashing import PageHashingModule
 from .services.processor_modules.png_conversion import PngConversionModule
 from .services.processor_modules.summary import SummaryModule
@@ -290,15 +292,31 @@ def create_app(config: ServerConfig) -> web.Application:
     app["file_service"] = file_service
     app["url_signer"] = UrlSigner(config.auth.secret_key, coordination_service)
     app["schedule_service"] = ScheduleService(session_manager)
-    gemini_service = GeminiService(
-        config.gemini_api_key, max_concurrency=config.gemini_max_concurrency
-    )
-    app["gemini_service"] = gemini_service
+    ai_service: AIService
+    if config.mistral_api_key:
+        logger.info("Using Mistral as AI backend")
+        ai_service = MistralService(
+            api_key=config.mistral_api_key,
+            ocr_model=config.mistral_ocr_model,
+            embedding_model=config.mistral_embedding_model,
+            chat_model=config.mistral_chat_model,
+            max_concurrency=config.mistral_max_concurrency,
+        )
+    else:
+        logger.info("Using Gemini as AI backend")
+        ai_service = GeminiService(
+            api_key=config.gemini_api_key,
+            ocr_model=config.gemini_ocr_model,
+            embedding_model=config.gemini_embedding_model,
+            chat_model=config.gemini_chat_model,
+            max_concurrency=config.gemini_max_concurrency,
+        )
+    app["ai_service"] = ai_service
 
     summary_service = SummaryService(user_service, session_manager)
     app["summary_service"] = summary_service
 
-    search_service = SearchService(session_manager, gemini_service, config)
+    search_service = SearchService(session_manager, ai_service)
     app["search_service"] = search_service
 
     app["sync_locks"] = {}  # user -> (equipment_no, expiry_time)
@@ -313,16 +331,17 @@ def create_app(config: ServerConfig) -> web.Application:
     processor_service.register_modules(
         hashing=PageHashingModule(file_service=file_service),
         png=PngConversionModule(file_service=file_service),
-        ocr=GeminiOcrModule(
-            file_service=file_service, config=config, gemini_service=gemini_service
+        ocr=OcrModule(
+            file_service=file_service,
+            ai_service=ai_service,
         ),
-        embedding=GeminiEmbeddingModule(
-            file_service=file_service, config=config, gemini_service=gemini_service
+        embedding=EmbeddingModule(
+            file_service=file_service,
+            ai_service=ai_service,
         ),
         summary=SummaryModule(
             file_service=file_service,
-            config=config,
-            gemini_service=gemini_service,
+            ai_service=ai_service,
             summary_service=summary_service,
         ),
     )