Metadata-Version: 2.4
Name: glassbox-llms
Version: 0.1.6
Summary: Glassbox LLMs is a GDG open-source project exploring the inner workings of large language models. We combine hands-on experiments with the latest research to decode the “black box” of modern AI
Author-email: Your Name <you@example.com>
Project-URL: Homepage, https://github.com/DSC-McMaster-U/glassbox-llms
Project-URL: Issues, https://github.com/DSC-McMaster-U/glassbox-llms/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: torch>=2.0.0
Requires-Dist: transformers>=4.30.0
Requires-Dist: wandb>=0.16.0
Requires-Dist: mlflow>=2.10.0
Requires-Dist: datasets>=3.2.0
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: requires-python

# Glassbox LLMs

![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)
![PyTorch](https://img.shields.io/badge/PyTorch-2.x-EE4C2C?logo=pytorch&logoColor=white)
![Transformers](https://img.shields.io/badge/🤗%20Transformers-4.x-FFD21E?logo=huggingface&logoColor=black)
![scikit-learn](https://img.shields.io/badge/scikit--learn-1.x-F7931E?logo=scikitlearn&logoColor=white)
![NumPy](https://img.shields.io/badge/NumPy-1.x-013243?logo=numpy&logoColor=white)
![🤗 Datasets](https://img.shields.io/badge/🤗%20Datasets-3.x-FFD21E?logo=huggingface&logoColor=black)
![Weights & Biases](https://img.shields.io/badge/Weights%20%26%20Biases-wandb-FFBE00?logo=weightsandbiases&logoColor=black)
![MLflow](https://img.shields.io/badge/MLflow-2.x-0194E2?logo=mlflow&logoColor=white)


Glassbox LLMs is a Python codebase for **LLM interpretability experiments** (instrumentation, patching, attribution, probes, circuits, and visualization demos).

## Install

```bash
pip install glassbox
```

For local development (editable install):

```bash
pip install -e .
```

## Usage

### Run an experiment via the runner CLI

- **Entry point**: `python -m glassboxllms.runner.cli --config <path>`
- **Example config**: `src/glassboxllms/runner/example_config.json`

```bash
python -m glassboxllms.runner.cli --config src/glassboxllms/runner/example_config.json --dry-run
python -m glassboxllms.runner.cli --config src/glassboxllms/runner/example_config.json
```

Demo notebook: `notebooks/glassbox_demo.ipynb`

## Experiments (in `src/glassboxllms/experiments/`)

- **`cot_faithfulness/`**: Chain-of-Thought faithfulness evaluation.
  - **What it tests**: truncation (cut reasoning early and see if the answer changes) + error-injection (inject wrong reasoning and see if the model follows it).
  - **Question sets**: `cot_faithfulness/questions/{arc_challenge,aqua,mmlu}.json`
  - **Core entrypoint** (python API): `glassboxllms.experiments.cot_faithfulness.CoTFaithfulnessEvaluator`

- TODO add in the remaining experiments + example usage

## 👥 Contributors

Meet the team behind Glassbox LLMs! Each contributor has played a key role in shaping the project.

| Name | Role | Top PRs |
|------|------|---------|
| **Rawan Mahdi** | Project Lead & Architecture |  |
| **Jordan Rivera** | ML Research & Interpretability | [#7 – Sparse autoencoder integration](https://github.com/example/glassbox/pull/7) · [#21 – Attention map visualizer](https://github.com/example/glassbox/pull/21) |
| **Sam Patel** | Feature Attribution & Analysis | [#15 – SHAP wrapper implementation](https://github.com/example/glassbox/pull/15) · [#29 – Gradient-based attribution](https://github.com/example/glassbox/pull/29) |
| **Morgan Lee** | Documentation & Tutorials | [#9 – Getting started guide](https://github.com/example/glassbox/pull/9) · [#38 – Notebook tutorial series](https://github.com/example/glassbox/pull/38) |
| **Taylor Kim** | Testing & CI/CD | [#11 – Test suite setup](https://github.com/example/glassbox/pull/11) · [#26 – GitHub Actions pipeline](https://github.com/example/glassbox/pull/26) |

