Coverage for /home/admin/Documents/AI/applications/lexigram-dev/lexigram/experimental/ai/lexigram-ai-memory/src/lexigram/ai/memory/config.py: 100%

1"""Configuration for lexigram-ai-memory.""" 

2 

3from __future__ import annotations 

4 

5from typing import ClassVar 

6 

7from lexigram.ai.memory import constants as const 

8from lexigram.config.base import BaseConfig 

9from lexigram.validation import ConfigDict, Field 

10 

11 

12class WorkingMemoryConfig(BaseConfig): 

13 """Token-budget allocation for working memory assembly. 

14 

15 Attributes: 

16 system_prompt_tokens: Fixed token allocation for system prompt. 

17 recent_turns_fraction: Fraction of remaining budget for recent turns. 

18 episodic_fraction: Fraction of remaining budget for episodic recall. 

19 semantic_fraction: Fraction of remaining budget for semantic facts. 

20 tool_descriptions_fraction: Fraction of remaining budget for tool descriptions. 

21 max_recent_turns: Hard cap on recent turns regardless of budget. 

22 """ 

23 

24 model_config: ClassVar[ConfigDict] = ConfigDict(extra="ignore") 

25 

26 system_prompt_tokens: int = Field( 

27 default=const.DEFAULT_SYSTEM_PROMPT_TOKENS, 

28 description="Fixed token allocation for system prompt", 

29 ) 

30 recent_turns_fraction: float = Field( 

31 default=const.DEFAULT_RECENT_TURNS_FRACTION, 

32 ge=0.0, 

33 le=1.0, 

34 description="Fraction of remaining budget for recent turns", 

35 ) 

36 episodic_fraction: float = Field( 

37 default=const.DEFAULT_EPISODIC_FRACTION, 

38 ge=0.0, 

39 le=1.0, 

40 description="Fraction of remaining budget for episodic recall", 

41 ) 

42 semantic_fraction: float = Field( 

43 default=const.DEFAULT_SEMANTIC_FRACTION, 

44 ge=0.0, 

45 le=1.0, 

46 description="Fraction of remaining budget for semantic facts", 

47 ) 

48 tool_descriptions_fraction: float = Field( 

49 default=const.DEFAULT_TOOL_DESC_FRACTION, 

50 ge=0.0, 

51 le=1.0, 

52 description="Fraction of remaining budget for tool descriptions", 

53 ) 

54 max_recent_turns: int = Field( 

55 default=const.DEFAULT_MAX_RECENT_TURNS, 

56 ge=1, 

57 description="Hard cap on recent turns regardless of budget", 

58 ) 

59 

60 

61class EpisodicMemoryConfig(BaseConfig): 

62 """Configuration for episodic memory tier. 

63 

64 Attributes: 

65 default_top_k: Default number of episodes to retrieve. 

66 recency_weight: Weight applied to temporal recency during scoring. 

67 importance_weight: Weight applied to entry importance during scoring. 

68 relevance_weight: Weight applied to semantic similarity during scoring. 

69 ttl_seconds: Time-to-live for entries (0 = never expire). 

70 """ 

71 

72 model_config: ClassVar[ConfigDict] = ConfigDict(extra="ignore") 

73 

74 default_top_k: int = Field( 

75 default=const.DEFAULT_EPISODIC_TOP_K, 

76 ge=1, 

77 description="Default number of episodes to retrieve", 

78 ) 

79 recency_weight: float = Field( 

80 default=const.DEFAULT_RECENCY_WEIGHT, 

81 ge=0.0, 

82 le=1.0, 

83 description="Weight applied to temporal recency during scoring", 

84 ) 

85 importance_weight: float = Field( 

86 default=const.DEFAULT_IMPORTANCE_WEIGHT, 

87 ge=0.0, 

88 le=1.0, 

89 description="Weight applied to entry importance during scoring", 

90 ) 

91 relevance_weight: float = Field( 

92 default=const.DEFAULT_RELEVANCE_WEIGHT, 

93 ge=0.0, 

94 le=1.0, 

95 description="Weight applied to semantic similarity during scoring", 

96 ) 

97 ttl_seconds: int = Field( 

98 default=const.DEFAULT_EPISODIC_TTL_SECONDS, 

99 ge=0, 

100 description="Time-to-live for entries in seconds (0 = never expire)", 

101 ) 

102 

103 

104class SemanticMemoryConfig(BaseConfig): 

105 """Configuration for semantic memory tier. 

106 

107 Attributes: 

108 min_confidence: Minimum confidence to store a fact. 

109 max_facts_per_entity: Hard cap on stored facts per entity. 

110 """ 

111 

