SOURCE_API_FINAL.md

# 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)
```