Coverage for src / lexigram / contracts / data / vector / __init__.py: 0%

1"""Vector store contracts — protocols, types, and filter primitives. 

2 

3These define the interface boundary for all vector store backends. 

4Application code depends on these protocols. Concrete implementations 

5live in ``lexigram-vector``. 

6 

7Basic Usage: 

8 ```python 

9 from lexigram.contracts.data.vector import ( 

10 VectorStoreProtocol, 

11 VectorCollectionProtocol, 

12 VectorRecord, 

13 SearchQuery, 

14 Filter, 

15 ) 

16 ``` 

17""" 

18 

19from __future__ import annotations 

20 

21from typing import TYPE_CHECKING, Any 

22 

23if TYPE_CHECKING: 

24 from lexigram.contracts.data.vector.enums import ( 

25 DistanceMetric, 

26 IndexState, 

27 IndexType, 

28 ) 

29 from lexigram.contracts.data.vector.exceptions import ( 

30 EmbeddingError, 

31 VectorError, 

32 VectorIndexError, 

33 VectorStoreError, 

34 ) 

35 from lexigram.contracts.data.vector.filters import ( 

36 Filter, 

37 FilterOperator, 

38 LogicalOperator, 

39 MetadataCondition, 

40 MetadataConditionGroup, 

41 MetadataFilter, 

42 ) 

43 from lexigram.contracts.data.vector.protocols import ( 

44 VectorCollectionProtocol, 

45 VectorStoreProtocol, 

46 ) 

47 from lexigram.contracts.data.vector.tenancy import ( 

48 TenantCollectionResolver, 

49 ) 

50 from lexigram.contracts.data.vector.types import ( 

51 CollectionConfig, 

52 CollectionInfo, 

53 DeleteResult, 

54 SearchQuery, 

55 UpsertResult, 

56 VectorRecord, 

57 ) 

58 

59_LAZY_IMPORTS: dict[str, tuple[str, str]] = { 

60 # --- Exceptions --- 

61 "VectorError": ( 

62 "lexigram.contracts.data.vector.exceptions", 

63 "VectorError", 

64 ), 

65 "VectorStoreError": ( 

66 "lexigram.contracts.data.vector.exceptions", 

67 "VectorStoreError", 

68 ), 

69 "EmbeddingError": ( 

70 "lexigram.contracts.data.vector.exceptions", 

71 "EmbeddingError", 

72 ), 

73 "VectorIndexError": ( 

74 "lexigram.contracts.data.vector.exceptions", 

75 "VectorIndexError", 

76 ), 

77 # --- Protocols --- 

78 "VectorStoreProtocol": ( 

79 "lexigram.contracts.data.vector.protocols", 

80 "VectorStoreProtocol", 

81 ), 

82 "VectorCollectionProtocol": ( 

83 "lexigram.contracts.data.vector.protocols", 

84 "VectorCollectionProtocol", 

85 ), 

86 # --- Types --- 

87 "VectorRecord": ( 

88 "lexigram.contracts.data.vector.types", 

89 "VectorRecord", 

90 ), 

91 "SearchQuery": ( 

92 "lexigram.contracts.data.vector.types", 

93 "SearchQuery", 

94 ), 

95 "SearchResult": ( 

96 "lexigram.contracts.data.vector.types", 

97 "SearchResult", 

98 ), 

99 "CollectionConfig": ( 

100 "lexigram.contracts.data.vector.types", 

101 "CollectionConfig", 

102 ), 

103 "CollectionInfo": ( 

104 "lexigram.contracts.data.vector.types", 

105 "CollectionInfo", 

106 ), 

107 "UpsertResult": ( 

108 "lexigram.contracts.data.vector.types", 

109 "UpsertResult", 

110 ), 

111 "DeleteResult": ( 

112 "lexigram.contracts.data.vector.types", 

113 "DeleteResult", 

114 ), 

115 # --- Tenancy --- 

116 "TenantCollectionResolver": ( 

117 "lexigram.contracts.data.vector.tenancy", 

118 "TenantCollectionResolver", 

119 ), 

120 # --- Enums --- 

121 "DistanceMetric": ( 

122 "lexigram.contracts.data.vector.enums", 

123 "DistanceMetric", 

124 ), 

125 "IndexType": ( 

126 "lexigram.contracts.data.vector.enums", 

127 "IndexType", 

128 ), 

129 "IndexState": ( 

130 "lexigram.contracts.data.vector.enums", 

131 "IndexState", 

132 ), 

133 # --- Filters --- 

134 "Filter": ( 

135 "lexigram.contracts.data.vector.filters", 

136 "Filter", 

137 ), 

138 "MetadataFilter": ( 

139 "lexigram.contracts.data.vector.filters", 

140 "MetadataFilter", 

141 ), 

142 "MetadataCondition": ( 

143 "lexigram.contracts.data.vector.filters", 

144 "MetadataCondition", 

145 ), 

146 "MetadataConditionGroup": ( 

147 "lexigram.contracts.data.vector.filters", 

148 "MetadataConditionGroup", 

149 ), 

150 "FilterOperator": ( 

151 "lexigram.contracts.data.vector.filters", 

152 "FilterOperator", 

153 ), 

154 "LogicalOperator": ( 

155 "lexigram.contracts.data.vector.filters", 

156 "LogicalOperator", 

157 ), 

158} 

159 

160 

161def __getattr__(name: str) -> Any: 

162 """Lazy-load symbols on first access.""" 

163 if name in _LAZY_IMPORTS: 

164 import importlib 

165 

166 module_path, attr_name = _LAZY_IMPORTS[name] 

167 module = importlib.import_module(module_path) 

168 value = getattr(module, attr_name) 

169 globals()[name] = value 

170 return value 

171 raise AttributeError(f"module {__name__!r} has no attribute {name!r}") 

172 

173 

174def __dir__() -> list[str]: 

175 """Enumerate available attributes for IDE support.""" 

176 return sorted(set(__all__) | set(_LAZY_IMPORTS.keys())) 

177 

178 

179__all__ = [ 

180 "CollectionConfig", 

181 "CollectionInfo", 

182 "DeleteResult", 

183 "DistanceMetric", 

184 "EmbeddingError", 

185 "Filter", 

186 "FilterOperator", 

187 "IndexState", 

188 "IndexType", 

189 "LogicalOperator", 

190 "MetadataCondition", 

191 "MetadataConditionGroup", 

192 "MetadataFilter", 

193 "SearchQuery", 

194 "SearchResult", 

195 "TenantCollectionResolver", 

196 "UpsertResult", 

197 "VectorCollectionProtocol", 

198 "VectorError", 

199 "VectorIndexError", 

200 "VectorRecord", 

201 "VectorStoreError", 

202 "VectorStoreProtocol", 

203]