ConditionExplanation

Explains the logic and parameters of a condition definition.

Returned by POST /conditions/explain. Deterministic given (condition_id, condition_version) — application context may influence wording but MUST NOT influence strategy type, parameter values, or the natural language summary's factual claims.

condition_idCondition Id (string)required

condition_versionCondition Version (string)required

strategy objectrequired

typerequired

Possible values: [change, composite, equals, percentile, threshold, z_score]

change

params objectrequired

change strategy parameters.

direction: 'increase' | 'decrease' | 'any' value: percentage change threshold (must be >= 0) window: lookback duration string (default '1d')

Note: parameter key is 'value' (not 'threshold' or 'cutoff').

directionChangeDirection (string)required

Possible values: [increase, decrease, any]

valueValue (number)required

Possible values: >= 0

windowWindow (string)

Default value: 1d

composite

params objectrequired

composite strategy parameters.

operator: 'AND' | 'OR' operands: list of condition_ids to evaluate (minimum 2)

Compiler enforcement rules (checked at compile time, not here):

• all operands must produce decision — equals is excluded
• composite cannot be nested inside another composite's operands
• all operand condition_ids must exist in the registry

Minimum 2 operands is enforced here at model construction time.

operatorCompositeOperator (string)required

Possible values: [AND, OR]

operandsstring[]required

Possible values: >= 2

equals

params objectrequired

equals strategy parameters.

value: the label to match labels: optional closed set of valid labels (subset of the categorical type's declared label set). When provided, 'value' must be a member of this list. Validated at compile time against the concept's declared categorical labels.

Calibration note: equals has no numeric parameter to adjust. POST /conditions/calibrate always returns no_recommendation with reason='not_applicable_strategy' for conditions using this strategy.

valueValue (string)required

labels object

anyOf

• string[]
• null

Array [

string

]

percentile

params objectrequired

percentile strategy parameters.

direction: 'top' | 'bottom' (NOT 'above'/'below') value: percentile cutoff in range [0, 100]

directionPercentileDirection (string)required

top / bottom — NOT above / below (a common source of bugs).

Possible values: [top, bottom]

valueValue (number)required

Possible values: >= 0 and <= 100

threshold

params objectrequired

threshold strategy parameters.

direction: 'above' | 'below' value: the fixed cutoff (any float — no global bounds)

Note: parameter key is 'value', NOT 'cutoff'. Fires when: direction='above' → concept_value > value direction='below' → concept_value < value

directionThresholdDirection (string)required

Possible values: [above, below]

valueValue (number)required

z_score

params objectrequired

z_score strategy parameters.

threshold: number of standard deviations required to trigger (must be > 0) direction: 'above' | 'below' | 'any' window: lookback duration string (default '30d')

Note: parameter key is 'threshold', NOT 'value' or 'cutoff'. This is different from every other strategy — z_score is the only one where the sensitivity param is called 'threshold'.

thresholdThreshold (number)required

Possible values: > 0

directionZScoreDirection (string)required

Possible values: [above, below, any]

windowWindow (string)

Default value: 30d

concept_idConcept Id (string)required

concept_versionConcept Version (string)required

natural_language_summaryNatural Language Summary (string)required

parameter_rationaleParameter Rationale (string)required

ConditionExplanation

{
  "condition_id": "string",
  "condition_version": "string",
  "strategy": {
    "type": "threshold",
    "params": {
      "direction": "above",
      "value": 0
    }
  },
  "concept_id": "string",
  "concept_version": "string",
  "natural_language_summary": "string",
  "parameter_rationale": "string"
}