Merge pull request #30 from t81dev/phase-20-learning-fabric-1960836874901330008

Implement Phase 20: Learning & Self-Tuning Fabric

Author: t81dev

README.md

@@ -173,12 +173,12 @@ Telemetry exposes sparsity, residency, economic cost, and semantic efficiency in
 
 ## 🏗️ Project State & Architecture
 
-The project is currently in **Phase 19**, representing a **Cost-Aware Economic Fabric**:
+The project is currently in **Phase 20**, representing a **Learning & Self-Tuning Fabric**:
 
-* **Economic Introspection:** Decisions are driven by projected cost and residency rebates.
-* **Hysteresis Scheduling:** Stabilized tile selection to prevent state thrashing.
-* **Sparse-Stress Hardening:** Verified performance at 99%+ sparsity.
-* **Temporal Pipelining:** Overlapping memory hydration with compute.
+* **Adaptive Cost Modeling:** Real-time tuning of scheduler coefficients based on measured costs.
+* **Dynamic Scheduler Weighting:** Tiles "learn" kernel preferences to maximize economic efficiency.
+* **Self-Tuning Eviction:** Feedback-driven scoring protects blocks that contribute most to efficiency.
+* **Temporal Auto-Tuning:** Dynamic batch sizing to optimize the meaning-to-cost ratio.
 
 ### Architecture Layers
 

USER_MANUAL.md

@@ -34,7 +34,9 @@ Welcome to the **Ternary Fabric** user manual. This documentation is designed to
     Optimizing llama.cpp and GGUF workflows.
 15. **[Data-Driven Adaptation](docs/19_DATA_DRIVEN_ADAPTATION.md)**
     Details on Phase 19 cost-aware scheduling and adaptive residency.
-16. **[Strategy Roadmap](docs/ROADMAP.md)**
+16. **[Learning & Self-Tuning](docs/20_LEARNING_AND_SELF_TUNING.md)**
+    Phase 20 documentation on adaptive cost modeling and scheduler weighting.
+17. **[Strategy Roadmap](docs/ROADMAP.md)**
     The project roadmap detailing completed and future phases.
 
 ---
@@ -73,9 +75,28 @@ When running with the interposer or Python API, the Fabric provides real-time te
 *   **Zero-Skips:** The number of operations eliminated because an operand was zero. Typically 50-75% for LLM workloads.
 *   **Semantic Efficiency:** The ratio of useful operations (`active_ops`) to total operations.
 *   **Economic Efficiency:** The ratio of useful operations to total `fabric_cost` (weighted sum of ops, memory, and residency misses).
+*   **Adaptive Coefficients:** (Phase 20) Real-time values for `weight_cost`, `mem_read_cost`, etc., reflecting the scheduler's learned cost model.
 *   **Pool Usage:** Current consumption of the 128MB emulation pool.
-*   **Eviction Events:** Increments when the policy (Recency + Frequency) frees space for new weight frames.
-*   **Async Queue:** Shows in-flight GEMVs being processed by the background worker thread.
+*   **Eviction Events:** Increments when the policy (Frequency + Age + Success) frees space for new weight frames.
+*   **Dynamic Batch Size:** (Phase 20) Shows the current auto-tuned batch size optimized for the current workload.
+
+---
+
+## 🤖 Adaptive Learning (Phase 20)
+
+Starting with Phase 20, the Ternary Fabric is a self-tuning co-processor. It automatically optimizes its own internal parameters based on measured performance:
+
+### Self-Tuning Cost Model
+The scheduler uses a **Hill-Climbing** algorithm to adjust its cost projection coefficients. If the actual `fabric_cost` differs from the `projected_cost`, the fabric updates its internal model to ensure more accurate tile selection in the future.
+
+### Dynamic Scheduler Weighting
+Tiles "learn" which kernels they are most efficient at executing. A tile that consistently delivers higher **Economic Efficiency** for a specific kernel (e.g., LSTM) will be favored for that kernel in future scheduling decisions.
+
+### Eviction Policy Optimization
+The eviction policy is no longer fixed LRU. It now dynamically weights **Frequency**, **Recency (Age)**, and **Residency Success Rate**. This ensures that weights critical to maintaining high efficiency are protected from eviction.
+
+### Temporal Auto-Tuning
+The asynchronous command queue automatically adjusts its **Batch Size** (between 1 and 32) to maximize a composite score of efficiency and throughput. It occasionally "explores" different batch sizes to find the optimal throughput for the current sparsity regime.
 
 ---
 

WHITE_PAPER.md

@@ -53,6 +53,7 @@ Ternary Fabric sits at the intersection of Ternary Neural Networks (TNNs) and do
 As of Phase 15, the Ternary Fabric has achieved deep integration with high-level frameworks like PyTorch and native hardware acceleration for complex structures.
 - **PyTorch Integration:** The `TFMBSLinear` module enables seamless acceleration of deep learning models with automatic quantization and residency management.
 - **Native RTL Kernels:** Recurrent and attention-based structures, including **T-LSTM**, **T-Attention**, and **T-CONV3D**, are now natively supported in hardware, providing extreme throughput for diverse AI workloads.
