Skip to content

AI setup

Synapse uses an LLM for two features: exercise generation from your course material, and OCR of scanned documents. AI is always opt-in: nothing is configured out of the box, nothing leaves your device until you set up a provider yourself, and the app works fully without one. You bring your own API key or point it at a model running on your own machine.

The default provider is OpenAI with the gpt-4o-mini model, which is available on OpenAI's free usage tier: a fresh install works with a free key, no paid plan needed.

1. Quick start (OpenAI free tier)

  1. Create an account at https://platform.openai.com and generate an API key (Dashboard > API keys > Create new secret key).
  2. In Synapse, open Settings > AI, keep the provider on OpenAI and the model on gpt-4o-mini, paste your key and save. The key is stored server-side and never sent back to the browser.
  3. Enable AI for a course from that course's settings page, then use "Generate exercises" on any document.

The free tier allows a few requests per minute and a daily cap (see https://developers.openai.com/api/docs/guides/rate-limits#usage-tiers for the current numbers). Synapse is tuned for this: generation requests run one at a time and rate limit responses are retried automatically with a growing delay. If you still hit the limit, wait a minute and try again; generating for many documents in a row simply takes longer on the free tier. Adding a small prepaid balance moves the account to tier 1 and removes most of the friction.

Instead of the settings screen, the key can also come from the environment (OPENAI_API_KEY in apps/api/.env); values saved in Settings take precedence.

2. Other providers

  • Local model: set the provider to Local with any OpenAI-compatible endpoint. The default base URL targets Ollama (http://localhost:11434/v1); install it from https://ollama.com, pull a model (ollama pull llama3.1) and set the model name accordingly. No API key needed, nothing leaves your machine.
  • Anthropic: set the provider to Claude in Settings > AI with a key from https://console.anthropic.com.

3. What uses which key

Both features follow the provider configured in Settings > AI, so on the default setup the OpenAI key covers everything.

Feature Providers Notes
Exercise generation OpenAI, Claude, or Local Per-course toggle in the course settings
OCR (scanned PDFs) OpenAI or Claude Local models work only if they accept PDF input

4. Device AI (no server)

When the app cannot reach a server (the desktop app in standalone mode, or a browser that lost its connection), AI runs against the provider configured in Settings > This device > Device AI:

  • A local runtime through any OpenAI-compatible API. The default expects Ollama on http://localhost:11434/v1 with the llama3.2 model pulled (ollama pull llama3.2).
  • Or your own OpenAI / Anthropic key, stored on the device only. This also enables the transcription of scanned PDFs on import (local models cannot read PDF input).

With a server connected, the server's AI settings apply instead. Generated exercises are written straight into the local workspace and sync to your other devices like any other change.