# Phase Zero — Complete Repository Inventory

## 1. Root-Level Source, Configuration, and Export Files

| Path | Type | Size (Bytes) | Role & Status |
| :--- | :--- | :--- | :--- |
| `README.md` | Documentation | ~56 KB | Primary repository documentation & Hugging Face Hub landing page |
| `MODEL_CARD.md` | Documentation | ~18 KB | Standalone model card with architecture, evidence, and limitations |
| `config.json` | Configuration | 834 B | Hugging Face `QTensorFormerConfig` JSON descriptor |
| `configuration_qtensorformer.py` | Source (Family 4) | 11,708 B | Hugging Face `PretrainedConfig` (`QTensorFormerConfig`) |
| `modeling_qtensorformer.py` | Source (Family 4) | 36,326 B | Hugging Face `PreTrainedModel` (`QTensorFormerForCausalLM`) |
| `qtensorformer_vision.py` | Source | 10,842 B | Experimental multimodal vision-language extension (`QTensorFormerForConditionalGeneration`) |
| `qtensorformer_to_gguf.py` | Deployment Tool | 12,150 B | Pure-Python GGUF v3 binary serializer & Ollama `Modelfile` generator (`strict=True` enforced) |
| `export_onnx.py` | Deployment Tool | 4,120 B | ONNX graph exporter and structural checker for `TTLinear` |
| `q_tensor_former.py` | Legacy Prototype (Family 1) | 26,462 B | Historical single-file v1 prototype (`CFG`, `QTensorFormer`) |
| `q_tensor_former_v2.py` | Legacy Prototype (Family 2) | 43,441 B | Historical single-file v2 prototype (`Config`, `QTensorFormer`) |
| `qtensorformer_small.pt` | Legacy Checkpoint | 5,432,305 B | Historical external TensorLy container checkpoint (incompatible under `strict=True`) |
| `demo.py` | Script | ~12 KB | Interactive demonstration script |
| `app.py` | UI Script | ~14 KB | Gradio telemetry & interactive dashboard |
| `requirements.txt` | Packaging | 145 B | Core Python dependencies |
| `pyproject.toml` / `setup.py` | Packaging | ~2 KB | Package build metadata |

---

## 2. Core Research Package (`src/` — Family 3)

| Path | Classes / Functions | Status |
| :--- | :--- | :--- |
| `src/__init__.py` | Package exports | Active |
| `src/config.py` | `ModelConfig`, `TrainingConfig`, `BudgetConfig`, `ExperimentConfig`, `validate_model_config` | Active, Canonical Research Config |
| `src/models.py` | `QTensorFormer`, `DenseBaseline`, `PositionalEncoding`, `create_model` | Active, Canonical Research Model |
| `src/blocks.py` | `HybridBlock` | Active |
| `src/attention.py` | `MultiHeadAttention` (SDPA, GQA/MQA, RoPE, optional QKSAM fidelity kernel) | Active |
| `src/tensor_layers.py` | `TTLinear`, `TTFeedForward`, `factorize_dim` | Active |
| `src/information_state.py` | `TokenInformationState` (8D normalized information vector $z_t$ + LOFO ablation) | Active |
| `src/resource_allocator.py` | `MarginalValueModel`, `InformationValueAllocator`, `PIDDualSubgradientController`, `ConstrainedDecisionEngine`, `AllocationBudget` | Active |
| `src/kv_cache.py` | `AdaptiveKVCache`, `HierarchicalAdaptiveKVCache`, `QuantizedKVTensor`, `KVPrecision` | Active |
| `src/quantum_backend.py` | `QuantumBackend`, `ClassicalSurrogateUnitary`, `BackendType`, `compute_meyer_wallach_entanglement`, `compute_quantum_expressibility` | Active |
| `src/quantum_layers.py` | `QuantumAngleEmbedding`, `EntanglementMonitor`, `ClassicalQuantumFallback` | Active |
| `src/router.py` | `QuantumRouter` | Active (fixed deterministic `__init__` layer registration) |
| `src/scheduler.py` | `RankScheduler`, `BudgetAwareScheduler` | Active |
| `src/hardware_cost_model.py` | `HardwareCostModel`, `HardwareRooflineAnalyzer`, `KernelBreakdownProfiler` | Active |
| `src/phase_aware_profiler.py` | `PhaseAwareProfiler`, `PhaseProfileResult` | Active |
| `src/counterfactual_learning.py` | `CounterfactualDatasetGenerator`, `PolicyBenchmarkEvaluator` | Active |
| `src/baseline_comparator.py` | `BaselineComparator` | Active |
| `src/baselines.py` | `StandardTransformer`, `DistilledTransformer`, `PrunedTransformer` | Active |
| `src/hf_model.py` | Re-exports `QTensorFormerConfig` and `QTensorFormerForCausalLM` | Active |
| `src/validator.py` | `ScientificClaimValidator` | Active |

