# technion-cs-nlp/llmsknow architecture

> Architecture diagram of the GitHub repository technion-cs-nlp/llmsknow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/technion-cs-nlp/llmsknow
- Repository: https://github.com/technion-cs-nlp/llmsknow

## Overview

##### Project Type and Purpose
- This is a research codebase (Python 3.11) for probing large language models (LLMs) to study intrinsic representations of hallucinations, reproducing the experiments from the paper “LLMs Know More Than They Show.”
- It is organized as a data‐processing and ML‐evaluation pipeline, not a client-server app.

##### File Structure Analysis
- Top‐level:
- data/ — raw CSV datasets (AnswerableMath, MNLI, MovieQA, Winobias, Winogrande, Natural Questions, etc.) and placeholders for TriviaQA and HotpotQA.
- src/ — CLI Python scripts that implement each pipeline stage.
- requirements.txt — Python dependencies, including WandB and HuggingFace.
- src/ contents reveal modular stages:
- generate_model_answers.py → calls the LLM to generate answers
- extract_exact_answer.py → post-processes generations to pull out exact answers
- resampling.py & resampling_merge_runs.py → bootstrap resamples of model outputs
- probe_all_layers_and_tokens.py, probe.py, probe_type_of_error.py, probe_choose_answer.py → classification probes on hidden activations
- logprob_detection.py, p_true_detection.py → baseline error detectors
- compute_correctness.py → final metric computation
- probing_utils.py, resamples_utils.py → shared utility functions

##### Core Components and Interactions
- Data Ingestion Layer
- Sources: local CSV files in data/ and HuggingFace-loaded datasets.
- Output: consolidated input data fed into the pipeline.

- Model Inference Layer
- Component: generate_model_answers.py
- Input: datasets + model name
- Output: raw model-generated answers (logged via WandB and/or saved locally)

- Answer Extraction Layer
- Component: extract_exact_answer.py
- Input: raw generations
- Output: exact answer tokens per example

- Resampling Layer (Sections 5 & 6)
- Component: resampling.py → bootstrap sampling of generated answers
- resampling_merge_runs.py → consolidates parallel runs
- extract_exact_answer.py (with do_resampling flag) → extracts from resamples

- Probing Layer (Sections 2–4)
- probe_all_layers_and_tokens.py → heatmaps over all layers & tokens
- probe.py → train/evaluate linear classifiers on specific layer/token
- probe_type_of_error.py → error‐type classification
- probe_choose_answer.py → answer‐selection experiments

- Baseline Detection Layer
- logprob_detection.py → detect hallucinations via token log-probs
- p_true_detection.py → detect via model’s predicted probability

- Evaluation & Logging
- compute_correctness.py → aggregates final correctness metrics
- WandB service → logs experiments, metrics, and visualizations

##### Architectural Patterns & Design Principles
- Pipeline Pattern: Each script represents a stage; outputs feed as inputs to the next.
- Modularity: Utility scripts factor out shared code (probing_utils, resamples_utils).
- CLI-driven: Each step executed via a script with flags (–model, –dataset, etc.).
- External Service Integration: WandB for experiment tracking; HuggingFace Hub for model/data.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Sources"
        A[("CSV Datasets")]:::data
        B[("HuggingFace Datasets")]:::data
    end

    subgraph "Inference & Extraction"
        C["generate_model_answers.py"]:::process
        D["extract_exact_answer.py"]:::process
    end

    subgraph "Resampling"
        E["resampling.py"]:::process
        F["resampling_merge_runs.py"]:::process
        G["resamples_utils.py"]:::utility
    end

    subgraph "Probing & Analysis"
        H["probe_all_layers_and_tokens.py"]:::ml
        I["probe.py"]:::ml
        J["probe_type_of_error.py"]:::ml
        K["probe_choose_answer.py"]:::ml
        L["probing_utils.py"]:::utility
    end

    subgraph "Baseline Detection"
        M["logprob_detection.py"]:::ml
        N["p_true_detection.py"]:::ml
    end

    subgraph "Evaluation & Logging"
        O["compute_correctness.py"]:::process
        P[("WandB")]:::external
    end

    A --> C
    B --> C
    C --> D
    D --> H
    D --> I
    D --> J
    D --> K
    D --> M
    D --> N
    D --> E
    E --> F
    F --> D
    H --> O
    I --> O
    J --> O
    K --> O
    M --> O
    N --> O
    C --> P
    D --> P
    E --> P
    F --> P
    H --> P
    I --> P
    J --> P
    K --> P
    M --> P
    N --> P
    O --> P

    click A "https://github.com/technion-cs-nlp/llmsknow/tree/main/data/"
    click C "https://github.com/technion-cs-nlp/llmsknow/blob/main/src/generate_model_answers.py"
    click D "https://github.com/technion-cs-nlp/llmsknow/blob/main/src/extract_exact_answer.py"
    click E "https://github.com/technion-cs-nlp/llmsknow/blob/main/src/resampling.py"
    click F "https://github.com/technion-cs-nlp/llmsknow/blob/main/src/resampling_merge_runs.py"
    click G "https://github.com/technion-cs-nlp/llmsknow/blob/main/src/resamples_utils.py"
    click H "https://github.com/technion-cs-nlp/llmsknow/blob/main/src/probe_all_layers_and_tokens.py"
    click I "https://github.com/technion-cs-nlp/llmsknow/blob/main/src/probe.py"
    click J "https://github.com/technion-cs-nlp/llmsknow/blob/main/src/probe_type_of_error.py"
    click K "https://github.com/technion-cs-nlp/llmsknow/blob/main/src/probe_choose_answer.py"
    click L "https://github.com/technion-cs-nlp/llmsknow/blob/main/src/probing_utils.py"
    click M "https://github.com/technion-cs-nlp/llmsknow/blob/main/src/logprob_detection.py"
    click N "https://github.com/technion-cs-nlp/llmsknow/blob/main/src/p_true_detection.py"
    click O "https://github.com/technion-cs-nlp/llmsknow/blob/main/src/compute_correctness.py"
    click P "https://github.com/technion-cs-nlp/llmsknow/blob/main/requirements.txt"

    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef process fill:#98FB98,stroke:#333,stroke-width:1px
    classDef ml fill:#FFD700,stroke:#333,stroke-width:1px
    classDef utility fill:#F0E68C,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
