# ---- Locale ------------------------------------------------------------
# UI / CLI language. Resolved cfg → CODEXA_LOCALE env → LANG env → "en".
# Ships catalogs for: en, es, fr, pt_BR. A sub-tag (e.g. pt_BR) falls
# back to its base (pt) when its catalog is missing. Internal log event
# keys stay English regardless.
locale: "en"

# ---- Corpus ------------------------------------------------------------
# Directories to index. Multiple roots allowed. Symlinks followed.
data_dirs:
  - "/path/to/corpus"

# ---- Vector store ------------------------------------------------------
store:
  backend: "chroma"                    # built-in backend; plugins can
                                       # register more with
                                       # codexa.store.register_store_backend
  persist_dir: "./chroma_db"
  collection_name: "documents"         # main chunk collection
  file_collection: "files"             # per-file metadata collection
  entity_collection: "entities"        # per-entity rollups
  # ROB-1: when true, an HNSW segment-corrupt error from query() raises
  # ChromaSegmentCorruptError instead of returning an empty hit list.
  # Off by default so a single bad collection doesn't take the panel down.
  raise_on_segment_corrupt: false

# ---- Embeddings --------------------------------------------------------
embeddings:
  # HF identifier OR an absolute on-disk path. Identifier → pre-cache once
  # with `codexa fetch embedding` (or opt a first run into download with
  # allow_model_download / CODEXA_ALLOW_MODEL_DOWNLOAD); subsequent loads
  # pin HF_HUB_OFFLINE=1 against the `<persist_dir>/hf_cache` snapshot.
  # Point at an absolute path for a strictly-offline first run.
  model_path: "sentence-transformers/all-MiniLM-L6-v2"
  batch_size: 32                       # encoder batch ceiling
  auto_batch: true                     # halve at ≥60% RAM (≥80% VRAM on
                                       # CUDA); double back to the ceiling
                                       # at ≤40% RAM (≤55% VRAM); floor 1.
  # "auto" probes cuda → mps → xpu → cpu. Override with "cuda"/"cuda:1"/
  # "mps"/"xpu"/"cpu". AMD ROCm rides the cuda branch. Failed probes log
  # device_probe_failed DEBUG so `--verbose` ops can tell torch-missing
  # from ROCm-broken from ipex-import-explodes.
  device: "auto"
  # Cap PyTorch's per-process VRAM allocator (0.0 < x < 1.0) so a
  # re-index can't starve the rest of the desktop of GPU memory.
  # Logged once at init as cuda_memory_capped.
  cuda_memory_fraction: 0.7
  # BLAS / tokenizer / torch intra-op cap for the main-process embedder.
  # Dominant throughput lever on CPU-only hosts; default/template value 8
  # suits a large CPU host.
  # Operator env vars (OMP_NUM_THREADS=…) win.
  main_thread_cap: 8
  # On-disk shard cache. Content-addressed; sha256(text) → vector.
  cache:
    enabled: true
    dir: "{store.persist_dir}/emb_cache"
    shards: 16

# ---- OCR ---------------------------------------------------------------
ocr:
  enabled: true
  # "both" (Paddle + Tesseract merged) | "paddle" | "tesseract".
  # Paddle adapter targets PaddleOCR 3.x (use_textline_orientation,
  # predict(path)); legacy use_gpu is gone — paddlepaddle picks
  # CPU/GPU from the installed wheel.
  engine: "tesseract"
  languages: "eng"                     # Tesseract codes (ISO 639-2/T)
  pdf_dpi: 200                         # render DPI for image-only PDF pages
  # When a PDF's text-layer averages fewer than this many chars per
  # page, fall back to inline OCR. Lower = OCR less aggressively; higher
  # = OCR more aggressively. Only consulted when ocr.enabled.
  pdf_text_threshold_chars: 512
  # Per-stream FlateDecode cap (MiB) used on retry when a PDF page blows
  # past pypdf's 75 MB default. Per-call only — global pypdf cap stays
  # safe. 4 GiB covers every legitimate textbook we've seen.
  pdf_decompress_limit_mb: 4096
  # Content-addressed OCR cache. Keyed on sha256(file_bytes) + (engine,
  # languages, pdf_dpi). Default-off; flip on for OCR-heavy corpora.
  cache:
    enabled: false
    dir: "{store.persist_dir}/ocr_cache"
    shards: 8

# ---- SVG ---------------------------------------------------------------
svg:
  # When an SVG's stdlib-XML pass returns < text_threshold_chars chars
  # AND ocr.enabled, rasterise (render_dpi) and OCR the bitmap. Needs the
  # [svg] extra (svglib + reportlab) or a system cairosvg; without one
  # the fallback is a silent no-op.
  render_fallback: true
  render_dpi: 150
  text_threshold_chars: 16

