Goldcrest

LLM compression framework focusing on low-rank factorization (matrices and tensors), managing your whole experiment pipelines - compression, evaluation, profiling and logging.

Features

Quick Start

1. Install

pip install goldcrest

With optional dependencies:

pip install goldcrest[eval]    # lm-eval-harness integration
pip install goldcrest[cola]    # CoLA algebra backend

2. Configure

Create a YAML config file specifying your compression pipeline, this is an example:

model:
  name: Qwen/Qwen3-14B
  source: hf
  device: cuda

compression:
  svd:
    backend: cola
    cola:
      algorithm: lanczos

factorization:
  objects:
    - "model.layers[*].mlp.gate_proj"
    - "model.layers[*].mlp.up_proj"
    - "model.layers[*].self_attn.q_proj"
  func_name: svd
  rank: 64

evaluation:
  type: lm_eval         #   lm-eval-harness
  tasks: [arc_easy]

More example configurations are in config/.

3. Run

python scripts/examples/gpu/h100_activation_svd.py --config config/h100_activation_svd.yaml

Configuration Options

There are more detailed clarification about configuration settings for compression algorithms, and layer types to be compressed.

Example Scripts

CPU Examples (scripts/examples/cpu/)

Lightweight scripts for development and testing.

GPU Examples (scripts/examples/gpu/)

GPU scripts for H100 and H200 workloads:

Third-Party Integrations (scripts/examples/third-party/)

Project Structure

goldcrest/
├── config/                # Experiment configs plus base/ and profiles/
│   ├── base/
│   └── profiles/
├── docs/                  # Documentation and changelogs
├── logs/                  # Runtime logs
├── scripts/
│   ├── bash/              # Shell scripts (cpu/, gpu/, third-party/)
│   ├── examples/          # Python examples (cpu/, gpu/, third-party/)
│   ├── logs/              # Script execution logs
│   └── utils/             # Utility scripts
├── tests/                 # Pytest regression and integration suite
└── goldcrest/
    ├── config/            # Config loader
    ├── framework/         # Core framework (layers, state, IO)
    ├── orchestration/     # Pipeline orchestration
    └── plugins/
        ├── analysis/      # Metrics and layer selection
        ├── compression/   # SVD, Tucker, CP, pruning
        ├── evaluation/    # lm-eval integration
        └── models/        # Model utilities

Documentation

• Architecture — Plugin-based design, EventBus, and workflow system
• Changelogs — Notes on recent fixes
• Successful Runs — H200 GPU benchmark results (7 compression strategies, third-party tests)