Coverage for watcher/decision_engine/scoring/base.py: 100%

1# -*- encoding: utf-8 -*- 

2# Copyright (c) 2016 Intel 

3# 

4# Authors: Tomasz Kaczynski <tomasz.kaczynski@intel.com> 

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 

15# implied. 

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

17# limitations under the License. 

18 

19import abc 

20 

21from watcher.common.loader import loadable 

22 

23 

24class ScoringEngine(loadable.Loadable, metaclass=abc.ABCMeta): 

25 """A base class for all the Scoring Engines. 

26 

27 A Scoring Engine is an instance of a data model, to which the learning 

28 data was applied. 

29 

30 Please note that this class contains non-static and non-class methods by 

31 design, so that it's easy to create multiple Scoring Engine instances 

32 using a single class (possibly configured differently). 

33 """ 

34 

35 @abc.abstractmethod 

36 def get_name(self): 

37 """Returns the name of the Scoring Engine. 

38 

39 The name should be unique across all Scoring Engines. 

40 

41 :return: A Scoring Engine name 

42 :rtype: str 

43 """ 

44 

45 @abc.abstractmethod 

46 def get_description(self): 

47 """Returns the description of the Scoring Engine. 

48 

49 The description might contain any human readable information, which 

50 might be useful for Strategy developers planning to use this Scoring 

51 Engine. It will be also visible in the Watcher API and CLI. 

52 

53 :return: A Scoring Engine description 

54 :rtype: str 

55 """ 

56 

57 @abc.abstractmethod 

58 def get_metainfo(self): 

59 """Returns the metadata information about Scoring Engine. 

60 

61 The metadata might contain a machine-friendly (e.g. in JSON format) 

62 information needed to use this Scoring Engine. For example, some 

63 Scoring Engines require to pass the array of features in particular 

64 order to be able to calculate the score value. This order can be 

65 defined in metadata and used in Strategy. 

66 

67 :return: A Scoring Engine metadata 

68 :rtype: str 

69 """ 

70 

71 @abc.abstractmethod 

72 def calculate_score(self, features): 

73 """Calculates a score value based on arguments passed. 

74 

75 Scoring Engines might be very different to each other. They might 

76 solve different problems or use different algorithms or frameworks 

77 internally. To enable this kind of flexibility, the method takes only 

78 one argument (string) and produces the results in the same format 

79 (string). The consumer of the Scoring Engine is ultimately responsible 

80 for providing the right arguments and parsing the result. 

81 

82 :param features: Input data for Scoring Engine 

83 :type features: str 

84 :return: A score result 

85 :rtype: str 

86 """ 

87 

88 @classmethod 

89 def get_config_opts(cls): 

90 """Defines the configuration options to be associated to this loadable 

91 

92 :return: A list of configuration options relative to this Loadable 

93 :rtype: list of :class:`oslo_config.cfg.Opt` instances 

94 """ 

95 return [] 

96 

97 

98class ScoringEngineContainer(loadable.Loadable, metaclass=abc.ABCMeta): 

99 """A base class for all the Scoring Engines Containers. 

100 

101 A Scoring Engine Container is an abstraction which allows to plugin 

102 multiple Scoring Engines as a single Stevedore plugin. This enables some 

103 more advanced scenarios like dynamic reloading of Scoring Engine 

104 implementations without having to restart any Watcher services. 

105 """ 

106 

107 @classmethod 

108 @abc.abstractmethod 

109 def get_scoring_engine_list(self): 

110 """Returns a list of Scoring Engine instances. 

111 

112 :return: A list of Scoring Engine instances 

113 :rtype: :class: `~.scoring_engine.ScoringEngine` 

114 """ 

115 

116 @classmethod 

117 def get_config_opts(cls): 

118 """Defines the configuration options to be associated to this loadable 

119 

120 :return: A list of configuration options relative to this Loadable 

121 :rtype: list of :class:`oslo_config.cfg.Opt` instances 

122 """ 

123 return []