Initial SCI framework upload (v1)

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vishal Joshua Meesala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,3 +1,133 @@
----
-license: mit
----
+SCI: Surgical Cognitive Interpreter
+A Metacognitive Control Layer for Signal Dynamics
+
+This repository contains the reference implementation of the Surgical Cognitive Interpreter (SCI), a closed-loop metacognitive controller that wraps existing models and turns prediction into a regulated process rather than a one-shot function evaluation.
+
+SCI is introduced in:
+
+Vishal Joshua Meesala
+SCI: A Metacognitive Control for Signal Dynamics.
+arXiv:2511.12240, 2025
+https://arxiv.org/abs/2511.12240
+
+The paper formalizes interpretability as a feedback-regulated state: SCI monitors a scalar interpretive signal SP(t), defined over reliability-weighted, multi-scale features, and adaptively adjusts an interpreter’s parameters to reduce interpretive error
+
+ΔSP(t) = SP*(t) − SP(t)
+
+under Lyapunov-style stability constraints.
+
+1. Motivation
+Most neural networks are deployed as open-loop function approximators: they map inputs to outputs in a single forward pass, with no explicit mechanism to regulate how much computation, explanation quality, or clarification is applied to a given case. In safety–critical domains (medicine, industrial monitoring, environmental sensing), this is brittle:
+
+Easy and ambiguous inputs receive the same computational budget.
+Explanations are static, post hoc, and do not adapt under drift.
+There is no explicit notion of “interpretive error” that can be monitored and controlled.
+SCI addresses this by introducing a closed-loop metacognitive layer that:
+
+Monitors a scalar interpretive state SP(t) ∈ [0, 1] over time.
+Computes interpretive error ΔSP = SP* − SP relative to a target clarity level SP*.
+Updates interpreter parameters Θ according to a Lyapunov-inspired rule with safeguards.
+Allocates more inference steps and adaptation to ambiguous or unstable inputs.
+Exposes ΔSP as a safety signal for abstention, escalation, or human-in-the-loop review.
+Empirically, SCI:
+
+Allocates roughly 3.6–3.8× more computation to misclassified inputs than to correct ones.
+Produces a scalar safety signal ΔSP with AUROC ≈ 0.70–0.86 for detecting errors across vision, medical, and industrial benchmarks.
+2. Conceptual Overview
+SCI is a modular architecture with the following core components.
+
+2.1 Decomposition Π
+A multi-scale, multimodal feature bank P(t, s) that organizes raw signals X(t) into interpretable blocks:
+
+Rhythmic components (frequency bands, oscillatory structure)
+Trend components (low-frequency baselines, drifts)
+Spatial / structural components (sensor topology, modes)
+Cross-modal interactions (coherence, cross-correlation, causal couplings)
+Compact but auditable latent composites Π*
+Each feature is associated with a reliability weight w_f(t), derived from quantities such as:
+
+Signal-to-noise ratio (SNR)
+Temporal persistence
+Multi-sensor or cross-modal coherence
+These weights allow SCI to emphasize trustworthy features and down-weight degraded sensors or spurious patterns.
+
+2.2 Interpreter ψΘ
+A knowledge-guided interpreter that maps the reliability-weighted feature bank into:
+
+Markers m_k: human-meaningful states or concepts
+Confidences p_k(t): calibrated probabilities
+Rationales r_k(t): sparse feature-level attributions and/or templated text
+The interpreter can be instantiated as a modest neural head (e.g., linear layer or shallow MLP) on top of P(t, s), optionally constrained by ontologies or domain rules.
+
+2.3 Surgical Precision (SP)
+A scalar interpretive signal SP(t) ∈ [0, 1] that aggregates calibrated components such as:
+
+Clarity / selectivity
+Pattern strength
+Domain consistency
+Predictive alignment
+In the minimal implementation, SP is instantiated as normalized entropy of a marker distribution or predictive distribution: high SP corresponds to focused, confident internal usage of markers; low SP indicates diffuse or ambiguous internal state.
+
+2.4 Closed-Loop Controller
+A controller monitors ΔSP(t) and updates Θ accordingly. At a high level:
+
+Compute ΔSP(t) = SP*(t) − SP(t) relative to a target SP*(t).
+
+If |ΔSP(t)| exceeds a threshold, update parameters:
+
+Θ_{t+1} = Proj_C [ Θ_t + η_t ( ΔSP(t) · ∇_Θ SP(t) + λ_h · u_h(t) ) ]
+
+where:
+
+η_t is a step-size schedule,
+λ_h is a human-gain budget,
+u_h(t) is a bounded human feedback signal (optional),
+Proj_C enforces constraints (e.g., trust region, sparsity, or parameter bounds).
+Lyapunov-style analysis shows that, under suitable conditions on η_t and λ_h, the “interpretive energy”
+
+V(t) = ½ · (ΔSP(t))²
+
+decreases monotonically up to bounded noise, so explanations become more stable and consistent over time.
+
+This yields a reactive interpretability layer that not only explains but also stabilizes explanations under drift, feedback, and evolving conditions.
+
+3. Repository Structure
+The repository is organized as follows:
+
+sci/                  # Core library
+  __init__.py
+  controller.py       # SCIController: closed-loop update over Θ using ΔSP
+  interpreter.py      # Interpreter / marker head and SP computation
+  sp_evaluator.py     # SP and component metrics, calibration, logging
+  decomposition.py    # Decomposition Π and reliability-weighted feature bank
+  reliability.py      # Reliability scores (SNR, persistence, coherence)
+  utils.py            # Shared utilities and helper functions
+
+configs/              # Example configuration files
+  mnist.yaml
+  mitbih.yaml
+  bearings.yaml
+
+examples/             # Jupyter notebooks (to be populated)
+  mnist_sci_demo.ipynb
+  ecg_sci_demo.ipynb
+  bearings_sci_demo.ipynb
+
+experiments/          # Experiment scripts, logs, and analysis
+
+scripts/              # Training utilities, Hub utilities, etc.
+  push_to_hub.py
+
+run_sci_mitbih_fixed_k.py
+run_sci_bearings.py
+run_sci_signal_v2.py  # Signal-domain SCI experiments
+
+plot_metacognition_hero.py  # Plotting script for metacognitive behavior
+sc_arxiv.pdf          # Paper PDF (for convenience)
+sci_latex.tex         # LaTeX source of the paper
+
+pyproject.toml
+setup.cfg
+LICENSE
+README.md
+

