How brainpolo/llmshield works
Main Components
• LLMShield Interface: At the top level you have the LLMShield class (likely defined or used in core.py and __init__.py) that acts as the main façade. This object exposes the primary methods (e.g., cloak, uncloak, ask) and optionally integrates with an external LLM function.
• Cloaking & Uncloaking Modules: These include separate modules for cloaking prompts (cloak_prompt.py) and processing responses (uncloak_response.py). They handle the transformation of sensitive data to placeholder tokens and vice versa.
• Entity Detection: The entity_detector.py module is in charge of identifying sensitive entities. This component interacts with a variety of matchers.
• Matchers: These are organized under the “matchers” directory. Within this group you have:
• Dictionary matchers (with prebuilt lists such as cities, countries, organisations in the “dicts” subfolder) that provide static data to detect matches.
• Rule-based/pattern-based matchers such as those implemented in the “regex.py”, “lists.py”, and “functions.py” modules.
• Utilities: The utils.py module provides ancillary functions that support the main cloaking and uncloaking processes.
• Test Suite: The “tests” directory indicates a strong emphasis on testing system components like the core logic, regex matching, and utility functions.
Relationships and Interactions Between Components
• The client code instantiates the LLMShield interface.
• When calling the cloak method, the LLMShield interface passes the input prompt to the cloaking component (cloak_prompt.py) which invokes the entity detector (entity_detector.py).
• The entity detector uses several matchers (from matchers/dicts, regex, lists, etc.) to find sensitive entities, forming an “entity map” that keeps track of identified tokens.
• The processed prompt (with protected tokens) is then either passed to an external LLM function (if provided) or returned to the client for further processing.
• After receiving the LLM’s response, the uncloak module (uncloak_response.py) uses the entity map to restore the original sensitive data back into the text.
Architectural Patterns and Design Principles
• Facade Pattern: The LLMShield class provides a simple and clear API that abstracts the internal modules.
• Modularity and Separation of Concerns: Every key task (cloaking, entity detection, matching, and uncloaking) is isolated in its own module.
• Data Flow Pattern: There is a clear input-process-output chain, with an explicit mapping of detected entities to cloaked placeholders and back.
• Zero Dependencies: The design decision to remain dependency-free means the implementation relies entirely on built-in Python features which is also an essential part of the system design.
Relevant Technologies, Frameworks, or Libraries
• Python 3.7+ is required.
• The entire project is built with native Python modules, with a strong focus on performance and security.
• No external libraries are used, preserving the “zero dependencies” objective.
• Testing leverages Python’s built-in unittest framework.
Instructing the Principal Software Engineer to Include the Following Elements
• From the client to the LLMShield API.
• From LLMShield to Cloaking; from Cloaking to the Entity Detector.
• From the Entity Detector to various Matchers.
• Optionally, include annotations or legends to mention key design considerations such as “Zero Dependencies”, “High Performance”, and “Data Privacy & Security”.