Coverage for /home/admin/Documents/AI/applications/lexigram-dev/lexigram/experimental/ai/lexigram-ai-session/src/lexigram/ai/session/module.py: 87%

1"""Session module for dependency injection.""" 

2 

3from __future__ import annotations 

4 

5from typing import TYPE_CHECKING 

6 

7from lexigram.contracts.ai.session import SessionManagerProtocol, SessionStoreProtocol 

8from lexigram.di.module import DynamicModule, Module, module 

9 

10if TYPE_CHECKING: 

11 from lexigram.ai.session.config import SessionConfig 

12 

13 

14@module() 

15class SessionModule(Module): 

16 """AI conversation session management integration. 

17 

18 Call :meth:`configure` to register 

19 :class:`~lexigram.contracts.ai.session.SessionStoreProtocol` and 

20 :class:`~lexigram.contracts.ai.session.SessionManagerProtocol` 

21 implementations for injection. 

22 

23 Usage:: 

24 

25 from lexigram.ai.session.config import SessionConfig 

26 

27 @module( 

28 imports=[ 

29 SessionModule.configure( 

30 SessionConfig(backend="cache"), 

31 enable_cleanup_scheduler=True, 

32 ) 

33 ] 

34 ) 

35 class AppModule(Module): 

36 pass 

37 

38 Error Handling:: 

39 

40 Session operations surface typed exceptions that can be caught 

41 directly or handled via the Result pattern:: 

42 

43 from lexigram.ai.session.exceptions import ( 

44 SessionError, # base — catch-all 

45 SessionNotFoundError, # session ID not in store 

46 SessionClosedError, # write on a closed session 

47 SessionExpiredError, # TTL exceeded 

48 CheckpointNotFoundError,# checkpoint ID not found 

49 ) 

50 

51 Exports: 

52 :class:`~lexigram.contracts.ai.session.SessionStoreProtocol`, 

53 :class:`~lexigram.contracts.ai.session.SessionManagerProtocol`, 

54 :class:`~lexigram.ai.session.exceptions.SessionError`, 

55 :class:`~lexigram.ai.session.exceptions.SessionNotFoundError`, 

56 :class:`~lexigram.ai.session.exceptions.SessionClosedError`, 

57 :class:`~lexigram.ai.session.exceptions.SessionExpiredError`, 

58 :class:`~lexigram.ai.session.exceptions.CheckpointNotFoundError` 

59 """ 

60 

61 @classmethod 

62 def configure( 

63 cls, 

64 config: SessionConfig | None = None, 

65 *, 

66 enable_cleanup_scheduler: bool = True, 

67 ) -> DynamicModule: 

68 """Create a SessionModule with the given configuration. 

69 

70 Args: 

71 config: :class:`~lexigram.ai.session.config.SessionConfig`, a 

72 plain ``dict`` of the same keys, or ``None`` to use defaults. 

73 enable_cleanup_scheduler: Start the background expired-session 

74 cleanup loop during boot. Defaults to ``True``. 

75 

76 Returns: 

77 A :class:`~lexigram.di.module.DynamicModule` descriptor. 

78 """ 

79 from lexigram.ai.session.di.provider import SessionProvider 

80 

81 return DynamicModule( 

82 module=cls, 

83 providers=[ 

84 SessionProvider( 

85 config=config, 

86 enable_cleanup_scheduler=enable_cleanup_scheduler, 

87 ) 

88 ], 

89 exports=[ 

90 SessionStoreProtocol, 

91 SessionManagerProtocol, 

92 ], 

93 ) 

94 

95 @classmethod 

96 def stub(cls, config: SessionConfig | None = None) -> DynamicModule: 

97 """Create a SessionModule suitable for unit and integration testing. 

98 

99 Uses in-memory store with the cleanup scheduler disabled to avoid 

100 background tasks during tests. 

101 

102 Args: 

103 config: Optional config override. Uses safe test defaults when None. 

104 

105 Returns: 

106 A :class:`~lexigram.di.module.DynamicModule` descriptor. 

107 """ 

108 from lexigram.ai.session.di.provider import SessionProvider 

109 

110 return DynamicModule( 

111 module=cls, 

112 providers=[ 

113 SessionProvider( 

114 config=config, 

115 enable_cleanup_scheduler=False, 

116 ) 

117 ], 

118 exports=[ 

119 SessionStoreProtocol, 

120 SessionManagerProtocol, 

121 ], 

122 ) 

123 

124 

125__all__ = ["SessionModule"]