reports/SOURCE_API_AUDIT.md

Phase One — Source API & Execution Path Audit

1. Canonical Research API (src/)

1.1 src.config.ModelConfig

• File: src/config.py
• Fields:
  • d_model: int = 128
  • n_heads: int = 4
  • n_layers: int = 2
  • ff_multiplier: int = 4
  • max_seq_len: int = 128
  • vocab_size: int = 10000
  • dropout: float = 0.1
  • tt_rank: int = 8
  • tt_min_rank: int = 2
  • use_tensor_ffn: bool = True
  • n_qubits: int = 4
  • n_quantum_layers: int = 2
  • quantum_sparsity: float = 0.3
  • use_quantum: bool = True
  • rank_alpha: float = 2.0
  • rank_smoothing: float = 0.9
• Validation: ModelConfig.validate() asserts d_model % n_heads == 0, 1 <= tt_min_rank <= tt_rank, n_qubits <= 8, and 0 <= quantum_sparsity <= 1. validate_model_config(config, model_class) checks all required fields without inventing defaults.

1.2 src.models.QTensorFormer

• File: src/models.py
• Constructor: QTensorFormer(config: ModelConfig, preset: str = "QTF_BALANCED")
• Supported Presets: QTF_FULL, QTF_BALANCED, QTF_LATENCY, QTF_MEMORY, QTF_ENERGY, QTF_EDGE, QTF_CLASSICAL_ONLY.
• Execution Path (forward):
  1. Embeds input_ids (nn.Embedding) + sinusoidal PositionalEncoding.
  2. Iterates over self.blocks (nn.ModuleList of HybridBlock):
     • HybridBlock calls self.info_engine(hidden_states=x) $\rightarrow z_t \in [0, 1]^{B \times T \times 8}$.
     • HybridBlock calls self.allocator(z_t, budget=budget, preset=preset, force_classical=...) $\rightarrow$ selects rank, token_ranks, attn_mode_idx, depth_mode, kv_precision, is_quantum_token.
     • If depth_mode == "skip", returns residual x immediately.
     • Updates kv_cache.set_precision(kv_precision) if kv_cache is supplied.
     • Runs self.attention(normed_x, mask=mask, kv_cache=kv_cache, use_quantum=has_quantum_attn and not force_classical).
     • Checks optional early_exit_head if enable_early_exit=True.
     • If depth_mode == "partial", skips FFN and returns x.
     • Sets self.tt_ffn.set_rank(chosen_rank) and executes self.tt_ffn(normed_ffn_in, token_ranks=token_ranks).
     • If is_quantum_token.any() and not force_classical, applies self.quantum_backend(normed_ffn_in) masked by is_quantum_token.
  3. Applies final self.ln_f and weight-tied self.lm_head.

---

2. Canonical Hugging Face API (configuration_qtensorformer.py & modeling_qtensorformer.py)

2.1 configuration_qtensorformer.QTensorFormerConfig

• Inherits from: transformers.PretrainedConfig (model_type = "qtensorformer")
• Strict Loading Policy: keys_to_ignore_at_loading = [] (repaired in Phase Two so no missing weights are ignored).
• Bridge Properties: Exposes .d_model, .n_layers, .n_heads, .n_kv_heads, .max_seq_len and accepts legacy keyword arguments (d_model, n_layers, n_heads, ff_multiplier, tt_rank) in __init__.

2.2 modeling_qtensorformer.QTensorFormerForCausalLM

• Inherits from: transformers.PreTrainedModel
• Submodules:
  • model.embed_tokens (nn.Embedding)
  • model.layers (nn.ModuleList of QTensorFormerDecoderLayer, each containing QTensorFormerAttention with TensorTrainLinear projections, QTensorFormerMLP with TensorTrainLinear gate_proj/up_proj/down_proj, QTensorFormerRMSNorm, and PIDResourceController)
  • model.norm (QTensorFormerRMSNorm)
  • lm_head (nn.Linear)
• Execution Path (forward & generate):
  • Fully compatible with Hugging Face CausalLMOutputWithPast and model.generate().
  • Uses AdaptiveKVCache(Cache) when use_cache=True.