hoops_ai.ml.context_layer.ContextProvider

class hoops_ai.ml.context_layer.ContextProvider

Bases: ABC

describe_for(part_ids)

Summarize key availability across part_ids.

Issues a single get_contexts() call and aggregates {observed, missing, coverage} per top-level key.

coverage = observed / len(part_ids). Ids that the store does not resolve count as missing for every key (consistent with get_contexts omitting unknown ids).

Partners with a cheaper schema endpoint can override this method and skip the get_contexts round-trip entirely.

Parameters:

part_ids (Sequence[str])

Return type:

dict[str, dict]

abstract get_contexts(part_ids)

Return {part_id: attribute_dict} for ids that resolve.

Missing ids must be omitted from the result (not returned with None). Each value is a free-form dict whose top-level keys match the keys passed to ContextPredictor.infer(..., keys=[...]).

Implementations must treat this as the primary API and issue a single batched call against the backend — not a loop.

Parameters:

part_ids (Sequence[str])

Return type:

Mapping[str, dict]

list_numeric_keys()

Return the metadata keys that should be treated as numeric.

ContextPredictor consults this list to route un-mapped keys to its numerical rule. Keys not returned here are treated as categorical. The default returns () (everything is categorical) so existing partner subclasses keep working unchanged; subclasses with a real schema should override.

Per-key rules supplied to ContextPredictor always win over this list, so callers can still override on a per-call basis without changing the provider.

Return type:

Sequence[str]

abstract set_contexts(updates)

Persist one update per part_id.

Merge semantics, durability, and authentication are the implementation’s choice. The predictor never calls this method.

Parameters:

updates (Mapping[str, dict])

Return type:

None