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 /EXISTING_FAILURES.md

Premchandyadav369

Complete 16-phase scientific hardening, strict checkpoint audit, empirical benchmarks, and documentation

7aefd9e 13 days ago

preview code

Raw History Blame Contribute Delete

4.99 kB

# Phase Zero — Existing Failures, Defects, and Skipped Tests

## 1. Historical & Pre-Hardening Failures Recorded

### 1.1 Legacy Checkpoint Incompatibility (`qtensorformer_small.pt`)
- **Symptom:** Attempting to load `qtensorformer_small.pt` into `src.models.QTensorFormer` or `modeling_qtensorformer.QTensorFormerForCausalLM` with `strict=True` raises `RuntimeError: Error(s) in loading state_dict`.
- **Root Cause:** `qtensorformer_small.pt` was exported from an external TensorLy container (`/app/qtensorformer`, version `1.0.0`) with state-dict keys `blocks.{0,1,2}.ffn.layer.weight.factors.factor_{0..5}` and `embeddings.quantum_enhancer.qlayer.weights`. None of the repository's pure-PyTorch TT classes (`src.tensor_layers.TTLinear` or `modeling_qtensorformer.TensorTrainLinear`) use TensorLy `FactorizedTensor` naming (`0/113` keys match).
- **Resolution:** Per Phase Two non-negotiable rules, `strict=False` is prohibited and checkpoint tensors are never altered to fake compatibility. `qtensorformer_small.pt` is quarantined as a legacy external artifact (`FAIL_STRICT_LOAD`), and all benchmarks run on verified canonical models (`src.models.QTensorFormer` and `modeling_qtensorformer.QTensorFormerForCausalLM`) with `strict=True` round-trip verification.

### 1.2 Historical Config Attribute Mismatch (`backend_type`, `d_model`, `n_heads`, `n_layers`, `dropout`)
- **Symptom:** An earlier external notebook attempted to instantiate `src.models.QTensorFormer` using a raw dictionary or mismatched Hugging Face config class that lacked `src.config.ModelConfig` attributes.
- **Root Cause:** Mixing Family 4 (`QTensorFormerConfig`) and Family 3 (`ModelConfig`) without property bridges or validation.
- **Resolution:**
  - `src.config.validate_model_config()` explicitly validates required attributes (`d_model`, `n_heads`, `n_layers`, `ff_multiplier`, `max_seq_len`, `vocab_size`) and raises `ConfigurationValidationError` without guessing defaults.
  - `QTensorFormerConfig` provides read-only property accessors (`d_model`, `n_layers`, `n_heads`, `n_kv_heads`, `max_seq_len`) and constructor keyword mapping so both config families remain unambiguous and tested.

---

## 2. Source Defects Discovered and Fixed During This Audit

| Defect ID | File & Location | Description of Defect | Fix Implemented | Regression Test Added |
| :--- | :--- | :--- | :--- | :--- |
| **DEF-01** | `qtensorformer_to_gguf.py` (lines 216–231) | Fell back to `qtensorformer_small.pt` when `pytorch_model.bin` was absent and called `model.load_state_dict(state_dict, strict=False)`, silently ignoring all 113 unexpected keys and exporting untrained random weights as if they were loaded from the checkpoint. | Removed automatic fallback to `qtensorformer_small.pt`; changed checkpoint loading to enforce `strict=True` (`strict_load: bool = True`) and raise `RuntimeError` on mismatch; added explicit `[EXPORT_MODE: INITIALIZED_ARCHITECTURE]` logging when exporting an uninitialized model directory. | `tests/test_scientific_guardrails.py::test_gguf_exporter_rejects_incompatible_checkpoint_under_strict` |
| **DEF-02** | `configuration_qtensorformer.py` (line 119) | Set `keys_to_ignore_at_loading = ["model.embed_tokens.weight"]`, which could allow Hugging Face `from_pretrained` to silently ignore a missing token embedding matrix. | Set `keys_to_ignore_at_loading = []` so all model parameters are strictly required during loading. | `tests/test_scientific_guardrails.py::test_hf_config_does_not_ignore_missing_weights` |
| **DEF-03** | `src/router.py` (lines 91–93) | `QuantumRouter.forward()` lazily created `self._q_out_proj = nn.Linear(self.q_input_dim, d_model).to(x.device)` on the first forward call, meaning parameters were missing from `router.parameters()` right after `__init__()`. | Registered `self._q_out_proj = nn.Linear(q_input_dim, d_model)` deterministically inside `QuantumRouter.__init__()`. | `tests/test_scientific_guardrails.py::test_quantum_router_deterministic_init_registration` |

---

## 3. Skipped Tests & Environment Blockers

