Configuration

Provider configuration keeps modules independent from infrastructure choices.

Democr.ai lets deployments choose storage, media, AI, extraction, vector, graph, and observability providers while modules keep using the same SDK contracts.

Provider map

Configuration decides which runtime provider owns each concern.

Modules should not hardcode infrastructure choices. They ask the SDK for capabilities, while deployment config selects storage, media, knowledge, engine, and observability providers.

Storage architecture: relational, media, vector, and graph providers selected by configuration behind the same SDK contracts

01

Storage and media

Relational data can use local or shared database providers. Media can stay on disk locally or move to object storage with a public delivery endpoint.

02

AI objectives

Models are configured with capabilities, runtime methods, provider options, and performance defaults. Application code asks for objectives or explicitly configured models.

03

Knowledge services

Extractor, embedding, vector, and graph providers define whether a deployment can ingest files, search chunks, or retrieve graph context.

config.yaml examples

Small examples show the shape of the runtime configuration.

These snippets are intentionally partial. They use keys from the project configuration examples and show where local and distributed deployments usually differ.

Local-first providersconfig.yaml

database:
  type: sqlite
  data_type: sqlite

storage:
  media:
    type: local
    path: /home/user/.local/share/democrai/assets
  kg:
    type: ladybug
  vector:
    type: sqlite-vec
  observability:
    type: sqlite

network:
  redis:
    enabled: false

session:
  identity:
    provider: sqlite
  ui_state:
    provider: sqlite
  cache:
    provider: memory

Distributed providersconfig.yaml

database:
  type: postgres
  url: postgresql://democrai:secret@localhost:5432/democrai_core
  data_type: postgres
  data_url: postgresql://democrai:secret@localhost:5432/democrai_data

storage:
  kg:
    type: neo4j
    uri: bolt://localhost:7687
    user: neo4j
    password: secret
  vector:
    type: milvus
    host: localhost
    port: 19530

network:
  redis:
    enabled: true
    url: redis://localhost:6379/0

session:
  identity:
    provider: redis
  ui_state:
    provider: postgres
    url: postgresql://democrai:secret@localhost:5432/democrai_ui_state
  cache:
    provider: redis

Knowledge pipelineconfig.yaml

knowledge:
  vector_index:
    tenant_id: democrai
    app_id: knowledge
    name: items
    metric: cosine
  retrieval:
    graph_traversal_depth_default: 3
    graph_expansion_limit: 12
    graph_score_weight: 0.25
  runtime:
    poll_interval_seconds: 1.0
    batch_size: 32
    lease_seconds: 60
    max_attempts: 12

Knowledge enablement, embedding/rerank/classification/triple-extractor model selection, and MIME-to-extractor bindings are runtime settings stored in the database and managed from the system UI.

Query servicesconfig.yaml

knowledge:
  query_service:
    enabled: true
    # unix on Linux/macOS, tcp on Windows when omitted.
    # transport: unix
    # socket_path: /home/user/.local/state/democrai/knowledge-query.sock
    host: 127.0.0.1
    port: 50153
    startup_timeout_seconds: 30
    timeout_seconds: 120
    max_message_mb: 64

ai:
  engine_orchestrator:
    enabled: true
    transport: tcp
    host: 127.0.0.1
    port: 50151
    startup_timeout_seconds: 30
    invoke_timeout_seconds: 0
    max_message_mb: 128
    scheduler_worker_count: 4
    batch_wait_seconds: 0.05
    runtime_transition_worker_count: 1
    invocation_worker_count: 4
    tls:
      enabled: false
      cert_file: ""
      key_file: ""
      ca_file: ""

engines:
  # extra_paths:
  #   - /srv/democrai/external-engines

extractors:
  # extra_paths:
  #   - /srv/democrai/external-extractors

If the engine orchestrator uses TCP on 0.0.0.0 or on a non-loopback host, TLS is required. Service JWT authentication remains enabled for orchestrator RPCs.

Local to distributed

The same contracts can point to different backends.

A local setup can use SQLite, local media, sqlite-vec, and local graph providers. A distributed setup can move those concerns to Postgres-compatible storage, object storage, Redis-backed coordination, Milvus, Neo4j, ClickHouse, or other configured providers. Provider implementations may appear before they are certified through the current integration pass.

ConfigDeclares provider choices and model defaults.

RuntimeInitializes services through provider factories.

SDKExposes stable methods to modules and extensions.

ModuleUses capabilities without owning infrastructure wiring.

Responsibility split

Configuration is deployment behavior, not product behavior.

The boundary is useful because it keeps feature modules portable across development, desktop, server, and distributed deployments.

01

Modules consume

Modules consume SDK capabilities such as UI effects, scoped models, media, AI, tasks, and knowledge.

02

Core resolves

The core resolves configured providers and carries user, organization, module, request, and runtime context.

03

Providers implement

Providers implement the actual storage, model, extraction, graph, vector, and observability behavior.