`nexyron.lens_rule_run_many`

Description

nexyron.lens_rule_run_many executes a saved Lens predictive rule ensemble for many subjects. It returns one canonical prediction per subject and target feature, repeated on the corresponding rule rows so callers can inspect the supporting evidence.

The model can be selected by lens, by predictive-model report artifact through report, or directly through predictive_model_json.

Parameters

• lens or lenses: Lens name or names whose latest lens_predictive_model artifact should run.
• report: Predictive-model report artifact name.
• predictive_model_json: Raw predictive-model JSON.
• target_abstraction: Optional target abstraction filter.
• target_features: Optional target-feature allow-list.
• target_values: Optional target-value allow-list.
• subject_ids: Optional explicit subject ids. Omit it to evaluate subjects with required materialized features. When a valid target retains zero predictive rules, explicit subjects receive unclassified decisions with assignment_reason: no_selected_predictive_rules.
• rule_ids: Optional selected-rule allow-list.
• scenario, at, system_at: Optional abstraction scenario and temporal cutoffs.

Output columns

• subject_id, subject_key
• target_abstraction, target_feature
• predicted_target, prediction_confidence, prediction_margin
• confidence_tier_id, confidence_tier_name, assignment_reason
• matched_rule_count, matched_evidence_family_count
• best_rule_id, best_rule_score
• rule_id, rule_target_value, rule_weight, passed
• matched_condition_count, condition_count
• confidence, support, support_ratio, reliability
• accelerator_target, accelerator_reason
• lens, predictive_model_report

Prediction contract

Lens training retains up to 100 useful separability findings per target. Target bucket boundaries and separability conditions are derived from training subjects only. Candidate rules are replayed only on that target's model-selection split. A rule remains eligible when its observed model-selection accuracy beats the target-value prior. Its weight is then conservatively shrunk using the 95% Wilson lower bound, validation sample size, coverage, support, snapshot stability, and source quality; a small promising rule is therefore retained at low strength instead of being mistaken for either certainty or no evidence. Exact duplicates and near-identical same-target rules are removed. Greedy forward selection plus backward pruning chooses at most 100 rules per target using population accuracy lower bound, macro F1, balanced accuracy, and coverage. Selection may retain zero rules only when no eligible candidate improves on abstention.

The final ensemble is measured once on the untouched final-test split. This final test is not used for rule weighting or selection.

At execution time, rules remain grouped by (target_abstraction, target_feature). Passed-rule weights vote for actual target values; rules for another target can never participate in that vote. The winning target is the value with the largest total selected weight. Confidence combines absolute corroborating evidence strength with the winner's relative vote share, so one weak rule does not become a high-confidence result merely because no competing rule matched. If no rule matches, the model abstains and returns unclassified with an empty predicted_target.

The confidence tiers are downstream labels, not prediction outcomes:

• confirmed: high confidence and margin, at least two winning rules, and at least two independent evidence families.
• action: sufficient confidence and margin for prioritized review.
• monitor: directional evidence below the action threshold.
• baseline: the predicted value is the model's observed baseline target and clears its confidence threshold.
• unclassified: no selected rule matched.

Data-tab example

CALL nexyron.lens_rule_run_many({
  lens: 'Retention Lens',
  target_abstraction: 'Member',
  subject_ids: $subject_ids
})
YIELD lens,
      target_abstraction,
      target_feature,
      subject_id,
      predicted_target,
      prediction_confidence,
      prediction_margin,
      confidence_tier_id,
      confidence_tier_name,
      assignment_reason,
      matched_rule_count,
      matched_evidence_family_count,
      best_rule_id,
      best_rule_score,
      rule_id,
      rule_target_value,
      rule_weight,
      passed,
      matched_condition_count,
      condition_count,
      confidence,
      support_ratio,
      reliability
RETURN lens,
       target_abstraction,
       target_feature,
       subject_id,
       predicted_target,
       prediction_confidence,
       prediction_margin,
       confidence_tier_id,
       confidence_tier_name,
       assignment_reason,
       matched_rule_count,
       matched_evidence_family_count,
       best_rule_id,
       best_rule_score,
       rule_id,
       rule_target_value,
       rule_weight,
       passed,
       matched_condition_count,
       condition_count,
       confidence,
       support_ratio,
       reliability

Group by (subject_id, target_feature) when a caller needs one prediction row. The Data tab does this and renders one actual predicted value per target column.

Accelerator behavior

The procedure reads each required materialized feature stream once, lowers the subject/rule/condition grid into typed arrays, and submits bounded batches to the existing accelerator boundary. Categorical and numeric batches may use Metal/GPU when the configured runtime selects it. The Metal numeric kernel compares ordered IEEE-754 f64 bit representations, preserving exact range and threshold boundaries. accelerator_target and accelerator_reason expose the selected path on every returned row.

Limitations

• The procedure executes a saved model; it does not train or repair feature contracts.
• Unsupported operators and rules without executable conditions are skipped.
• A subject needs materialized values for every condition in a matching rule.
• Prediction confidence is evidence strength, not a causal probability.