# character-ai/prompt-poet architecture

> Architecture diagram of the GitHub repository character-ai/prompt-poet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/character-ai/prompt-poet
- Repository: https://github.com/character-ai/prompt-poet

## Overview

##### Main Components
- Prompt Creation Engine: This is the core component that ties together the templating process. It processes a “raw_template” with provided “template_data”.
- Rendering Stage: Represent the use of Jinja2 to perform variable substitutions, control flow (e.g., loops/conditionals), and even invoke Python functions. This is where the raw template transforms into an intermediate string.
- Loading/Parsing Stage: Indicate the subsequent YAML parsing stage that converts the rendered string into a structured format – a list of prompt “parts” with attributes such as name, role, content, and optional truncation priority.
- Tokenization Module: Include the component responsible for calling the tokenizer (by default using TikToken “o200k_base” or a custom encode_func) to convert the final prompt string into token sequences.
- Truncation Logic: Show how the tokenized prompt is processed to apply cache-aware or custom truncation logic, ensuring that the prompt meets token limits while preserving high cache hit rates.
- Exception Handling: Include prompt-related exceptions handled by the “pp_exceptions” module.
- External Dependencies/Integrations: Identify external libraries and services such as LangChain (for LLM communication) and TikToken for tokenization.

##### Displaying Relationships and Data Flow
- Finally, illustrate that the fully processed prompt (as string, tokens, or structured messages) is passed to an “LLM Integration” component (e.g., ChatOpenAI).

##### Architectural Patterns and Designs
- Two-Stage Pipeline:
- Stage 1 (Rendering): Use Jinja2 to embed control flow and direct Python function calls.
- Stage 2 (Parsing): Process the output using a YAML parser to ensure a uniform data structure for prompt elements.
- Data Transformation process where a raw string evolves into a structured prompt.
- That the system differentiates between various prompt “parts” (system instructions, user query, reply prompt, etc.) based on its YAML structure.
- Plug-in architecture that supports different encoding functions, custom truncation, and template registries to facilitate extendability and performance tuning.

- The multi-stage transformation of prompt templates.
- The extensibility offered by the template registry.
- External integration for model invocation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Node
    A["Template Data & Raw Template"]:::internal

    %% Prompt Creation Engine
    B["Prompt Creation Engine: Combines rendering and loading"]:::internal

    %% Two-stage Prompt Pipeline subgraph
    subgraph "Prompt Processing Pipeline"
        C["Jinja2 Renderer: renders raw template"]:::internal
        D["YAML Parsing Stage: parses rendered string"]:::internal
    end

    %% Tokenization and Truncation Modules
    E["Tokenization Module: tokenizes prompt (uses TikToken)"]:::internal
    F["Truncation Logic: applies cache-aware truncation"]:::internal

    %% LLM Integration
    G["LLM Integration: invokes LangChain/ChatOpenAI"]:::external

    %% Supporting Components
    H["Template Registry: loads & caches file templates"]:::registry
    I["Prompt Exceptions (pp_exceptions): handles prompt errors"]:::exception

    %% External Dependencies (for reference)
    J["TikToken"]:::external
    K["LangChain"]:::external

    %% Data Flow
    A -->|"provides data"| B
    B -->|"calls"| C
    C -->|"renders to"| D
    D -->|"outputs structured prompt to"| E
    E -->|"produces tokens for"| F
    F -->|"sends processed prompt to"| G

    %% Supporting Component Relationships
    B ---|"optionally loads templates from"| H
    B ---|"handles errors via"| I
    E ---|"utilizes"| J
    G ---|"communicates with"| K

    %% Click Events
    click B "https://github.com/character-ai/prompt-poet/blob/main/prompt_poet/prompt.py"
    click C "https://github.com/character-ai/prompt-poet/blob/main/prompt_poet/template.py"
    click D "https://github.com/character-ai/prompt-poet/blob/main/prompt_poet/template_loaders.py"
    click E "https://github.com/character-ai/prompt-poet/blob/main/prompt_poet/tokenizer.py"
    click F "https://github.com/character-ai/prompt-poet/blob/main/prompt_poet/tokenizer.py"
    click H "https://github.com/character-ai/prompt-poet/blob/main/prompt_poet/template_registry.py"
    click I "https://github.com/character-ai/prompt-poet/blob/main/prompt_poet/pp_exceptions.py"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef external fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef registry fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef exception fill:#FFCCCB,stroke:#000,stroke-width:2px;
```
