Upload README.md

README.md

@@ -1,97 +1,72 @@
----
-title: Q-TensorFormer
-emoji: ⚛️
-colorFrom: purple
-colorTo: blue
-sdk: gradio
-sdk_version: 4.44.1
-app_file: app.py
-pinned: false
-license: apache-2.0
-tags:
-- ml-intern
----
-
 # Q-TensorFormer: Quantum-Enhanced Tensor Network LLM Compression Engine
 
-## Overview
+A hybrid quantum-tensor transformer that adaptively compresses FFN layers using
+**Tensor-Train decomposition** and **quantum feature encoding**, guided by
+**entanglement entropy**.
 
-**Q-TensorFormer** is a hybrid quantum-tensor model that adaptively compresses itself using entanglement entropy, achieving major efficiency gains with minimal performance loss.
+## Key Innovation
 
-**Claim**: 50-70% parameter reduction with same accuracy ± small drop, fewer compute ops / latency.
+```
+rank = r_min + α × S(ρ)
+```
 
-## Architecture
+Where S(ρ) is the entanglement entropy (estimated from attention patterns).
+Higher entropy → higher tensor rank needed; lower entropy → more compression.
 
-### Three Pillars
+## Architecture
 
-1. **Tensor Compression (Efficiency)**
-   - Dense FFN layers replaced with Tensor-Train (TT) decomposition via tltorch
-   - Dramatic parameter reduction while preserving expressivity
+| Component | Technology |
+|-----------|-----------|
+| FFN Layers | Pure-PyTorch Tensor-Train (TT) decomposition |
+| Feature Encoding | PennyLane quantum angle embedding (4 qubits) |
+| Attention | Classical multi-head attention (stable) |
+| Rank Scheduler | Entanglement-guided adaptive rank |
+| Quantum Router | Selective: only "hard" tokens → quantum circuit |
 
-2. **Quantum Feature Encoding (Expressivity)**
-   - PennyLane quantum circuits encode token embeddings into quantum states
-   - Angle encoding + variational circuits extract richer features than classical
+## Benchmark Results
 
-3. **Entanglement-Guided Rank Adaptation (Novelty)**
-   - `r = r_min + α · S(ρ)` — tensor ranks adjust based on quantum state entropy
-   - Model becomes input-aware and compute-efficient
+**Config**: d_model=64, 2 layers, 4 heads, TT-rank=8, 4 qubits
 
-### Core Components
+| Metric | Q-TensorFormer | Baseline |
+|--------|:---:|:---:|
+| Parameters | **115,292** | 167,808 |
+| Val Perplexity | 925.7 | 923.5 |
+| Model Size (MB) | **0.4** | 0.6 |
+| Compression | **1.5×** fewer params | — |
+| PPL Ratio | **1.00×** | — |
 
-- `TTFactorizedLinear`: Tensor-Train compressed linear layers
-- `QuantumFeatureEncoder`: PennyLane angle encoding with TorchLayer
-- `QuantumKernelAttention`: Quantum kernel self-attention (QKSAN-style)
-- `SelectiveQuantumRouter`: Only "hard" tokens go to quantum circuit
-- `RankScheduler`: Entanglement-guided dynamic rank adjustment
+**✅ 31.3% parameter reduction with identical perplexity!**
 
-## Results
+## File Structure
 
-| Metric | Baseline | Q-TensorFormer | Reduction |
-|--------|----------|----------------|-----------|
-| Parameters | 10,764,288 | 1,325,102 | **8.12x** |
-| Memory (MB) | ~42 MB | ~5 MB | **8.12x** |
-| Compression | 1.00x | 8.12x | ✓ |
+```
+q_tensor_former.py    — Full self-contained implementation (480+ lines)
+                      — PureTTLinear, QuantumEmbed, TTFFN, RankScheduler,
+                        QuantumRouter, MHA, HybridBlock, QTensorFormer,
+                        Baseline, training + evaluation pipeline
+```
 
-## Usage
+## Dependencies
 
-```python
-from qtensorformer import QTensorFormer, ModelConfig
+```
+pip install torch pennylane
+```
 
-config = ModelConfig(
-    vocab_size=10000,
-    hidden_dim=128,
-    n_layers=3,
-    tt_rank=4,
-    n_qubits=4,
-    use_quantum_attention=True,
-    use_adaptive_rank=True,
-)
+## Quick Start
 
-model = QTensorFormer(config)
-logits, loss, stats = model(input_ids, labels=labels)
+```bash
+python q_tensor_former.py
 ```
 
+Runs a full benchmark: trains Q-TensorFormer and Baseline, evaluates both,
+and prints the comparison.
+
 ## Citation
 
 ```bibtex
-@misc{qtensorformer2025,
-  title={Q-TensorFormer: Quantum-Enhanced Tensor Network LLM Compression},
-  author={Q-TensorFormer Team},
-  year={2025},
-  note={Hybrid quantum-tensor model with entanglement-guided compression}
+@software{q_tensorformer,
+  title = {Q-TensorFormer: Quantum-Enhanced Tensor Network LLM Compression},
+  year = {2026},
+  url = {https://huggingface.co/Premchan369/q-tensorformer}
 }
 ```
-
-## References
-
-- QKSAN (Quantum Kernel Self-Attention Network): arXiv:2308.13422
-- tltorch: TensorLy-Torch for deep tensor learning
-- PennyLane: Quantum machine learning library
-
-<!-- ml-intern-provenance -->
-## Generated by ML Intern
-
-This model repository was generated by [ML Intern](https://github.com/huggingface/ml-intern), an agent for machine learning research and development on the Hugging Face Hub.
-
-- Try ML Intern: https://smolagents-ml-intern.hf.space
-- Source code: https://github.com/huggingface/ml-intern