# google-research/camel-prompt-injection architecture

> Architecture diagram of the GitHub repository google-research/camel-prompt-injection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google-research/camel-prompt-injection
- Repository: https://github.com/google-research/camel-prompt-injection

## Overview

##### Project Type and Purpose
- This is a Python-based research artifact (CaMeL) implementing a defense-by-design framework to defeat prompt injections when interacting with large language models (LLMs).
- It exposes a CLI entrypoint (`main.py`) orchestrated via the “uv” runner, loads API keys from `.env`, constructs LLM prompts, runs attacks/evaluations, and applies a multi-stage pipeline of security policies and sandboxed interpretation.

##### File-Structure Analysis
Top-Level:
- `main.py`, `run_code.py`, `print_conversation.py` – CLI scripts driven by uv
- `pyproject.toml`, `uv.lock`, `.env.example` – build/configuration/runtime lockfile
- `analysis.ipynb`, `count_tokens.py` – ad-hoc analysis notebooks/scripts
src/camel/ (Core Library):
- `capabilities/` – token counting, readers, sources, caching utilities
- `interpreter/` – sandboxed code execution, protocol definitions, result/value models
- `pipeline_elements/` – chain‐of‐responsibility filters (AgentDojo, Anthropic filter, privileged LLM wrapper, replay), with submodule `security_policies/` for domain-specific policy sets (banking, travel, Slack, workspace)
- Other modules: `models.py` (supported LLMs), `system_prompt_generator.py`, `security_policy.py`, `quarantined_llm.py`, `chat_turn.py`, etc.
tests/ – unit tests covering the interpreter, language constructs, pipeline elements, token counting.

##### README Insights
- CLI arguments drive model choice, defense toggles, evaluation mode.
- External dependencies: OpenAI/Anthropic API, AgentDojo attack harness, “uv” runtime.
- The paper title and warning highlight that this is research code, not a production-grade system.

##### Main Components
a. CLI Layer (uv runner with `main.py` / `run_code.py`)
b. Configuration (.env, API keys)
c. Core Library:
- Prompt Generator
- Pipeline of Elements (filters, policy enforcement, replay)
- Interpreter Sandbox
- Capabilities (token counter, cache)
- Model Interface (OpenAI, Anthropic wrappers, quarantined LLM)
d. External Services: LLM Providers (OpenAI, Anthropic), AgentDojo attack harness
e. Test Suite (separate, can be a side-component)

##### Component Relationships and Data Flow
- CLI invokes the Prompt Generator → builds system/user prompts.
- Prompts are fed into the Pipeline (chain-of-responsibility): each pipeline element intercepts or transforms the prompt/response.
- After filtering, the request goes to the Model Interface which calls the external LLM API.
- Model’s response may yield code snippets – passed into the Interpreter Sandbox for execution.
- Interpreter outputs results → Security Policy module validates or rejects outputs.
- Final output returned to user or evaluation harness (AgentDojo).
- Capabilities (token counter, cache) are invoked at various points to track usage or reuse prior results.

##### Architectural Patterns & Principles
- Chain-of-Responsibility (pipeline elements)
- Interpreter Pattern (sandboxed code execution)
- Modular Separation (capabilities, policies, prompt generation, model abstraction)
- Test-Driven Approach (comprehensive unit tests for each module)

##### Technologies and Frameworks
- Python 3.x, “uv” CLI runner
- ONNX or direct HTTP calls to LLM APIs (OpenAI, Anthropic)
- PyProject/TOML build, Ruff for linting, Pyright for type checks, Pytest for testing

