# brainpolo/llmshield architecture

> Architecture diagram of the GitHub repository brainpolo/llmshield, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brainpolo/llmshield
- Repository: https://github.com/brainpolo/llmshield

## Overview

##### 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”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Client["Client"]:::external

    %% API Interface
    subgraph "LLMShield API"
        API["LLMShield API"]:::api
    end

    %% Processing Pipeline
    subgraph "Processing Pipeline"
        Cloak["Cloaking Module"]:::processing
        ED["Entity Detector"]:::processing
        Uncloak["Uncloaking Module"]:::processing
        U["Utility Functions"]:::utils
    end

    %% Matching Logic
    subgraph "Matching Logic"
        D["Dictionary Matchers"]:::matcher
        PB1["Regex Matcher"]:::matcher
        PB2["Lists Matcher"]:::matcher
        PB3["Function Matcher"]:::matcher
    end

    %% External Integration
    subgraph "External Integration"
        External["External LLM"]:::external
    end

    %% Test Suite
    subgraph "Tests"
        Tests["Test Suite"]:::tests
    end

    %% Data Flow Connections
    Client -->|"calls"| API
    API -->|"cloak"| Cloak
    Cloak -->|"detect"| ED
    ED -->|"match"| D
    ED -->|"match"| PB1
    ED -->|"match"| PB2
    ED -->|"match"| PB3
    Cloak -->|"return_prompt"| API
    Cloak -->|"send_prompt"| External
    External -->|"response"| Uncloak
    Uncloak -->|"restore"| API
    API -->|"output"| Client

    %% Utility usage
    Cloak -->|"utilizes"| U
    Uncloak -->|"utilizes"| U
    API -->|"utilizes"| U

    %% Click Events
    click API "https://github.com/brainpolo/llmshield/blob/main/llmshield/__init__.py"
    click Cloak "https://github.com/brainpolo/llmshield/blob/main/llmshield/cloak_prompt.py"
    click Uncloak "https://github.com/brainpolo/llmshield/blob/main/llmshield/uncloak_response.py"
    click ED "https://github.com/brainpolo/llmshield/blob/main/llmshield/entity_detector.py"
    click D "https://github.com/brainpolo/llmshield/tree/main/llmshield/matchers/dicts/"
    click PB1 "https://github.com/brainpolo/llmshield/blob/main/llmshield/matchers/regex.py"
    click PB2 "https://github.com/brainpolo/llmshield/blob/main/llmshield/matchers/lists.py"
    click PB3 "https://github.com/brainpolo/llmshield/blob/main/llmshield/matchers/functions.py"
    click U "https://github.com/brainpolo/llmshield/blob/main/llmshield/utils.py"
    click Tests "https://github.com/brainpolo/llmshield/tree/main/tests/"

    %% Styles
    classDef api fill:#ffdddd,stroke:#aa0000,stroke-width:2px;
    classDef processing fill:#ddffdd,stroke:#00aa00,stroke-width:2px;
    classDef matcher fill:#ddddff,stroke:#0000aa,stroke-width:2px;
    classDef utils fill:#fff0b3,stroke:#b38f00,stroke-width:2px;
    classDef tests fill:#ffccff,stroke:#aa00aa,stroke-width:2px;
    classDef external fill:#e0e0e0,stroke:#666666,stroke-width:2px;
```
