hoops_ai.ml.context_layer.RelevanceWeighter

class hoops_ai.ml.context_layer.RelevanceWeighter(factors)

Bases: object

Adjusts hit scores based on metadata agreement with a query context.

When predicting a target key (e.g. “Cost”), other known attributes of the query (Material, Process, InternalFeatures) can inform which neighbors are most trustworthy. A neighbor that matches on Material AND Process should be weighted higher than one differing on both.

For categorical attributes: exact match → full boost, mismatch → no boost. For numeric attributes: proximity-based boost using a Gaussian kernel.

The adjustment is multiplicative:

adjusted_score = base_score × product(boost_per_attribute)

Parameters:

factors (dict[str, dict[str, Any]]) –

Dict mapping metadata keys to their boost configuration. Each entry is a dict with:

”weight”: float — How much this attribute matters (0.0 to 1.0).

1.0 = full match doubles the score; 0.5 = half effect.

”type”: “categorical” | “numeric” — How to compute similarity. “scale”: float (numeric only) — Gaussian kernel bandwidth.

Example

weighter = RelevanceWeighter(factors={

“Material”: {“weight”: 1.0, “type”: “categorical”}, “Process”: {“weight”: 0.8, “type”: “categorical”}, “InternalFeatures”: {“weight”: 0.5, “type”: “numeric”, “scale”: 5.0},

})

adjust_scores(hits, base_scores, target_key, query_context)

Compute adjusted scores based on metadata agreement.

Parameters:
Return type:

list[float]

classmethod fit(records, target_key, feature_keys=None, min_samples_per_group=2)

Learn importance factors from data.

Parameters:

  • records (list[dict[str, Any]]) – List of metadata dicts from indexed parts.

  • target_key (str) – The key to predict (e.g. “Cost”). Must be numeric.

  • feature_keys (list[str] | None) – Keys to evaluate as predictors. If None, uses all top-level record keys excluding target_key.

  • min_samples_per_group (int) – Minimum samples per categorical group.

Returns:

A configured RelevanceWeighter with learned factors.

Return type:

RelevanceWeighter

max_boost_for(target_key, query_context)

Return the multiplicative boost a perfect-match neighbour would receive.

For every factor key that is both known to the weighter and present in query_context (except target_key itself), a perfect match contributes (1 + weight). The product gives the ceiling against which an actual adjust_scores result can be normalised into [0, 1] — useful for nearest-neighbour-style gates that need a scale-invariant agreement signal.

Returns 1.0 when no relevant factor is present (the adjusted score then equals the raw shape score and no normalisation is needed).

Parameters:
Return type:

float

property factors: dict[str, dict[str, Any]]

The learned or manually-specified factor configuration.