> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kair.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Full config.yml reference — all fields, defaults, and what each controls.

Configuration lives in `config.yml`. On production servers it must be at `/kair_voice_config/config.yml`. The app validates all fields at startup and refuses to boot on missing or invalid config.

## Full reference

```yaml theme={null}
database:
  url: "postgresql://user:pass@host:5432/kair_voice"

app:
  base_url: "0.0.0.0:8000"
  uploads_dir: "/kair_voice_config/uploads"   # temporary staging dir for uploads
  otel_exporter_otlp_endpoint: "http://127.0.0.1:4318"   # optional, OTLP tracing

redis:
  url: "redis://localhost:6379"

s3:
  endpoint: "https://fsn1.your-objectstorage.com"
  bucket_name: "kair-voice-audio"
  access_key: "your-access-key"
  secret_key: "your-secret-key"
  region: "fsn1"

transcription:
  client: "local"          # "local" (whisper.cpp) or "foresight" (remote cluster)
  realtime_model: "ai_models/ggml-base.bin"
  final_model: "ai_models/ggml-large-v3.bin"
  nr_of_threads_for_transcription: 14
  uploads_dir: "/kair_voice_config/uploads"
  foresight:
    base_url: "https://inference.internal/v1"
    api_key: "your-cluster-api-key"
    realtime_model: "whisper-1"
    final_model: "whisper-1"
    diarize: false           # speaker labelling on final pass only

summarisation:
  backend: "openai"          # "openai" or "local" (ollama)
  api_key: "your-openai-api-key"
  model: "gpt-4o-mini"

hirag:
  enabled: true
  agent_client: "ollama"     # "ollama" | "anthropic" | "gemini"
  embedding_client: "ollama" # "ollama" | "openai" | "gemini"
  ollama:
    base_url: "http://localhost:11434"
  neo4j:
    url: "bolt://localhost:7687"
    username: "neo4j"
    password: ""
  indexing:
    enabled: true
  retrieval:
    top_n_entities: 10
    top_m_key_entities: 5
  agent:
    enabled: true
    max_iterations: 4
    use_pipeline: false

# Optional — only needed if using Anthropic/Gemini/OpenAI for HiRAG
anthropic:
  base_url: "https://api.anthropic.com"   # optional override
gemini: {}
openai: {}

# Optional — Recall.ai meeting bot (Google Meet / Zoom / Microsoft Teams)
recall:
  region: "eu-central-1"
  api_key: "your-recall-api-key"
  webhook_secret: "whsec_..."   # workspace verification secret from Recall dashboard
  bot_display_name: "Kair Cognito"   # optional; defaults to "Kair Cognito"
```

## Key decisions

| Setting                           | Notes                                                                                                                                                                                                                |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transcription.client`            | Switchable at runtime via admin UI. `base_url`/`api_key` stay in config.                                                                                                                                             |
| `transcription.foresight.diarize` | Only affects the final full-audio pass. Chunks are never diarised.                                                                                                                                                   |
| `s3` block                        | If omitted, files are stored locally in `uploads_dir`. S3 is recommended for production.                                                                                                                             |
| `hirag.enabled`                   | Set to `false` to disable knowledge graph entirely (Neo4j not required).                                                                                                                                             |
| `recall` block                    | Optional. When set, enables meeting-bot dispatch via Recall.ai and `POST /api/webhooks/recall` for recording ingest. Register the webhook URL in the Recall dashboard for `audio_mixed.done` and `recording.failed`. |
| `summarisation.backend`           | `"local"` uses Ollama; `"openai"` uses OpenAI API.                                                                                                                                                                   |

## Runtime overrides

Admins can override the following without restarting, via the System page or the admin API:

* Transcription client, Foresight model names, diarisation toggle
* HiRAG agent client, embedding client, LLM model, embedding model, Ollama URL
* Summarisation Ollama URL

All other settings require a config file change + service restart.

## S3 lifecycle

Audio files are large. Configure automatic deletion after 30 days:

```bash theme={null}
aws s3api put-bucket-lifecycle-configuration \
  --bucket kair-voice-audio \
  --endpoint-url https://fsn1.your-objectstorage.com \
  --lifecycle-configuration '{
    "Rules": [{
      "Id": "delete-audio-after-30-days",
      "Status": "Enabled",
      "Prefix": "kair-voice/",
      "Expiration": {"Days": 30}
    }]
  }'
```

## Audio model sizes

Whisper model RAM requirements per worker:

| Model               | RAM      |
| ------------------- | -------- |
| `ggml-tiny.bin`     | \~1 GB   |
| `ggml-base.bin`     | \~1–2 GB |
| `ggml-medium.bin`   | \~5 GB   |
| `ggml-large-v3.bin` | \~10 GB  |

Workers load the model once at startup. 3 concurrent workers on a 64 GB machine can each hold a large-v3 model.