+- **Learning & Self-Tuning (Phase 20):** The fabric now includes a data-driven adaptation layer that autonomously optimizes cost coefficients, scheduling multipliers, and eviction priorities in real-time, maximizing economic efficiency for dynamic workloads.
 
 ## 6. Conclusion
 The Ternary Fabric provides a scalable, efficient, and high-throughput substrate for the next generation of ternary-quantized neural networks. The successful completion of Phase 15 demonstrates that ternary-native computing can scale to meet the demands of modern AI, from LLMs to computer vision, while maintaining a fraction of the power and area overhead of binary systems.

docs/20_LEARNING_AND_SELF_TUNING.md

@@ -0,0 +1,48 @@
+# Phase 20: Learning & Self-Tuning Fabric
+
+## Overview
+Phase 20 introduces the **Learning Layer** to the Ternary Fabric. It moves beyond fixed heuristics and implements a self-tuning feedback loop that optimizes the co-processor's behavior based on real-time execution metrics.
+
+## 1. Adaptive Cost Coefficients
+The scheduler's decision-making process relies on a set of projection coefficients (`weight_cost`, `mem_read_cost`, etc.). In Phase 20, these are no longer static.
+
+- **Mechanism:** Hill-climbing feedback loop.
+- **Feedback Signal:** Error delta between `projected_cost` and actual measured `fabric_cost`.
+- **Goal:** Minimize projection error to ensure the scheduler always selects the truly optimal tile.
+
+## 2. Dynamic Scheduler Weighting
+Each tile maintains a set of kernel-specific performance multipliers.
+
+- **Learning:** After each kernel execution, the tile's performance multiplier is adjusted based on its **Economic Efficiency** relative to the moving average.
+- **Decay:** Multipliers slowly decay back toward 1.0 to ensure the fabric remains responsive to changing workload patterns.
+- **Result:** The fabric "learns" tile preferences automatically, favoring tiles that have historically performed best for specific operations.
+
+## 3. Feedback-Driven Eviction
+The eviction policy uses a composite score to determine which memory blocks to keep resident.
+
+- **Scoring Formula:** `Score = W_freq * Frequency + W_age * Recency + W_success * Success_Rate`
+- **Tuning:** If the fabric experiences high residency misses, it automatically increases the weight of success and frequency to protect critical weights.
+- **Result:** Automatically protected hot weights that contribute most to system efficiency.
+
+## 4. Temporal Pipeline Optimization (Auto-Batching)
+The asynchronous execution engine dynamically tunes its batch size.
+
+- **Objective Function:** `0.7 * Economic Efficiency + 0.3 * Throughput`
+- **Exploration:** The engine occasionally (5% of the time) tries a slightly different batch size.
+- **Adaptation:** If the exploration yields a better composite score, the "base" batch size is updated in that direction.
+
+## 5. Economic Introspection
+The `economic_metrics.csv` log has been expanded to track the evolution of these learning parameters over time.
+
+| Field | Description |
+| :--- | :--- |
+| `projected_cost` | The cost predicted by the scheduler. |
+| `batch_size` | The auto-tuned batch size used for the operation. |
+| `weight_cost` | The current value of the learned weight cost coefficient. |
+| `eviction_scores` | The scores assigned to blocks during the last eviction event. |
+
+## 6. Interpreting the Learning Curve
+When analyzing logs, a healthy "learning" phase should show:
+1. `projected_cost` converging toward `fabric_cost`.
+2. `economic_efficiency` steadily increasing as the scheduler favors better tiles.
+3. `dynamic_batch_size` stabilizing at a value that balances latency and throughput.

docs/ROADMAP.md

@@ -148,6 +148,15 @@ Using Phase 18 metrics to drive autonomous fabric behavior and scheduling.
     *   **Sparse-Regime Hardening:** Verified efficiency in 95-99% sparse regimes with dedicated stress benchmarks.
     *   **KPI Maturation:** Introduction of `Economic Efficiency` (Meaning / Cost) vs `Semantic Efficiency` (Meaning / Ops).
 
+### Phase 20 — Learning & Self-Tuning Fabric ✅
+Turning heuristics into a self-tuning system that optimizes its own parameters.
+*   **Status:** Complete.
+*   **Deliverables:**
+    *   **Adaptive Cost Coefficients:** Scheduler now uses a hill-climbing feedback loop to minimize the delta between projected and actual costs.
+    *   **Dynamic Scheduler Weighting:** Per-tile/per-kernel multipliers that adapt based on historical economic efficiency.
+    *   **Eviction Policy Self-Tuning:** Scoring weights (frequency, recency, success) adjust automatically to maximize residency hit rates.
+    *   **Temporal Pipeline Optimization:** Auto-tuning of async batch sizes to maximize a composite efficiency/throughput score.
+
 ---
 
 # 🔑 What This Strategy Gives You