Instructions to use Premchan369/Q-TensorFormer with libraries, inference providers, notebooks, and local apps. Follow these links to get started.

Libraries

How to use Premchan369/Q-TensorFormer with Transformers:

# Use a pipeline as a high-level helper
from transformers import pipeline

pipe = pipeline("text-generation", model="Premchan369/Q-TensorFormer", trust_remote_code=True)

# pip install -U transformers accelerate
# Load model directly
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("Premchan369/Q-TensorFormer", trust_remote_code=True, device_map="auto")

Notebooks
Google Colab
Kaggle
Local Apps Settings

vLLM

How to use Premchan369/Q-TensorFormer with vLLM:

Install from pip and serve model

# Install vLLM from pip:
pip install vllm
# Start the vLLM server:
vllm serve "Premchan369/Q-TensorFormer"
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:8000/v1/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "Premchan369/Q-TensorFormer",
		"prompt": "Once upon a time,",
		"max_tokens": 512,
		"temperature": 0.5
	}'

Use Docker

docker model run hf.co/Premchan369/Q-TensorFormer

SGLang

How to use Premchan369/Q-TensorFormer with SGLang:

Install from pip and serve model

# Install SGLang from pip:
pip install sglang
# Start the SGLang server:
python3 -m sglang.launch_server \
    --model-path "Premchan369/Q-TensorFormer" \
    --host 0.0.0.0 \
    --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "Premchan369/Q-TensorFormer",
		"prompt": "Once upon a time,",
		"max_tokens": 512,
		"temperature": 0.5
	}'

Use Docker images

docker run --gpus all \
    --shm-size 32g \
    -p 30000:30000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=<secret>" \
    --ipc=host \
    lmsysorg/sglang:latest \
    python3 -m sglang.launch_server \
        --model-path "Premchan369/Q-TensorFormer" \
        --host 0.0.0.0 \
        --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "Premchan369/Q-TensorFormer",
		"prompt": "Once upon a time,",
		"max_tokens": 512,
		"temperature": 0.5
	}'

Docker Model Runner
How to use Premchan369/Q-TensorFormer with Docker Model Runner:
```
docker model run hf.co/Premchan369/Q-TensorFormer
```

Q-TensorFormer / reports /REPOSITORY_FORENSICS_AUDIT_V2.md

Premchandyadav369

feat: complete scientific repair, canonical checkpoint training, tokenizer, GQA zero-copy, and release gating

d279df0 13 days ago

preview code

Raw History Blame Contribute Delete

7.83 kB

# Q-TensorFormer — Repository Forensics & Scientific Verification Audit (v2)

**Timestamp:** 2026-10-13T12:00:00Z  
**Canonical Project Name:** `Q-TensorFormer`  
**Host Environment:** Windows 10, Python 3.11.9, PyTorch 2.10.0+cpu, Transformers 4.41.2, NumPy 2.4.6  
**Repository URI:** https://huggingface.co/Premchan369/Q-TensorFormer  
**Audit Version:** v2 (Post-Repair & Canonical Checkpoint Release)  
**Historical Audit Preserved:** `reports/FORENSIC_AUDIT.md` (v1 historical findings preserved without overwrite)

---

## 1. Traceable Component Classification Matrix

