Provider Configuration

SwarmVault does not require provider configuration to start. The built-in heuristic provider is always available for local/offline workflows.

The providers object in your config maps provider names to their configuration when you want higher-quality synthesis or extra capabilities such as embeddings, vision, image generation, or a specific hosted backend.

This page covers LLM providers. Deep-lint web augmentation uses a separate webSearch block documented in Web Search.

CLI Provider Registry

Use the provider registry commands when you want to update swarmvault.config.json without hand-editing JSON:

swarmvault provider add fast --type openai --model gpt-4o-mini --api-key-env OPENAI_API_KEY --capability chat --capability structured --task queryProvider
swarmvault provider list
swarmvault provider show fast
swarmvault provider remove fast --fallback local

provider add validates provider type, declared capabilities, and task assignments before writing the config. It stores only environment variable names for secrets; literal API key values are rejected. Unknown top-level config fields are preserved.

provider remove deletes a provider and reassigns any tasks that pointed at it to --fallback, or to local when that built-in provider is present. The --fallback provider must already be configured; an unknown id is rejected. Removing the last configured provider is refused while required tasks (compileProvider, queryProvider, lintProvider, visionProvider) still point at it, so the config never ends up with tasks that no provider can serve; optional task assignments such as imageProvider are cleared instead.

Provider Config Fields

Common capabilities include chat, structured, vision, embeddings, image_generation, and audio.

Built-In Provider Types

• heuristic
• openai
• anthropic
• gemini
• ollama
• openrouter
• groq
• together
• xai
• cerebras
• local-whisper
• openai-compatible
• custom

Example: Multiple Providers

{
  "providers": {
    "local": {
      "type": "heuristic",
      "model": "heuristic-v1"
    },
    "openai": {
      "type": "openai",
      "model": "gpt-4o",
      "apiKeyEnv": "OPENAI_API_KEY"
    },
    "claude": {
      "type": "anthropic",
      "model": "claude-sonnet-4-20250514",
      "apiKeyEnv": "ANTHROPIC_API_KEY"
    },
    "openrouter": {
      "type": "openrouter",
      "model": "openai/gpt-4o-mini"
    }
  },
  "tasks": {
    "compileProvider": "openai",
    "queryProvider": "claude",
    "lintProvider": "local",
    "visionProvider": "openai",
    "imageProvider": "openai",
    "embeddingProvider": "openrouter"
  }
}

Each task can use a different provider. The local heuristic provider is always available as the built-in local path. imageProvider is optional unless you want native raster image generation for --format image, and embeddingProvider is optional unless you want semantic graph query and embedding-backed similarity enrichment.

audioProvider is the parallel optional task for audio-file ingest. By default, SwarmVault treats openai, ollama, groq, and generic openai-compatible providers as audio-capable unless you override their declared capabilities explicitly.

Local Embeddings Without API Keys

Use an embedding-capable local backend for tasks.embeddingProvider. heuristic is a valid local default for compile/query/lint, but it does not provide embeddings.

{
  "providers": {
    "local": {
      "type": "heuristic",
      "model": "heuristic-v1"
    },
    "ollama-embeddings": {
      "type": "ollama",
      "model": "nomic-embed-text",
      "baseUrl": "http://localhost:11434/v1"
    }
  },
  "tasks": {
    "compileProvider": "local",
    "queryProvider": "local",
    "embeddingProvider": "ollama-embeddings"
  }
}