File size: 2,130 Bytes
0b7ee79 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 | # SOURCE API FINAL: Standard Model & Configuration Interfaces
**Date**: September 17, 2026
**Repository**: `Premchan369/Q-TensorFormer`
---
## 1. Canonical Model Configuration Interface
```python
from src.config import ModelConfig, validate_model_config
# Canonical ModelConfig hyperparameter signature
config = ModelConfig(
vocab_size=10000, # Vocabulary size
d_model=128, # Model embedding dimension
n_heads=4, # Number of attention heads
n_layers=2, # Number of transformer blocks
ff_multiplier=4, # Feed-forward expansion factor (D_ff = d_model * ff_multiplier)
max_seq_len=128, # Maximum sequence context length
dropout=0.1, # Dropout rate
tt_rank=8, # Maximum Tensor-Train rank
tt_min_rank=2, # Minimum Tensor-Train rank
use_tensor_ffn=True, # Enable TT-FFN
n_qubits=4, # Number of quantum simulation wires
n_quantum_layers=2, # Number of variational circuit layers
quantum_sparsity=0.3, # Target quantum routing sparsity
use_quantum=True, # Enable quantum pathway
rank_alpha=2.0, # Rank allocation slope
rank_smoothing=0.9, # EMA rank smoothing factor
)
# Validate config against model requirements
validate_model_config(config, QTensorFormer)
```
---
## 2. Canonical Model Instantiation & Forward Pass
```python
from src.models import QTensorFormer, DenseBaseline
# Instantiate Q-TensorFormer
qtf = QTensorFormer(config, preset="QTF_BALANCED")
# Instantiate Apples-to-Apples Dense Baseline
dense = DenseBaseline(config)
# Forward pass
import torch
input_ids = torch.randint(0, config.vocab_size, (1, 32), dtype=torch.long)
logits_qtf = qtf(input_ids) # Shape: [1, 32, 10000]
logits_dense = dense(input_ids) # Shape: [1, 32, 10000]
```
---
## 3. Legacy Module Interoperability
Both `q_tensor_former.py` and `q_tensor_former_v2.py` accept the canonical `ModelConfig` directly:
```python
import q_tensor_former as qtf1
import q_tensor_former_v2 as qtf2
m1 = qtf1.QTensorFormer(config)
m2 = qtf2.QTensorFormer(config)
```
|