##### Detailed Capture of Architectural Elements
- Security policies under one composite element with sub-labels for each domain
- Token-count capability hooking into both prompt construction and response processing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        CLI_MAIN["main.py"]:::cli
        CLI_RUN["run_code.py"]:::cli
        CLI_PRINT["print_conversation.py"]:::cli
    end

    %% Configuration
    CONFIG[".env"]:::config

    %% Core Library Modules
    PROMPT_GEN["Prompt Generator"]:::core
    subgraph "Pipeline of Elements" 
        direction TB
        AGDJ_FN["agentdojo_function"]:::core
        ANTH_TOOL["anthropic_tool_filter"]:::core
        OLD_LL["old_google_llm"]:::core
        PRIV_LL["privileged_llm"]:::core
        REPLAY_PRIV["replay_privileged_llm"]:::core
        subgraph "Security Policies"
            direction TB
            POL_ADSP["agentdojo_security_policies"]:::core
            POL_BANK["banking"]:::core
            POL_TRAVEL["travel"]:::core
            POL_SLACK["slack"]:::core
            POL_WS["workspace"]:::core
        end
    end

    subgraph "Model Interface / LLM Wrappers"
        direction TB
        MODELS["models.py"]:::core
        QUARANTINE["quarantined_llm.py"]:::core
    end

    subgraph "Interpreter Sandbox"
        direction TB
        INT_PT["interpreter.py"]:::core
        INT_LIB["library.py"]:::core
        INT_NS["namespace.py"]:::core
        INT_PROTO["op_protocols.py"]:::core
        INT_RES["result.py"]:::core
        INT_VAL["value.py"]:::core
    end

    %% Capabilities
    subgraph "Capabilities" 
        direction TB
        CAP_ALL["capabilities.py"]:::util
        CAP_READ["readers.py"]:::util
        CAP_SRC["sources.py"]:::util
        CAP_UTIL["utils.py"]:::util
        TOKEN_CNT["count_tokens.py"]:::util
        CACHE["conditional_cache.py"]:::util
    end

    %% External Services
    OPENAI[(OpenAI API)]:::external
    ANTHROPIC[(Anthropic API)]:::external
    AGENTDOJO[(AgentDojo Harness)]:::external

    %% Data Flow
    CLI_MAIN -->|"invokes"| PROMPT_GEN
    CLI_RUN -->|"invokes"| PROMPT_GEN
    CLI_PRINT -->|"invokes"| PROMPT_GEN
    CONFIG --> PROMPT_GEN

    PROMPT_GEN -->|"system+user prompt"| AGDJ_FN
    AGDJ_FN --> ANTH_TOOL
    ANTH_TOOL --> OLD_LL
    OLD_LL --> PRIV_LL
    PRIV_LL --> REPLAY_PRIV
    REPLAY_PRIV --> POL_ADSP
    POL_ADSP --> POL_BANK
    POL_BANK --> POL_TRAVEL
    POL_TRAVEL --> POL_SLACK
    POL_SLACK --> POL_WS
    POL_WS --> MODELS

    MODELS -->|"API call (JSON)"| OPENAI
    MODELS -->|"API call (JSON)"| ANTHROPIC
    QUARANTINE -->|"API call (JSON)"| OPENAI
    QUARANTINE -->|"API call (JSON)"| ANTHROPIC

    OPENAI -->|"response"| INT_PT
    ANTHROPIC --> INT_PT

    INT_PT --> INT_LIB
    INT_LIB --> INT_NS
    INT_NS --> INT_PROTO
    INT_PROTO --> INT_RES
    INT_RES --> INT_VAL
    INT_VAL --> POL_WS

    POL_WS -->|"validated output"| CLI_PRINT
    POL_WS -->|"evaluation results"| AGENTDOJO

    %% Capabilities Hooks
    TOKEN_CNT -.->|"token count"| PROMPT_GEN
    TOKEN_CNT -.->|"token count"| INT_RES
    CAP_READ -.-> PROMPT_GEN
    CAP_SRC -.-> PROMPT_GEN
    CAP_UTIL -.-> INT_PT
    CACHE -.-> INT_RES

    %% Test Suite
    TESTS["tests/"]:::test --> INT_PT
    TESTS --> AGDJ_FN
    TESTS --> TOKEN_CNT

    %% Click Events
    click CLI_MAIN "https://github.com/google-research/camel-prompt-injection/blob/main/main.py"
    click CLI_RUN "https://github.com/google-research/camel-prompt-injection/blob/main/run_code.py"
    click CLI_PRINT "https://github.com/google-research/camel-prompt-injection/blob/main/print_conversation.py"
    click CONFIG "https://github.com/google-research/camel-prompt-injection/blob/main/.env.example"
    click PROMPT_GEN "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/system_prompt_generator.py"
    click AGDJ_FN "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/pipeline_elements/agentdojo_function.py"
    click ANTH_TOOL "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/pipeline_elements/anthropic_tool_filter.py"
    click OLD_LL "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/pipeline_elements/old_google_llm.py"
    click PRIV_LL "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/pipeline_elements/privileged_llm.py"
    click REPLAY_PRIV "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/pipeline_elements/replay_privileged_llm.py"
    click POL_ADSP "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/pipeline_elements/security_policies/agentdojo_security_policies.py"
    click POL_BANK "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/pipeline_elements/security_policies/banking.py"
    click POL_TRAVEL "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/pipeline_elements/security_policies/travel.py"
    click POL_SLACK "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/pipeline_elements/security_policies/slack.py"
    click POL_WS "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/pipeline_elements/security_policies/workspace.py"
    click INT_PT "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/interpreter/interpreter.py"
    click INT_LIB "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/interpreter/library.py"
    click INT_NS "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/interpreter/namespace.py"
    click INT_PROTO "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/interpreter/op_protocols.py"
    click INT_RES "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/interpreter/result.py"
    click INT_VAL "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/interpreter/value.py"
    click CAP_ALL "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/capabilities/capabilities.py"
    click CAP_READ "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/capabilities/readers.py"
    click CAP_SRC "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/capabilities/sources.py"
    click CAP_UTIL "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/capabilities/utils.py"
    click TOKEN_CNT "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/count_tokens.py"
    click CACHE "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/conditional_cache.py"
    click MODELS "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/models.py"
    click QUARANTINE "https://github.com/google-research/camel-prompt-injection/blob/main/src/camel/quarantined_llm.py"
    click TESTS "https://github.com/google-research/camel-prompt-injection/tree/main/tests/"

    %% Styles
    classDef cli fill:#D0E6FF,stroke:#0366D6,color:#0366D6
    classDef config fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32,shape:parallelogram
    classDef core fill:#E3F2FD,stroke:#1E88E5,color:#1E88E5
    classDef util fill:#F5F5F5,stroke:#9E9E9E,color:#616161
    classDef external fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef test fill:#F3E5F5,stroke:#8E24AA,color:#6A1B9A
```
