07 Configuration

Configuration

The corpus config (config/<name>.yaml): every field, defaults, and the traps that were measured the hard way. Template: examples/ragraf.example.yaml.

---

Creating a config

Don't hand-write it from scratch. init inspects the directory and derives languages, includes, excludes and thresholds from actual contents:

ragraf init C:\work\myproject        # prints the created config path

Then review two lists — include and exclude: they decide what lands in the index. Pay special attention to secret-bearing paths (config.local.*, .env, keys) — they must be in secrets_exclude.

Configs live in config/ — machine-local, git-ignored by design (.gitignore pins /config/ with a leading slash so test fixtures under tests/fixtures/proj/config/ are not caught — verified with git check-ignore -v).

Full field reference

project: myproject                  # display name (required)
root: C:/path/to/your/project       # corpus root (required; must exist)

languages

Tree-parsed (graph nodes+edges), 16: php · python · javascript · typescript · java · csharp · c · cpp · ruby · lua · go · perl · bash · powershell · css · html. Text-attached (searchable, no nodes), 10: markdown · sql · yaml · json · toml · ini · xml · rst · batch · text.

If the project has .ps1/.sh/.bat scripts or .cs/.py/.pl code — make sure the language is listed, otherwise those files are silently not indexed. init fills this from actual contents.

include / exclude

Glob masks relative to root. The base exclusion list (VCS, dependencies, build output, caches, .ragraf/ itself) ALWAYS applies — your exclude entries are added to it, never replace it.

Supported glob syntax (util.py:_translate): ** (any dirs) · * (within a segment) · ? (one char) · [...] (sets). Directory pruning: a pattern ending /** also prunes traversal at the prefix (performance).

⚠️ Case sensitivity trap (known defect E-01 / roadmap R-CORE-1). Matching is case-sensitive including on Windows: **/cache/** catches src/cache/ but not src/Cache/. Until fixed: list both cases when in doubt, and after any exclusion edit verify the file count via status before/after (recipe: Troubleshooting §4).

secrets_exclude

Files matching these masks are never opened: not indexed, not chunked, not embedded, not logged. Exclusion-only — no «masking» of values anywhere (NFR-3). Verification: pattern search across all three stores + logs must yield 0 (test M3-T2).

secrets_exclude:
  - "**/*.local.php"
  - "**/.env"
  - "**/*.pem"

db

db:
  enabled: false                    # schema layer from migrations/*.sql
  # dsn_from: "src/Core/Config.php" # WHERE credentials are referenced —
  #                                 # only the FACT of the reference is indexed, never values
  # schema_source: ["information_schema", "db/migrations/*.sql"]

The schema stage reads migrations, not the live DB — indexing must work without DBMS access (that is what made write_check possible pre-runtime).

embedding

embedding:
  model: sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
  dim: 384                # MUST match the model — a probe verifies at load; mismatch refuses
  batch_size: 64
  use_gpu: false          # GPU path needs torch + sentence-transformers (NOT declared deps — see below)
  device: auto

• Model downloads once (~240 MB) at the first vector indexing → ~/.ragraf/models; override with RAGRAF_MODEL_CACHE. Read operations never download.
• Multilingual model chosen deliberately: code identifiers are English, comments/docs may not be.
• Vectors are not normalized by this model (norm ≈ 3.5) — scores are computed via exact cosine with norms (the score = 1 − distance shortcut silently returned 0.000 for everything — article defect №1).
• GPU caveat: use_gpu: true requires sentence-transformers + torch (~2.5 GB), which are not in dependencies/extras (defect E-05, roadmap R-PKG-1). Break-even thresholds: ~1800 texts (vectors), ~5000 vertices (graph algorithms) — below them CPU wins because GPU map preparation costs ~15 s once. The compute state always carries the actual reason; don't lower thresholds «to force the GPU».

chunking

chunking:
  by_symbol: true         # chunks follow symbol boundaries
  max_chunk_lines: 120    # window cap for functionless/giant files (pilot had a 9222-line file)
  min_chunk_lines: 3

Procedural files without symbols are cut into windows; an 11 331-token mega-chunk (article defect №3) matched everything weakly and polluted search — chunk-size distribution is now a quality indicator in the admin panel.

index

index:
  retain_revs: 3              # revisions kept in stores; rotated ones are cleaned,
                              # but rev_history + drift_archive remain FOREVER
  batch_size: 2000
  joern_enabled: true         # CPG layer (needs Java+Joern; absent → degraded, not broken)
  joern_server: true          # persistent Joern server mode
  joern_server_port: 9500
  joern_heap_gb: 8            # JVM limit; single source of truth — env RAGRAF_JOERN_HEAP_GB only overrides.
                              # Passed as -J-Xmx8g (the '=' form is rejected by the launcher; JAVA_OPTS never arrives)
  reindex_after_changes: 5    # guard thresholds (accumulated ledger entries)
  full_reindex_after_changes: 20
  reindex_interval_minutes: 15

Threshold semantics (derived from measured costs — scan 0.16 s vs no-CPG index 5.57 s vs full 20.81 s on a 124-file corpus): 0 edits → nothing; 1–19 → fast reindex; 20+ or older than 15 min → full. Consistency is validated on write: full ≤ fast is rejected (a full-rebuild threshold below the fast one would make the fast mode unreachable — defect found by the panel's validation, settings.py:validate).

Global settings (admin panel / settings.json)

Machine-level thresholds (same three reindex knobs + category overrides) are editable through the Admin Panel — validated (bounds, enums, cross-field consistency) and, for project configs, written line-wise with comments preserved and a timestamped .bak backup. Changes apply at the next freshness check; the current revision never mutates.

Note: the global settings store currently writes without a backup/atomic-replace (defects C-03/E-06, roadmap R-SEC-3).

Environment variables

Variable	Effect
RAGRAF_MODEL_CACHE	embedding model cache directory
RAGRAF_MODEL_CACHE_FORCE	force cache re-validation
RAGRAF_DEBUG=1	re-raise exceptions instead of exit codes (tracebacks)
RAGRAF_TASK	task label for usage telemetry
RAGRAF_JOERN_HOME · RAGRAF_JAVA_HOME	external layer locations (else .tools/joern-cli, .tools/jdk)
RAGRAF_JOERN_HEAP_GB	overrides index.joern_heap_gb
RAGRAF_PHP_BIN*	PHP interpreter for php2cpg (*roadmap R-CORE-2; today discovery is PATH + two hardcoded C:/tools/... fallbacks — defect E-02)

Validation behavior

config.load() fails loudly with typed reasons (ConfigError): missing file · broken YAML · non-mapping root · missing project · nonexistent root. The CLI turns these into a hint (exit 2), never a traceback — an agent must see «tool says what to do», not «tool is broken».

---

Next: CPG & Joern Layer →