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

1"""GuardProtocol module for Lexigram.""" 

2 

3from __future__ import annotations 

4 

5from typing import TYPE_CHECKING, Any 

6 

7from lexigram.contracts.ai.guards import ( 

8 GuardPipelineProtocol, 

9 InputGuardProtocol, 

10 OutputGuardProtocol, 

11) 

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

13 

14if TYPE_CHECKING: 

15 from lexigram.ai.guard.config import GuardConfig 

16 

17 

18@module() 

19class GuardModule(Module): 

20 """Module for content safety guard pipeline. 

21 

22 Registers the :class:`~lexigram.ai.guard.di.provider.GuardProvider` 

23 which builds and wires the configured guard pipeline into the container. 

24 

25 Usage:: 

26 

27 app = LexigramApplication( 

28 modules=[..., GuardModule()], 

29 ) 

30 

31 Or with custom config:: 

32 

33 app = LexigramApplication( 

34 modules=[ 

35 ..., 

36 GuardModule( 

37 config=GuardConfig( 

38 injection_detection=True, 

39 pii_action="redact", 

40 max_input_chars=8000, 

41 ) 

42 ) 

43 ] 

44 ) 

45 """ 

46 

47 @classmethod 

48 def configure( 

49 cls, 

50 config: GuardConfig | None = None, 

51 enable_audit_logging: bool = True, 

52 **kwargs: Any, 

53 ) -> DynamicModule: 

54 """Create a GuardModule with explicit configuration. 

55 

56 Args: 

57 config: :class:`~lexigram.ai.guard.config.GuardConfig` or ``None`` 

58 for defaults. 

59 enable_audit_logging: Emit structured audit log entries for every 

60 guard decision (allow, block, redact). Defaults to ``True``; 

61 set to ``False`` to reduce log volume in high-throughput 

62 environments. 

63 **kwargs: Additional keyword arguments forwarded to 

64 :class:`~lexigram.ai.guard.di.provider.GuardProvider`. 

65 

66 Returns: 

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

68 """ 

69 from lexigram.ai.guard.di.provider import GuardProvider 

70 

71 return DynamicModule( 

72 module=cls, 

73 providers=[ 

74 GuardProvider( 

75 config=config, 

76 enable_audit_logging=enable_audit_logging, 

77 **kwargs, 

78 ) 

79 ], 

80 exports=[ 

81 GuardPipelineProtocol, 

82 InputGuardProtocol, 

83 OutputGuardProtocol, 

84 ], 

85 ) 

86 

87 @classmethod 

88 def stub(cls, config: GuardConfig | None = None) -> DynamicModule: 

89 """Create a GuardModule suitable for unit and integration testing. 

90 

91 Uses a pass-through (allow-all) guard pipeline with no external API 

92 calls. Audit logging is disabled by default to keep test output clean. 

93 

94 Args: 

95 config: Optional :class:`~lexigram.ai.guard.config.GuardConfig` 

96 override. Uses safe test defaults when ``None``. 

97 

98 Returns: 

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

100 """ 

101 from lexigram.ai.guard.di.provider import GuardProvider 

102 

103 return DynamicModule( 

104 module=cls, 

105 providers=[GuardProvider(config=config, enable_audit_logging=False)], 

106 exports=[ 

107 GuardPipelineProtocol, 

108 InputGuardProtocol, 

109 OutputGuardProtocol, 

110 ], 

111 ) 

112 

113 

114__all__ = ["GuardModule"]