Upload README.md with huggingface_hub

README.md

@@ -104,15 +104,75 @@ The Splice method works because:
 - The (26,34) config is the Pareto-optimal configuration validated by dnhkng's math+EQ probe sweep on the base model
 - 78% uncensored layer ratio preserves the fine-tuned personality while the central reasoning zone provides disciplined inference
 
-### Source Models
+### The Hybrid SSM Attention Constraint
 
-| Component | Source | Link |
-|-----------|--------|------|
-| Uncensored weights (layers 0–25, 42–71) | HauhauCS/Qwen3.5-27B-Uncensored-HauhauCS-Aggressive | [HuggingFace](https://huggingface.co/HauhauCS/Qwen3.5-27B-Uncensored-HauhauCS-Aggressive) |
-| RYS duplicate zone (layers 26–41) | dnhkng/RYS-Qwen3.5-27B-FP8-XL (F16 GGUF) | [HuggingFace](https://huggingface.co/dnhkng/RYS-Qwen3.5-27B-FP8-XL) |
-| Base architecture | Qwen/Qwen3.5-27B | [HuggingFace](https://huggingface.co/Qwen/Qwen3.5-27B) |
-| RYS method | dnhkng/RYS | [GitHub](https://github.com/dnhkng/RYS) |
-| RYS research | LLM Neuroanatomy II by dnhkng | [Blog Post](https://dnhkng.github.io/posts/rys-ii/) |
+Qwen3.5-27B is **not** a standard transformer — it uses a hybrid architecture where two types of layers alternate in a strict repeating pattern:
+
+```
+Layer Type Pattern (repeats every 4 layers):
+  [0] Linear Attention (Gated DeltaNet / SSM)
+  [1] Linear Attention (Gated DeltaNet / SSM)
+  [2] Linear Attention (Gated DeltaNet / SSM)
+  [3] Full Attention (GQA — 24 heads Q, 4 heads KV, 256 dim)
+  [4] Linear Attention ...
+  ...repeating...
+```
+
+This pattern is governed by `full_attention_interval=4` in the model config. **The total layer count must be divisible by 4** for this pattern to remain valid. If violated, llama.cpp and other GGUF runtimes cannot reconcile the layer types and will crash at load.
+
+This constraint eliminates many RYS configurations:
+
+| RYS Config | Total Layers | Divisible by 4 | Status |
+|------------|-------------|----------------|--------|
+| (24,35) | 75 | ❌ No | Crashes |
+| **(24,36)** | **76** | **✅ Yes** | **Works** |
+| **(26,34)** | **72** | **✅ Yes** | **Works (this model)** |
+| (33,34) | 65 | ❌ No | Crashes |
+
+The (26,34) config duplicates 8 layers (26–33), which contains exactly **2 Full Attention layers** (at positions 27 and 31) and **6 Gated DeltaNet layers**. This preserves the 4-layer repeating pattern perfectly:
+
+```
+Layers 24-27: [DeltaNet, DeltaNet, DeltaNet, FullAttn] ← original
+Layers 28-31: [DeltaNet, DeltaNet, DeltaNet, FullAttn] ← original
+Layers 32-35: [DeltaNet, DeltaNet, DeltaNet, FullAttn] ← DUPLICATED from 24-27
+Layers 36-39: [DeltaNet, DeltaNet, DeltaNet, FullAttn] ← DUPLICATED from 28-31
+```
+
+### F16 → BF16 Tensor Conversion
+
+The dnhkng RYS source GGUF uses F16 (IEEE 754 half-precision), while the uncensored model uses BF16 (Brain Float 16). These are different 16-bit formats:
+
+- **F16**: 1 sign + 5 exponent + 10 mantissa bits — higher precision, smaller range
+- **BF16**: 1 sign + 8 exponent + 7 mantissa bits — lower precision, same range as float32
+
+During the splice, F16 tensors are converted to BF16:
+```
+F16 → Float32 (lossless upcast) → BF16 (take upper 2 bytes of float32)
+```
+
+This conversion loses ~3 bits of mantissa precision but gains the dynamic range benefits of BF16, which is what the rest of the model uses. In practice, this has no measurable impact on output quality.
+
+### Source Models & Attribution
+
+This model would not exist without the work of these authors:
+
+**1. [Qwen Team](https://huggingface.co/Qwen) — Qwen3.5-27B (Base Architecture)**
+- [Qwen/Qwen3.5-27B](https://huggingface.co/Qwen/Qwen3.5-27B) — The foundation model. All 64 original layers, the tokenizer, the hybrid SSM architecture, and all training were done by the Qwen team. This model is a derivative work.
+- License: Apache 2.0
+
+**2. [HauhauCS](https://huggingface.co/HauhauCS) — Uncensored Fine-Tune**
+- [HauhauCS/Qwen3.5-27B-Uncensored-HauhauCS-Aggressive](https://huggingface.co/HauhauCS/Qwen3.5-27B-Uncensored-HauhauCS-Aggressive) — Provides the uncensored weights used in **56 of 72 layers** (layers 0–25 and 42–71). This fine-tune removes the safety guardrails that interfere with legitimate coding workflows. The "Aggressive" variant was chosen for maximum uncensoring.
+- Contribution: 78% of this model's total layer weights
+
+**3. [dnhkng](https://github.com/dnhkng) — RYS Method & Validated Layer Configuration**
+- [dnhkng/RYS-Qwen3.5-27B-FP8-XL](https://huggingface.co/dnhkng/RYS-Qwen3.5-27B-FP8-XL) — Provides the **duplicate zone layers** (layers 26–41). These are the base Qwen3.5-27B weights that went through FP8 quantization and were validated as the optimal duplication zone via systematic math+EQ probe sweeps.
+- [RYS GitHub Repository](https://github.com/dnhkng/RYS) — The RYS method implementation
+- [LLM Neuroanatomy: How I Topped the LLM Leaderboard Without Changing a Single Weight](https://dnhkng.github.io/posts/rys/) — Original RYS research
+- [LLM Neuroanatomy II: Modern LLM Hacking and hints of a Universal Language?](https://dnhkng.github.io/posts/rys-ii/) — Extended research with Qwen3.5-27B, including the (26,34) Pareto-optimal configuration used in this model
+- Contribution: 22% of this model's total layer weights (the critical reasoning duplication zone)
+
+**4. [ikawrakow](https://github.com/ikawrakow) — ik_llama.cpp**
+- Quantization tooling (llama-quantize) used to produce the Q8_0, Q6_K, and IQ4_NL variants
 
 ### Build Tools
 
@@ -189,9 +249,15 @@ We conducted head-to-head live coding tests against a HybridBase variant (same u
 - 0 looping responses (repetition ratio check)
 - 2 empty responses on very hard constraint prompts
 
-### Expected Performance (Extrapolated from Source Models)
+### Expected Performance (Extrapolated from Source Models & dnhkng's Research)
+
+Performance expectations are derived from two sources:
+1. The [official Qwen3.5-27B benchmark scores](https://huggingface.co/Qwen/Qwen3.5-27B)
+2. dnhkng's [LLM Neuroanatomy II](https://dnhkng.github.io/posts/rys-ii/) research, which systematically measured the impact of RYS layer duplication on Qwen3.5-27B using math and EQ (emotional quotient) probe sets
 
-Based on the official Qwen3.5-27B scores and the RYS method's documented impact:
+In dnhkng's research, the (26,34) XL configuration achieved a combined delta of **+0.1288** across math and EQ probes with only 12.5% parameter overhead — sitting on the validated Pareto frontier of performance vs. compute cost. The full probe sweep tested all possible (i,j) configurations and identified four optimal variants (S, M, L, XL), with XL (26,34) being the maximum-performance option.
+
+Based on these findings:
 
 | Benchmark | Qwen3.5-27B Official | Expected for this model |
 |-----------|---------------------|------------------------|
@@ -202,7 +268,7 @@ Based on the official Qwen3.5-27B scores and the RYS method's documented impact:
 | SWE-bench Verified | 72.4 | ~68-71 |
 | HLE w/ CoT | 24.3 | ~22-24 |
 
-*Note: These are estimates. The RYS method typically adds +1-3% on reasoning benchmarks (per dnhkng's research) but may lose some on instruction following due to architectural changes. The uncensored fine-tune may also shift scores. Full benchmark results were not completed due to infrastructure limitations (BF16 thinking mode inference is slow).*
+*Note: These are estimates based on dnhkng's published RYS research findings and the official Qwen3.5-27B scores. The RYS method was shown to improve reasoning capabilities (math +0.0755, EQ +0.0533 for the XL config in dnhkng's probe sweep) while potentially trading small amounts of instruction-following precision. The uncensored fine-tune may also shift absolute scores. Full standardized benchmark results were not completed due to infrastructure limitations (BF16 thinking mode inference at ~60-120s per request made large benchmark suites impractical). The live coding tests above provide the most reliable quality signal for this model's intended use case.*
 
 ## Usage with llama.cpp / ik_llama.cpp
 
@@ -266,6 +332,24 @@ Output Layer → Source
 42–71        → HauhauCS Uncensored layers 34–63
 ```
 
+## Research Foundation
+
+This project would not have been possible without [dnhkng's](https://github.com/dnhkng) groundbreaking RYS (Repeat Your Self) research. The key insights from their work that directly informed this model:
+
+1. **Layer duplication enhances reasoning without training** ([LLM Neuroanatomy](https://dnhkng.github.io/posts/rys/)): dnhkng discovered that duplicating specific middle layers of a transformer creates a "deeper reasoning circuit" that measurably improves performance on math and emotional intelligence benchmarks — with zero training, zero weight modification, and zero data.
+
+2. **Systematic configuration optimization** ([LLM Neuroanatomy II](https://dnhkng.github.io/posts/rys-ii/)): dnhkng conducted exhaustive sweeps of all possible (i,j) duplication configurations on Qwen3.5-27B, measuring each with dedicated math (Math120) and EQ (EQ140) probe sets. This identified four Pareto-optimal configurations:
+   - S (33,34): +1 layer, minimal overhead
+   - M (31,34): +3 layers, balanced
+   - L (30,35): +5 layers, strong
+   - **XL (26,34): +8 layers, maximum performance** ← used in this model
+
+3. **The hybrid SSM constraint**: dnhkng's work on Qwen3.5's hybrid Gated DeltaNet + Full Attention architecture revealed that the `full_attention_interval=4` pattern must be preserved post-duplication — a critical constraint for GGUF-based inference that is not documented elsewhere.
+
+4. **Pareto-optimal validation**: The (26,34) configuration was validated not just on the initial scan but on larger probe sets, confirming it as the best performance-per-compute option at +0.1288 combined delta with 12.5% overhead.
+
+The author's contribution was to combine these RYS findings with the HauhauCS uncensored fine-tune using the novel splice method — taking dnhkng's already-validated duplicate zone layers directly and embedding them within the uncensored model's layer stack, rather than re-duplicating from scratch.
+
 ## Limitations
 
 1. **Uncensored**: This model will follow most instructions without refusal. It is the user's responsibility to ensure ethical use.