# ---- Vision (object detection) -----------------------------------------
# Appends an "[objects: …]" line to image extraction via an ONNX-Runtime
# detector. Independent of ocr.enabled (run either / both / neither).
# Operator-supplied model — no runtime fetch. Needs the [vision] extra
# (onnxruntime, no torch). Extra or model absent → silent no-op.
vision:
  enabled: false
  model_path: ""                       # "" → {persist_dir}/vision/model.onnx
  class_names_path: ""                 # "" → bundled COCO-80
  score_threshold: 0.35
  max_labels: 12

# ---- LLM ---------------------------------------------------------------
llm:
  provider: "none"                     # "none" | "ollama" | "local"
  fallback: "local"                    # retried when primary unreachable
  # Ollama (external server)
  model: "llama3"
  host: "http://localhost:11434"
  # Intra-Ollama model chain — when `model` times out/errors the
  # dispatcher walks each entry before falling over to `fallback`.
  # Each miss emits one ollama_model_failed WARNING.
  model_fallbacks: []
  # Per-Ollama-call timeout (seconds). Default 300 covers cold-start
  # weight loads on CPU-only hosts. Drop to 30–60 on fast-GPU boxes.
  # Garbage values silently fall back to default.
  timeout: 300
  # Fast /api/tags availability probe timeout. Generation still uses
  # `timeout`; raise this for slow remote Ollama hosts.
  probe_timeout: 3.0
  # Embedded llama.cpp — deterministic (temperature=0, top_k=1, fixed
  # seed). `pip install -e ".[local-llm]"`, then point `model_path` at
  # a GGUF on disk. Curated GGUFs land under `{persist_dir}/models/` via
  # `codexa fetch model --name <entry>` (override dir with $CODEXA_MODEL_DIR
  # or --out). `codexa fetch model --recommend` probes the host and
  # ✓/✗-marks every catalog entry; `--largest` downloads the biggest
  # entry that fits (size × 1.2 ≤ RAM).
  #
  # Catalog entries (8-bit / Q4_K_M GGUFs):
  #   name                      size    license               notes
  #   ------------------------  ------  --------------------  -----------------------------------------------
  #   qwen2.5-0.5b   (default)  0.4 GB  Apache-2.0            smallest / fastest first run
  #   llama-3.2-1b              0.8 GB  Llama 3.2 Community   131 K context, runs anywhere
  #   qwen2.5-1.5b              1.0 GB  Apache-2.0            balanced 32 K context
  #   qwen3-30b-a3b              19 GB  Apache-2.0            MoE (3 B active) — fastest big-class on CPU
  #   qwen3-32b                  20 GB  Apache-2.0            dense, hybrid thinking/non-thinking modes
  #   llama-3.3-70b              42 GB  Llama 3.3 Community   highest-quality dense for ≥64 GB hosts
  #   deepseek-r1-distill-70b    42 GB  MIT                   reasoning-tuned (chain-of-thought baked in)
  #   qwen2.5-72b                47 GB  Apache-2.0            multi-part download (auto-concatenated)
  #   mixtral-8x22b              85 GB  Apache-2.0            multi-part; MoE (~39 B active); RAM-hungry
  local:
    model_path: "{store.persist_dir}/models/qwen2.5-0.5b-instruct-q4_k_m.gguf"
    n_ctx: 4096                        # raise per-model when catalog suggests
    seed: 1337                         # fixed seed → reproducible answers
    max_tokens: 512
  max_summary_chars: 500               # truncate LLM-generated corpus summary