---

## 3. Custom Kernel & Acceleration Modules (`kernels/`)

| Path | Classes / Functions | Status |
| :--- | :--- | :--- |
| `kernels/tt_kernels.py` | `FusedTTContraction`, `DynamicINT4Quantizer`, `HAS_TRITON` | Active (PyTorch fallback on CPU; Triton JIT when CUDA + Triton available) |

---

## 4. Verification & Test Suite (`tests/`)

| Test File | Scope | Status |
| :--- | :--- | :--- |
| `tests/test_advanced_features.py` | GQA, Early Exit, Roofline, Kernel Breakdown, Marginal Value | Passing |
| `tests/test_baseline_comparator.py` | Multi-baseline evaluation & Pareto domination | Passing |
| `tests/test_frontier_v10.py` | GGUF v3 binary spec, Vision-Language forward, Triton/PyTorch fallback, ONNX export | Passing |
| `tests/test_hf_integration.py` | `AutoConfig`, `AutoModelForCausalLM`, `.generate()`, `save_pretrained`/`from_pretrained` | Passing |
| `tests/test_information_state.py` | 8D `TokenInformationState` bounds, normalization, ablation | Passing |
| `tests/test_kv_cache.py` | `AdaptiveKVCache` FP16/INT8/INT4 quantization, sink retention, eviction | Passing |
| `tests/test_model.py` | Model forward/backward shapes and presets | Passing |
| `tests/test_nested_tt.py` | Nested TT core slicing and rank consistency | Passing |
| `tests/test_quantum_backend.py` | `QuantumBackend`, `ClassicalSurrogateUnitary`, Meyer-Wallach, Expressibility | Passing |
| `tests/test_quantum_layers.py` | Quantum embeddings & classical fallback (3 PennyLane-specific tests skipped when `pennylane` absent) | Passing / Skipped |
| `tests/test_research_hardening.py` | Counterfactual learning, hierarchical KV, phase-aware profiler | Passing |
| `tests/test_resource_allocator.py` | `InformationValueAllocator`, hysteresis, PID dual controller | Passing |
| `tests/test_scientific_guardrails.py` | `strict=True` checkpoint enforcement, GGUF strict check, config validation, router init | Passing |
| `tests/test_tensor_layers.py` | `TTLinear` & `TTFeedForward` shapes, reconstruction, compression | Passing |
| `tests/test_v4.py` | End-to-end integration tests | Passing |

---

## 5. Benchmark Scripts, Raw Results, and Forensic Reports

- **Scripts (`scripts/`):**
  - `scripts/run_scientific_benchmark.py` — End-to-end reproducible benchmark suite (`RUN-20261013-QTF-HARDENING`)
  - `scripts/scientific_integrity_checker.py` — Automated scientific integrity & evidence-label auditor
  - `scripts/smoke_test.py` — Fast deterministic one-command smoke test
  - `scripts/generate_figures.py` & `scripts/run_experiments.py` — Historical figure and experiment generators
- **Empirical Results (`results/`):**
  - `results/metadata/run_metadata.json`
  - `results/raw/checkpoint_integrity.json`
  - `results/raw/cold_start_and_edge.json`
  - `results/raw/tt_compression_audit.json`
  - `results/raw/controller_audit.json`
  - `results/raw/kv_cache_audit.json`
  - `results/raw/quantum_pathway_audit.json`
  - `results/processed/benchmark_summary.json`
  - `results/processed/benchmark_summary.csv`
- **Reports (`reports/`):**
  - Full 22-document forensic, architectural, checkpoint, benchmark, edge/cold-start, energy, novelty, and release-readiness report suite.