Skip to main content

Rules

ai_core.entities.RuleEntity represents a conditional configuration constraint. Every IF condition must match before the THEN requirement applies. The rule type determines the requirement for the THEN list. Neither object accepts a configurable operator.

Schema​

FieldMeaning
codeSource rule code, when available
rule_typeRequired inclusion, exclusion or only_one_of
rule_ifOrdered IF parts, each with feature_code and negated; empty for only_one_of
rule_thenOrdered THEN parts, each with feature_code
validityNonempty list of date intervals; a slice with null bounds means all time

rule_if and rule_then are lists and default to empty. Neither part accepts an operator field. Missing, null, or unsupported rule types fail validation. negated defaults to false; null is invalid. Array order is preserved.

The consolidated tier resolves both lists against the feature catalog through a foreign key and writes the matched ids to rule_if_feature_ids and rule_then_feature_ids. An id list names the features a clause mentions and states no polarity, which negated on the IF part supplies.

Conditions and consequences​

Every IF part must be satisfied: a non-negated feature must be selected, and a negated feature must be absent. Here A, B, and C represent feature codes:

A AND B AND NOT C

When the conditions match:

Rule typeTHEN feature codes D, E meanEquivalent requirement
inclusionSelect at least one of D and ED OR E
exclusionSelect neither D nor ENOT D AND NOT E
only_one_ofSelect at most one of D and ENOT (D AND E)

“At least one” permits both features unless another constraint forbids that combination. Excluding D and E forbids each feature individually; it does not merely forbid selecting them together. A excludes [D, E] therefore has the same allowed configurations as A excludes D plus A excludes E.

For only_one_of, rule_then names a set rather than a consequence. The rule permits a configuration to hold no more than one of its codes. Its rule_if must be empty, and a rule that names an IF part fails validation. The restriction therefore applies to every configuration under the rule's model key.

only_one_of [D, E, F] permits the same configurations as D excludes [E, F], E excludes [D, F] and F excludes [D, E] together. A consumer reads the set from the one row instead of reassembling it from the three exclusions.

An only_one_of limits how many of its codes are selected and never requires one. An inclusion and an only_one_of over the same codes together require exactly one of them. The inclusion holds whatever IF parts scope the requirement; the only_one_of applies under the model key alone.

For matched IF parts, the truth table is:

D selectedE selectedinclusion satisfiedexclusion satisfiedonly_one_of satisfied
NoNoNoYesYes
YesNoYesNoYes
NoYesYesNoYes
YesYesYesNoNo

When IF does not match, this rule imposes no THEN requirement. An empty IF list matches unconditionally. An empty inclusion THEN list cannot be satisfied when IF matches; an empty exclusion THEN list imposes no restriction. An only_one_of THEN list of fewer than two codes permits every configuration, because no pair of its codes can conflict.

The ingestion schema stores these constraints. It does not evaluate a configuration or change its selected features.

Example​

This rule says: if A is selected and B is absent, require C or D.

{
"code": "example",
"rule_type": "inclusion",
"rule_if": [
{"feature_code": "A", "negated": false},
{"feature_code": "B", "negated": true}
],
"rule_then": [
{"feature_code": "C"},
{"feature_code": "D"}
],
"validity": [{"valid_from": null, "valid_to": null}]
}

Validity​

Each ValiditySlice contains nullable valid_from and valid_to date bounds. A null bound is unrestricted. A rule applies when the date falls within at least one slice. Omitted or empty validity normalizes to one slice with both bounds null, representing all time. Invalid dates and reversed bounds fail validation. The interval belongs to the whole rule; individual parts have no timing fields.

Source references and enrichment​

The common schema holds feature_code references. Source-specific transformed schemas can retain OEM code references, including family codes and codes absent from the feature catalog. Enrichment rewrites family references into their member codes before rules enter consolidation, and the consolidated foreign key resolves the codes into ids.

A family reference denotes the selection of a member of that family. Family expansion must preserve the fixed IF and THEN semantics:

Reference positionExpansion
Positive IF familySeparate rules, one for each member condition
Negated IF familyEvery member appears as a negated condition
Inclusion THEN familyAll members become alternatives in the THEN list
Exclusion THEN familyAll members appear in the forbidden THEN list
only_one_of THEN familyAll members appear in the THEN list

For example, if family F contains A and B, F requires C becomes A requires C and B requires C. Putting A and B together in one IF list would require both and change the meaning. Multiple positive family conditions produce one rule for each combination of member conditions.

Expansion alone does not limit selection to one feature per family or require a family selection. Where a family's members cannot be selected together, an only_one_of over its member codes states the restriction.

Unknown-reference handling depends on the catalog policy. Treating an absent reference as unselectable affects the whole rule: an unknown positive condition makes IF false, while an unknown negative condition is satisfied. Each source rule needs a recorded outcome so discarded rules remain traceable.

When a source treats absent codes as unselectable, discard a source rule when all its THEN codes are absent from the catalog for its model and trim. Treat it as inapplicable to that model and trim. Do not preserve an empty inclusion or infer an exclusion of its subject.

Consolidation​

Rules are optional in ConsolidatedComponent. Omitting its rules block builds no rules asset. A configured rules entity receives rule_id using its key_fields; each pipeline configures matching and model foreign keys. Foreign keys may only target entities configured in the same component.

Rule parts hold feature_code values, and the foreign key resolves them into rule_if_feature_ids and rule_then_feature_ids. The dependency graph is per entity, so feature consolidation produces the feature catalog used by rule enrichment. Rule consolidation then consumes the enriched rules. See ConsolidatedComponent for configuration and Foreign Keys for reference resolution.