| Component | Actual Implementation | Evidence | Status | Required Action / Resolution |
| :--- | :--- | :--- | :--- | :--- |
| **Canonical Model** | `src/models.py` (`QTensorFormer`, `DenseBaseline`, `PositionalEncoding`) | Full forward/backward passes verified in `tests/test_model.py`, `tests/test_advanced_features.py`, and `scripts/smoke_test.py`. Strict config validation enforced; context-window boundaries and dynamic sinusoidal positional encodings supported. | **Verified Working** | None. Source of truth established; config validation strictly active. |
| **Configuration** | `src/config.py` (`ModelConfig`, `TrainingConfig`, `BudgetConfig`, `validate_model_config`) | `tests/test_scientific_guardrails.py` confirms rejection of incomplete configs without default guessing; YAML serialization roundtrip verified. | **Verified Working** | None. Canonical research schema validated. |
| **Checkpoint** | `src/checkpoint.py`, `checkpoints/qtensorformer_canonical_trained.pt` (SHA-256 `9e5a96913477263d...`), legacy `qtensorformer_small.pt` | Legacy checkpoint confirmed incompatible (`0/113` key overlap, TensorLy container artifact). Newly trained canonical checkpoint loads with 100% key match under `strict=True`, verifies parameter values, records full training provenance and companion `.metadata.json`. | **Verified Working** | Preserved legacy artifact untouched; canonical trained checkpoint deployed as default. |
| **Tokenizer** | `src/tokenizer.py` (`QTensorFormerTokenizer`), `checkpoints/tokenizer/` | `tests/test_tokenizer_and_training.py` verifies deterministic 256-token vocabulary, `<pad>=0, <bos>=1, <eos>=2, <unk>=3`, exact text roundtrip, batch padding + `attention_mask` generation, and model vocabulary alignment checks. | **Verified Working** | Canonical tokenizer saved to `checkpoints/tokenizer/` and synced with model output heads. |
| **Training Pipeline** | `src/training.py` (`LanguageModelTrainer`, `DistillationTrainer`), `scripts/train_and_evaluate.py`, `scripts/distill.py` | Real training executed on `data/qtensorformer_corpus.txt`. Loss decreased from 5.8646 (ppl 352.35) to 3.8086 (ppl 45.09) on QTensorFormer; matched DenseBaseline decreased from 5.7282 to 3.8242. Metrics logged to `results/raw/training_and_quality_validation.json`. | **Verified Working** | Real training pipeline active and reproducible via deterministic seeds. |
| **Tensor-Train Compression** | `src/tensor_layers.py` (`TTLinear`, `TTFeedForward`), `kernels/tt_kernels.py` | `tests/test_tensor_layers.py` and `tests/test_nested_tt.py` verify exact dense matrix reconstruction, instantaneous rank slicing (r=1,2,4,8), and gradient flow. PyTorch native fallback active on CPU; Triton kernels available on CUDA. | **Verified Working** | Zero-dependency PyTorch fallback active; Triton acceleration ready when GPU present. |
| **Adaptive Rank** | `src/resource_allocator.py` (`InformationValueAllocator`, `PIDDualSubgradientController`) | `tests/test_resource_allocator.py` and `tests/test_model.py` verify 100-step entropy stabilization, hysteresis threshold ($\tau=0.15$) suppressing chattering, and Pareto budget enforcement. | **Verified Working** | Dynamic rank switching verified under closed-loop control. |
| **Adaptive Attention** | `src/attention.py` (`MultiHeadAttention`), `modeling_qtensorformer.py` | Zero-copy 5D GQA broadcasting (`num_queries_per_kv > 1`) verified without K/V replication. IEEE-754 NaN bug resolved via boolean `masked_fill`. Full causal + padding mask combinations verified without NaNs. | **Verified Working** | K/V expansion memory copy eliminated; padding masks fully tested. |
| **KV-Cache Optimization** | `src/kv_cache.py` (`AdaptiveKVCache`, `HierarchicalAdaptiveKVCache`, `QuantizedKVTensor`) | `tests/test_kv_cache.py` verifies sink token retention across long horizons, dynamic precision transitions (FP16 $\rightarrow$ INT8 $\rightarrow$ INT4), and metadata tracking. | **Verified Working** | Quantized INT4/INT8 tensors and sink-preserving eviction fully functional. |
| **Quantum Pathway** | `src/quantum_backend.py`, `src/quantum_layers.py`, `src/router.py` | `ClassicalSurrogateUnitary` executes SU($2^N$) Lie group emulator deterministically without external simulator dependencies. Meyer-Wallach entanglement ($Q \in [0, 1]$) and Haar expressibility divergence verified in `tests/test_quantum_backend.py`. | **Verified Working (Classical Surrogate) / Partially Working (Physical QPU)** | Labeled strictly as `SIMULATED` (classical surrogate); physical QPU bridge stubbed as `HARDWARE_INTERFACE`. |
| **Hugging Face Integration** | `configuration_qtensorformer.py`, `modeling_qtensorformer.py`, `checkpoints/hf_canonical_trained/` | `tests/test_hf_integration.py` verifies `AutoConfig`, `AutoModelForCausalLM`, `generate()`, and `save_pretrained`/`from_pretrained` roundtrips without ignoring missing keys. | **Verified Working** | `keys_to_ignore_at_loading = []` verified. Canonical checkpoint export completed. |
| **Export & Deployment** | `qtensorformer_to_gguf.py`, `export_onnx.py` | `tests/test_scientific_guardrails.py` verifies GGUF exporter strictly enforces `strict=True` and rejects mismatched checkpoints. ONNX export verified in `tests/test_frontier_v10.py`. | **Verified Working** | `strict=False` bypasses removed; exports produce verifiable target artifacts. |
| **Benchmarks** | `scripts/run_scientific_benchmark.py`, `scripts/scientific_integrity_checker.py`, `scripts/smoke_test.py` | 94 unit tests passing (0 failing, 4 PennyLane-specific skipped). All empirical outputs logged to `results/raw/`, `results/processed/`, and `results/metadata/`. Every metric explicitly classified as `MEASURED`, `SIMULATED`, or `ESTIMATED`. | **Verified Working** | Automated integrity checker enforces evidence tagging across all reported figures. |

