config.example.yaml

# vectorless-engine example configuration.
#
# Three ways to configure the engine, in increasing priority:
#   1. YAML file   - copy this to config.yaml and edit.
#   2. Environment - VLE_* vars, dot-path flattened with underscores
#                    (e.g. server.tls.cert_file -> VLE_SERVER_TLS_CERT_FILE).
#   3. CLI flags   - mirror the YAML tree, dot-separated
#                    (e.g. --server.addr=:8080, --log.level=debug).
#
# Later layers override earlier ones on a per-key basis (not per-subtree),
# so you can ship a YAML file in the image, set secrets via env, and tweak
# individual knobs per run with flags.
#
# `vectorless-engine config print` prints the effective config with secrets
# redacted; `vectorless-engine config check` validates it and exits 0/1.

server:
  addr: ":8080"
  read_timeout: 30s
  write_timeout: 120s

  # TLS is OPT-IN. Leave both files empty to serve plaintext HTTP behind a
  # reverse proxy (Caddy, nginx, an ALB, ingress) — the recommended
  # production setup because cert rotation stays in the proxy. Set both
  # cert_file and key_file to have the engine terminate TLS directly
  # (useful for single-node / homelab / MCP-over-public-internet).
  tls:
    cert_file: ""            # path to PEM cert chain
    key_file: ""             # path to PEM private key
    min_version: "1.2"       # "1.2" | "1.3"

database:
  # Postgres connection used for documents, sections (the tree), and (if
  # queue.driver=river) the job queue.
  url: "postgres://vectorless:vectorless@localhost:5432/vectorless?sslmode=disable"
  max_conns: 10

storage:
  # Where document bytes are stored.
  # driver: local | s3
  driver: "local"

  local:
    root: "./data/documents"

  s3:
    # Works for AWS S3, Cloudflare R2, MinIO, Backblaze B2, DigitalOcean Spaces,
    # and any other S3-compatible provider — just point endpoint at their URL.
    endpoint: "http://localhost:9000"
    region: "us-east-1"
    bucket: "vectorless-docs"
    access_key: "minio"
    secret_key: "miniominio"
    use_path_style: true     # true for MinIO / R2 / most non-AWS providers

queue:
  # Where background jobs (ingest, tree-build, summarize) are scheduled.
  # driver: qstash | river | asynq
  driver: "river"

  qstash:
    # Upstash QStash — ideal for serverless hosts (Vercel, Cloudflare Workers).
    token: ""
    webhook_base_url: "https://your-engine.example.com"

  river:
    # Postgres-backed, uses database.url above. No extra infra needed.
    num_workers: 10

  asynq:
    # Redis-backed. Higher throughput when Redis is already available.
    addr: "localhost:6379"
    password: ""
    db: 0
    concurrency: 20

llm:
  # Provider used for tree construction and retrieval reasoning.
  # driver: anthropic | openai | gemini
  driver: "anthropic"

  anthropic:
    api_key: ""
    model: "claude-sonnet-4-5"
    reasoning_model: "claude-opus-4-5"   # optional override for deep-reason strategy

  openai:
    api_key: ""
    model: "gpt-4o-mini"
    reasoning_model: "gpt-4o"

  gemini:
    api_key: ""
    model: "gemini-2.0-flash"
    reasoning_model: "gemini-2.5-pro"

retrieval:
  # strategy: single-pass | chunked-tree
  strategy: "chunked-tree"

  chunked_tree:
    # Max tokens of tree view to feed a single LLM call (per subtree slice).
    max_tokens_per_call: 60000
    # Max parallel LLM calls when the tree must be split.
    max_parallel_calls: 8
    # If true, include summary-only breadcrumbs of sibling subtrees each call
    # doesn't own, so the model knows what else exists in the document.
    include_sibling_breadcrumbs: true

  # answer_span: when enabled, every section returned by /v1/query gets an
  # extra `answer_span` field carrying the verbatim quote the model judged
  # most relevant to the query, plus byte offsets back into the section's
  # content. Costs one LLM call per returned section. Opt-in by default.
  answer_span:
    enabled: false
    # Override the model used for span extraction; empty inherits the
    # request's model. Keep this on a cheap/fast model — the call is
    # short and runs once per returned section.
    model: ""
    max_concurrency: 4
    max_quote_len: 400

  # answer: /v1/answer endpoint configuration. The endpoint runs
  # retrieval + per-section span extraction + a synthesis LLM call,
  # returning {answer, citations:[{section_id, page_start, page_end, quote}]}.
  answer:
    # Override the synthesis-call model; empty inherits the request's model.
    model: ""
    max_sections: 5
    max_answer_tokens: 1024

  # planning: Phase 2.1 query planning + Phase 2.2 multi-hop decomposition.
  # When enabled, every /v1/query and /v1/answer request first issues a
  # short LLM call that returns a structured Plan (intent, entities,
  # expected document areas, multi-hop flag, sub-questions). Multi-hop
  # plans fan retrieval out one selection call per sub-question and
  # union the results.
  #
  # OPT-IN. Default disabled. Per-request `enable_planning` body field
  # overrides this block, so callers can experiment without a restart.
  # Plans are cached in a per-process LRU keyed on (query, model);
  # repeated questions don't burn extra LLM budget.
  planning:
    enabled: false
    # Override the planner's model; empty inherits the engine's
    # configured default. Point this at a small/fast model — planning
    # is a short prompt that shouldn't run on the flagship model.
    model: ""
    cache_size: 128
    # decompose: when planning runs, multi-hop plans fan retrieval
    # out per sub-question. Set false to validate the planner in
    # isolation (plan returned, but retrieval uses the original query).
    decompose: true

ingest:
  # The summarize and HyDE stages run concurrently. This caps the total
  # number of LLM calls in flight across both stages combined, so the
  # provider's per-tenant concurrency limit isn't exceeded. 0 disables
  # the global cap; default applied by the engine is 12.
  global_llm_concurrency: 12

  # HyDE candidate-question stage. For each leaf section the pipeline asks
  # the LLM to enumerate questions the section answers; those are folded
  # into the retrieval prompt at query time to widen recall on queries
  # that don't echo the section's exact wording.
  hyde:
    enabled: true
    # Override the LLM model used for HyDE; empty inherits the summary model.
    model: ""
    num_questions: 5
    concurrency: 4

log:
  level: "info"            # debug | info | warn | error
  format: "json"           # json | console