Skip to main content

​
Runtime Contract

Last Updated: 2026-04-09

​
Purpose

Define which file is authoritative for each runtime concern. This file is for engineering only. It prevents duplicated logic across config files and prompt files.

​
Source of Truth by Concern

​
1. Model invocation

Authoritative file:
  • model_config.json
Includes:
  • provider
  • model name
  • temperature
  • max tokens
  • top_p

​
2. Prompt assembly

Authoritative file:
  • model_config.json
Includes:
  • instruction file order
  • whether conversation memory is included in prompt
  • max history turns included in prompt

​
3. Retrieval behavior

Authoritative file:
  • retrieval_config.json
Includes:
  • intent classification
  • query rewrite
  • metadata prefiltering
  • hybrid search
  • reranking
  • conflict detection
  • top-k selection
  • confidence thresholds
  • follow-up trigger rules
  • escalation trigger rules
  • retrieval logging

​
4. Knowledge and behavior instructions

Authoritative files:
  • system_behavior.md
  • audience_rules.md
  • advisor_behavior.md
  • response_rules.md
  • escalation_rules.md
  • retrieval_rules.md
These files define assistant behavior and reasoning constraints for the model. They do not define backend runtime logic or override runtime config.

​
5. Knowledge content

Authoritative location:
  • /knowledge/**
These files define product logic, policy, UI, datasets, and routing content. They do not define retrieval pipeline code behavior unless explicitly copied into runtime config.

​
Precedence Rules

If two sources overlap, use this order:
  1. Runtime contract
  2. JSON runtime config
  3. Prompt instruction files
  4. Retrieved knowledge chunks
Additional rule:
  • Prompt files may shape wording and behavior.
  • Prompt files must not be parsed as backend config.
Additional rule:
  • Retrieved knowledge may answer user questions.
  • Retrieved knowledge must not change runtime pipeline settings.

​
Engineering Rule

Do not define the same operational setting in both:
  • model_config.json
  • retrieval_config.json
If a setting affects retrieval selection, ranking, confidence, follow-up triggering, escalation triggering, conflict handling, or retrieval logging:
  • it belongs in retrieval_config.json
If a setting affects model call parameters or prompt assembly:
  • it belongs in model_config.json