Core

Analysis and embedding models

MailSubsystem has two separate model roles: analysis models for LLM work and embedding models for vector search. Configure them independently so providers, keys, costs, and reembedding behavior stay clear.

Model roles

Role	Setting	Used for	Change impact
Analysis	`ANALYSIS_MODEL=provider/model`	Classification, summaries, threat analysis, location reasoning, and other LLM work.	New work uses the new model after runtime restart. Existing analysis remains until re-run.
Embeddings	`EMBEDDING_MODEL=provider/model`	Vector search, retrieval context, and related-message lookup.	The model defines the vector space. Changing it requires reembedding stored mail.

ANALYSIS_MODEL=gemini/gemini-2.0-flash
ANALYSIS_API_KEY=...

EMBEDDING_MODEL=gemini/gemini-embedding-001
EMBEDDING_API_KEY=...

Model reference format

Selectors use provider/model-name. The provider is normalized to lowercase, and the model name is passed through to that provider.

ANALYSIS_MODEL=openai/gpt-4o
ANALYSIS_MODEL=anthropic/claude-3-5-sonnet-20241022
ANALYSIS_MODEL=codex/your-codex-model
ANALYSIS_MODEL=lmstudio/local-analysis-model

EMBEDDING_MODEL=gemini/gemini-embedding-001
EMBEDDING_MODEL=openai/text-embedding-3-small
EMBEDDING_MODEL=ollama/nomic-embed-text

Analysis options

Provider ref	Required configuration	Notes
`gemini/<model>`	`ANALYSIS_API_KEY` or `GEMINI_API_KEY`	Google Gemini frontier analysis. Review pricing and quotas before large batches.
`openai/<model>`	`ANALYSIS_API_KEY` or `OPENAI_API_KEY`	OpenAI API analysis. Review project limits before large batches.
`anthropic/<model>`	`ANALYSIS_API_KEY` or `ANTHROPIC_API_KEY`	Anthropic Claude analysis. Review billing and rate limits before large batches.
`codex/<model>`	Local Codex CLI login	Uses `codex exec --model` through the `codex` binary on `PATH`. `CODEX_BIN` is optional only when the binary is not on `PATH`.
`lmstudio/<model>`, `ollama/<model>`, `omlx/<model>`, `local/<model>`	`LOCAL_LLM_URL`	Local OpenAI-compatible analysis endpoints. Add `LOCAL_LLM_API_KEY` or `ANALYSIS_API_KEY` only when the server requires auth.

Embedding options

Provider ref	Required configuration	Notes
`gemini/<model>`	`EMBEDDING_API_KEY` or `GEMINI_API_KEY`	Gemini embeddings. Common default: `gemini/gemini-embedding-001`.
`openai/<model>`	`EMBEDDING_API_KEY` or `OPENAI_API_KEY`	OpenAI embeddings. Default base URL: `https://api.openai.com/v1`.
`lmstudio/<model>`, `ollama/<model>`, `omlx/<model>`, `local/<model>`	`EMBEDDING_BASE_URL` or `LOCAL_LLM_URL`	Local OpenAI-compatible embedding endpoint. The model must be installed and serving embeddings.
`openai-compatible/<model>`	`EMBEDDING_BASE_URL`	Explicit generic OpenAI-compatible embedding endpoint.

Safe configuration patterns

Frontier analysis and frontier embeddings

ANALYSIS_MODEL=gemini/gemini-2.0-flash
ANALYSIS_API_KEY=...
EMBEDDING_MODEL=gemini/gemini-embedding-001
EMBEDDING_API_KEY=...

Codex analysis and Gemini embeddings

ANALYSIS_MODEL=codex/your-codex-model
CODEX_SANDBOX=read-only
CODEX_TIMEOUT_SECS=300

EMBEDDING_MODEL=gemini/gemini-embedding-001
EMBEDDING_API_KEY=...

Local analysis and frontier embeddings

ANALYSIS_MODEL=lmstudio/local-analysis-model
LOCAL_LLM_URL=http://localhost:1234/v1

EMBEDDING_MODEL=openai/text-embedding-3-small
EMBEDDING_API_KEY=...

Local analysis and local embeddings

ANALYSIS_MODEL=lmstudio/local-analysis-model
LOCAL_LLM_URL=http://localhost:1234/v1

EMBEDDING_MODEL=lmstudio/local-embedding-model
EMBEDDING_BASE_URL=http://localhost:1234/v1

Changing models safely

Analysis models are operational choices. Change ANALYSIS_MODEL, restart the runtime, and future analysis work uses the new model. Force or re-run analysis when old rows should be refreshed.

Embedding models are data-shape choices. Changing EMBEDDING_MODEL changes the meaning and often the dimensions of stored vectors. By default, EMBEDDING_MODEL_MISMATCH=rebuild clears incompatible embedding values and lets backfill regenerate them.

EMBEDDING_MODEL_MISMATCH=fail
mailsubsystem embed-rebuild

If stored metadata only needs conversion from legacy raw model names to canonical provider/model form, MailSubsystem updates metadata without rebuilding when dimensions match.

Legacy compatibility

Legacy setting	Preferred setting
`AI_PROVIDER`, `FRONTIER_PROVIDER`, `FRONTIER_MODEL`, `LOCAL_LLM_MODEL`	`ANALYSIS_MODEL=provider/model`
Provider-specific analysis API keys	`ANALYSIS_API_KEY`
`EMBEDDING_PROVIDER`, `EMBEDDING_GEMINI_MODEL`	`EMBEDDING_MODEL=provider/model`
Provider-specific embedding API keys	`EMBEDDING_API_KEY`

Paid frontier providers can generate real charges. Before processing a large mailbox, confirm the selected analysis and embedding models, current provider pricing, and project limits.