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

1"""GuardProtocol configuration for the Lexigram framework.""" 

2 

3from __future__ import annotations 

4 

5from dataclasses import dataclass, field 

6from typing import ClassVar 

7 

8from lexigram.ai.guard.constants import ENV_NESTED_DELIMITER, ENV_PREFIX 

9from lexigram.config.base import BaseConfig 

10from lexigram.validation import ConfigDict, Field 

11 

12 

13@dataclass(init=False) 

14class GuardConfig(BaseConfig): 

15 """Configuration for the content safety guard pipeline. 

16 

17 Controls which guards are enabled by default and their behaviour. 

18 Guards can be further customised programmatically via 

19 :class:`~lexigram.ai.guard.pipeline.guard_pipeline.GuardPipeline`. 

20 

21 Attributes: 

22 enabled: Master switch — when ``False`` the guard pipeline is 

23 bypassed entirely. 

24 injection_detection: Enable the prompt injection detector. 

25 injection_action: Action on detected injection (``"block"``/``"warn"``). 

26 pii_detection: Enable PII detection on inputs. 

27 pii_action: Action on detected PII (``"redact"``/``"block"``/``"warn"``). 

28 pii_entities: PII entity types to detect. Empty list means all types. 

29 pii_redaction_output: Enable PII redaction on LLM outputs. 

30 max_input_chars: Maximum allowed input length in characters. 

31 ``0`` disables the length guard. 

32 max_output_chars: Maximum allowed output length in characters. 

33 ``0`` disables the output length guard. 

34 length_action: Action when length limit exceeded (``"block"``/``"warn"``). 

35 restricted_topics: Topics to block in user inputs. 

36 """ 

37 

38 config_section: ClassVar[str] = "ai_guard" 

39 

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

41 env_prefix=ENV_PREFIX, 

42 env_nested_delimiter=ENV_NESTED_DELIMITER, 

43 extra="ignore", 

44 ) 

45 

46 enabled: bool = Field(default=True) 

47 """Master on/off switch for the guard pipeline.""" 

48 

49 injection_detection: bool = Field(default=True) 

50 """Enable prompt injection detector on all inputs.""" 

51 

52 injection_action: str = Field(default="block") 

53 """Action when injection is detected: ``"block"`` or ``"warn"``.""" 

54 

55 pii_detection: bool = Field(default=True) 

56 """Enable PII detection on user inputs.""" 

57 

58 pii_action: str = Field(default="redact") 

59 """Action when PII is detected: ``"redact"``, ``"block"``, or ``"warn"``.""" 

60 

61 pii_entities: list[str] = field(default_factory=list) 

62 """PII entity types to scan for. Empty = all types.""" 

63 

64 pii_redaction_output: bool = Field(default=True) 

65 """Enable PII redaction on LLM outputs.""" 

66 

67 max_input_chars: int = Field(default=0, ge=0) 

68 """Maximum input length in characters. ``0`` = unlimited.""" 

69 

70 max_output_chars: int = Field(default=0, ge=0) 

71 """Maximum output length in characters. ``0`` = unlimited.""" 

72 

73 length_action: str = Field(default="block") 

74 """Action when input or output length limit exceeded.""" 

75 

76 restricted_topics: list[str] = field(default_factory=list) 

77 """Topic keywords/phrases to block in user inputs.""" 

78 

79 enable_llm_guards: bool = Field(default=False) 

80 """Enable LLM-based injection and jailbreak detection guards. 

81 

82 When ``True`` and an ``LLMClientProtocol`` is available in the container, 

83 :class:`~lexigram.ai.guard.input.llm_injection.LLMInjectionDetector` and 

84 :class:`~lexigram.ai.guard.input.llm_jailbreak.LLMJailbreakDetector` are 

85 added to the pipeline after the heuristic guards. 

86 """ 

87 

88 guard_model: str = Field(default="gpt-4o-mini") 

89 """Model to use for LLM-based guards (should be a fast, small model).""" 

90 

91 llm_guard_threshold: float = Field(default=0.7, ge=0.0, le=1.0) 

92 """Confidence threshold above which LLM guards trigger their action.""" 

93 

94 llm_guard_fail_open: bool = Field(default=False) 

95 """Fail open when the LLM-based guards cannot classify (two-tier). 

96 

97 ``False`` (default): on LLM client error or an error result the guards 

98 return an error result and the pipeline treats them as a blocked check 

99 (fail-closed on infrastructure failures, per the audit recommendation). 

100 An unparseable detection verdict still passes content through with a 

101 warning — heuristic nondeterminism is not evidence of attack, so the 

102 verdict-ambiguity class stays fail-open (fail-open only for 

103 detection-verdict errors). ``True``: all three classes pass content 

104 through and log a warning (today's fully fail-open behavior, for 

105 deployments that prefer availability during provider outages). 

106 """ 

107 

108 sensitivity_level: str = Field(default="medium") 

109 """Guard sensitivity: ``"low"``, ``"medium"``, or ``"high"``. 

110 

111 Controls how aggressively guards flag content: 

112 - ``"low"`` — only flag obvious violations. 

113 - ``"medium"`` — balanced detection (default). 

114 - ``"high"`` — aggressive detection, may produce more false positives. 

115 """ 

116 

117 parallel_execution: bool = Field(default=False) 

118 """Run guards concurrently with asyncio.gather instead of sequentially. 

119 

120 When enabled, redaction chaining is disabled — each guard receives 

121 the original content. Useful when guards are independent and I/O-bound. 

122 """ 

123 

124 

125__all__ = ["GuardConfig"]