# 3dagentworld/toolkit-for-prompt-compression architecture

> Architecture diagram of the GitHub repository 3dagentworld/toolkit-for-prompt-compression, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/3dagentworld/toolkit-for-prompt-compression
- Repository: https://github.com/3dagentworld/toolkit-for-prompt-compression

## Overview

##### Project type and purpose
- PCToolkit is an open-source Python toolkit (library + CLI/demo) for prompt compression of Large Language Models.
- Purpose: provide a plug-and-play framework with modular “compressors,” dataset loaders, evaluation metrics, and a runner to orchestrate compression + evaluation flows.

##### File structure
- Top-level:
- dataset/ & datasets_card/: raw datasets (BBH, GSM8K, LongBench, etc.) and markdown cards
- pctoolkit/: core Python package
- pctoolkit_demo.py & imgs/: demo scripts and architecture image
- requirements.txt
- pctoolkit/ submodules:
- compressors.py → Compressor module (SC, LLMLingua, SCRL, KiS, etc.)
- datasets.py → Dataset module (loaders for each dataset)
- metrics.py → Metric module (evaluation functions, LongBench special handling)
- runners.py → Runner module (ties compressor + dataset + metrics + external APIs)
- methods/ → implementations of specific compression algorithms and their configs
- pretrain_models/ → placeholders & instructions for Huggingface/OpenAI model downloads

##### README for architecture insights
- README highlights a 4-module design (Compressor, Dataset, Metric, Runner).
- External dependencies: Huggingface Hub, OpenAI API, pretrained models, standard Python libs.

##### Main components
a. **Core Modules (internal)**
- Compressor Module
- Dataset Module
- Metric Module
- Runner Module
b. **Data Stores & Files**
- Local dataset files (JSONL, parquet under dataset/)
- Configuration files (pctoolkit/methods/*/config/*.json)
c. **External Services**
- Huggingface Hub (model download & token)
- OpenAI API (completion endpoints)
d. **CLI / Demo Layer**
- pctoolkit_demo.py & sample scripts calling Runner
- User script interface (PromptCompressor API)

##### Relationships & data flow
1. **User** invokes CLI/demo or imports PromptCompressor & Runner from pctoolkit.
2. **Runner Module** loads:
- a compressor instance from Compressor Module
- a dataset from Dataset Module
- metrics from Metric Module
3. **Runner** orchestrates: for each example:
- feed prompt → Compressor → compressed prompt
- send (original vs. compressed) to LLM via OpenAI/Huggingface
- collect responses → Metric Module for evaluation
4. **Results** written to disk or printed to console.

##### Architectural patterns & design principles
- **Modular Plug-In**: loose coupling between compressors, datasets, metrics.
- **Factory/Registry**: dynamic instantiation of compressors and datasets by name.
- **Pipeline Orchestration**: Runner drives sequential steps (load → compress → infer → evaluate).
- **Config-Driven**: compressors under methods/* read JSON configs for hyperparameters.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI / Demo Layer
    subgraph "CLI / Demo Layer"
        CLI["CLI / Demo (pctoolkit_demo.py)"]:::cli
    end

    %% Core Modules
    subgraph "Core Modules"
        Runner["Runner Module"]:::module
        Compressor["Compressor Module"]:::module
        Dataset["Dataset Module"]:::module
        Metric["Metric Module"]:::module
    end

    %% Compressor Implementations
    subgraph "Methods (Compressors)"
        Abs["Abstract Compressor"]:::module
        SC["SelectiveContext Compressor"]:::module
        SCRL["SCRL Compressor"]:::module
        KiS["KiS Compressor"]:::module
        subgraph "LLMLingua Family"
            LLPro["LLMLingua Pro"]:::module
            LLUtils["LLMLingua Utils"]:::module
            LLLong["LongLingua Compressor"]:::module
        end
    end

    %% Data Stores & Config
    subgraph "Data Stores & Config"
        DSFiles["Local Dataset Files"]:::datastore
        Config["Config Files"]:::datastore
        Models["Pretrained Models Placeholders"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        HF["Huggingface Hub"]:::external
        OpenAI["OpenAI API"]:::external
    end

    %% Connections
    User(["User"]):::external
    User --> CLI
    CLI --> Runner
    Runner -->|instantiates| Compressor
    Runner -->|instantiates| Dataset
    Runner -->|instantiates| Metric
    Dataset -.->|loads data| DSFiles
    Compressor -.->|reads configs| Config
    Runner -->|model download| HF
    Runner -->|completion call| OpenAI
    Runner -->|uses placeholders| Models

    Compressor --> Abs
    Compressor --> SC
    Compressor --> SCRL
    Compressor --> KiS
    Compressor --> LLPro
    Compressor --> LLUtils
    Compressor --> LLLong

    %% Click Events
    click Compressor "https://github.com/3dagentworld/toolkit-for-prompt-compression/blob/main/pctoolkit/compressors.py"
    click Abs "https://github.com/3dagentworld/toolkit-for-prompt-compression/blob/main/pctoolkit/methods/abs_compressor.py"
    click SC "https://github.com/3dagentworld/toolkit-for-prompt-compression/blob/main/pctoolkit/methods/selective_context_compressor.py"
    click SCRL "https://github.com/3dagentworld/toolkit-for-prompt-compression/blob/main/pctoolkit/methods/scrl_compressor.py"
    click SCRL "https://github.com/3dagentworld/toolkit-for-prompt-compression/tree/main/pctoolkit/methods/SCRL_new/"
    click KiS "https://github.com/3dagentworld/toolkit-for-prompt-compression/blob/main/pctoolkit/methods/kis.py"
    click LLPro "https://github.com/3dagentworld/toolkit-for-prompt-compression/blob/main/pctoolkit/methods/llmlingua_compressor_pro.py"
    click LLUtils "https://github.com/3dagentworld/toolkit-for-prompt-compression/blob/main/pctoolkit/methods/llmlingua_compressor_utils.py"
    click LLLong "https://github.com/3dagentworld/toolkit-for-prompt-compression/blob/main/pctoolkit/methods/longlingua_compressor.py"
    click Dataset "https://github.com/3dagentworld/toolkit-for-prompt-compression/blob/main/pctoolkit/datasets.py"
    click DSFiles "https://github.com/3dagentworld/toolkit-for-prompt-compression/tree/main/dataset/"
    click Metric "https://github.com/3dagentworld/toolkit-for-prompt-compression/blob/main/pctoolkit/metrics.py"
    click Runner "https://github.com/3dagentworld/toolkit-for-prompt-compression/blob/main/pctoolkit/runners.py"
    click Config "https://github.com/3dagentworld/toolkit-for-prompt-compression/tree/main/pctoolkit/methods/SCRL_new/config/"
    click Models "https://github.com/3dagentworld/toolkit-for-prompt-compression/tree/main/pctoolkit/pretrain_models/"
    click CLI "https://github.com/3dagentworld/toolkit-for-prompt-compression/blob/main/pctoolkit_demo.py"

    %% Styles
    classDef module fill:#AEDFF7,stroke:#036,stroke-width:2px
    classDef datastore fill:#FAF3C0,stroke:#B58900,stroke-width:2px
    classDef external fill:#D0F0C0,stroke:#2E8B57,stroke-width:2px
    classDef cli fill:#F0D0F0,stroke:#C71585,stroke-width:2px
```