configs/bearings.yaml

@@ -0,0 +1,4 @@
+dataset: bearings
+feature_dim: 128
+num_classes: 3
+num_markers: 8

configs/mitbih.yaml

@@ -0,0 +1,4 @@
+dataset: mitbih
+feature_dim: 128
+num_classes: 5
+num_markers: 8

configs/mnist.yaml

@@ -0,0 +1,4 @@
+dataset: mnist
+feature_dim: 128
+num_classes: 10
+num_markers: 8

examples/bearings_demo.ipynb

@@ -0,0 +1,10 @@
+{
+ "cells": [],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

examples/ecg_demo.ipynb

@@ -0,0 +1,10 @@
+{
+ "cells": [],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

examples/mnist_demo.ipynb

@@ -0,0 +1,10 @@
+{
+ "cells": [],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

experiments/mitbih_sci_v2/summary.json

@@ -0,0 +1,23 @@
+[
+    {
+        "acc_base": 0.8715,
+        "acc_sci": 0.879,
+        "mean_steps": 14.6775,
+        "err_reduction": 7.323214740265229,
+        "seed": 42
+    },
+    {
+        "acc_base": 0.8795,
+        "acc_sci": 0.885,
+        "mean_steps": 14.405,
+        "err_reduction": 6.982341868782045,
+        "seed": 100
+    },
+    {
+        "acc_base": 0.818,
+        "acc_sci": 0.8395,
+        "mean_steps": 15.8745,
+        "err_reduction": 3.616387450617109,
+        "seed": 2024
+    }
+]

plot_metacognition_hero.py

@@ -0,0 +1,38 @@
+import json
+import matplotlib.pyplot as plt
+import numpy as np
+import os
+
+DOMAINS = [
+    ("experiments/mnist_sci_v2", "MNIST (Vision)"),
+    ("experiments/mitbih_sci_v2", "MIT-BIH (Medical)")
+]
+
+def plot():
+    plt.figure(figsize=(10, 4))
+    
+    for i, (path, name) in enumerate(DOMAINS):
+        log = os.path.join(path, "per_example.jsonl")
+        if not os.path.exists(log): continue
+        
+        data = []
+        with open(log, 'r') as f:
+            for l in f: data.append(json.loads(l))
+            
+        corr = [d['steps'] for d in data if d['correct_sci']]
+        wrong = [d['steps'] for d in data if not d['correct_sci']]
+        
+        plt.subplot(1, 2, i+1)
+        plt.hist(corr, bins=np.arange(1, 26)-0.5, alpha=0.6, density=True, label='Correct', color='green')
+        plt.hist(wrong, bins=np.arange(1, 26)-0.5, alpha=0.6, density=True, label='Incorrect', color='red')
+        plt.title(f"{name}: Adaptive Compute")
+        plt.xlabel("Inference Steps")
+        plt.ylabel("Density")
+        plt.legend()
+        
+    plt.tight_layout()
+    plt.savefig("metacognition_hero.png")
+    print("Saved metacognition_hero.png")
+
+if __name__ == "__main__":
+    plot()

pyproject.toml

@@ -0,0 +1,10 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sci"
+version = "0.0.0"
+description = "Surgical Cognitive Interpreter (SCI) minimal prototype"
+authors = [ { name = "Vishal Joshua Meesala" } ]
+requires-python = ">=3.8"

run_sci_bearings.py

@@ -0,0 +1,168 @@
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+import torch.optim as optim
+from torch.utils.data import Dataset, DataLoader
+import numpy as np
+import pandas as pd
+import json
+import os
+import random
+from sklearn.metrics import roc_auc_score
+
+# --- CONFIGURATION ---
+SEEDS = [42, 100, 2024]
+BATCH_SIZE = 64
+EPOCHS = 10
+SP_TARGET = 0.85
+MAX_STEPS = 25
+PATIENCE = 3
+TEMPERATURE = 0.5
+DEVICE = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+# --- DATASET: PHYSICS-BASED BEARINGS ---
+class SyntheticBearings(Dataset):
+    """
+    Simulates rotating machinery.
+    Class 0: Healthy (Sine Wave + Noise)
+    Class 1: Inner Race Fault (Impulses at specific frequencies)
+    """
+    def __init__(self, n_samples):
+        self.data = []
+        self.targets = []
+        t = np.linspace(0, 1, 200) # 200 time steps (0.2s at 1kHz)
+        
+        for _ in range(n_samples):
+            # Base Carrier (Shaft Rotation 30Hz)
+            signal = 0.5 * np.sin(2 * np.pi * 30 * t) 
+            label = 0
+            
+            # Fault Injection (50% chance)
+            if np.random.rand() > 0.5:
+                label = 1
+                # Fault: High freq impulses (120Hz) decaying exponentially
+                fault_sig = 0.8 * np.sin(2 * np.pi * 120 * t) * np.exp(-5*t)
+                signal += fault_sig
+            
+            # Industrial Noise
+            signal += np.random.normal(0, 0.4, size=len(t))
+            
+            self.data.append(torch.tensor(signal, dtype=torch.float32).unsqueeze(0))
+            self.targets.append(label)
+
+    def __len__(self):
+        return len(self.data)
+
+    def __getitem__(self, idx):
+        return self.data[idx], self.targets[idx]
+
+# --- MODEL ---
+class BearingCNN(nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.conv1 = nn.Conv1d(1, 16, 5)
+        self.conv2 = nn.Conv1d(16, 32, 5)
+        self.dropout = nn.Dropout(0.3)
+        self.pool = nn.MaxPool1d(2)
+        self.fc = nn.Linear(32 * 47, 2) 
+
+    def forward(self, x):
+        x = self.pool(F.relu(self.conv1(x)))
+        x = self.pool(F.relu(self.conv2(x)))
+        x = self.dropout(x)
+        x = x.view(x.size(0), -1)
+        x = self.fc(x)
+        return x
+
+# --- UTILS ---
+def compute_sp(probs):
+    probs = torch.clamp(probs, min=1e-9)
+    entropy = -torch.sum(probs * torch.log(probs), dim=1)
+    sp = 1.0 - (entropy / np.log(2))
+    return sp
+
+# --- RUNNER ---
+def run_experiment(seed):
+    print(f"Running Bearings Seed {seed}...")
+    torch.manual_seed(seed)
+    np.random.seed(seed)
+    
+    train_ds = SyntheticBearings(2000)
+    test_ds = SyntheticBearings(500)
+    train_loader = DataLoader(train_ds, batch_size=64, shuffle=True)
+    test_loader = DataLoader(test_ds, batch_size=1, shuffle=False)
+    
+    model = BearingCNN().to(DEVICE)
+    opt = optim.Adam(model.parameters(), lr=0.001)
+    
+    model.train()
+    for _ in range(EPOCHS):
+        for x, y in train_loader:
+            x, y = x.to(DEVICE), y.to(DEVICE)
+            opt.zero_grad()
+            out = model(x)
+            loss = F.cross_entropy(out, y)
+            loss.backward()
+            opt.step()
+            
+    # Eval SCI
+    logs = []
+    with torch.no_grad():
+        for x, y in test_loader:
+            x = x.to(DEVICE)
+            accum = model(x)
+            steps = 1
+            sp_hist = []
+            
+            while steps < MAX_STEPS:
+                new_logits = model(x)
+                accum += new_logits
+                steps += 1
+                
+                curr_prob = F.softmax(accum/steps, dim=1)
+                curr_sp = compute_sp(curr_prob).item()
+                sp_hist.append(curr_sp)
+                
+                # Convergence Check
+                if len(sp_hist) >= PATIENCE:
+                    if abs(sp_hist[-1] - sp_hist[-PATIENCE]) < 0.005 and curr_sp > 0.8:
+                        break
+            
+            final_prob = F.softmax(accum/steps, dim=1)
+            pred = final_prob.argmax().item()
+            correct = (pred == y.item())
+            delta = abs(SP_TARGET - curr_sp)
+            
+            logs.append({
+                "correct": int(correct),
+                "delta": delta,
+                "steps": steps
+            })
+            
+    return logs
+
+def analyze(logs):
+    df = pd.DataFrame(logs)
+    errors = 1 - df['correct']
+    
+    # Safety Analysis
+    auc = roc_auc_score(errors, df['delta'])
+    steps_correct = df[df['correct']==1]['steps'].mean()
+    steps_wrong = df[df['correct']==0]['steps'].mean()
+    
+    print("\n" + "="*40)
+    print("BEARINGS (INDUSTRIAL) RESULTS")
+    print("="*40)
+    print(f"Error Rate:      {errors.mean()*100:.2f}%")
+    print(f"Safety AUROC:    {auc:.4f}")
+    print("-" * 40)
+    print("Metacognition (Avg Steps):")
+    print(f"Correct:         {steps_correct:.2f}")
+    print(f"Wrong:           {steps_wrong:.2f}")
+    print("="*40)
+
+if __name__ == "__main__":
+    all_logs = []
+    for s in SEEDS:
+        all_logs.extend(run_experiment(s))
+    analyze(all_logs)

run_sci_mitbih_fixed_k.py

@@ -0,0 +1,157 @@
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+import torch.optim as optim
+from torch.utils.data import Dataset, DataLoader
+import numpy as np
+import pandas as pd
+import json
+import os
+import random
+
+# --- CONFIGURATION (COMPUTE MATCHED BASELINE) ---
+# We match the ~15.6 steps from SCI v10
+FIXED_K = 16  
+SEEDS = [42, 100, 2024]
+BATCH_SIZE = 64
+EPOCHS = 10
+TEMPERATURE = 0.5
+DEVICE = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+OUT_DIR = "experiments/mitbih_fixed_k"
+
+# --- UTILS ---
+def set_seed(seed):
+    torch.manual_seed(seed)
+    np.random.seed(seed)
+    random.seed(seed)
+    if torch.cuda.is_available():
+        torch.cuda.manual_seed(seed)
+
+def compute_sp(probs):
+    probs = torch.clamp(probs, min=1e-9)
+    entropy = -torch.sum(probs * torch.log(probs), dim=1)
+    max_entropy = np.log(2)
+    sp = 1.0 - (entropy / max_entropy)
+    return sp
+
+# --- DATASET ---
+class RealMITBIH(Dataset):
+    def __init__(self, csv_file, limit=None):
+        df = pd.read_csv(csv_file, header=None)
+        df.iloc[:, 187] = df.iloc[:, 187].apply(lambda x: 0 if x == 0 else 1)
+        if limit:
+            df = df.sample(n=limit, random_state=42).reset_index(drop=True)
+        self.y = df.iloc[:, 187].values.astype(int)
+        self.X = df.iloc[:, :187].values.astype(np.float32)
+        self.X = np.expand_dims(self.X, axis=1)
+        num_neg = (self.y == 0).sum()
+        num_pos = (self.y == 1).sum()
+        self.pos_weight = num_neg / (num_pos + 1e-6)
+
+    def __len__(self):
+        return len(self.y)
+
+    def __getitem__(self, idx):
+        return torch.tensor(self.X[idx]), torch.tensor(self.y[idx])
+
+# --- MODEL ---
+class ECGCNN(nn.Module):
+    def __init__(self):
+        super(ECGCNN, self).__init__()
+        self.conv1 = nn.Conv1d(1, 32, 5)
+        self.conv2 = nn.Conv1d(32, 64, 5)
+        self.dropout1 = nn.Dropout(0.3)
+        self.dropout2 = nn.Dropout(0.5)
+        self.pool = nn.MaxPool1d(2)
+        self.global_pool = nn.AdaptiveAvgPool1d(1)
+        self.fc1 = nn.Linear(64, 64)
+        self.fc2 = nn.Linear(64, 2)
+
+    def forward(self, x):
+        x = self.pool(F.relu(self.conv1(x)))
+        x = self.pool(F.relu(self.conv2(x)))
+        x = self.dropout1(x)
+        x = self.global_pool(x)
+        x = x.view(x.size(0), -1)
+        x = F.relu(self.fc1(x))
+        x = self.dropout2(x)
+        x = self.fc2(x)
+        return x
+
+# --- RUNNER ---
+def run_experiment(seed):
+    print(f"\n>>> Running Fixed-K Baseline (K={FIXED_K}), Seed {seed}...")
+    set_seed(seed)
+    
+    train_ds = RealMITBIH("mitbih_train.csv", limit=12000)
+    test_ds = RealMITBIH("mitbih_test.csv", limit=2000)
+    train_loader = DataLoader(train_ds, batch_size=BATCH_SIZE, shuffle=True)
+    test_loader = DataLoader(test_ds, batch_size=1, shuffle=False)
+
+    model = ECGCNN().to(DEVICE)
+    optimizer = optim.Adam(model.parameters(), lr=0.001)
+    weight = torch.tensor([1.0, train_ds.pos_weight], dtype=torch.float32).to(DEVICE)
+    criterion = nn.CrossEntropyLoss(weight=weight)
+    
+    model.train()
+    for epoch in range(EPOCHS):
+        for data, target in train_loader:
+            data, target = data.to(DEVICE), target.to(DEVICE)
+            optimizer.zero_grad()
+            output = model(data)
+            loss = criterion(output, target)
+            loss.backward()
+            optimizer.step()
+
+    per_example = []
+    
+    with torch.no_grad():
+        for i, (data, target) in enumerate(test_loader):
+            data, target = data.to(DEVICE), target.to(DEVICE)
+            
+            # FIXED K ENSEMBLE
+            accum_logits = model(data)
+            
+            # Already did 1, do K-1 more
+            for _ in range(FIXED_K - 1):
+                accum_logits += model(data)
+                
+            final_mean_logits = accum_logits / FIXED_K
+            probs = F.softmax(final_mean_logits / TEMPERATURE, dim=1)
+            sp = compute_sp(probs).item()
+            pred = probs.argmax(dim=1).item()
+            correct = (pred == target.item())
+            
+            per_example.append({
+                "seed": seed,
+                "y_true": target.item(),
+                "correct": bool(correct),
+                "sp": sp,
+                "steps": FIXED_K
+            })
+
+    # Basic stats for print
+    acc = np.mean([1 if x['correct'] else 0 for x in per_example])
+    return {"acc": acc}, per_example
+
+def main():
+    if not os.path.exists(OUT_DIR):
+        os.makedirs(OUT_DIR)
+    
+    all_metrics = []
+    all_examples = []
+    
+    for seed in SEEDS:
+        m, ex = run_experiment(seed)
+        all_metrics.append(m)
+        all_examples.extend(ex)
+        print(f"Seed {seed} Fixed-K Accuracy: {m['acc']:.4f}")
+        
+    with open(f"{OUT_DIR}/per_example.jsonl", "w") as f:
+        for e in all_examples:
+            f.write(json.dumps(e) + "\n")
+            
+    print(f"\nDone. Logs saved to {OUT_DIR}")
+
+if __name__ == "__main__":
+    main()

run_sci_signal_v2.py

@@ -0,0 +1,157 @@
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+import torch.optim as optim
+from torchvision import datasets, transforms
+from torch.utils.data import DataLoader, Subset
+import numpy as np
+
+# --- CONFIGURATION v3 ---
+BATCH_SIZE = 64
+TRAIN_SIZE = 4000      # Increased for stability
+TEST_SIZE = 1000
+EPOCHS = 5             # Increased for better convergence
+SP_TARGET = 0.85       # Realistically calibrated target (was 0.95)
+MAX_STEPS = 15         # Give controller room to work
+TEMPERATURE = 0.5      # Temperature scaling (sharpening)
+DEVICE = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+# --- 1. MODEL DEFINITION ---
+class SimpleCNN(nn.Module):
+    def __init__(self):
+        super(SimpleCNN, self).__init__()
+        self.conv1 = nn.Conv2d(1, 32, 3, 1) # Larger filters
+        self.conv2 = nn.Conv2d(32, 64, 3, 1)
+        self.dropout1 = nn.Dropout(0.25)
+        self.dropout2 = nn.Dropout(0.5)
+        self.fc1 = nn.Linear(9216, 128)
+        self.fc2 = nn.Linear(128, 10)
+
+    def forward(self, x):
+        x = self.conv1(x)
+        x = F.relu(x)
+        x = self.conv2(x)
+        x = F.relu(x)
+        x = F.max_pool2d(x, 2)
+        x = self.dropout1(x)
+        x = torch.flatten(x, 1)
+        x = self.fc1(x)
+        x = F.relu(x)
+        x = self.dropout2(x)
+        x = self.fc2(x)
+        return x # Returns logits
+
+# --- 2. UTILS: SP CALCULATION ---
+def compute_sp(probs):
+    """SP = 1 - (Entropy / MaxEntropy)"""
+    probs = torch.clamp(probs, min=1e-9)
+    entropy = -torch.sum(probs * torch.log(probs), dim=1)
+    max_entropy = np.log(10)
+    sp = 1.0 - (entropy / max_entropy)
+    return sp
+
+# --- 3. TRAINING ---
+def train_model():
+    print(f"Loading MNIST (Train: {TRAIN_SIZE}, Test: {TEST_SIZE})...")
+    transform = transforms.Compose([transforms.ToTensor(), transforms.Normalize((0.1307,), (0.3081,))])
+    
+    full_train = datasets.MNIST('./data', train=True, download=True, transform=transform)
+    train_loader = DataLoader(Subset(full_train, range(TRAIN_SIZE)), batch_size=BATCH_SIZE, shuffle=True)
+    
+    model = SimpleCNN().to(DEVICE)
+    optimizer = optim.Adam(model.parameters(), lr=0.001)
+    
+    model.train()
+    print(f"Training for {EPOCHS} epochs...")
+    for epoch in range(EPOCHS):
+        for data, target in train_loader:
+            data, target = data.to(DEVICE), target.to(DEVICE)
+            optimizer.zero_grad()
+            output = model(data)
+            loss = F.cross_entropy(output, target)
+            loss.backward()
+            optimizer.step()
+    return model
+
+# --- 4. EVALUATION ---
+def evaluate(model):
+    transform = transforms.Compose([transforms.ToTensor(), transforms.Normalize((0.1307,), (0.3081,))])
+    test_loader = DataLoader(Subset(datasets.MNIST('./data', train=False, transform=transform), range(TEST_SIZE)), batch_size=1, shuffle=False)
+    
+    base_acc, sci_acc = 0, 0
+    base_sp_list, sci_sp_list = [], []
+    sci_steps_list = []
+    
+    model.train() # Stochastic mode ON
+    
+    print(f"Running Inference (Target SP={SP_TARGET}, Temp={TEMPERATURE})...")
+    
+    with torch.no_grad():
+        for i, (data, target) in enumerate(test_loader):
+            data, target = data.to(DEVICE), target.to(DEVICE)
+            
+            # --- BASELINE (1 Pass) ---
+            logits = model(data)
+            # Apply Temperature Scaling to Baseline too for fair comparison
+            probs = F.softmax(logits / TEMPERATURE, dim=1) 
+            sp = compute_sp(probs)
+            pred = probs.argmax(dim=1)
+            
+            base_acc += pred.eq(target).sum().item()
+            base_sp_list.append(sp.item())
+            
+            # --- SCI (Logit Averaging Controller) ---
+            accum_logits = logits.clone() # Start with first pass logits
+            steps = 1
+            current_sp = sp.item()
+            
+            # Loop: while quality is low, compute more
+            while current_sp < SP_TARGET and steps < MAX_STEPS:
+                new_logits = model(data)
+                accum_logits += new_logits
+                steps += 1
+                
+                # KEY CHANGE: Average Logits -> Softmax (Not Average Probs)
+                mean_logits = accum_logits / steps
+                current_probs = F.softmax(mean_logits / TEMPERATURE, dim=1)
+                current_sp = compute_sp(current_probs).item()
+            
+            # Final Decision
+            final_mean_logits = accum_logits / steps
+            sci_probs = F.softmax(final_mean_logits / TEMPERATURE, dim=1)
+            sci_pred = sci_probs.argmax(dim=1)
+            
+            sci_acc += sci_pred.eq(target).sum().item()
+            sci_sp_list.append(current_sp)
+            sci_steps_list.append(steps)
+
+    # --- 5. STATS ---
+    base_acc_pct = 100.0 * base_acc / TEST_SIZE
+    sci_acc_pct = 100.0 * sci_acc / TEST_SIZE
+    mean_base_sp = np.mean(base_sp_list)
+    mean_sci_sp = np.mean(sci_sp_list)
+    
+    base_errors = [abs(SP_TARGET - sp) for sp in base_sp_list]
+    sci_errors = [abs(SP_TARGET - sp) for sp in sci_sp_list]
+    
+    mean_base_error = np.mean(base_errors)
+    mean_sci_error = np.mean(sci_errors)
+    reduction = (mean_base_error - mean_sci_error) / mean_base_error * 100.0
+    avg_steps = np.mean(sci_steps_list)
+
+    print("\n" + "="*65)
+    print(f"RESULTS v3: SCI (Logit Avg + Temp Scaling) vs Baseline")
+    print("="*65)
+    print(f"{'Metric':<25} | {'Baseline':<10} | {'SCI (Adaptive)':<15}")
+    print("-" * 65)
+    print(f"{'Accuracy':<25} | {base_acc_pct:.2f}%     | {sci_acc_pct:.2f}%")
+    print(f"{'Mean Surgical Precision':<25} | {mean_base_sp:.4f}     | {mean_sci_sp:.4f}")
+    print(f"{'Mean Steps':<25} | {1.0:.2f}       | {avg_steps:.2f}")
+    print("-" * 65)
+    print(f"{'Interpretive Error (dSP)':<25} | {mean_base_error:.4f}     | {mean_sci_error:.4f}")
+    print(f"{'Error Reduction':<25} | -          | {reduction:.2f}%")
+    print("="*65)
+
+if __name__ == "__main__":
+    trained_model = train_model()
+    evaluate(trained_model)

sci/__init__.py

@@ -0,0 +1,45 @@
+"""
+SCI: Surgical Cognitive Interpreter
+Metacognitive control for signal dynamics.
+
+This package is structured to keep the top-level import lightweight:
+- `import sci` does NOT import torch or heavy submodules immediately.
+- Actual components are imported lazily when accessed.
+
+Author: Vishal Joshua Meesala
+"""
+
+from importlib import import_module
+from typing import Any
+
+__all__ = [
+    "SCIController",
+    "compute_sp",
+    "Interpreter",
+    "Decomposition",
+    "ReliabilityWeighting",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """
+    Lazy attribute access so that:
+
+        import sci
+        sci.SCIController
+
+    does not import torch until the attribute is actually used.
+    """
+    if name == "SCIController":
+        return import_module("sci.controller").SCIController
+    if name == "compute_sp":
+        return import_module("sci.sp").compute_sp
+    if name == "Interpreter":
+        return import_module("sci.interpreter").Interpreter
+    if name == "Decomposition":
+        return import_module("sci.decomposition").Decomposition
+    if name == "ReliabilityWeighting":
+        return import_module("sci.reliability").ReliabilityWeighting
+
+    raise AttributeError(f"module 'sci' has no attribute {name!r}")
+

sci/config.py

@@ -0,0 +1,22 @@
+"""Placeholder config module for SCI.
+
+This file can be extended to expose default configuration
+objects or helper loaders for YAML config files in `configs/`.
+"""
+
+from pathlib import Path
+
+DEFAULTS = {
+    "feature_dim": 128,
+    "num_markers": 8,
+    "num_classes": 10,
+}
+
+def load_yaml(path: str):
+    try:
+        import yaml
+    except Exception:
+        raise RuntimeError("PyYAML is required to load config files")
+    p = Path(path)
+    with p.open("r", encoding="utf-8") as f:
+        return yaml.safe_load(f)

sci/controller.py

@@ -0,0 +1,75 @@
+import torch
+from torch import nn
+
+
+class SCIController(nn.Module):
+    """
+    Minimal SCI closed-loop controller.
+
+    It monitors a scalar interpretive state SP, compares it
+    to a target SP*, and performs a projected gradient-style
+    update on the interpreter parameters Θ based on ΔSP.
+
+    This is a simplified, minimal prototype to show the core idea.
+    """
+
+    def __init__(
+        self,
+        interpreter: nn.Module,
+        sp_target: float = 0.90,
+        eta: float = 0.01,
+        gamma: float = 0.10,
+        trust_region: float = 0.1,
+    ):
+        super().__init__()
+        self.interpreter = interpreter
+        self.sp_target = sp_target
+        self.eta = eta
+        self.gamma = gamma
+        self.trust_region = trust_region
+
+    @torch.no_grad()
+    def _project(self, theta: torch.Tensor, theta_old: torch.Tensor) -> torch.Tensor:
+        """Simple trust-region projection on parameter vector."""
+        delta = theta - theta_old
+        norm = delta.norm()
+        if norm > self.trust_region:
+            return theta_old + self.trust_region * delta / (norm + 1e-9)
+        return theta
+
+    def forward(self, x: torch.Tensor):
+        """
+        Run a single SCI control step.
+
+        Args:
+            x: input features (batch_size, feature_dim)
+
+        Returns:
+            pred: raw predictions (logits)
+            sp: scalar SP estimate (float tensor)
+            d_sp: SP* - SP
+            interpreter: the (possibly) updated interpreter module
+        """
+        sp, pred = self.interpreter.compute(x)
+        d_sp = self.sp_target - sp
+
+        # No-op zone: if |ΔSP| is small, do not update
+        if torch.abs(d_sp) < self.gamma:
+            return pred, sp, d_sp, self.interpreter
+
+        # Collect old parameters as a flat vector
+        theta_old = self.interpreter.parameters_vector().detach()
+
+        # Compute gradient of SP wrt parameters
+        grad = self.interpreter.grad_sp(x)
+
+        # Basic controller update: Θ_new = Θ_old + η * ΔSP * ∇Θ SP
+        theta_new = theta_old + self.eta * d_sp * grad
+
+        # Trust-region projection
+        theta_new = self._project(theta_new, theta_old)
+
+        # Push updated parameters back into the interpreter
+        self.interpreter.update_parameters(theta_new)
+
+        return pred, sp, d_sp, self.interpreter

sci/decomposition.py

@@ -0,0 +1,20 @@
+import torch
+
+
+class Decomposition:
+    """
+    Placeholder semantic decomposition Π.
+
+    In the full SCI framework, this would include:
+    - Rhythmic features (FFT/STFT, wavelets, etc.)
+    - Trend features (detrending, SSA, etc.)
+    - Spatial / cross-modal features
+    Here we expose a simple identity mapping for now.
+    """
+
+    def __init__(self):
+        pass
+
+    def __call__(self, x: torch.Tensor) -> torch.Tensor:
+        # TODO: replace with real decomposition (e.g., STFT/wavelets)
+        return x

sci/interpreter.py

@@ -0,0 +1,73 @@
+import torch
+from torch import nn
+from .sp import compute_sp
+
+
+class Interpreter(nn.Module):
+    """
+    A lightweight SCI interpreter.
+
+    - Encodes input features into a hidden representation
+    - Emits marker logits (for SP)
+    - Emits task logits (for classification)
+
+    This is a minimal prototype; in practice you would replace
+    the feature encoder with a CNN/Transformer/etc.
+    """
+
+    def __init__(self, feature_dim: int = 128, num_markers: int = 8, num_classes: int = 10):
+        super().__init__()
+        self.encoder = nn.Linear(feature_dim, feature_dim)
+        self.marker_head = nn.Linear(feature_dim, num_markers)
+        self.classifier = nn.Linear(feature_dim, num_classes)
+
+    def encode(self, x: torch.Tensor) -> torch.Tensor:
+        h = torch.relu(self.encoder(x))
+        return h
+
+    def compute(self, x: torch.Tensor):
+        """
+        Compute SP and predictions for a batch of inputs.
+
+        Args:
+            x: tensor of shape (batch_size, feature_dim)
+
+        Returns:
+            sp_mean: scalar SP value (mean over batch)
+            logits: tensor of shape (batch_size, num_classes)
+        """
+        h = self.encode(x)
+        marker_logits = self.marker_head(h)
+        sp = compute_sp(marker_logits)  # (batch_size,)
+        logits = self.classifier(h)
+        return sp.mean(), logits
+
+    def grad_sp(self, x: torch.Tensor) -> torch.Tensor:
+        """
+        Compute gradient of SP wrt parameters as a flat vector.
+        NOTE: This assumes gradients have been zeroed before calling.
+        """
+        self.zero_grad()
+        sp, _ = self.compute(x)
+        sp.backward()
+        grads = []
+        for p in self.parameters():
+            if p.grad is not None:
+                grads.append(p.grad.view(-1))
+        if not grads:
+            return torch.zeros(0)
+        return torch.cat(grads).detach()
+
+    @torch.no_grad()
+    def parameters_vector(self) -> torch.Tensor:
+        """Flatten all parameters into a single vector."""
+        return torch.cat([p.data.view(-1) for p in self.parameters()])
+
+    @torch.no_grad()
+    def update_parameters(self, new_theta: torch.Tensor) -> None:
+        """Load a flat parameter vector back into the module parameters."""
+        offset = 0
+        for p in self.parameters():
+            n = p.numel()
+            p.data.copy_(new_theta[offset : offset + n].view_as(p))
+            offset += n

sci/reliability.py

@@ -0,0 +1,18 @@
+import torch
+
+
+class ReliabilityWeighting:
+    """
+    Placeholder reliability weighting.
+
+    In the full SCI framework this would:
+    - Estimate SNR, persistence, coherence for each feature
+    - Convert them to reliability scores z_f
+    - Normalize via a softmax to obtain weights w_f
+
+    For now, we return the input unchanged.
+    """
+
+    def __call__(self, features: torch.Tensor) -> torch.Tensor:
+        # TODO: implement reliability-based weighting
+        return features

sci/sp.py

@@ -0,0 +1,24 @@
+import torch
+import torch.nn.functional as F
+
+
+def compute_sp(marker_logits: torch.Tensor) -> torch.Tensor:
+    """
+    Compute an entropy-based Surgical Precision (SP) score.
+
+    SP = 1 - H(q) / log(K), where:
+    - q = softmax(marker_logits)
+    - H(q) is Shannon entropy over markers
+    - K is the number of markers
+
+    Args:
+        marker_logits: tensor of shape (..., K)
+
+    Returns:
+        SP: tensor of shape (...,) with values in [0, 1].
+    """
+    q = F.softmax(marker_logits, dim=-1)
+    k = q.shape[-1]
+    entropy = -torch.sum(q * torch.log(q + 1e-9), dim=-1)
+    sp = 1.0 - entropy / torch.log(torch.tensor(float(k), device=marker_logits.device))
+    return sp

sci/utils.py

@@ -0,0 +1,7 @@
+import torch
+from torch import nn
+
+
+def flatten_params(model: nn.Module) -> torch.Tensor:
+    """Flatten all parameters of a model into a single vector."""
+    return torch.cat([p.data.view(-1) for p in model.parameters()])

scripts/push_to_hub.py

@@ -0,0 +1,21 @@
+from huggingface_hub import HfApi, create_repo, upload_folder
+
+
+def main():
+    repo_id = "vishal-1344/sci"  # adjust if needed
+    api = HfApi()
+
+    # Create repo if it doesn't exist
+    create_repo(repo_id, exist_ok=True, repo_type="model")
+
+    # Upload entire project folder
+    upload_folder(
+        folder_path=".",
+        repo_id=repo_id,
+        repo_type="model",
+        commit_message="Initial SCI framework push",
+    )
+
+
+if __name__ == "__main__":
+    main()

setup.cfg

@@ -0,0 +1,10 @@
+[metadata]
+name = sci
+version = 0.0.0
+description = Surgical Cognitive Interpreter
+
+[options]
+packages = find:
+install_requires =
+    torch
+    pyyaml