Coverage for sources/librovore/interfaces.py: 58%

1# vim: set filetype=python fileencoding=utf-8: 

2# -*- coding: utf-8 -*- 

3 

4#============================================================================# 

5# # 

6# Licensed under the Apache License, Version 2.0 (the "License"); # 

7# you may not use this file except in compliance with the License. # 

8# You may obtain a copy of the License at # 

9# # 

10# http://www.apache.org/licenses/LICENSE-2.0 # 

11# # 

12# Unless required by applicable law or agreed to in writing, software # 

13# distributed under the License is distributed on an "AS IS" BASIS, # 

14# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 

15# See the License for the specific language governing permissions and # 

16# limitations under the License. # 

17# # 

18#============================================================================# 

19 

20 

21''' Common enumerations and interfaces. ''' 

22 

23 

24from . import __ 

25 

26 

27class DisplayFormat( __.enum.Enum ): 

28 ''' Enumeration for CLI display formats. ''' 

29 

30 JSON = 'json' 

31 Markdown = 'markdown' 

32 

33 

34class FilterCapability( __.immut.DataclassObject ): 

35 ''' Describes a filter supported by a processor. ''' 

36 

37 name: str 

38 description: str 

39 type: str # "string", "enum", "boolean" 

40 values: __.typx.Optional[ list[ str ] ] = None # For enums 

41 required: bool = False 

42 

43 

44class ProcessorGenera( __.enum.Enum ): 

45 ''' Processor types/genera. ''' 

46 

47 Inventory = 'inventory' 

48 Structure = 'structure' 

49 

50 

51 

52class MatchMode( str, __.enum.Enum ): 

53 ''' Different term matching modes. ''' 

54 

55 Exact = 'exact' 

56 Similar = 'similar' 

57 Pattern = 'pattern' 

58 

59 

60class ContentExtractionFeatures( str, __.enum.Enum ): 

61 ''' Content extraction capability features. ''' 

62 

63 Signatures = 'signatures' # Function/class signatures 

64 Descriptions = 'descriptions' # Descriptive content and documentation 

65 Arguments = 'arguments' # Individual parameter documentation 

66 Returns = 'returns' # Return value documentation 

67 Attributes = 'attributes' # Class and module attribute docs 

68 CodeExamples = 'code-examples' # Code blocks with language information 

69 CrossReferences = 'cross-references' # Links and references to other docs 

70 Navigation = 'navigation' # Navigation context extraction 

71 

72 

73class SearchBehaviors( __.immut.DataclassObject ): 

74 ''' Search behavior configuration for the search engine. ''' 

75 

76 match_mode: MatchMode = MatchMode.Similar 

77 similarity_score_min: int = 50 

78 contains_term: __.typx.Annotated[ 

79 bool, 

80 __.ddoc.Doc( 

81 "Enable substring matching in Exact and Similar modes. " 

82 "When enabled, allows terms to match as substrings." ), 

83 ] = True 

84 case_sensitive: __.typx.Annotated[ 

85 bool, 

86 __.ddoc.Doc( 

87 "Enable case-sensitive matching. When False, " 

88 "performs case-insensitive matching (default)." ), 

89 ] = False 

90 

91 

92_search_behaviors_default = SearchBehaviors( ) 

93_filters_default = __.immut.Dictionary[ str, __.typx.Any ]( ) 

94 

95 

96class ProcessorCapabilities( __.immut.DataclassObject ): 

97 ''' Complete capability description for a processor. ''' 

98 

99 processor_name: str 

100 version: str 

101 supported_filters: list[ FilterCapability ] 

102 results_limit_max: __.typx.Optional[ int ] = None 

103 response_time_typical: __.typx.Optional[ str ] = None # "fast", etc. 

104 notes: __.typx.Optional[ str ] = None 

105 

106 def render_as_json( self ) -> dict[ str, __.typx.Any ]: 

107 ''' Renders capabilities as JSON-compatible dictionary. ''' 

108 return { 

109 'processor_name': self.processor_name, 

110 'version': self.version, 

111 'supported_filters': [ 

112 { 

113 'name': filter_cap.name, 

114 'type': filter_cap.type, 

115 'required': filter_cap.required, 

116 'description': filter_cap.description, 

117 } 

118 for filter_cap in self.supported_filters 

119 ], 

120 'results_limit_max': self.results_limit_max, 

121 'response_time_typical': self.response_time_typical, 

122 'notes': self.notes, 

123 } 

124 

125 def render_as_markdown( self ) -> tuple[ str, ... ]: 

126 ''' Renders capabilities as Markdown lines for display. ''' 

127 lines = [ f"**Version:** {self.version}" ] 

128 if self.results_limit_max: 

129 lines.append( f"**Max results:** {self.results_limit_max}" ) 

130 if self.response_time_typical: 

131 lines.append( f"**Response time:** {self.response_time_typical}" ) 

132 if self.notes: 

133 lines.append( f"**Notes:** {self.notes}" ) 

134 if self.supported_filters: 

135 lines.append( "" ) 

136 lines.append( "**Supported filters:**" ) 

137 for filter_cap in self.supported_filters: 

138 filter_line = f"- `{filter_cap.name}` ({filter_cap.type})" 

139 if filter_cap.required: 

140 filter_line += " *required*" 

141 if filter_cap.description: 

142 filter_line += f": {filter_cap.description}" 

143 lines.append( filter_line ) 

144 return tuple( lines ) 

145 

146 

147class StructureProcessorCapabilities( __.immut.DataclassObject ): 

148 ''' Capability advertisement for structure processors. ''' 

149 

150 supported_inventory_types: frozenset[ str ] 

151 content_extraction_features: frozenset[ ContentExtractionFeatures ] 

152 confidence_by_inventory_type: __.immut.Dictionary[ str, float ] 

153 

154 def get_confidence_for_type( self, inventory_type: str ) -> float: 

155 ''' Gets extraction confidence for inventory type. 

156 

157 The confidence score (0.0-1.0) indicates how well this processor 

158 can extract content from the inventory type. Used for processor 

159 selection when multiple processors support the same type. 

160 ''' 

161 return self.confidence_by_inventory_type.get( inventory_type, 0.0 ) 

162 

163 def supports_inventory_type( self, inventory_type: str ) -> bool: 

164 ''' Checks if processor supports specified inventory type. ''' 

165 return inventory_type in self.supported_inventory_types