perda.utils.search#

pydantic model perda.utils.search.SearchResult[source]#

Bases: BaseModel

Fields:
field rank: int [Required]#

1-based position in the result list (1 = best match).

field score: float [Required]#

Relevance score (higher is better).

field var_id: int [Required]#

Internal variable ID.

field cpp_name: str [Required]#

C++ variable name used for data access.

field descript: str [Required]#

Human-readable variable description.

perda.utils.search.build_semantic_index(id_to_descript, verbose=1)[source]#

Encode every variable description into a L2-normalized and FAISS inner-product index. Cosine similarity scores range [-1, 1].

Parameters:

  • id_to_descript (dict[int, str]) – Mapping from variable ID to its human-readable description.

  • verbose (int, optional) – Verbosity level. 0 for no output, 1 or higher for status and warnings. Default is 1.

Returns:

The built index, or None if the optional dependencies or model are unavailable.

Return type:

VariableSemanticIndex | None

perda.utils.search.keyword_score(query_terms, normalized_text)[source]#

Score normalized variable text against query terms using fuzzy partial matching.

Parameters:

  • query_terms (list[str]) – Normalized, whitespace-split query terms.

  • normalized_text (str) – A variable’s normalized name and description, from a VariableKeywordIndex.

Returns:

Mean fuzzy match score in [0, 1].

Return type:

float

Notes

Scoring each term separately makes matching order-independent, so “front wheel speed” still matches a variable stored as “wheel speeds front right”.

perda.utils.search.search(data, query, top_n=10)[source]#

Search telemetry variables, print the top matches, and return them.

Parameters:

  • data (SingleRunData) – Parsed CSV telemetry data.

  • query (str) – Free-text search query (e.g. “front wheel speed”).

  • top_n (int, optional) – Maximum number of results to return and display. Default is 10.

Returns:

Top matches in descending relevance order (at most top_n entries).

Return type:

list[SearchResult]

Notes

Uses semantic vector search when data.semantic_index was built at construction time, and fuzzy keyword matching otherwise.

Examples

>>> results = search(aly.data, "front wheel speed")
>>> names = [r.cpp_name for r in results]