---

## 2. Summary of Resolved Blockers

1. **Checkpoint Blocker**: Legacy `qtensorformer_small.pt` had 0/113 key overlap under `strict=True` due to an incompatible external TensorLy structure. A genuine canonical checkpoint (`checkpoints/qtensorformer_canonical_trained.pt`) has been trained and saved with complete provenance, SHA-256 fingerprinting, and strict loading verification.
2. **Attention Mask NaN Bug**: Replaced vulnerable `mask * float("-inf")` multiplications in `src/attention.py` and `src/baselines.py` with boolean `masked_fill`, guarding against all-masked padding query rows and preventing `NaN` generation in both forward and backward passes.
3. **GQA Memory Copy Blocker**: Eliminated `repeat_interleave` and `.expand().reshape()` memory copies in `src/attention.py` and `modeling_qtensorformer.py`. GQA now broadcasts key and value heads directly via 5D zero-copy views.
4. **Tokenizer Missing Infrastructure**: Implemented `QTensorFormerTokenizer` in `src/tokenizer.py` supporting deterministic vocabulary building, explicit special tokens (`<pad>=0, <bos>=1, <eos>=2, <unk>=3`), batch encoding with attention masks, model alignment validation, and JSON artifact persistence.
5. **Training and Evaluation Blocker**: Implemented `LanguageModelTrainer`, `DistillationTrainer`, and `evaluate_model` in `src/training.py` and `src/metrics.py`, making both canonical LM training and distillation fully functional.

	# Q-TensorFormer — Repository Forensics & Scientific Verification Audit (v2)

	Timestamp: 2026-10-13T12:00:00Z
	Canonical Project Name: `Q-TensorFormer`
	Host Environment: Windows 10, Python 3.11.9, PyTorch 2.10.0+cpu, Transformers 4.41.2, NumPy 2.4.6
	Repository URI: https://huggingface.co/Premchan369/Q-TensorFormer
	Audit Version: v2 (Post-Repair & Canonical Checkpoint Release)
	Historical Audit Preserved: `reports/FORENSIC_AUDIT.md` (v1 historical findings preserved without overwrite)

	---

	## 1. Traceable Component Classification Matrix

	\| Component \| Actual Implementation \| Evidence \| Status \| Required Action / Resolution \|
	\| :--- \| :--- \| :--- \| :--- \| :--- \|
	\| Canonical Model \| `src/models.py` (`QTensorFormer`, `DenseBaseline`, `PositionalEncoding`) \| Full forward/backward passes verified in `tests/test_model.py`, `tests/test_advanced_features.py`, and `scripts/smoke_test.py`. Strict config validation enforced; context-window boundaries and dynamic sinusoidal positional encodings supported. \| Verified Working \| None. Source of truth established; config validation strictly active. \|
	\| Configuration \| `src/config.py` (`ModelConfig`, `TrainingConfig`, `BudgetConfig`, `validate_model_config`) \| `tests/test_scientific_guardrails.py` confirms rejection of incomplete configs without default guessing; YAML serialization roundtrip verified. \| Verified Working \| None. Canonical research schema validated. \|
	\| Checkpoint \| `src/checkpoint.py`, `checkpoints/qtensorformer_canonical_trained.pt` (SHA-256 `9e5a96913477263d...`), legacy `qtensorformer_small.pt` \| Legacy checkpoint confirmed incompatible (`0/113` key overlap, TensorLy container artifact). Newly trained canonical checkpoint loads with 100% key match under `strict=True`, verifies parameter values, records full training provenance and companion `.metadata.json`. \| Verified Working \| Preserved legacy artifact untouched; canonical trained checkpoint deployed as default. \|
	\| Tokenizer \| `src/tokenizer.py` (`QTensorFormerTokenizer`), `checkpoints/tokenizer/` \| `tests/test_tokenizer_and_training.py` verifies deterministic 256-token vocabulary, `<pad>=0, <bos>=1, <eos>=2, <unk>=3`, exact text roundtrip, batch padding + `attention_mask` generation, and model vocabulary alignment checks. \| Verified Working \| Canonical tokenizer saved to `checkpoints/tokenizer/` and synced with model output heads. \|
	\| Training Pipeline \| `src/training.py` (`LanguageModelTrainer`, `DistillationTrainer`), `scripts/train_and_evaluate.py`, `scripts/distill.py` \| Real training executed on `data/qtensorformer_corpus.txt`. Loss decreased from 5.8646 (ppl 352.35) to 3.8086 (ppl 45.09) on QTensorFormer; matched DenseBaseline decreased from 5.7282 to 3.8242. Metrics logged to `results/raw/training_and_quality_validation.json`. \| Verified Working \| Real training pipeline active and reproducible via deterministic seeds. \|
	\| Tensor-Train Compression \| `src/tensor_layers.py` (`TTLinear`, `TTFeedForward`), `kernels/tt_kernels.py` \| `tests/test_tensor_layers.py` and `tests/test_nested_tt.py` verify exact dense matrix reconstruction, instantaneous rank slicing (r=1,2,4,8), and gradient flow. PyTorch native fallback active on CPU; Triton kernels available on CUDA. \| Verified Working \| Zero-dependency PyTorch fallback active; Triton acceleration ready when GPU present. \|
	\| Adaptive Rank \| `src/resource_allocator.py` (`InformationValueAllocator`, `PIDDualSubgradientController`) \| `tests/test_resource_allocator.py` and `tests/test_model.py` verify 100-step entropy stabilization, hysteresis threshold ($\tau=0.15$) suppressing chattering, and Pareto budget enforcement. \| Verified Working \| Dynamic rank switching verified under closed-loop control. \|
	\| Adaptive Attention \| `src/attention.py` (`MultiHeadAttention`), `modeling_qtensorformer.py` \| Zero-copy 5D GQA broadcasting (`num_queries_per_kv > 1`) verified without K/V replication. IEEE-754 NaN bug resolved via boolean `masked_fill`. Full causal + padding mask combinations verified without NaNs. \| Verified Working \| K/V expansion memory copy eliminated; padding masks fully tested. \|
	\| KV-Cache Optimization \| `src/kv_cache.py` (`AdaptiveKVCache`, `HierarchicalAdaptiveKVCache`, `QuantizedKVTensor`) \| `tests/test_kv_cache.py` verifies sink token retention across long horizons, dynamic precision transitions (FP16 $\rightarrow$ INT8 $\rightarrow$ INT4), and metadata tracking. \| Verified Working \| Quantized INT4/INT8 tensors and sink-preserving eviction fully functional. \|
	\| Quantum Pathway \| `src/quantum_backend.py`, `src/quantum_layers.py`, `src/router.py` \| `ClassicalSurrogateUnitary` executes SU($2^N$) Lie group emulator deterministically without external simulator dependencies. Meyer-Wallach entanglement ($Q \in [0, 1]$) and Haar expressibility divergence verified in `tests/test_quantum_backend.py`. \| Verified Working (Classical Surrogate) / Partially Working (Physical QPU) \| Labeled strictly as `SIMULATED` (classical surrogate); physical QPU bridge stubbed as `HARDWARE_INTERFACE`. \|
	\| Hugging Face Integration \| `configuration_qtensorformer.py`, `modeling_qtensorformer.py`, `checkpoints/hf_canonical_trained/` \| `tests/test_hf_integration.py` verifies `AutoConfig`, `AutoModelForCausalLM`, `generate()`, and `save_pretrained`/`from_pretrained` roundtrips without ignoring missing keys. \| Verified Working \| `keys_to_ignore_at_loading = []` verified. Canonical checkpoint export completed. \|
	\| Export & Deployment \| `qtensorformer_to_gguf.py`, `export_onnx.py` \| `tests/test_scientific_guardrails.py` verifies GGUF exporter strictly enforces `strict=True` and rejects mismatched checkpoints. ONNX export verified in `tests/test_frontier_v10.py`. \| Verified Working \| `strict=False` bypasses removed; exports produce verifiable target artifacts. \|
	\| Benchmarks \| `scripts/run_scientific_benchmark.py`, `scripts/scientific_integrity_checker.py`, `scripts/smoke_test.py` \| 94 unit tests passing (0 failing, 4 PennyLane-specific skipped). All empirical outputs logged to `results/raw/`, `results/processed/`, and `results/metadata/`. Every metric explicitly classified as `MEASURED`, `SIMULATED`, or `ESTIMATED`. \| Verified Working \| Automated integrity checker enforces evidence tagging across all reported figures. \|

	---

	## 2. Summary of Resolved Blockers

	1. Checkpoint Blocker: Legacy `qtensorformer_small.pt` had 0/113 key overlap under `strict=True` due to an incompatible external TensorLy structure. A genuine canonical checkpoint (`checkpoints/qtensorformer_canonical_trained.pt`) has been trained and saved with complete provenance, SHA-256 fingerprinting, and strict loading verification.
	2. Attention Mask NaN Bug: Replaced vulnerable `mask * float("-inf")` multiplications in `src/attention.py` and `src/baselines.py` with boolean `masked_fill`, guarding against all-masked padding query rows and preventing `NaN` generation in both forward and backward passes.
	3. GQA Memory Copy Blocker: Eliminated `repeat_interleave` and `.expand().reshape()` memory copies in `src/attention.py` and `modeling_qtensorformer.py`. GQA now broadcasts key and value heads directly via 5D zero-copy views.
	4. Tokenizer Missing Infrastructure: Implemented `QTensorFormerTokenizer` in `src/tokenizer.py` supporting deterministic vocabulary building, explicit special tokens (`<pad>=0, <bos>=1, <eos>=2, <unk>=3`), batch encoding with attention masks, model alignment validation, and JSON artifact persistence.
	5. Training and Evaluation Blocker: Implemented `LanguageModelTrainer`, `DistillationTrainer`, and `evaluate_model` in `src/training.py` and `src/metrics.py`, making both canonical LM training and distillation fully functional.