1"""Abstract base class for prompt libraries.

2

3 This module defines the interface that all prompt library implementations must follow.

4"""

5

6 from abc import ABC, abstractmethod

7 from typing import Any, Dict, List

8

9 from .types import PromptTemplateDict, MessageIndex, RAGConfig

10

11

12 class AbstractPromptLibrary(ABC):

13 """Abstract base class for prompt library implementations.

14

15 All prompt libraries (filesystem, config, composite, etc.) must implement

16 this interface to provide consistent access to prompts, message indexes,

17 and RAG configurations.

18 """

19

20 # ===== System Prompts =====

21

22 @abstractmethod

23 def get_system_prompt(

24 self,

25 name: str,

26 **kwargs: Any

27 ) -> PromptTemplateDict | None:

28 """Retrieve a system prompt template by name.

29

30 Args:

31 name: System prompt identifier

32 **kwargs: Additional library-specific parameters

33

34 Returns:

35 PromptTemplateDict if found, None otherwise

36 """

37 pass

38

39 @abstractmethod

40 def list_system_prompts(self) -> List[str]:

41 """List all available system prompt names.

42

43 Returns:

44 List of system prompt identifiers

45 """

46 pass

47

48 # ===== User Prompts =====

49

50 @abstractmethod

51 def get_user_prompt(

52 self,

53 name: str,

54 **kwargs: Any

55 ) -> PromptTemplateDict | None:

56 """Retrieve a user prompt template by name.

57

58 Args:

59 name: User prompt identifier

60 **kwargs: Additional library-specific parameters

61

62 Returns:

63 PromptTemplateDict if found, None otherwise

64 """

65 pass

66

67 @abstractmethod

68 def list_user_prompts(self) -> List[str]:

69 """List available user prompts.

70

71 Returns:

72 List of user prompt identifiers

73 """

74 pass

75

76 # ===== Message Indexes =====

77

78 @abstractmethod

79 def get_message_index(

80 self,

81 name: str,

82 **kwargs: Any

83 ) -> MessageIndex | None:

84 """Retrieve a message index by name.

85

86 Args:

87 name: Message index identifier

88 **kwargs: Additional library-specific parameters

89

90 Returns:

91 MessageIndex if found, None otherwise

92 """

93 pass

94

95 @abstractmethod

96 def list_message_indexes(self) -> List[str]:

97 """List all available message index names.

98

99 Returns:

100 List of message index identifiers

101 """

102 pass

103

104 # ===== RAG Configurations =====

105

106 @abstractmethod

107 def get_rag_config(

108 self,

109 name: str,

110 **kwargs: Any

111 ) -> RAGConfig | None:

112 """Retrieve a standalone RAG configuration by name.

113

114 Standalone RAG configs can be referenced from prompts or used directly.

115

116 Args:

117 name: RAG configuration identifier

118 **kwargs: Additional library-specific parameters

119

120 Returns:

121 RAGConfig if found, None otherwise

122 """

123 pass

124

125 @abstractmethod

126 def get_prompt_rag_configs(

127 self,

128 prompt_name: str,

129 prompt_type: str = "user",

130 **kwargs: Any

131 ) -> List[RAGConfig]:

132 """Retrieve RAG configurations for a specific prompt.

133

134 This resolves both inline RAG configs and references to standalone configs.

135

136 Args:

137 prompt_name: Name of the prompt

138 prompt_type: Type of prompt ("user" or "system")

139 **kwargs: Additional library-specific parameters

140

141 Returns:

142 List of RAG configurations (empty if none defined)

143 """

144 pass

145

146 # ===== Metadata & Lifecycle =====

147

148 @abstractmethod

149 def get_metadata(self) -> Dict[str, Any]:

150 """Get metadata about this prompt library.

151

152 Returns:

153 Dictionary with library metadata (source, version, etc.)

154 """

155 pass

156

157 @abstractmethod

158 def reload(self) -> None:

159 """Reload the prompt library from its source.

160

161 This is optional - implementations that support reloading should override.

162 Default implementation does nothing.

163 """

164 pass

165

166 # ===== Validation & Health Checks =====

167

168 def validate(self) -> List[str]:

169 """Validate the prompt library configuration.

170

171 Returns:

172 List of validation error messages (empty if valid)

173

174 Note:

175 Default implementation returns empty list. Implementations should

176 override to provide specific validation logic.

177 """

178 return []

179

180 def __repr__(self) -> str:

181 """Return a string representation of this library."""

182 metadata = self.get_metadata()

183 return f"{self.__class__.__name__}({metadata.get('source', 'unknown')})"