| Item | Status | Reason |
| :--- | :--- | :--- |
| `tests/test_quantum_layers.py` (3 PennyLane circuit tests) | `SKIPPED` | Optional package `pennylane` is not installed in the default CPU environment; `ClassicalSurrogateUnitary` and `ClassicalQuantumFallback` are active and tested. |
| `tests/test_tensor_layers.py::test_tltorch_comparison` | `SKIPPED` | Optional package `tltorch` is not installed; native PyTorch `TTLinear.to_matrix()` reconstruction is verified to `< 1.3e-6` max absolute error. |
| Physical GPU / CUDA Kernel Execution | `BLOCKED / N/A` | Host has no NVIDIA GPU (`torch.cuda.is_available() == False`). Triton kernel path falls back cleanly to PyTorch tensor contraction. |
| Hardware Power Sensor (NVML / RAPL / Wall Meter) | `UNVERIFIED / N/A` | Host does not expose NVML or unprivileged RAPL counters; energy figures are explicitly labeled `ESTIMATED (LEVEL 1/2/3)` and never reported as measured sensor joules. |

	# Phase Zero — Existing Failures, Defects, and Skipped Tests

	## 1. Historical & Pre-Hardening Failures Recorded

	### 1.1 Legacy Checkpoint Incompatibility (`qtensorformer_small.pt`)
	- Symptom: Attempting to load `qtensorformer_small.pt` into `src.models.QTensorFormer` or `modeling_qtensorformer.QTensorFormerForCausalLM` with `strict=True` raises `RuntimeError: Error(s) in loading state_dict`.
	- Root Cause: `qtensorformer_small.pt` was exported from an external TensorLy container (`/app/qtensorformer`, version `1.0.0`) with state-dict keys `blocks.{0,1,2}.ffn.layer.weight.factors.factor_{0..5}` and `embeddings.quantum_enhancer.qlayer.weights`. None of the repository's pure-PyTorch TT classes (`src.tensor_layers.TTLinear` or `modeling_qtensorformer.TensorTrainLinear`) use TensorLy `FactorizedTensor` naming (`0/113` keys match).
	- Resolution: Per Phase Two non-negotiable rules, `strict=False` is prohibited and checkpoint tensors are never altered to fake compatibility. `qtensorformer_small.pt` is quarantined as a legacy external artifact (`FAIL_STRICT_LOAD`), and all benchmarks run on verified canonical models (`src.models.QTensorFormer` and `modeling_qtensorformer.QTensorFormerForCausalLM`) with `strict=True` round-trip verification.

	### 1.2 Historical Config Attribute Mismatch (`backend_type`, `d_model`, `n_heads`, `n_layers`, `dropout`)
	- Symptom: An earlier external notebook attempted to instantiate `src.models.QTensorFormer` using a raw dictionary or mismatched Hugging Face config class that lacked `src.config.ModelConfig` attributes.
	- Root Cause: Mixing Family 4 (`QTensorFormerConfig`) and Family 3 (`ModelConfig`) without property bridges or validation.
	- Resolution:
	- `src.config.validate_model_config()` explicitly validates required attributes (`d_model`, `n_heads`, `n_layers`, `ff_multiplier`, `max_seq_len`, `vocab_size`) and raises `ConfigurationValidationError` without guessing defaults.
	- `QTensorFormerConfig` provides read-only property accessors (`d_model`, `n_layers`, `n_heads`, `n_kv_heads`, `max_seq_len`) and constructor keyword mapping so both config families remain unambiguous and tested.

	---

	## 2. Source Defects Discovered and Fixed During This Audit

	\| Defect ID \| File & Location \| Description of Defect \| Fix Implemented \| Regression Test Added \|
	\| :--- \| :--- \| :--- \| :--- \| :--- \|
	\| DEF-01 \| `qtensorformer_to_gguf.py` (lines 216–231) \| Fell back to `qtensorformer_small.pt` when `pytorch_model.bin` was absent and called `model.load_state_dict(state_dict, strict=False)`, silently ignoring all 113 unexpected keys and exporting untrained random weights as if they were loaded from the checkpoint. \| Removed automatic fallback to `qtensorformer_small.pt`; changed checkpoint loading to enforce `strict=True` (`strict_load: bool = True`) and raise `RuntimeError` on mismatch; added explicit `[EXPORT_MODE: INITIALIZED_ARCHITECTURE]` logging when exporting an uninitialized model directory. \| `tests/test_scientific_guardrails.py::test_gguf_exporter_rejects_incompatible_checkpoint_under_strict` \|
	\| DEF-02 \| `configuration_qtensorformer.py` (line 119) \| Set `keys_to_ignore_at_loading = ["model.embed_tokens.weight"]`, which could allow Hugging Face `from_pretrained` to silently ignore a missing token embedding matrix. \| Set `keys_to_ignore_at_loading = []` so all model parameters are strictly required during loading. \| `tests/test_scientific_guardrails.py::test_hf_config_does_not_ignore_missing_weights` \|
	\| DEF-03 \| `src/router.py` (lines 91–93) \| `QuantumRouter.forward()` lazily created `self._q_out_proj = nn.Linear(self.q_input_dim, d_model).to(x.device)` on the first forward call, meaning parameters were missing from `router.parameters()` right after `__init__()`. \| Registered `self._q_out_proj = nn.Linear(q_input_dim, d_model)` deterministically inside `QuantumRouter.__init__()`. \| `tests/test_scientific_guardrails.py::test_quantum_router_deterministic_init_registration` \|

	---

	## 3. Skipped Tests & Environment Blockers

	\| Item \| Status \| Reason \|
	\| :--- \| :--- \| :--- \|
	\| `tests/test_quantum_layers.py` (3 PennyLane circuit tests) \| `SKIPPED` \| Optional package `pennylane` is not installed in the default CPU environment; `ClassicalSurrogateUnitary` and `ClassicalQuantumFallback` are active and tested. \|
	\| `tests/test_tensor_layers.py::test_tltorch_comparison` \| `SKIPPED` \| Optional package `tltorch` is not installed; native PyTorch `TTLinear.to_matrix()` reconstruction is verified to `< 1.3e-6` max absolute error. \|
	\| Physical GPU / CUDA Kernel Execution \| `BLOCKED / N/A` \| Host has no NVIDIA GPU (`torch.cuda.is_available() == False`). Triton kernel path falls back cleanly to PyTorch tensor contraction. \|
	\| Hardware Power Sensor (NVML / RAPL / Wall Meter) \| `UNVERIFIED / N/A` \| Host does not expose NVML or unprivileged RAPL counters; energy figures are explicitly labeled `ESTIMATED (LEVEL 1/2/3)` and never reported as measured sensor joules. \|