Q-GPT / README.md

Remove Merlin-Agent promo

5fb2e32 verified 3 months ago

9.75 kB

	---
	license: apache-2.0
	language:
	- en
	library_name: transformers
	tags:
	- quantum
	- confidence-estimation
	- uncertainty
	- pennylane
	- gpt-oss
	- hallucination-detection
	pipeline_tag: text-classification
	---

	<div align="center">

	# Q-GPT

	![qgpt](https://cdn-uploads.huggingface.co/production/uploads/67329d3f69fded92d56ab41a/91QMIE7cP4V8xZHvS_cTA.jpeg)

	### Quantum-Enhanced Confidence Estimation for Language Models

	[![PennyLane](https://img.shields.io/badge/PennyLane-Quantum_ML-6C3483?style=for-the-badge)](https://pennylane.ai/)
	[![PyTorch](https://img.shields.io/badge/PyTorch-Compatible-EE4C2C?style=for-the-badge&logo=pytorch)](https://pytorch.org/)
	[![License](https://img.shields.io/badge/License-Apache_2.0-green?style=for-the-badge)](https://www.apache.org/licenses/LICENSE-2.0)

	Know when your LLM is confident — and when it's guessing.

	</div>

	---

	## 🎯 What is Q-GPT?

	Q-GPT is a quantum neural network head that attaches to any language model and estimates how confident the model is in its response. It helps you detect when the model might be "hallucinating" or making up information.

	### The Problem

	Large Language Models (LLMs) always produce fluent text — even when they don't know the answer. They sound confident even when they're wrong. This makes it hard to trust their outputs in critical applications.

	### The Solution

	Q-GPT analyzes the internal hidden states of the model using a variational quantum circuit. Quantum computing naturally captures complex patterns and uncertainties that classical networks might miss. The result: a confidence score that tells you whether to trust the response.

	---

	## 🧠 How It Works

	```
	┌─────────────────────────────────────────────────────────────────┐
	│ Q-GPT Architecture │
	├─────────────────────────────────────────────────────────────────┤
	│ │
	│ LLM Hidden States Quantum Circuit │
	│ [2880 dimensions] [4 qubits] │
	│ │ │ │
	│ ▼ │ │
	│ ┌─────────────┐ │ │
	│ │ Compress │ ──────────────────► │ │
	│ │ to 4 dims │ │ │
	│ └─────────────┘ ▼ │
	│ ┌─────────────────┐ │
	│ │ RY RZ │ │
	│ │ │ │ │ Layer 1 │
	│ │ Rot ─●─ CNOT │ │
	│ ├─────────────────┤ │
	│ │ Rot ─●─ CNOT │ Layer 2 │
	│ ├─────────────────┤ │
	│ │ Rot ─●─ CNOT │ Layer 3 │
	│ └─────────────────┘ │
	│ │ │
	│ ▼ │
	│ ┌─────────────────┐ │
	│ │ Measure ⟨Z⟩ │ │
	│ │ on each qubit │ │
	│ └─────────────────┘ │
	│ │ │
	│ ▼ │
	│ ┌─────────────────┐ │
	│ │ Confidence │ │
	│ │ 0.0 — 1.0 │ │
	│ └─────────────────┘ │
	│ │
	└─────────────────────────────────────────────────────────────────┘
	```

	### Step by Step:

	1. Extract Hidden States — When the LLM generates a response, we capture its internal representation (hidden states from the last layer).

	2. Compress — The high-dimensional hidden states (2880 dimensions for GPT-OSS) are compressed to 4 values using a small neural network.

	3. Quantum Encoding — These 4 values are encoded into quantum states using rotation gates (RY, RZ). Each value controls the angle of rotation for one qubit.

	4. Variational Layers — The qubits pass through multiple layers of:
	- Rotation gates (trainable parameters that learn patterns)
	- CNOT gates (create entanglement between qubits)

	5. Measurement — We measure the expectation value ⟨Z⟩ of each qubit, giving us 4 numbers between -1 and +1.

	6. Confidence Output — A final layer converts these measurements into a confidence score (0-1) and an uncertainty estimate.

	### Why Quantum?

	- Entanglement captures complex correlations in the data that classical networks struggle with
	- Superposition allows exploring multiple states simultaneously
	- Inherent probabilistic nature naturally represents uncertainty
	- Compact representation — 4 qubits can represent 16-dimensional state space

	---

	## 📊 What You Get

	\| Output \| Description \|
	\|--------\|-------------\|
	\| `confidence` \| Score from 0.0 to 1.0 — how sure the model is \|
	\| `uncertainty` \| Quantum-derived uncertainty measure \|
	\| `should_refuse` \| Boolean — True if confidence < 0.3 (model should decline to answer) \|
	\| `confidence_label` \| Human-readable: "very high", "high", "moderate", "low", "very low" \|

	---

	## 💻 Usage

	### Installation

	```bash
	pip install pennylane torch transformers
	```

	### Quick Start

	```python
	from quantum_head import load_qgpt

	# Load model with quantum head
	model, tokenizer = load_qgpt("squ11z1/gpt-oss-9b-reasoning")

	# Prepare input
	prompt = "What is the capital of France?"
	inputs = tokenizer(prompt, return_tensors="pt").to(model.device)

	# Generate with confidence
	outputs = model.generate_with_confidence(
	inputs.input_ids,
	max_new_tokens=50
	)

	# Check results
	print(f"Response: {tokenizer.decode(outputs['sequences'][0])}")
	print(f"Confidence: {outputs['confidence_label']}") # "high"
	print(f"Should refuse: {outputs['should_refuse']}") # False
	```

	### Using Just the Quantum Head

	```python
	from quantum_head import QuantumHead
	import torch

	# Create quantum head for your model's hidden size
	head = QuantumHead(hidden_size=2880)

	# Get hidden states from your model
	# hidden_states shape: [batch_size, hidden_size]
	hidden_states = torch.randn(1, 2880)

	# Get confidence
	output = head(hidden_states)
	print(f"Confidence: {output['confidence'].item():.2%}")
	```

	---

	## 🎓 Training the Quantum Head

	The quantum head can be trained on examples where you know if the model was correct:

	```python
	from train import train_quantum_head

	train_quantum_head(
	model_name="squ11z1/gpt-oss-9b-reasoning",
	train_data_path="train_data.jsonl", # {text, confidence, is_correct}
	epochs=3,
	)
	```

	Training data format (JSONL):
	```json
	{"text": "What is 2+2? The answer is 4.", "confidence": 0.95, "is_correct": true}
	{"text": "The moon is made of cheese.", "confidence": 0.2, "is_correct": false}
	```

	---

	## 📁 Files

	\| File \| Description \|
	\|------\|-------------\|
	\| `quantum_head.py` \| Main implementation (QuantumHead, QGPT, load_qgpt) \|
	\| `train.py` \| Training script for the quantum head \|
	\| `__init__.py` \| Package initialization \|

	---

	## 🔬 Technical Details

	\| Parameter \| Value \|
	\|-----------\|-------\|
	\| Qubits \| 4 \|
	\| Variational Layers \| 3 \|
	\| Trainable Parameters \| ~2,000 (quantum) + ~200,000 (classical) \|
	\| Framework \| PennyLane + PyTorch \|
	\| Fallback \| Classical approximation if PennyLane unavailable \|

	---

	## ⚠️ Limitations

	- Not perfect — Confidence estimation is inherently uncertain
	- Training data dependent — Quality depends on training examples
	- Simulation — Currently runs on quantum simulator, not real hardware
	- Latency — Adds ~10-50ms per inference (quantum circuit execution)

	---

	## 📖 Citation

	```bibtex
	@misc{qgpt2026,
	title={Q-GPT: Quantum-Enhanced Confidence Estimation for Language Models},
	author={squ11z1},
	year={2026},
	url={https://huggingface.co/squ11z1/Q-GPT}
	}
	```

	---

	## 🙏 Acknowledgments

	- [PennyLane](https://pennylane.ai/) — Quantum ML framework
	- [GPT-OSS](https://huggingface.co/squ11z1/gpt-oss-9b-reasoning) — Base model

	---

	<div align="center">

	Pro Mundi Vita

	</div>