112 model_config: ClassVar[ConfigDict] = ConfigDict(extra="ignore") 

113 

114 min_confidence: float = Field( 

115 default=const.DEFAULT_MIN_CONFIDENCE, 

116 ge=0.0, 

117 le=1.0, 

118 description="Minimum confidence score required to store a fact", 

119 ) 

120 max_facts_per_entity: int = Field( 

121 default=const.DEFAULT_MAX_FACTS_PER_ENTITY, 

122 ge=1, 

123 description="Hard cap on stored facts per entity", 

124 ) 

125 

126 

127class ConsolidationConfig(BaseConfig): 

128 """Configuration for the background consolidation pipeline. 

129 

130 Attributes: 

131 enabled: Whether automatic consolidation is active. 

132 interval_seconds: How often to run a consolidation pass. 

133 age_threshold_hours: Minimum entry age before it can be consolidated. 

134 importance_prune_threshold: Entries below this importance are eligible for pruning. 

135 batch_size: Maximum entries processed per consolidation pass. 

136 """ 

137 

138 model_config: ClassVar[ConfigDict] = ConfigDict(extra="ignore") 

139 

140 enabled: bool = Field( 

141 default=True, 

142 description="Whether automatic background consolidation is active", 

143 ) 

144 interval_seconds: float = Field( 

145 default=const.DEFAULT_CONSOLIDATION_INTERVAL_S, 

146 gt=0.0, 

147 description="How often to run a consolidation pass (seconds)", 

148 ) 

149 age_threshold_hours: float = Field( 

150 default=const.DEFAULT_CONSOLIDATION_AGE_THRESHOLD_HOURS, 

151 gt=0.0, 

152 description="Minimum entry age (hours) before it can be consolidated", 

153 ) 

154 importance_prune_threshold: float = Field( 

155 default=const.DEFAULT_CONSOLIDATION_IMPORTANCE_PRUNE, 

156 ge=0.0, 

157 le=1.0, 

158 description="Entries below this importance score are eligible for pruning", 

159 ) 

160 batch_size: int = Field( 

161 default=const.DEFAULT_CONSOLIDATION_BATCH_SIZE, 

162 ge=1, 

163 description="Maximum entries processed per consolidation pass", 

164 ) 

165 

166 

167ENV_PREFIX: str = const.ENV_PREFIX 

168 

169 

170class MemoryConfig(BaseConfig): 

171 """Top-level configuration for lexigram-ai-memory. 

172 

173 Attributes: 

174 working: Working memory token budget configuration. 

175 episodic: Episodic memory retrieval configuration. 

176 semantic: Semantic memory fact storage configuration. 

177 consolidation: Background consolidation pipeline configuration. 

178 default_backend: Backend type to use ('in_memory', 'cache', 'database', 'vector'). 

179 ttl_seconds: Default entry TTL in seconds (0 = never expire). 

180 """ 

181 

182 config_section: ClassVar[str] = "ai_memory" 

183 

184 model_config: ClassVar[ConfigDict] = ConfigDict( # type: ignore[typeddict-unknown-key] 

185 env_prefix=ENV_PREFIX, 

186 env_nested_delimiter=const.ENV_NESTED_DELIMITER, 

187 extra="ignore", 

188 ) 

189 

190 enabled: bool = Field(default=True, description="Enable the AI memory subsystem") 

191 

192 working: WorkingMemoryConfig = Field( 

193 default_factory=WorkingMemoryConfig, 

194 description="Working memory token budget configuration", 

195 ) 

196 episodic: EpisodicMemoryConfig = Field( 

197 default_factory=EpisodicMemoryConfig, 

198 description="Episodic memory retrieval configuration", 

199 ) 

200 semantic: SemanticMemoryConfig = Field( 

201 default_factory=SemanticMemoryConfig, 

202 description="Semantic memory fact storage configuration", 

203 ) 

204 consolidation: ConsolidationConfig = Field( 

205 default_factory=ConsolidationConfig, 

206 description="Background consolidation pipeline configuration", 

207 ) 

208 default_backend: str = Field( 

209 default=const.DEFAULT_BACKEND, 

210 description="Backend type to use ('in_memory', 'cache', 'database', 'vector')", 

211 ) 

212 ttl_seconds: int = Field( 

213 default=const.DEFAULT_TTL_SECONDS, 

214 ge=0, 

215 description="Default entry TTL in seconds (0 = never expire)", 

216 ) 

217 

218 

219__all__ = [ 

220 "ENV_PREFIX", 

221 "ConsolidationConfig", 

222 "EpisodicMemoryConfig", 

223 "MemoryConfig", 

224 "SemanticMemoryConfig", 

225 "WorkingMemoryConfig", 

226]