# ---- Search / retrieval ------------------------------------------------
search:
  history_turns: 6                     # 3 user + 3 assistant; 0 disables
  history_compress: false              # LLM-summarise dropped turns; opt-in
  highlight_entities: false            # bold recognised entities in passages
  passage_thumbnail_dpi: 100           # PDF page render DPI in expanders

  # Cross-encoder reranker over the retrieved top-K. Disabled by default
  # — costs ~50-200 ms per query on CPU (sub-50 ms on GPU) but catches
  # nuance the bi-encoder misses. Auto-downloads on first use.
  reranker:
    enabled: false
    model_id: "BAAI/bge-reranker-base"
    top_k_keep: 5
    device: "auto"                     # "auto" → cuda when available

  # Drop paraphrase near-duplicates after the Jaccard dedup. Bounded to
  # the over-fetched ≤30 rows. Costs one extra embed pass; set false on
  # latency-tight hosts.
  semantic_dedup:
    enabled: true
    threshold: 0.93                    # cosine ≥ this ⇒ near-duplicate

  # Pseudo-relevance feedback (Rocchio). Results merged, never replaced,
  # so PRF only ever adds recall. Costs one extra embed + store query.
  prf:
    enabled: true
    top_m: 5                           # survivors fed into the centroid
    alpha: 1.0                         # original-query weight
    beta: 0.75                         # feedback-centroid weight

  # Compound-question splitter — RRF-fuses 2–3 sub-query results.
  # User query is wrapped in <<<USER_INPUT>>> fence so a hostile
  # multi-line query can't break out of its role slot.
  query_decomp:
    enabled: false

  # HyDE — embed a hypothetical answer paragraph as a second retrieval
  # pass. Same fencing as query_decomp.
  hyde:
    enabled: false
    n: 1                               # clamped to [1, 5]

  # Conversational rewrite — when history exists and the query looks like
  # a follow-up, build a standalone query with the same prompt fences and
  # locale directive as HyDE / query_decomp.
  query_rewrite:
    enabled: false
    ab_fuse: false                     # RRF-fuse original + rewrite

  # Optional fan-out variants. All ride the same batched sub-query embed
  # + concurrent store.query path before RRF merge.
  multilingual:
    enabled: false
  query_expansion:
    enabled: false
    synonyms_path: ""                  # YAML/JSON alias map

  # FLARE — watch the streaming answer for low-confidence sentences and
  # fire additional retrieval rounds. Each trigger logs flare_retrigger
  # + flare_passages_added DEBUG events.
  flare:
    enabled: false
    min_logprob: -2.5                  # per-token logprob threshold
    max_rounds: 3                      # hard cap on re-retrieval rounds
    top_k_extra: 5                     # passages per re-retrieval

  # Offline "🧠 Passage insights" expander (LexRank TL;DR + KeyBERT
  # phrases) computed with the search embedder already in memory.
  insights:
    enabled: false
    max_sentences: 3
    top_keyphrases: 8

  # Offline encyclopedic enrichment. Tier walk: ZIM → seed → online.
  # codexa/data/wikipedia_seed*.json ships 25 English topics plus
  # localized pt/es/fr overlays.
  wikipedia:
    enabled: true
    data_dirs: []                      # extra operator-supplied seed JSONs
    zim_path: ""                       # single .zim or list of paths
    zim_dir: ""                        # glob *.zim under a folder
    online: false                      # opt-in fallback; breaks offline-first
    lang: "auto"                       # "auto" derives from cfg.locale

  # Optional hierarchical retrieval: indexer.hierarchical emits L0/L1/L2
  # rows; this stage swaps L2 child hits for their L1 parent when present.
  expand_to_parent:
    enabled: false

# ---- Metadata / sessions -----------------------------------------------
metadata:
  # Both manifest_file and sessions_file pick a backend from the suffix:
  # `.json` → JSON (full-file rewrite per save), `.db`/`.sqlite` → SQLite
  # (per-row UPSERT in one tx). On hosts without POSIX fcntl locks,
  # `.json` sessions route to a sibling `.db` automatically for
  # cross-process safety. Switch to SQLite explicitly at ~50k files /
  # 1k saved threads.
  manifest_file: "{store.persist_dir}/manifest.json"
  sessions_file: "{store.persist_dir}/sessions.json"
  index_info_file: "{store.persist_dir}/index_info.json"
  enable_entity_extraction: true
  tag_count: 50

# ---- Indexer -----------------------------------------------------------
indexer:
  # Upper bounds — effective values are cores-aware capped (chunker:
  # cores//4, floor 2, ceiling 8; OCR: 2). Over-cap values are silently
  # downscaled and emit a workers_downscaled WARNING.
  workers: 4
  ocr_workers: 2
  skip_dirs: []                        # extra dir names to skip
  # Optional ramp-up cap. 0 = process everything. Mirrors --max-files.
  max_files: 0
  # Manifest checkpoint cadence during the embed loop. Saves happen
  # every N files OR every M seconds, whichever comes first.
  checkpoint_every_files: 10
  checkpoint_every_seconds: 5.0
  # Optional L0/L1/L2 chunk tree. Default off keeps the flat chunk path.
  hierarchical:
    enabled: false

# ---- Chunking ----------------------------------------------------------
chunking:
  # Per-chunk token cap. Overlap is computed dynamically per file
  # (10% of token count, min 20). The optional hierarchical producer
  # rebuilds flat chunks into L0/L1/L2 rows when indexer.hierarchical
  # is enabled.
  chunk_size: 512

# ---- Format gates ------------------------------------------------------
formats:
  enabled: []                          # allow-list; empty = all
  disabled: []                         # deny-list (always wins)
  # When no registered extractor matches a file's extension, read its
  # bytes as UTF-8 with errors='ignore'. True is backwards-compatible
  # but unsafe on mixed-binary corpora — flip false to make unknown
  # extensions return "" instead.
  text_fallback: true
  # Cap (MiB) on the text-fallback read; a multi-GB binary under
  # data_dirs is decoded to its prefix only and logged
  # text_fallback_truncated.
  text_fallback_max_mb: 64

# ---- Plugins -----------------------------------------------------------
plugins:
  disabled: []                         # block individual plugin names
  # Cap on the timeout-dispatch thread pool. Only matters when plugins
  # opt into a `timeout_s`.
  executor_workers: 4
  # slow_threshold_ms: 1000            # WARN when a plugin hook exceeds
  # Per-plugin slices land as siblings of `disabled`:
  # plugins:
  #   word_counter:
  #     min_words: 100