Configure

Overview & example

Required: qllm.preset.yaml + qllm.catalog.yaml. Optional: qllm.config.yaml, qllm.env.yaml, qllm.access.yaml. Secrets are names of env vars (*Env), never the secret text in YAML.

my-project/
  qllm.preset.yaml
  qllm.catalog.yaml
  qllm.config.yaml    # optional
  qllm.env.yaml       # optional (local)
  qllm.access.yaml    # optional (per-app keys)

./qllm validate --config-dir ./my-project
./qllm serve --http --config-dir ./my-project

Worked example: warehouse DB + stock API

Postgres holds product master data; a REST inventory service exposes GET /v1/stock. You only publish the fields the agent may see.

# qllm.preset.yaml (excerpt)
protocolVersion: "0.2.0"
project: warehouse
limits:
  maxSyncMs: 15000      # ms  (~15 s total)
  maxSourceMs: 12000    # ms  (~12 s per source)
  defaultLimit: 100     # rows
  maxLimit: 1000        # rows
  readOnly: true
sources:
  - id: warehouse_pg
    type: postgres
    connection:
      hostEnv: QLLM_PG_HOST
      port: 5432
      database: warehouse
      userEnv: QLLM_PG_USER
      passwordEnv: QLLM_PG_PASSWORD
      sslMode: require

  - id: stock_api
    type: rest
    connection:
      baseUrlEnv: QLLM_STOCK_API_BASE
      auth:
        type: bearer
        tokenEnv: QLLM_STOCK_API_TOKEN
    options:
      timeoutMs: 10000   # ms
      resources:
        stock:
          list:
            method: GET
            path: /v1/stock
            queryParams: [sku, warehouse_id, limit, offset]
            itemsKey: data
          getById:
            method: GET
            path: /v1/stock/{sku}
            itemsKey: data

# qllm.catalog.yaml (excerpt)
protocolVersion: "0.2.0"
project: warehouse
entities:
  - name: products
    source: warehouse_pg
    binding: { kind: table, schema: warehouse, table: products }
    fields:
      - { name: sku, physical: sku, type: string }
      - { name: title, physical: title, type: string }
      - { name: weight_kg, physical: weight_kg, type: number }

  - name: stock_levels
    source: stock_api
    binding: { kind: rest_resource, resource: stock }
    fields:
      - { name: sku, physical: sku, type: string }
      - { name: qty, physical: qty, type: number }
      - name: location
        physical: location
        type: json
        shape: "{aisle, bin}"
      - name: tags
        physical: tags
        type: json
        shape: "string[]"
      - name: warehouse_id
        physical: warehouse_id
        type: string
        fromFilter: true

• json Nested objects/arrays: one top-level field with type: json + optional shape (decision D22). REST does not resolve dotted paths like location.aisle.
• fromFilter API takes a filter key but omits it in the body → set fromFilter: true (decision D20). Needs a top-level eq or the query is INVALID_IR.
• itemsKey When the body is { "data": [ … ] }, set itemsKey: data on the REST operation.

Draft helpers: catalog introspect (SQL) and catalog from-openapi (REST). Always review before serve.

Preset & catalog fields

Logical ids (sources[].id, entity/field names): ^[a-z][a-z0-9_]*$. Extra keys on closed objects → reject.

qllm.config.yaml

Optional. Only the serve key. Precedence: secure defaults → this file → CLI flags. If you set authTokenEnv, that env var must be non-empty or serve refuses to start.

serve:
  addr: "127.0.0.1:8088"
  mcpAddr: "127.0.0.1:8089"
  authTokenEnv: "QLLM_AUTH_TOKEN"
  insecureBind: false
  cors:
    origins: []

CLI overrides: --addr, --mcp-addr, --auth-token-env, --insecure-bind, --cors-origin (repeatable).

Optional: qllm.access.yaml

Replaces the single Bearer token with per-app keys and tables. Not part of qllm.config.yaml, but often configured next to it. Row scope comes from the credential (decision D21). Details: multi-user-safety.md.

apps:
  - name: inventory-agent
    key: ${QLLM_INVENTORY_AGENT_KEY}
    tables: [products, stock_levels]

qllm.env.yaml

Optional seed file. Required shape: root key env with at least one entry. Used when the process does not already have the variable set — a non-empty process / Secret value wins and is not overwritten.

# qllm.env.yaml — local / compose style
env:
  QLLM_AUTH_TOKEN: ${QLLM_AUTH_TOKEN}
  QLLM_PG_HOST: postgres
  QLLM_PG_USER: qllm
  QLLM_PG_PASSWORD: ${QLLM_PG_PASSWORD}
  QLLM_STOCK_API_BASE: http://inventory:8080
  QLLM_STOCK_API_TOKEN: ${QLLM_STOCK_API_TOKEN}

Every *Env name in the preset (and authTokenEnv in config) must resolve at serve time. Hostnames like postgres are fine for Compose DNS; passwords should stay as ${…} injected by the environment.

Prefer exporting vars in the shell or orchestration for production. This file is a convenience for local layouts — see environments.md.