# adam-s-tech/synthid-text architecture

> Architecture diagram of the GitHub repository adam-s-tech/synthid-text, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adam-s-tech/synthid-text
- Repository: https://github.com/adam-s-tech/synthid-text

## Overview

##### Project type and purpose
- SynthID Text is a researcher-focused Python library/reference implementation for watermarking and detecting watermarks in large-language-model text.
- It is not a standalone service but a pip-installable library with example Jupyter notebooks, integrating with Hugging Face Transformers models (Gemma & GPT-2) and providing two detectors (Weighted-Mean and Bayesian).

##### File structure
Top-level:
- .github/workflows/ci.yaml – CI for linting/tests
- data/ – released human evaluation JSONL
- notebooks/ – two Colab/Jupyter notebooks demonstrating model integration & testing
- src/synthid_text/ – core library modules
– detector_mean.py, detector_bayesian.py – scoring functions
– synthid_mixin.py – mix-in to inject watermarking into Transformers models
– logits_processing.py – compute G values, masks, EOS logic
– hashing_function.py, g_value_expectations.py – lower-level support
– torch_testing.py, *­_test.py – unit tests
- pyproject.toml – build/config

##### README for additional insights
- Describes two workflows: (a) watermark‐injection via SynthID mix-in subclass of Gemma/GPT-2; (b) detection via Weighted-Mean (no train) or Bayesian (requires JAX training).
- Explains use of external services: Hugging Face model hub, TensorFlow Datasets for human prompts, Colab for notebooks.

1. User Interface layer (Notebook or local Python script)
2. Library layer (synthid_text package)
- Watermark Mixin module
- Hashing & G-value module
- Logits Processing module
- Detector modules (Mean, Bayesian)
- Detector Training (Bayesian optimizer)
3. External ML Models (Hugging Face Transformers: Gemma & GPT-2)
4. Data layer
- Input prompts (user or TFDS)
- Human evaluation data (data/human_eval.jsonl)
5. External services
- Hugging Face model hub (for from_pretrained)
- PyPI (for pip install)
- Colab runtime / Jupyter server

1. Notebook → Library: calls mix-in’s `.from_pretrained()`, `.generate()`, `.detect()` APIs
2. Library → Transformers Model: mix-in intercepts `forward`/`generate` to insert watermarking (calls hashing_function + logits_processing)
3. Transformers Model → Library: returns logits → LogitsProcessing computes G-values & masks → Detector modules consume these to score
4. Detector Training: uses G-values + mask + labels (from data loader) → JAX optimizer → produces Bayesian detector parameters
5. Data flow: TFDS → prompts → library → models → watermarked text → detection → evaluation
6. CI Pipeline (ci.yaml) → unit tests → ensures correctness

c. Architectural patterns & design principles
- Modular Python package: clear separation of concerns (watermarking vs. detection vs. training)
- Extension via mix-in pattern to minimally modify HF model classes
- Functional separation: hashing → g-value computation → scoring → training
- Dependency injection: configuration TypedDict for watermark parameters
- Test-driven: each module has corresponding tests

d. Key technologies, frameworks, libraries
- Python 3, pyproject.toml (Poetry/PEP 621)
- PyTorch (model inference & mix-in)
- Hugging Face Transformers (Gemma, GPT-2 classes)
- JAX (& jax.numpy) for Bayesian detector training
- TensorFlow Datasets for prompt retrieval
- Jupyter/Colab for notebooks
- pytest for tests

