Upload 10 files

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()])