Configuration

Configure the Respondent community edition — database, server, AI, and LLM providers

All Respondent configuration lives in a single file: respondent.yaml. This page covers every section.

Database

database:
  path: "./respondent.db"

Retention (size-cap)

The observations table is append-only and grows without bound. The retention routine is opt-in: it stays disabled until database.retention.max_size is set. When enabled, it measures the on-disk size on an interval and, if the database exceeds max_size, prunes the oldest observations in batches down to max_size * low_water_ratio, then returns the freed space to the OS. Live ingestion is never throttled — the cap is chased by pruning.

database:
  path: "./respondent.db"
  retention:
    max_size: ""                      # e.g. "50GB" / "500MB"; empty disables retention
    low_water_ratio: 0.90
    check_interval: "10m"
    batch_size: 5000
    max_batches_per_tick: 200
    incremental_vacuum_pages: 10000

Server

server:
  port: 8090

Ingest

ingest:
  sources_dir: "./sources.d"
  # dev_mode: false

AI

Controls AI-powered enrichment and analysis features. Requires a configured LLM provider.

ai:
  enabled: true
  analysis_dir: "./analysis.d"
  min_attention: "low"
  workers:
    enrichment: 2
    analysis: 1

LLM

Configure the LLM provider used for AI enrichment. Set llm.provider to the provider name, then add the provider-specific block.

llm:
  provider: "zai"
  zai:
    base_url: "https://api.z.ai/api/coding/paas/v4"
    model: "glm-5.2"
    max_tokens: 8192
    timeout: "120s"          # GLM latency headroom on large prompts
    enable_thinking: false   # structured JSON output: skip reasoning (faster, no truncation)
    # api_key: set via RESPONDENT_LLM_ZAI_API_KEY env var

llm:
  provider: "openai"
  openai:
    model: "gpt-4o"
    max_tokens: 2048
    # api_key: set via RESPONDENT_LLM_OPENAI_API_KEY env var

llm:
  provider: "anthropic"
  anthropic:
    model: "claude-sonnet-4-20250514"
    max_tokens: 2048
    # api_key: set via RESPONDENT_LLM_ANTHROPIC_API_KEY env var

llm:
  provider: "xai"
  xai:
    model: "grok-3"
    max_tokens: 2048
    # api_key: set via RESPONDENT_LLM_XAI_API_KEY env var

llm:
  provider: "ollama"
  ollama:
    model: "llama3"
    max_tokens: 2048
    base_url: "http://host.docker.internal:11434"

llm:
  provider: "lmstudio"
  lmstudio:
    base_url: "http://localhost:1234/v1"
    # model is optional — LM Studio serves the currently loaded model when blank.
    model: "qwen/qwen3.6-35b-a3b"
    max_tokens: 4096

gemini is also a valid provider; configure a llm.gemini block with api_key, model, and optional base_url.

Geocoder

Configures the geocoding service used by AI enrichment to resolve location names to coordinates.

geocoder:
  provider: "nominatim"
  nominatim:
    base_url: "https://nominatim.openstreetmap.org"
    user_agent: "respondent/1.0 (geospatial-intelligence)"
  rate_limit:
    requests_per_second: 1.0
    burst: 5
  cache:
    enabled: true
    ttl: "168h"

Frontend

Client-safe values the server hands to the embedded SPA at runtime via GET /config.json, so per-deployment frontend config reaches the already-compiled bundle without a rebuild. Empty values are omitted from the payload so the frontend’s fallback chain (runtime config → build-time env → default) stays intact.

frontend:
  cesium_ion_token: ""   # set via RESPONDENT_FRONTEND_CESIUM_ION_TOKEN

Logging

logging:
  level: "info"

Environment variable overrides

Any respondent.yaml field can be overridden with an environment variable using the RESPONDENT_ prefix. Convert the YAML path to uppercase, replacing dots and nested keys with underscores.

The other database.retention.* sub-keys follow the same pattern (e.g. RESPONDENT_DATABASE_RETENTION_LOW_WATER_RATIO, RESPONDENT_DATABASE_RETENTION_CHECK_INTERVAL). Setting ingest.enabled to false (e.g. RESPONDENT_INGEST_ENABLED=false) serves a fully static instance with no source fetching.

Set these in a .env file in the same directory as compose.yaml:

RESPONDENT_LLM_OPENAI_API_KEY=sk-your-key-here
RESPONDENT_AI_ENABLED=true

Source-level credential expansion

Inside source YAML files (in sources.d/), you can reference environment variables with the ${VAR} syntax. At load time, ${VAR} is expanded by looking up RESPONDENT_VAR in the environment.

For example, if a source needs an API key:

# sources.d/my_source.yaml
transport:
  type: http_poll
  url: "https://api.example.com/data?key=${MY_API_KEY}"

Set the corresponding environment variable:

# .env
RESPONDENT_MY_API_KEY=your-api-key-here

You can also use the auth block for structured credential injection:

transport:
  auth:
    type: api_key
    header: "X-API-Key"
    env_var: "MY_API_KEY"   # Resolved from RESPONDENT_MY_API_KEY

Complete example

A full respondent.yaml with AI enabled using OpenAI:

database:
  path: "./respondent.db"

server:
  port: 8090

ingest:
  sources_dir: "./sources.d"

ai:
  enabled: true
  analysis_dir: "./analysis.d"
  workers:
    enrichment: 2
    analysis: 1

llm:
  provider: "openai"
  openai:
    model: "gpt-4o"
    max_tokens: 2048
    # api_key: set via RESPONDENT_LLM_OPENAI_API_KEY env var

geocoder:
  provider: "nominatim"
  nominatim:
    base_url: "https://nominatim.openstreetmap.org"
    user_agent: "respondent/1.0 (geospatial-intelligence)"
  rate_limit:
    requests_per_second: 1.0
    burst: 5
  cache:
    enabled: true
    ttl: "168h"

logging:
  level: "info"

Next steps

• Create your first data source