##### Detailed capture of essential elements
- Modules in layers:
Presentation (Notebook) → Library API → Model Extension → Processing & Detection → Data & Training
- Don’t overthink: break into as many logical components as possible
- Test/CI pipeline as a side branch verifying each module

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface" 
        direction TB
        NB1["SynthID HF Integration Notebook"]:::ui
        NB2["Testing HF Integration Notebook"]:::ui
    end

    %% SynthID Library Layer
    subgraph "SynthID Library" 
        direction TB
        Mixin["SynthIDMixin Module"]:::internal
        HashFunc["HashingFunction Module"]:::internal
        GValues["GValueExpectations Module"]:::internal
        LogitsProc["LogitsProcessing Module"]:::internal
        MeanDet["Weighted-Mean Detector"]:::internal
        BayesDet["Bayesian Detector"]:::internal
    end

    %% External Models
    subgraph "External Models"
        direction TB
        HF["Hugging Face Models<br/>(Gemma & GPT-2)"]:::external
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        TFDS["TensorFlow Datasets<br/>(prompts)"]:::data
        HumanEval["Human Eval Data<br/>(human_eval.jsonl)"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        HFHub["HF Model Hub"]:::external
        PyPI["PyPI"]:::external
        Colab["Colab/Jupyter Server"]:::external
    end

    %% CI Pipeline & Tests
    subgraph "CI Pipeline" 
        direction TB
        CIPipeline["CI Pipeline<br/>(ci.yaml)"]:::test
        LPTest["LogitsProcessing Tests"]:::test
        MixinTest["SynthIDMixin Tests"]:::test
        TorchTest["Torch Integration Tests"]:::test
    end

    %% Connections
    NB1 -->|uses from_pretrained/generate/detect| Mixin
    NB2 -->|testing integration| Mixin
    Mixin -->|injects watermark| HF
    HF -->|returns logits| LogitsProc
    LogitsProc -->|computes G-values & masks| MeanDet
    LogitsProc -->|computes G-values & masks| BayesDet
    TFDS -->|prompts| BayesDet
    HumanEval -->|evaluation data| BayesDet
    HFHub -->|model fetch| Mixin
    PyPI -->|library install| NB1
    Colab -->|executes notebooks| NB1
    CIPipeline --> LPTest
    CIPipeline --> MixinTest
    CIPipeline --> TorchTest
    LPTest --> LogitsProc
    MixinTest --> Mixin
    TorchTest --> HF

    %% Click Events
    click NB1 "https://github.com/adam-s-tech/synthid-text/blob/main/notebooks/synthid_text_huggingface_integration.ipynb"
    click NB2 "https://github.com/adam-s-tech/synthid-text/blob/main/notebooks/testing_huggingface_integration.ipynb"
    click Mixin "https://github.com/adam-s-tech/synthid-text/blob/main/src/synthid_text/synthid_mixin.py"
    click HashFunc "https://github.com/adam-s-tech/synthid-text/blob/main/src/synthid_text/hashing_function.py"
    click GValues "https://github.com/adam-s-tech/synthid-text/blob/main/src/synthid_text/g_value_expectations.py"
    click LogitsProc "https://github.com/adam-s-tech/synthid-text/blob/main/src/synthid_text/logits_processing.py"
    click MeanDet "https://github.com/adam-s-tech/synthid-text/blob/main/src/synthid_text/detector_mean.py"
    click BayesDet "https://github.com/adam-s-tech/synthid-text/blob/main/src/synthid_text/detector_bayesian.py"
    click LPTest "https://github.com/adam-s-tech/synthid-text/blob/main/src/synthid_text/logits_processing_test.py"
    click MixinTest "https://github.com/adam-s-tech/synthid-text/blob/main/src/synthid_text/synthid_mixin_test.py"
    click TorchTest "https://github.com/adam-s-tech/synthid-text/blob/main/src/synthid_text/torch_testing.py"
    click HumanEval "https://github.com/adam-s-tech/synthid-text/blob/main/data/human_eval.jsonl"
    click CIPipeline "https://github.com/adam-s-tech/synthid-text/blob/main/.github/workflows/ci.yaml"

    %% Styles
    classDef ui fill:#f9f,stroke:#333,stroke-width:1px
    classDef internal fill:#bbf,stroke:#333,stroke-width:1px
    classDef data fill:#bfb,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#fcf,stroke:#333,stroke-width:1px
    classDef test fill:#fdd,stroke:#c33,stroke-width:1px
```
