Update README.md

README.md

@@ -7,4 +7,125 @@ metrics:
 pipeline_tag: tabular-regression
 tags:
 - code
----
+---
+
+# RRF-Savant Meta-State Logistic Regression
+
+## Model Summary
+
+This repository contains a lightweight **logistic regression** classifier implemented with **scikit-learn**.  
+The model operates on **15-dimensional RRF-Savant meta-state features**, derived from the RRF / SavantEngine pipeline, and outputs a binary prediction with associated probabilities.
+
+It is designed as a fast, interpretable decision layer on top of the richer RRF-Savant embedding and resonance machinery.
+
+---
+
+## Model Details
+
+- **Model type:** Logistic Regression (binary classifier)  
+- **Framework:** scikit-learn  
+- **Input dimensionality:** 15  
+- **Source notebook:** `RRFSavant_AGI_Core_Colab.ipynb`  
+- **File format (recommended):** `joblib` (`.joblib`)
+
+### Input Features
+
+Each input is a 15-dimensional feature vector:
+
+- **RRF-Savant meta-state features**, including:
+  - φ / Φ phase indicators (RRF-Savant “phi” level)
+  - Ω / omega dynamics or cycle index
+  - Global coherence / resonance scores
+  - Spectral features:  
+    - `S_RRF`: spectral smoothness  
+    - `C_RRF`: spectral concentration  
+  - Energy-like measures (e.g. `E_H`)
+  - Dominant frequency or harmonic index
+  - One-hot encoded Φ nodes / states
+
+> Exact semantics and preprocessing are defined in the source notebook  
+> `RRFSavant_AGI_Core_Colab.ipynb`.
+
+### Outputs
+
+- `y_pred`: binary class label (e.g. `0` vs `1`)  
+- `proba`: probability estimates for each class via `predict_proba`
+
+The precise interpretation of class `0` and class `1` (e.g. baseline vs. “RRF-aligned” state, safe vs. risky, etc.) should be documented alongside your use-case.
+
+---
+
+## Intended Use
+
+- **Primary use:**  
+  - As a **meta-controller** for RRF-Savant systems, mapping high-level meta-state features to a simple decision (binary label).
+  - As a **fast screening / routing head** deciding whether to:
+    - escalate to a heavier RRF/Savant pipeline,
+    - trigger a specific operating mode,
+    - log / flag certain states.
+
+- **Not intended for:**  
+  - Standalone critical decision-making (medical, legal, safety-critical applications) without human oversight.
+  - Direct real-world risk scoring without proper calibration and validation.
+
+---
+
+## Training
+
+- **Training framework:** scikit-learn `LogisticRegression`
+- **Data source:**  
+  - Internal RRF-Savant meta-state dataset, generated and curated in  
+    `RRFSavant_AGI_Core_Colab.ipynb`.
+- **Preprocessing (typical):**
+  - Numeric features scaled (e.g. `StandardScaler`)  
+  - Categorical / discrete Φ nodes one-hot encoded  
+  - Train/validation split performed inside the notebook
+
+> For exact data splits, preprocessing, and hyperparameters, refer to the Colab notebook.
+
+---
+
+## Evaluation
+
+Typical metrics for this model family include:
+
+- Accuracy
+- ROC-AUC
+- Precision / Recall / F1
+- Calibration of probabilities
+
+You should log and report:
+
+- Metrics on a **held-out test set**
+- Any **class imbalance** handling performed (e.g. `class_weight="balanced"`)
+
+---
+
+## How to Use Assuming model is loaded 
+import joblib
+import numpy as np
+
+# Load model
+clf = joblib.load("rrf_savant_meta_logit.joblib")
+
+# Example: single feature vector (15 dims)
+x = np.array([
+    0.85087634, 0.67296168, 0.74652746,
+    0.03735409, 0.72399869, 0.66076596,
+    0.30312352, 0.69585885, 0.98531076,
+    0.28866375, 0.99602791, 0.69072907,
+    0.05884264, 0.74298728, 0.75928443
+]).reshape(1, -1)
+
+# Prediction
+y_pred = clf.predict(x)[0]
+proba = clf.predict_proba(x)[0]  # [P(class 0), P(class 1)]
+
+print("Predicted label:", y_pred)
+print("Probabilities:", proba)
+
+
+### Install Dependencies
+
+```bash
+pip install scikit-learn numpy joblib