LLM Providers

Configure Ollama, OpenAI, Anthropic, Gemini, or OpenRouter for wiki generation and semantic search.

Synapse uses LLM providers for two purposes:

Wiki generation (L2) — asynchronous markdown documentation
Semantic embeddings — vector similarity search (optional)

Synapse runs in structural Mode A with zero LLM calls if no provider is configured. AST symbol search, FTS5 keyword search, and all L3 memory tools work without any API key.

Configure a Provider

Run the interactive setup wizard:

synap setup .

This prompts for provider, model, and stores credentials in your OS keyring (via keyring).

Supported Providers

Ollama (Recommended — 100% Free & Local)

No API key needed. Runs entirely on your machine.

# Install Ollama: https://ollama.ai
ollama pull qwen2.5-coder:14b      # LLM for wiki generation
ollama pull nomic-embed-text       # Embeddings for vector search

Config in ~/.config/synap/config.toml:

llm_provider = "ollama"
llm_model = "qwen2.5-coder:14b"
embed_provider = "ollama"
embed_model = "nomic-embed-text"
ollama_url = "http://127.0.0.1:11434"

OpenAI

llm_provider = "openai"
llm_model = "gpt-4o-mini"

API key resolution order:

OS keyring (synap setup stores it here)
SYNAP_OPENAI_API_KEY environment variable
~/.synap/credentials file (must be chmod 600)

Anthropic

llm_provider = "anthropic"
llm_model = "claude-3-haiku-20240307"

Environment variable: SYNAP_ANTHROPIC_API_KEY

Google Gemini

llm_provider = "gemini"
llm_model = "gemini-2.0-flash-lite"

Environment variable: SYNAP_GEMINI_API_KEY

OpenRouter

llm_provider = "openrouter"
llm_model = "meta-llama/llama-3.1-70b-instruct"

Environment variable: SYNAP_OPENROUTER_API_KEY

Provider Comparison

| Provider | Wiki Quality | Cost/page | Privacy | Speed | |---|---|---|---|---| | Ollama | Very Good | Free | ✅ 100% local | Depends on GPU | | OpenAI GPT-4o-mini | Excellent | ~$0.0015 | ❌ Cloud | Fast | | Anthropic Haiku | Excellent | ~$0.0025 | ❌ Cloud | Fast | | Gemini Flash Lite | Good | ~$0.0005 | ❌ Cloud | Very Fast | | OpenRouter | Varies | Varies | ❌ Cloud | Varies |

Structural Mode A (No LLM)

To run entirely without any LLM:

synap init . --skip-llm

In structural mode:

L1 AST search, FTS5 keyword search work at full speed
L3 checkpoints, decisions, and lessons all work
Wiki files contain placeholder text instead of generated documentation
Vector similarity search is disabled

This mode is useful for air-gapped environments or when you only need structural code navigation.

Credential Security

API keys are resolved in this order:

1. OS Keyring (most secure — set via synap setup)
   keyring.get_password("synap", "{provider}_api_key")

2. Environment Variables
   SYNAP_OPENAI_API_KEY
   SYNAP_ANTHROPIC_API_KEY
   SYNAP_GEMINI_API_KEY
   SYNAP_OPENROUTER_API_KEY

3. Credentials file: ~/.synap/credentials
   ⚠️  Must have permissions: chmod 600
   Group/public read access causes this fallback to be skipped