Coverage for src / lexigram / contracts / search / types.py: 100%

1"""Search type aliases and value types. 

2 

3Canonical definitions for search domain operations. 

4""" 

5 

6from __future__ import annotations 

7 

8from dataclasses import dataclass, field 

9from typing import Any 

10 

11# Type aliases 

12DocumentData = dict[str, Any] 

13IndexSettings = dict[str, Any] 

14SearchFilters = dict[str, Any] 

15 

16 

17@dataclass(frozen=True, slots=True) 

18class SearchIndexResult: 

19 """Result of a search index operation. 

20 

21 Represents a single document found in a search index, 

22 with relevance score and search-specific metadata like highlights. 

23 

24 This is the search-layer specific result type (different from vector SearchResult). 

25 Use SearchResult from data.vector for vector database results. 

26 """ 

27 

28 id: str 

29 """Unique document identifier.""" 

30 

31 score: float 

32 """Relevance score (0.0-1.0 typical range).""" 

33 

34 data: dict[str, Any] = field(default_factory=dict) 

35 """Original indexed document data.""" 

36 

37 highlights: dict[str, str] | None = None 

38 """Search term highlights (field -> highlighted text).""" 

39 

40 

41@dataclass(frozen=True, slots=True) 

42class SearchableSpec: 

43 """Specification for search-index-based resource searching. 

44 

45 Shared across ``lexigram-admin`` (the admin resource opt-in) and 

46 ``lexigram-search`` (the index-backed execution machinery), so it lives 

47 in contracts per the shared-type rule. 

48 

49 Attributes: 

50 index_name: Name of the search index (defaults to resource name). 

51 fields: Which fields to include in the searchable document body. 

52 result_limit: Max results per query. 

53 """ 

54 

55 index_name: str | None = None 

56 fields: tuple[str, ...] = () 

57 result_limit: int = 50 

58 

59 

60__all__ = [ 

61 "DocumentData", 

62 "IndexSettings", 

63 "SearchFilters", 

64 "SearchIndexResult", 

65 "SearchableSpec", 

66]