Stephanie's Secret: The Dawn of Reflective AI

class MLP(nn.Module):
    def __init__(self, input_dim, output_dim):
        super().__init__()
        self.model = nn.Sequential(
            nn.Linear(input_dim, input_dim),
            nn.ReLU(),
            nn.Linear(input_dim, output_dim)
        )

    def forward(self, x):
        return self.model(x)

class ExpectileHead(nn.Module):
    def __init__(self, input_dim):
        super().__init__()
        self.net = nn.Sequential(
            nn.Linear(input_dim, input_dim),
            nn.ReLU(),
            nn.Linear(input_dim, 1)
        )

    def forward(self, x):
        return self.net(x)

class PolicyHead(nn.Module):
    def __init__(self, input_dim, action_dim=1):
        super().__init__()
        self.linear = nn.Linear(input_dim, action_dim)

    def forward(self, x):
        return self.linear(x)  # Optionally softmax if needed

class InContextQModel(nn.Module):
    def __init__(self, dim, hdim, action_dim=1, device="cpu"):
        supe Come on come onr().__init__()
        print(f"Initializing InContextQModel with dim={dim}, hdim={hdim}, action_dim={action_dim}, device={device}")
        self.device = device
        self.encoder = TextEncoder(dim, hdim).to(device)
        self.q_head = MLP(dim, 1).to(device)
        self.v_head = ExpectileHead(dim).to(device)
        self.pi_head = PolicyHead(dim, action_dim).to(device)

    def forward(self, prompt_emb, output_emb):
        prompt_emb = prompt_emb.to(self.device)
        output_emb = output_emb.to(self.device)

        zsa = self.encoder(prompt_emb, output_emb)  # shape: [batch, hdim]
        q_value = self.q_head(zsa)
        state_value = self.v_head(zsa)
        action_probabilities = self.pi_head(zsa)

        return {
            "q_value": q_value,
            "state_value": state_value,
            "action_probabilities": action_probabilities,
        }

class TextEncoder(nn.Module):
    def __init__(self, dim=4096, hdim=4096):
        super().__init__()
        self.encoder = nn.Sequential(
            nn.Linear(dim * 2, hdim),
            nn.ReLU(),
            nn.Linear(hdim, dim),
        )

zsa = self.encoder(prompt_emb, output_emb)

optimizer = Adam(model.q_head.parameters())
criterion = MSELoss()

for item in contrast_pairs:
    for side in ["a", "b"]:
        # Get prompt and document
        # Get LLM score
        # Embed both
        # Pass through model
        # Compute Q-value loss

(goal_emb, doc_emb) → Q-value ≈ LLM score

Q(goal, A) → 0.9
Q(goal, B) → 0.4

loss.backward()
optimizer.step()

class SICQLTrainer(BaseTrainer):

    def __init__(self, cfg, memory=None, logger=None):
        super().__init__(cfg, memory, logger)
        self.cfg = cfg
        self.memory = memory
        self.logger = logger
        self.embedding_type = self.memory.embedding.type
        self.dim = self.memory.embedding.dim
        self.hdim = self.memory.embedding.hdim
        self.root_dir = cfg.get("model_path", "models")
        self.dimension = cfg.get("dimension", "alignment")
        self.embedding_type = cfg.get("embedding_type", "hnet")
        self.model_type = "sicql"
        self.target_type = cfg.get("target_type", "document")
        self.version = cfg.get("model_version", "v1")

        # Device management
        self.device = torch.device(
            "cuda" if torch.cuda.is_available() else "cpu"
        )

        # Training configuration
        self._init_config(cfg)

        # Track training state
        self.best_loss = float("inf")
        self.early_stop_counter = 0
        self.models = {}
        self.tuners = {}
        self._load_tuners()

        # Log initialization
        self.logger.log(
            "SICQLTrainerInitialized",
            {
                "dimension": self.cfg.get("dimension", "alignment"),
                "embedding_type": self.cfg.get("embedding_type", "hnet"),
                "use_gild": self.use_gild,
                "use_qmax": self.use_qmax,
                "device": str(self.device),
            },
        )
 

    def _init_config(self, cfg):
        """Initialize training parameters from config"""
        self.use_tuner = cfg.get("use_tuner", True)
        self.use_early_stopping = cfg.get("early_stopping", True)
        self.early_stopping_patience = cfg.get("patience", 3)
        self.early_stopping_min_delta = cfg.get("min_delta", 1e-4)
        self.batch_size = cfg.get("batch_size", 32)
        self.epochs = cfg.get("epochs", 50)
        self.lr = cfg.get("lr", 1e-4)
        self.gamma = cfg.get("gamma", 0.95)  # Discount factor
        self.beta = cfg.get("beta", 1.0)  # Policy temperature
        self.entropy_weight = cfg.get("entropy_weight", 0.01)
        self.dimensions = cfg.get("dimensions", [])
        self.min_samples = cfg.get("min_samples", 10)
        self.expectile_tau = cfg.get("expectile_tau", 0.7)  # For V-head
        self.use_gild = cfg.get("use_gild", True)
        self.use_qmax = cfg.get("use_qmax", True)
        self.scorer_map = ["ebt", "svm", "mrq"]  # Policy head mapping

    def _load_tuners(self):
        """Load regression tuners for each dimension"""
        for dim in self.dimensions:
            tuner_path = super().get_locator(dim).tuner_file()
            if os.path.exists(tuner_path):
                self.tuners[dim] = RegressionTuner(dimension=dim)
                self.tuners[dim].load(tuner_path)
            else:
                self.tuners[dim] = None
                self.logger.log(
                    "TunerMissing", {"dimension": dim, "path": tuner_path}
                )

    def _build_model(self, dimension):
        """Build or load SICQL model"""
        locator = super().get_locator(dimension)
        if locator.model_exists():
            # Load existing model
            encoder = TextEncoder(dim=self.dim, hdim=self.hdim).to(self.device)
            q_head = QHead(zsa_dim=self.dim, hdim=self.hdim).to(self.device)
            v_head = VHead(zsa_dim=self.dim, hdim=self.hdim).to(self.device)
            pi_head = PolicyHead(
                zsa_dim=self.dim, hdim=self.hdim, num_actions=3
            ).to(self.device)

            # Load weights
            encoder.load_state_dict(
                torch.load(locator.encoder_file(), map_location=self.device)
            )
            q_head.load_state_dict(
                torch.load(locator.q_head_file(), map_location=self.device)
            )
            v_head.load_state_dict(
                torch.load(locator.v_head_file(), map_location=self.device)
            )
            pi_head.load_state_dict(
                torch.load(locator.pi_head_file(), map_location=self.device)
            )

            # Build model
            sicql_model = InContextQModel(
                encoder=encoder,
                q_head=q_head,
                v_head=v_head,
                pi_head=pi_head,
                embedding_store=self.memory.embedding,
                device=self.device,
            )
            return sicql_model

        # Build new model
        self.dim = self.memory.embedding.dim
        self.hdim = self.memory.embedding.hdim

        encoder = TextEncoder(dim=self.dim, hdim=self.hdim).to(self.device)
        q_head = QHead(zsa_dim=self.dim, hdim=self.hdim).to(self.device)
        v_head = VHead(zsa_dim=self.dim, hdim=self.hdim).to(self.device)
        pi_head = PolicyHead(
            zsa_dim=self.dim, hdim=self.hdim, num_actions=3
        ).to(self.device)

        return InContextQModel(
            encoder=encoder,
            q_head=q_head,
            v_head=v_head,
            pi_head=pi_head,
            embedding_store=self.memory.embedding,
            device=self.device,
        )

    def _train_epoch(self, model, dataloader):
        """Train for one epoch with all heads"""
        model.train()
        total_q_loss = 0.0
        total_v_loss = 0.0
        total_pi_loss = 0.0
        count = 0

        for ctx_emb, doc_emb, scores in tqdm(dataloader, desc="Training"):
            ctx_emb = ctx_emb.to(self.device)
            doc_emb = doc_emb.to(self.device)
            scores = scores.to(self.device)

            outputs = model(ctx_emb, doc_emb)

            q_loss = F.mse_loss(outputs["q_value"], scores)

            v_loss = (
                self._expectile_loss(
                    scores - outputs["state_value"], tau=self.expectile_tau
                )
                if self.use_qmax
                else torch.tensor(0.0, device=self.device)
            )

            pi_loss = torch.tensor(0.0, device=self.device)
            if self.use_gild and "action_logits" in outputs:
                advantage = (
                    outputs["q_value"] - outputs["state_value"]
                ).detach()
                weights = torch.exp(self.beta * advantage)
                weights = weights / weights.sum()

                # Corrected reshape
                weights = weights.unsqueeze(-1)  # Ensure (batch_size, 1)

                log_probs = F.log_softmax(outputs["action_logits"], dim=-1)
                pi_loss = -(log_probs * weights).mean()

                # Optional entropy regularization
                entropy = -(log_probs.exp() * log_probs).sum(dim=-1).mean()
                pi_loss += self.entropy_weight * entropy

            loss = (
                q_loss * self.cfg.get("q_weight", 1.0)
                + v_loss * self.cfg.get("v_weight", 0.5)
                + pi_loss * self.cfg.get("pi_weight", 0.3)
            )

            self.optimizer.zero_grad()
            loss.backward()
            torch.nn.utils.clip_grad_norm_(model.parameters(), 0.5)
            self.optimizer.step()

            total_q_loss += q_loss.item() * ctx_emb.size(0)
            total_v_loss += v_loss.item() * ctx_emb.size(0)
            total_pi_loss += pi_loss.item() * ctx_emb.size(0)
            count += ctx_emb.size(0)

        avg_q = total_q_loss / count
        avg_v = total_v_loss / count
        avg_pi = total_pi_loss / count

        if self.use_qmax:
            self.scheduler["q"].step(avg_q)
        if self.use_gild:
            self.scheduler["pi"].step(avg_pi)

        return {"q": avg_q, "v": avg_v, "pi": avg_pi, "total": loss.item()}

    def _expectile_loss(self, diff, tau=0.7):
        """Compute expectile loss for V-head"""
        return torch.where(
            diff > 0, tau * diff.pow(2), (1 - tau) * diff.pow(2)
        ).mean()

    def _should_stop_early(self, current_avg):
        """Check for early stopping"""
        if not self.use_early_stopping:
            return False

        if current_avg < self.best_loss - self.early_stopping_min_delta:
            self.best_loss = current_avg
            self.early_stop_counter = 0
        else:
            self.early_stop_counter += 1

        return self.early_stop_counter >= self.early_stopping_patience

    def _save_model(self, model, dimension, stats):
        locator = super().get_locator(dimension)
        """Save model components with metadata"""
        # Save each component
        torch.save(model.encoder.state_dict(), locator.encoder_file())
        torch.save(model.q_head.state_dict(), locator.q_head_file())
        torch.save(model.v_head.state_dict(), locator.v_head_file())
        torch.save(model.pi_head.state_dict(), locator.pi_head_file())

        # Calculate policy metrics
        policy_logits = model.pi_head.weight.data.mean(dim=0).tolist()
        policy_probs = F.softmax(torch.tensor(policy_logits), dim=-1).tolist()
        policy_entropy = -torch.sum(
            policy_probs * torch.log(torch.tensor(policy_probs) + 1e-8)
        ).item()

        # Build metadata
        meta = {
            "dim": self.dim,
            "hdim": self.hdim,
            "dimension": dimension,
            "version": self.cfg.get("model_version", "v1"),
            "avg_q_loss": stats.get("avg_q_loss", 0.0),
            "avg_v_loss": stats.get("avg_v_loss", 0.0),
            "avg_pi_loss": stats.get("avg_pi_loss", 0.0),
            "policy_logits": policy_logits,
            "policy_probs": policy_probs,
            "policy_entropy": policy_entropy,
            "policy_stability": max(policy_probs),
            "device": str(self.device),
            "embedding_type": self.cfg.get("embedding_type", "hnet"),
            "timestamp": datetime.utcnow().isoformat(),
        }

        # Save metadata
        with open(locator.meta_file(), "w") as f:
            json.dump(meta, f)

        # Save tuner if available
        if dimension in self.tuners and self.tuners[dimension]:
            self.tuners[dimension].save(locator.tuner_file())

        # Save model version
        model_version = ModelVersionORM(**meta)
        self.memory.session.add(model_version)
        self.memory.session.commit()

        return meta

    def _log_training_stats(self, dim, meta):
        """Log training stats to database"""
        training_stats = TrainingStatsORM(
            model_type="sicql",
            target_type=self.cfg.get("target_type", "document"),
            dimension=dim,
            version=meta["version"],
            avg_q_loss=meta["avg_q_loss"],
            avg_v_loss=meta["avg_v_loss"],
            avg_pi_loss=meta["avg_pi_loss"],
            policy_entropy=meta["policy_entropy"],
            policy_stability=meta["policy_stability"],
            performance=meta["avg_q_loss"],
        )
        self.memory.session.add(training_stats)
        self.memory.session.commit()

    def _validate_tensor(self, tensor, name):
        """Validate tensor before use"""
        if tensor is None:
            self.logger.log(
                "InvalidTensor",
                {"tensor_name": name, "reason": "tensor_is_none"},
            )
            return False

        if torch.isnan(tensor).any():
            self.logger.log(
                "NaNInTensor", {"tensor_name": name, "tensor": tensor.tolist()}
            )
            return False

        return True

    def _calculate_policy_logits(self, model):
        """Calculate policy logits from policy head weights"""
        with torch.no_grad():
            policy_weights = model.pi_head.get_policy_weights()
            policy_probs = F.softmax(policy_weights, dim=-1)
            return policy_probs.tolist()

    def _calculate_policy_stability(self, policy_logits):
        """Calculate policy stability from logits"""
        if not policy_logits:
            return 0.0
        policy_probs = F.softmax(torch.tensor(policy_logits), dim=-1)
        return policy_probs.max().item()

    def _calculate_policy_entropy(self, policy_logits):
        """Calculate policy entropy for versioning"""
        if not policy_logits:
            return 0.0
        policy_probs = F.softmax(torch.tensor(policy_logits), dim=-1)
        return (
            -torch.sum(policy_probs * torch.log(policy_probs + 1e-8), dim=-1)
            .mean()
            .item()
        )

    def train(self, samples, dim):
        """
        Train SICQL model for a dimension
        Args:
            samples: List of training samples
            dim: Dimension to train
        Returns:
            Training statistics and model
        """
        self.logger.log("DimensionTrainingStarted", {"dimension": dim})

        # Prepare data
        dataloader = super()._create_dataloader(samples)
        if not dataloader:
            return {"error": "insufficient_data", "dimension": dim}

        # Build model
        model = self._build_model(dim)
        model.train()

        # Optimizer for all heads
        self.optimizer = optim.Adam(model.parameters(), lr=self.lr)
        self.scheduler = {
            "q": ReduceLROnPlateau(
                self.optimizer, mode="min", factor=0.5, patience=2
            ),
            "v": ReduceLROnPlateau(
                self.optimizer, mode="min", factor=0.5, patience=2
            ),
            "pi": ReduceLROnPlateau(
                self.optimizer, mode="min", factor=0.5, patience=2
            ),
        }

        # Training stats
        stats = {
            "dimension": dim,
            "q_losses": [],
            "v_losses": [],
            "pi_losses": [],
            "policy_entropies": [],
            "avg_q_loss": 0.0,
            "avg_v_loss": 0.0,
            "avg_pi_loss": 0.0,
            "policy_entropy": 0.0,
            "policy_stability": 0.0,
        }

        # Training loop
        for epoch in range(self.epochs):
            epoch_stats = self._train_epoch(model, dataloader)
            stats["q_losses"].append(epoch_stats["q"])
            stats["v_losses"].append(epoch_stats["v"])
            stats["pi_losses"].append(epoch_stats["pi"])

            # Calculate policy entropy
            policy_logits = self._calculate_policy_logits(model)
            policy_entropy = self._calculate_policy_entropy(policy_logits)
            stats["policy_entropies"].append(policy_entropy)

            # Early stopping check
            if self._should_stop_early(stats["q_losses"][-1]):
                self.logger.log(
                    "EarlyStopping",
                    {
                        "dimension": dim,
                        "epoch": epoch + 1,
                        "best_loss": self.best_loss,
                    },
                )
                break

        # Final stats
        stats["avg_q_loss"] = np.mean(stats["q_losses"])
        stats["avg_v_loss"] = np.mean(stats["v_losses"])
        stats["avg_pi_loss"] = np.mean(stats["pi_losses"])
        stats["policy_entropy"] = np.mean(stats["policy_entropies"])
        stats["policy_stability"] = (
            max(stats["policy_entropies"])
            if stats["policy_entropies"]
            else 0.0
        )

        # Save model
        meta = self._save_model(model, dim, stats)
        stats.update(meta)

        # Log to database
        self._log_training_stats(dim, meta)

        self.logger.log(
            "DimensionTrainingComplete",
            {
                "dimension": dim,
                "final_q_loss": stats["avg_q_loss"],
                "final_v_loss": stats["avg_v_loss"],
                "final_pi_loss": stats["avg_pi_loss"],
            },
        )

        # Cache model
        self.models[dim] = model
        return stats

    def _log_training_stats(self, dim, meta):
        """Log training stats to database"""
        training_stats = TrainingStatsORM(
            model_type="sicql",
            target_type=self.cfg.get("target_type", "document"),
            dimension=dim,
            version=meta["version"],
            embedding_type=self.embedding_type,
            avg_q_loss=meta["avg_q_loss"],
            avg_v_loss=meta["avg_v_loss"],
            avg_pi_loss=meta["avg_pi_loss"],
            policy_entropy=meta.get("policy_entropy", 0.0),
            policy_stability=meta.get("policy_stability", 0.0),
        )
        self.memory.session.add(training_stats)
        self.memory.session.commit()

    def _train_sicql(self, model, dataloader, output_dir):
        """Train SICQL model with all heads"""
        model.train()
        best_loss = float("inf")
        patience_counter = 0

        # Build optimizers
        optimizers = {
            "encoder": optim.Adam(model.encoder.parameters(), lr=self.lr),
            "q_head": optim.Adam(model.q_head.parameters(), lr=self.lr),
            "v_head": optim.Adam(model.v_head.parameters(), lr=self.lr),
            "pi_head": optim.Adam(model.pi_head.parameters(), lr=self.lr),
        }

        # Build schedulers
        schedulers = {
            "encoder": ReduceLROnPlateau(
                optimizers["encoder"], mode="min", factor=0.5, patience=2
            ),
            "q_head": ReduceLROnPlateau(
                optimizers["q_head"], mode="min", factor=0.5, patience=2
            ),
            "v_head": ReduceLROnPlateau(
                optimizers["v_head"], mode="min", factor=0.5, patience=2
            ),
            "pi_head": ReduceLROnPlateau(
                optimizers["pi_head"], mode="min", factor=0.5, patience=2
            ),
        }

        # Training loop
        for epoch in range(self.epochs):
            total_q_loss = 0.0
            total_v_loss = 0.0
            total_pi_loss = 0.0
            count = 0

            for ctx_emb, doc_emb, scores in tqdm(
                dataloader, desc=f"Epoch {epoch + 1}"
            ):
                # Device management
                ctx_emb = ctx_emb.to(self.device)
                doc_emb = doc_emb.to(self.device)
                scores = scores.to(self.device)

                # Forward pass
                outputs = model(ctx_emb, doc_emb)

                # Q-head loss
                q_loss = F.mse_loss(outputs["q_value"], scores)

                # V-head loss
                v_loss = self._expectile_loss(
                    scores - outputs["state_value"],
                    tau=self.cfg.get("expectile", 0.7),
                )

                # Policy head loss
                pi_loss = torch.tensor(0.0, device=self.device)
                if self.use_gild:
                    advantage = (
                        outputs["q_value"] - outputs["state_value"]
                    ).detach()
                    weights = torch.exp(self.beta * advantage)
                    weights = weights / weights.sum()

                    policy_probs = F.softmax(outputs["action_logits"], dim=-1)
                    entropy = -torch.sum(
                        policy_probs * torch.log(policy_probs + 1e-8), dim=-1
                    ).mean()

                    pi_loss = -(
                        F.log_softmax(outputs["action_logits"], dim=-1)
                        * weights
                    ).mean()
                    pi_loss += self.entropy_weight * entropy

                # Backward pass
                optimizers["q_head"].zero_grad()
                q_loss.backward()
                optimizers["q_head"].step()

                optimizers["v_head"].zero_grad()
                v_loss.backward()
                optimizers["v_head"].step()

                if self.use_gild:
                    optimizers["pi_head"].zero_grad()
                    pi_loss.backward()
                    optimizers["pi_head"].step()

                # Track losses
                total_q_loss += q_loss.item() * ctx_emb.size(0)
                total_v_loss += v_loss.item() * ctx_emb.size(0)
                total_pi_loss += pi_loss.item() * ctx_emb.size(0)
                count += ctx_emb.size(0)

            # End of epoch
            avg_q = total_q_loss / count
            avg_v = total_v_loss / count
            avg_pi = total_pi_loss / count

            # Early stopping
            if avg_q < best_loss - self.early_stopping_min_delta:
                best_loss = avg_q
                patience_counter = 0
                # Save best model
                torch.save(
                    model.encoder.state_dict(), f"{output_dir}/encoder.pt"
                )
                torch.save(
                    model.q_head.state_dict(), f"{output_dir}/q_head.pt"
                )
                torch.save(
                    model.v_head.state_dict(), f"{output_dir}/v_head.pt"
                )
                torch.save(
                    model.pi_head.state_dict(), f"{output_dir}/pi_head.pt"
                )
            else:
                patience_counter += 1

            # Log epoch
            self.logger.log(
                "SICQLTrainingEpoch",
                {
                    "epoch": epoch + 1,
                    "q_loss": avg_q,
                    "v_loss": avg_v,
                    "pi_loss": avg_pi,
                    "lr": optimizers["q_head"].param_groups[0]["lr"],
                },
            )

            # Check for early stopping
            if patience_counter >= self.early_stopping_patience:
                self.logger.log(
                    "SICQLEarlyStopping",
                    {"epoch": epoch + 1, "best_loss": best_loss},
                )
                break

        self.logger.log("SICQLTrainingComplete", {"best_loss": best_loss})
        return model

    def _save_model(self, model, dimension, stats):
        """Save SICQL model components"""
        locator = super().get_locator(dimension)
        # Save components separately
        torch.save(model.encoder.state_dict(), locator.encoder_file())
        torch.save(model.q_head.state_dict(), locator.q_head_file())
        torch.save(model.v_head.state_dict(), locator.v_head_file())
        torch.save(model.pi_head.state_dict(), locator.pi_head_file())

        # Calculate policy metrics
        policy_logits = model.pi_head.get_policy_weights().tolist()
        policy_probs_tensor = F.softmax(torch.tensor(policy_logits), dim=-1)
        policy_probs = policy_probs_tensor.tolist()
        policy_entropy = -torch.sum(
            policy_probs_tensor * torch.log(policy_probs_tensor + 1e-8)
        ).item()
        policy_stability = max(policy_probs)


        # Build metadata
        meta = {
            "dim": self.dim,
            "hdim": self.hdim,
            "dimension": dimension,
            "version": self.cfg.get("model_version", "v1"),
            "avg_q_loss": float(stats["avg_q_loss"]),
            "avg_v_loss": float(stats["avg_v_loss"]),
            "avg_pi_loss": float(stats["avg_pi_loss"]),
            "policy_entropy": float(policy_entropy),
            "policy_stability": float(policy_stability),
            "policy_logits": policy_logits,
            "policy_probs": policy_probs,
            "embedding_type": self.embedding_type,
            "max_value": 100,
            "min_value": 0,
            "device": str(self.device), 
            "timestamp": datetime.utcnow().isoformat(),
        }

        super()._save_meta_file(meta, dimension)
        return meta

    def run(self, context: dict) -> dict:
        """Main entry point for training"""
        documents = context.get("documents", [])
        # Train each dimension
        results = {}
        for dim in self.dimensions:
            # Get training samples
            samples = self._get_samples(context, documents, dim)
            if not samples:
                continue

            # Train model
            stats = self.train(samples, dim)
            if "error" in stats:
                continue

            # Update belief cartridges
            self._update_belief_cartridge(context, dim, stats)
            results[dim] = stats

        # Update context with results
        context["training_stats"] = results
        return context

    def _get_samples(self, context, documents, dim):
        """Get training samples for dimension"""
        samples = []
        goal = context.get("goal", {})
        for doc in documents:
            scorable = ScorableFactory.from_dict(doc, TargetType.DOCUMENT)
            score = self.memory.scores.get_score(goal.id, scorable.id)
            if score:
                samples.append(
                    {
                        "title": goal.get("goal_text", ""),
                        "output": scorable.text,
                        "score": score.score,
                    }
                )
        return samples

    def _update_belief_cartridge(self, context, dim, stats):
        """Update belief cartridges with policy stats"""
        policy_logits = stats.get("policy_logits", [0.3, 0.7, 0.0])
        policy_probs = F.softmax(torch.tensor(policy_logits), dim=-1).tolist()

        # Build belief cartridge
        cartridge = BeliefCartridgeORM(
            title=f"{dim} policy",
            content=f"Policy head weights: {policy_probs}",
            goal_id=context.get("goal_id"),
            domain=dim,
            policy_logits=policy_probs,
            policy_entropy=stats.get("policy_entropy", 1.05),
            policy_stability=stats.get("policy_stability", 0.82),
        )
        self.memory.session.add(cartridge)
        self.memory.session.commit()

if self.use_gild and "action_logits" in outputs:
    advantage = (outputs["q_value"] - outputs["state_value"]).detach() # The 'aha!' moment: How much better was this than expected?
    weights = torch.exp(self.beta * advantage) # Prioritizing learning based on actual success
    weights = weights / weights.sum()

    weights = weights.unsqueeze(-1)  # Ensure shape (batch_size, 1)

    log_probs = F.log_softmax(outputs["action_logits"], dim=-1)
    pi_loss = -(log_probs * weights).mean()                   # Surgical policy adjustment

    entropy = -(log_probs.exp() * log_probs).sum(dim=-1).mean()
    pi_loss += self.entropy_weight * entropy

advantage = (outputs["q_value"] - outputs["state_value"]).detach()

weights = torch.exp(self.beta * advantage)
weights = weights / weights.sum()

log_probs = F.log_softmax(outputs["action_logits"], dim=-1)
pi_loss = -(log_probs * weights).mean()

entropy = -(log_probs.exp() * log_probs).sum(dim=-1).mean()
pi_loss += self.entropy_weight * entropy

locator = ModelLocator(
    root_dir="models",
    embedding_type="hnet",
    model_type="sicql",
    target_type="document",
    dimension="alignment",
    version="v1"
)

# List all available models in the system
ModelLocator.list_available_models()

# Find latest model per dimension
ModelLocator.find_best_model_per_dimension()

📦 models                                                                                                                   
└── 📦  hnet
    ├── 📁  ebt
    ├── 📁  mrq
    │   └── 📁  document
    │       ├── 📁  alignment
    │       │   └── 📁  v1
    │       │       ├── ⚙️  alignment.meta.json
    │       │       ├── 📦  alignment.pt
    │       │       ├── 🎚️  alignment.tuner.json
    │       │       └── 🧠  alignment_encoder.pt
    │       ├── 📁  clarity
    │       │   └── 📁  v1
    │       │       ├── ⚙️  clarity.meta.json
    │       │       ├── 📦  clarity.pt
    │       │       ├── 🎚️  clarity.tuner.json
    │       │       └── 🧠  clarity_encoder.pt
    │       ├── 📁  implementability
    │       │   └── 📁  v1
    │       │       ├── ⚙️  implementability.meta.json
    │       │       ├── 📦  implementability.pt
    │       │       ├── 🎚️  implementability.tuner.json
    │       │       └── 🧠  implementability_encoder.pt
    │       ├── 📁  novelty
    │       │   └── 📁  v1
    │       │       ├── ⚙️  novelty.meta.json
    │       │       ├── 📦  novelty.pt
    │       │       ├── 🎚️  novelty.tuner.json
    │       │       └── 🧠  novelty_encoder.pt
    │       └── 📁  relevance
    │           └── 📁  v1
    │               ├── ⚙️  relevance.meta.json
    │               ├── 📦  relevance.pt
    │               ├── 🎚️  relevance.tuner.json
    │               └── 🧠  relevance_encoder.pt
    ├── 📁  sicql
    │   └── 📁  document
    │       ├── 📁  alignment
    │       │   └── 📁  v1
    │       │       ├── ⚙️  alignment.meta.json
    │       │       ├── 📦  alignment.pt
    │       │       ├── 🎚️  alignment.tuner.json
    │       │       ├── 🧠  alignment_encoder.pt
    │       │       ├── 📦  alignment_pi.pt
    │       │       ├── 📦  alignment_q.pt
    │       │       └── 📦  alignment_v.pt
    │       ├── 📁  clarity
    │       │   └── 📁  v1
    │       │       ├── ⚙️  clarity.meta.json
    │       │       ├── 📦  clarity.pt
    │       │       ├── 🎚️  clarity.tuner.json
    │       │       ├── 🧠  clarity_encoder.pt
    │       │       ├── 📦  clarity_pi.pt
    │       │       ├── 📦  clarity_q.pt
    │       │       └── 📦  clarity_v.pt
    │       ├── 📁  implementability
    │       │   └── 📁  v1
    │       │       ├── ⚙️  implementability.meta.json
    │       │       ├── 📦  implementability.pt
    │       │       ├── 🎚️  implementability.tuner.json
    │       │       ├── 🧠  implementability_encoder.pt
    │       │       ├── 📦  implementability_pi.pt
    │       │       ├── 📦  implementability_q.pt
    │       │       └── 📦  implementability_v.pt
    │       ├── 📁  novelty
    │       │   └── 📁  v1
    │       │       ├── ⚙️  novelty.meta.json
    │       │       ├── 📦  novelty.pt
    │       │       ├── 🎚️  novelty.tuner.json
    │       │       ├── 🧠  novelty_encoder.pt
    │       │       ├── 📦  novelty_pi.pt
    │       │       ├── 📦  novelty_q.pt
    │       │       └── 📦  novelty_v.pt
    │       └── 📁  relevance
    │           └── 📁  v1
    │               ├── ⚙️  relevance.meta.json
    │               ├── 📦  relevance.pt
    │               ├── 🎚️  relevance.tuner.json
    │               ├── 🧠  relevance_encoder.pt
    │               ├── 📦  relevance_pi.pt
    │               ├── 📦  relevance_q.pt
    │               └── 📦  relevance_v.pt

class ModelLocatorMixin:
    class Locator:
        def __init__(
            self,
            root_dir: str,
            model_type: str,
            target_type: str,
            dimension: str,
            version: str,
            embedding_type: str,
        ):
            self.root_dir = root_dir
            self.model_type = model_type
            self.target_type = target_type
            self.dimension = dimension
            self.version = version
            self.embedding_type = embedding_type

        @property
        def base_path(self) -> str:
            path = os.path.join(
                self.root_dir,
                self.embedding_type,
                self.model_type,
                self.target_type,
                self.dimension,
                self.version,
            )
            os.makedirs(path, exist_ok=True)
            return path

        # Model-specific paths
        def model_file(self, suffix: str = ".pt") -> str:
            return os.path.join(self.base_path, f"{self.dimension}{suffix}")

        def encoder_file(self) -> str:
            return os.path.join(self.base_path, f"{self.dimension}_encoder.pt")

        def get_q_head_path(self) -> str:
            return os.path.join(self.base_path, f"{self.dimension}_q.pt")

        def get_v_head_path(self) -> str:
            return os.path.join(self.base_path, f"{self.dimension}_v.pt")

        def get_pi_head_path(self) -> str:
            return os.path.join(self.base_path, f"{self.dimension}_pi.pt")

        def meta_file(self) -> str:
            return os.path.join(self.base_path, f"{self.dimension}.meta.json")

        def tuner_file(self) -> str:
            return os.path.join(self.base_path, f"{self.dimension}.tuner.json")

        def scaler_file(self) -> str:
            return os.path.join(self.base_path, f"{self.dimension}_scaler.joblib")

    def get_model_name(self) -> str:
        return f"{self.target_type}_{self.model_type}_{self.model_version}"

    def get_locator(self, dimension: str):
        return self.Locator(
            root_dir=self.model_path,  # Path to the root directory for models
            model_type=self.model_type,
            target_type=self.target_type,
            dimension=dimension,
            version=self.version,
            embedding_type=self.embedding_type,
        )

models/{embedding_type}/{model_type}/{target_type}/{dimension}/{version}/

locator = self.get_locator("alignment")
model_path = locator.model_file()
encoder_path = locator.encoder_file()
meta_path = locator.meta_file()

models/sicql/document/{dimension}/v1/
├── {dimension}_encoder.pt   ← Shared encoder
├── {dimension}_q.pt         ← Q-value head
├── {dimension}_v.pt         ← V-value head (state value)
├── {dimension}_pi.pt        ← Policy head (action logits)
├── {dimension}.meta.json    ← Scoring range metadata
├── {dimension}.tuner.json   ← Regression tuner for score calibration

class SICQLScorer(BaseScorer):
    def __init__(self, cfg, memory, logger):
        super().__init__(cfg, memory, logger)
        self.model_type = "sicql"
        self.embedding_type = memory.embedding.type
        self.dim = memory.embedding.dim
        self.hdim = memory.embedding.hdim

        self.target_type = cfg.get("target_type", "document")
        self.model_path = cfg.get("model_path", "models")
        self.version = cfg.get("model_version", "v1")

        self.models = {}
        self.model_meta = {}
        self.tuners = {}

        self.dimensions = cfg.get("dimensions", [])
        self._load_models(self.dimensions)

    def _load_models(self, dimensions):
        for dim in dimensions:
            locator = ModelLocator(
                root_dir=self.model_path,
                embedding_type=self.embedding_type,
                model_type=self.model_type,
                target_type=self.target_type,
                dimension=dim,
                version=self.version,
            )

            encoder = TextEncoder(dim=self.dim, hdim=self.hdim).to(self.device)
            q_head = QHead(zsa_dim=self.dim, hdim=self.hdim).to(self.device)
            v_head = VHead(zsa_dim=self.dim, hIt's time dim=self.hdim).to(self.device)
            pi_head = PolicyHead(zsa_dim=self.dim, hdim=self.hdim, num_actions=3).to(self.device)

            encoder.load_state_dict(torch.load(locator.encoder_file(), map_location=self.device))
            q_head.load_state_dict(torch.load(locator.q_head_file(), map_location=self.device))
            v_head.load_state_dict(torch.load(locator.v_head_file(), map_location=self.device))
            pi_head.load_state_dict(torch.load(locator.pi_head_file(), map_location=self.device))

            model = InContextQModel(
                encoder=encoder,
                q_head=q_head,
                v_head=v_head,
                pi_head=pi_head,
                embedding_store=self.memory.embedding,
                device=self.device,
            )
            self.models[dim] = model

            meta = load_json(locator.meta_file()) if os.path.exists(locator.meta_file()) else {"min_score": 0, "max_score": 100}
            self.model_meta[dim] = meta

            tuner_path = locator.tuner_file()
            if os.path.exists(tuner_path):
                tuner = RegressionTuner(dimension=dim)
                tuner.load(tuner_path)
                self.tuners[dim] = tuner


    def score(self, goal: dict, scorable: Scorable, dimensions: list[str]) -> ScoreBundle:
        goal_text = goal.get("goal_text")
        results = {}

        for dim in dimensions:
            model = self.models.get(dim)
            prompt_emb = torch.tensor(
                self.memory.embedding.get_or_create(goal_text), device=self.device
            ).unsqueeze(0)
            output_emb = torch.tensor(
                self.memory.embedding.get_or_create(scorable.text), device=self.device
            ).unsqueeze(0)
            result = model(prompt_emb, output_emb)


            q_value = result["q_value"].item()
            v_value = result["state_value"].item()
            policy_logits = result["action_logits"].cpu().detach().numpy().tolist()

            if isinstance(policy_logits, list) and len(policy_logits) == 1:
                if isinstance(policy_logits[0], list):
                    # [[0.1166]] → [0.1166]
                    policy_logits = policy_logits[0]

            self.logger.log("PolicyLogits", {"dimension": dim, "logits": policy_logits})

                # Calculate uncertainty (|Q - V|)
            uncertainty = abs(q_value - v_value)
            
            # Calculate entropy from policy logits
            policy_tensor = torch.tensor(policy_logits)
            action_probs = F.softmax(policy_tensor, dim=-1)
            entropy = -torch.sum(action_probs * torch.log(action_probs + 1e-8)).item()
            
            # Calculate advantage
            advantage = q_value - v_value
            meta = self.model_meta.get(dim, {"min": 0, "max": 100})
            if dim in self.tuners:
                scaled_score = self.tuners[dim].transform(q_value)
            else:
                normalized = torch.sigmoid(torch.tensor(q_value)).item()
                scaled_score = normalized * (meta["max_value"] - meta["min_value"]) + meta["min_value"]

            scaled_score = max(min(scaled_score, meta["max_value"]), meta["min_value"])


            final_score = round(scaled_score, 4)
            prompt_hash = ScoreORM.compute_prompt_hash(gLike this right oal_text, scorable)

            rationale = f"Q={q_value:.4f}, V={v_value:.4f}, Δ={uncertainty:.3f}, H={entropy:.3f}"

            results[dim] = ScoreResult(
                        dimension=dim,
                        score=final_score,
                        rationale=rationale,
                        weight=1.0,
                        q_value=q_value,
                        energy=q_value,
                        source=self.name,
                        target_type=scorable.target_type,
                        prompt_hash=prompt_hash,
                        state_value=v_value,
                        policy_logits=policy_logits,
                        uncertainty=uncertainty,
                        entropy=entropy,
                        advantage=advantage,
                    )
        return ScoreBundle(results=results)

self._load_models(self.dimensions)

score(goal: dict, scorable: Scorable, dimensions: list[str]) -> ScoreBundle

scorers = [sicql_scorer, svm_scorer, mrq_scorer, ebt_scorer]

for scorer in scorers:
    score_bundle = scorer.score(goal=goal, scorable=scorable, dimensions=self.dimensions)

    @staticmethod
    def save_score_to_memory(
        bundle: ScoreBundle,
        scorable: Scorable,
        context: dict,
        cfg: dict,
        memory,
        logger,
        source,
        model_name=None,
    ):
        goal = context.get("goal")
        pipeline_run_id = context.get("pipeline_run_id")
        weighted_score = bundle.calculator.calculate(bundle)

        scores_json = {
            "stage": cfg.get("stage", "review"),
            "dimensions": bundle.to_dict(),
            "final_score": round(weighted_score, 2),
        }

        if not model_name:
            model_name = cfg.get("model", {}).get("name", "UnknownModel")

        # evaluation table bucket for all related score data
        eval_orm = EvaluationORM(
            goal_id=goal.get("id"),
            pipeline_run_id=pipeline_run_id,
            target_type=scorable.target_type,
            target_id=scorable.id,
            source=source,
            agent_name=cfg.get("name"),
            model_name=model_name,
            embedding_type=memory.embedding.type,
            evaluator_name=cfg.get("evaluator", cfg.get("model_type", "ScoreEvaluator")),
            strategy=cfg.get("strategy"),
            reasoning_strategy=cfg.get("reasoning_strategy"),
            scores=scores_json,
            extra_data={"source": source},
        )
        memory.session.add(eval_orm)
        memory.session.flush()

        # score results the actual score with weights and a rational (reason) for the score
        for result in bundle.results:
            score_result = bundle.results[result]
            score = ScoreORM(
                evaluation_id=eval_orm.id,
                dimension=score_result.dimension,
                score=score_result.score,
                source=score_result.source,
                weight=score_result.weight,
                rationale=score_result.rationale,
                prompt_hash=score_result.prompt_hash
                or ScoreORM.compute_prompt_hash(goal.get("goal_text", ""), scorable),
            )
            memory.session.add(score)

            # After inserting ScoreORM we insert the related attributs ebt and sicql extra data live here
            attribute = EvaluationAttributeORM(
                evaluation_id=eval_orm.id,
                dimension=score_result.dimension,
                source=score_result.source,
                raw_score=score_result.score,
                energy=score_result.energy,
                uncertainty=score_result.uncertainty,
                pi_value=score_result.policy_logits[0] if score_result.policy_logits else None,
                entropy=score_result.entropy,
                advantage=score_result.advantage,
                q_value=score_result.q_value,
                v_value=score_result.state_value,
                policy_logits=json.dumps(score_result.policy_logits),
                extra=score_result.to_dict(),
            )
            memory.session.add(attribute)

        memory.session.commit()

        logger.log(
            "ScoreSavedToMemory",
            {
                "goal_id": goal.get("id"),
                "target_id": scorable.id,
                "target_type": scorable.target_type,
                "scores": scores_json,
            },
        )
        ScoreDeltaCalculator(cfg, memory, logger).log_score_delta(
            scorable, weighted_score, goal.get("id")
        )
        ScoreDisplay.show(scorable, bundle.to_dict(), weighted_score)

📊 llm Dimension Scores document:37 Summary
╒══════════════════╤═════════╤══════════╤══════════════════════════════════════════════════════════════╕
│ Dimension        │   Score │ Weight   │ Rationale (preview)                                          │
╞══════════════════╪═════════╪══════════╪══════════════════════════════════════════════════════════════╡
│ alignment        │   15    │ 1.2      │ rationale: The document discusses a multilingual translation │
├──────────────────┼─────────┼──────────┼──────────────────────────────────────────────────────────────┤
│ clarity          │   78    │ 1.1      │ rationale: The document communicates its core idea of improv │
├──────────────────┼─────────┼──────────┼──────────────────────────────────────────────────────────────┤
│ implementability │   75    │ 1.3      │ rationale: The document describes a complex multilingual tra │
├──────────────────┼─────────┼──────────┼──────────────────────────────────────────────────────────────┤
│ novelty          │   88    │ 1.0      │ rationale: The document introduces a novel reward modeling a │
├──────────────────┼─────────┼──────────┼──────────────────────────────────────────────────────────────┤
│ relevance        │   20    │ 0.8      │ rationale: The document discusses reinforcement learning for │
├──────────────────┼─────────┼──────────┼──────────────────────────────────────────────────────────────┤
│ FINAL            │   56.54 │ -        │ Weighted average                                             │
╘══════════════════╧═════════╧══════════╧══════════════════════════════════════════════════════════════╛

The database tables look like this.

```mermaid

erDiagram
    EVALUATIONORM ||--o{ SCOREORM : has
    EVALUATIONORM ||--o{ EVALUATIONATTRIBUTEORM : has

    EVALUATIONORM {
        int id PK
        int goal_id
        int pipeline_run_id
        string target_type
        int target_id
        string source
        string agent_name
        string model_name
        string embedding_type
        string evaluator_name
        string strategy
        string reasoning_strategy
        json scores
        json extra_data
    }

    SCOREORM {
        int id PK
        int evaluation_id FK
        string dimension
        float score
        string source
        float weight
        string rationale
        string prompt_hash
    }

    EVALUATIONATTRIBUTEORM {
        int id PK
        int evaluation_id FK
        string dimension
        string source
        float raw_score
        float energy
        float uncertainty
        float pi_value
        float entropy
        float advantage
        float q_value
        float v_value
        json policy_logits
        json extra
    }

        sicql_scorer = SICQLScorer(self.cfg, memory=self.memory, logger=self.logger)  
        svm_scorer = SVMScorer(self.cfg, memory=self.memory, logger=self.logger)
        mrq_scorer = MRQScorer(self.cfg, memory=self.memory, logger=self.logger)
        ebt_scorer = EBTScorer(self.cfg, memory=self.memory, logger=self.logger)

        scorers = [sicql_scorer, svm_scorer, mrq_scorer, ebt_scorer]

        for doc in documents:

            doc_id = doc["id"]
            goal = context.get("goal", "")
            scorable = ScorableFactory.from_dict(doc, TargetType.DOCUMENT)

            for scorer in scorers:
                score_bundle: ScoreBundle = scorer.score(
                    goal=goal,
                    scorable=scorable,No one's going to be
                    dimensions=self.dimensions,
                )

prompt_emb = embedding_store.get_or_create(goal_text)
doc_emb = embedding_store.get_or_create(document_text)

result = model(prompt_emb, doc_emb)
q_value = result["q_value"].item()
v_value = result["state_value"].item()
policy_logits = result["action_logits"]

uncertainty = abs(q_value - v_value)
entropy = -∑(softmax(policy_logits) * log(softmax(policy_logits)))
advantage = q_value - v_value

scaled_score = tuner.transform(q_value)

# The essence of GILD's surgical precision
advantage = (q_value - state_value).detach()  # "How much better was this than expected?"
weights = torch.exp(beta * advantage)         # "How much should we prioritize this learning?"
pi_loss = -(weights * log_probs).sum()        # "Adjust policy exactly in proportion to success"

class ScoreComparisonAgent(BaseAgent):
    def __init__(self, cfg, memory=None, logger=None):
        super().__init__(cfg, memory, logger)
        self.dimensions = cfg.get("dimensions", [])  # Default dimensions, can be overridden in config
        # Configuration for sources to compare
        # Default to common scorers. Can be overridden in config.
        self.sources_to_compare = cfg.get("sources_to_compare", ["sicql", "mrq", "svm", "ebt"])
        self.ground_truth_source = cfg.get("ground_truth_source", "llm") # Typically "llm"
        # Ensure ground truth is included if not already in the list
        if self.ground_truth_source not in self.sources_to_compare:
             self.sources_to_compare.append(self.ground_truth_source)

        # Output directory for reports (optional)
        self.output_dir = cfg.get("report_output_dir", "logs/comparison_reports")
        os.makedirs(self.output_dir, exist_ok=True)

        # Get session from memory
        if memory and hasattr(memory, 'session'):
            self.session = memory.session
        else:
            raise ValueError("ScoreComparisonAgent requires a memory object with a session attribute.")

        # Initialize ScoringStore if it's the preferred way to interact
        # self.scoring_store = ScoringStore(self.session, logger) # Optional, if methods are adapted

    async def run(self, context: dict) -> dict:
        """
        Main execution logic for the agent.
        """
        try:
            # --- 1. Get Input Parameters ---
            pipeline_run_ids = context.get("pipeline_run_ids", [4148])
            # Fallback to single ID if list isn't provided
            single_pipeline_run_id = context.get("pipeline_run_id")
            if single_pipeline_run_id and not pipeline_run_ids:
                 pipeline_run_ids = [single_pipeline_run_id]
            
            if not pipeline_run_ids:
                self.logger.log("ScoreComparisonWarning", {"message": "No pipeline_run_id(s) provided. Analysis might be limited or empty."})
                # Decide if we should proceed or raise an error
                # For now, let's proceed but log it.

            dimensions = context.get("dimensions", self.dimensions) # Get from context or config
            # If still empty, we might fetch all available dimensions or use a default set
            # Let's assume ScoringStore/load_gild_examples handles this by fetching all if none specified implicitly

            self.logger.log("ScoreComparisonStarted", {
                "pipeline_run_ids": pipeline_run_ids,
                "dimensions": self.dimensions,
                "sources": self.sources_to_compare,
                "ground_truth": self.ground_truth_source
            })

            # --- 2. Fetch Scores from Pipeline-Linked Sources ---
            # We need scores linked to specific pipeline runs for SICQL, MRQ, SVM, EBT
            # We'll adapt the logic from PolicyAnalyzer._get_sicql_data/_get_mrq_data etc.
            # Or, if we modify ScoringStore, we could use a new method like:
            # local_scores_data = self.scoring_store.get_scores_for_pipeline_runs(
            #     pipeline_run_ids=pipeline_run_ids, 
            #     sources=[s for s in self.sources_to_compare if s != self.ground_truth_source],
            #     dimensions=dimensions
            # )
            
            # For now, let's implement the fetching logic directly using session
            # similar to PolicyAnalyzer methods.
            local_scores_data = self._fetch_local_scores(pipeline_run_ids, self.dimensions)

            # --- 3. Identify Targets for Ground Truth Lookup ---
            # Extract unique (target_id, dimension) combinations from local scores
            # Assuming target_type is consistent or handled, or we fetch it too.
            target_info_set = set()
            for score_record in local_scores_data:
                 # Adjust key names based on actual data structure from _fetch_local_scores
                 target_info_set.add((score_record.get('target_id'), score_record.get('dimension')))

            target_info_list = [{"target_id": tid, "dimension": dim} for tid, dim in target_info_set if tid is not None and dim is not None]

            self.logger.log("ScoreComparisonTargetsIdentified", {
                "target_count": len(target_info_list),
                "sample_targets": list(target_info_list)[:5] # Log first 5 for sanity check
            })

            # --- 4. Fetch Ground Truth (LLM) Scores ---
            # Fetch latest LLM scores for the identified targets, regardless of pipeline run
            # Adapted from PolicyAnalyzer._get_llm_data logic
            llm_scores_data = self._fetch_latest_ground_truth_scores(target_info_list, self.dimensions)

            # --- 5. Merge and Calculate Deltas ---
            # Create a lookup for LLM scores: {(target_id, dimension): score}
            llm_score_lookup = {(item['target_id'], item['dimension']): item['score'] for item in llm_scores_data}

            # Augment local scores with LLM score and delta
            aggregated_results = []
            for local_score in local_scores_data:
                target_id = local_score.get('target_id')
                dimension = local_score.get('dimension')
                source = local_score.get('source')
                local_score_value = local_score.get('score')

                llm_score_for_target = llm_score_lookup.get((target_id, dimension))
                delta = None
                if local_score_value is not None and llm_score_for_target is not None:
                     delta = local_score_value - llm_score_for_target

                # Add LLM score and delta to the local score record
                augmented_record = local_score.copy()
                augmented_record['llm_score'] = llm_score_for_target
                augmented_record['delta'] = delta
                aggregated_results.append(augmented_record)

            # --- 6. Store Results in Context ---
            context['score_comparison_data'] = aggregated_results
            context['score_comparison_metadata'] = {
                "pipeline_run_ids": pipeline_run_ids,
                "sources_compared": self.sources_to_compare,
                "ground_truth_source": self.ground_truth_source,
                "dimensions": dimensions,
                "comparison_timestamp": datetime.now().isoformat()
            }

            # --- 7. (Optional) Basic Reporting ---
            # Generate a simple summary or export
            self._generate_basic_report(aggregated_results, context['score_comparison_metadata'])

            self.logger.log("ScoreComparisonCompleted", {
                "total_scores_processed": len(aggregated_results),
                # Add more summary stats if needed
            })


            # --- 7. (Optional) Basic Reporting ---
            # Generate a simple summary or export
            self._generate_basic_report(aggregated_results, context['score_comparison_metadata'])

            # --- 8. NEW: Save Raw CSV ---
            self._save_comparison_csv(aggregated_results, context['score_comparison_metadata'])

            # --- 9. Log completion and return ---
            self.logger.log("ScoreComparisonCompleted", {
                "total_scores_processed": len(aggregated_results),
                # Add more summary stats if needed
            })


            # --- 9. NEW: Perform Statistical Analysis ---
            analysis_results = self._perform_statistical_analysis(aggregated_results)
            context['score_analysis_results'] = analysis_results
            context['score_analysis_metadata'] = {
                "analysis_timestamp": datetime.now().isoformat(),
                "sources_analyzed": self.sources_to_compare,
                "ground_truth_source": self.ground_truth_source,
                # You could add more metadata here if needed
            }

            # --- 10. NEW: Generate Detailed Analysis Report ---
            self._generate_analysis_report(analysis_results, context['score_comparison_metadata']) # Use comparison metadata for context

            # --- 11. Log completion and return ---
            self.logger.log("ScoreComparisonCompleted", {
                "total_scores_processed": len(aggregated_results),
                "analysis_results_generated": len(analysis_results) > 0,
                # Add more summary stats if needed
            })

            return context

        except Exception as e:
            error_msg = f"ScoreComparisonAgent failed: {str(e)}"
            self.logger.log("ScoreComparisonFailed", {"error": str(e), "context": str(context)})
            # Depending on requirements, you might want to re-raise or handle gracefully
            raise # Re-raise for now to halt the pipeline on critical failure


    def _fetch_local_scores(self, pipeline_run_ids: List[int], dimensions: List[str]) -> List[Dict[str, Any]]:
        """
        Fetches scores for specified sources linked to specific pipeline runs.
        Uses a SQL query with ROW_NUMBER() and pivoting for efficient retrieval
        of the latest score per target/dimension/source combination.
        """
        try:
            if not pipeline_run_ids:
                self.logger.log("LocalScoreFetchWarning", {"message": "No pipeline_run_ids provided. Returning empty list."})
                return []

            # 1. Build the list of sources to filter by (excluding ground truth for now)
            non_gt_sources = [s for s in self.sources_to_compare if s != self.ground_truth_source]
            
            # Handle case where only GT source is requested
            if not non_gt_sources:
                self.logger.log("LocalScoreFetchInfo", {"message": "No non-ground-truth sources to fetch. Returning empty list."})
                return []

            # 2. Create placeholders for the IN clauses in the SQL query
            # Note: Using tuple() for IN clauses in SQLAlchemy text queries
            pipeline_ids_tuple = tuple(pipeline_run_ids) if pipeline_run_ids else (None,) # Prevent empty tuple error
            sources_tuple = tuple(non_gt_sources) if non_gt_sources else (None,)
            dimensions_tuple = tuple(dimensions) if dimensions else None # Will handle NULL check in SQL

            # 3. Define the SQL query using text()
            # We'll build the CASE statements dynamically based on sources
            case_statements = []
            for source in non_gt_sources:
                # Normalize source name for column alias (e.g., 'sicql_scorer' -> 'sicql_score')
                # Adjust this normalization logic if needed based on your exact evaluator names
                # The key change: Use the column name 'source' directly, not 's.source'
                case_statements.append(f"MAX(CASE WHEN source = '{source}' THEN score END) AS {source}_score")
            
            case_part = ",\n        ".join(case_statements)

            # 4. Base query - CORRECTED: Removed 's.' prefix in the grouped_scores CTE
            query_text = f"""
            WITH pipeline_scores AS (
                SELECT
                    e.target_type,
                    e.target_id,
                    s.dimension,
                    s.source, -- Column alias 'source'
                    s.score,  -- Column alias 'score'
                    ROW_NUMBER() OVER (
                        PARTITION BY e.target_type, e.target_id, s.dimension, s.source
                        ORDER BY e.created_at DESC
                    ) AS row_num
                FROM scores s
                JOIN evaluations e ON s.evaluation_id = e.id
                WHERE e.pipeline_run_id IN :pipeline_run_ids
                AND s.source IN :sources
                -- Filter by dimensions if provided
                AND (:dimensions IS NULL OR s.dimension IN :dimensions)
            ),
            latest_scores AS (
                SELECT *
                FROM pipeline_scores
                WHERE row_num = 1
            ),
            grouped_scores AS (
                SELECT
                    target_type,
                    target_id,
                    dimension,
                    {case_part} -- Uses 'source' and 'score' from latest_scores
                FROM latest_scores
                GROUP BY target_type, target_id, dimension
            )
            SELECT *
            FROM grouped_scores
            ORDER BY dimension, target_type, target_id;
            """

            # 5. Log the query for debugging (optional, remove in production)
            # self.logger.log("DebugSQLQuery", {"query": query_text, "params": {
            #     "pipeline_run_ids": pipeline_ids_tuple,
            #     "sources": sources_tuple,
            #     "dimensions": dimensions_tuple
            # }})

            # 6. Execute the query with parameters
            result = self.session.execute(
                text(query_text),
                {
                    "pipeline_run_ids": pipeline_ids_tuple,
                    "sources": sources_tuple,
                    "dimensions": dimensions_tuple
                }
            )

            # 7. Process the results
            # The result will have columns like: target_type, target_id, dimension, sicql_score, mrq_score, ...
            raw_rows = result.fetchall()

            formatted_scores = []
            for row in raw_rows:
                row_dict = row._mapping # Convert Row to dict-like object
                
                target_type = row_dict.get("target_type")
                target_id = row_dict.get("target_id")
                dimension = row_dict.get("dimension")

                # Iterate through the dynamically created score columns
                for source_alias in non_gt_sources: # e.g., 'sicql', 'mrq', 'svm', 'ebt'
                    # The column name in the result set matches the alias used in CASE
                    column_name = f"{source_alias}_score" 
                    
                    score_value = row_dict.get(column_name)
                    
                    # Only add an entry if a score was found for this source
                    if score_value is not None:
                        formatted_scores.append({
                            # Evaluation ID is not directly available in this pivoted format.
                            "target_id": target_id,
                            "target_type": target_type,
                            "dimension": dimension,
                            "source": source_alias, # Use the original source name
                            "score": float(score_value), # Ensure it's a native Python type
                        })

            self.logger.log("LocalScoresFetched", {
                "requested_pipeline_runs": pipeline_run_ids,
                "requested_sources": non_gt_sources,
                "requested_dimensions": dimensions,
                "fetched_record_count": len(raw_rows), # Number of grouped rows
                "expanded_score_count": len(formatted_scores) # Number of individual score entries
            })
            return formatted_scores

        except sqlalchemy.exc.SQLAlchemyError as sae:
            # More specific error handling for database issues
            self.logger.log("LocalScoreFetchDatabaseError", {"error": f"SQLAlchemy Error: {str(sae)}", "query": query_text if 'query_text' in locals() else "Query construction failed"})
            return []
        except Exception as e:
            self.logger.log("LocalScoreFetchFailed", {"error": f"General Error: {str(e)}", "pipeline_run_ids": pipeline_run_ids, "dimensions": dimensions})
            return [] # Return empty list on error to allow pipeline to potentially continue

    def _fetch_latest_ground_truth_scores(self, target_info_list: List[Dict[str, Any]], dimensions: List[str]) -> List[Dict[str, Any]]:
        """
        Fetches the latest scores from the ground truth source (e.g., LLM) for given targets.
        Adapted from PolicyAnalyzer._get_llm_data.
        """

        if not target_info_list:
             return []

        try:
            # We need to get the LATEST score for each (target_id, dimension) pair where source is LLM
            # This is trickier than a simple filter. We can use a subquery or window function.
            # Let's use a common approach: join with a subquery that finds the max created_at per group.

            # Subquery to find the latest evaluation_id for each (target_id, dimension) for LLM
            latest_eval_subq = (
                self.session.query(
                    EvaluationORM.target_id,
                    ScoreORM.dimension,
                    # Using func.max might not directly give us the id, so we use a window function approach
                    # Or, simpler, get the latest EvaluationORM.id per group and join back
                )
                .join(ScoreORM, ScoreORM.evaluation_id == EvaluationORM.id)
                .filter(EvaluationORM.evaluator_name == self.ground_truth_source)
                .filter(EvaluationORM.target_id.in_([t['target_id'] for t in target_info_list]))
                .filter(ScoreORM.dimension.in_(dimensions) if dimensions else True)
                # Group by target and dimension
                .group_by(EvaluationORM.target_id, ScoreORM.dimension)
                # This approach with group_by alone won't give the latest id directly
                # Let's use a more robust method with a correlated subquery or distinct on
                # Or, use the logic from ScoringStore.load_gild_examples which handles "latest"
            )

            # Simpler and more aligned with existing patterns: Use a modified version of the logic
            # that gets latest scores for a specific source, similar to how `load_gild_examples` works
            # but filtered for LLM and specific targets/dimensions.

            # Let's adapt the CTE logic from ScoringStore.load_gild_examples for just LLM
            from sqlalchemy import text
            # This is a simplified version focusing only on LLM
            # Note: This assumes target_type is consistent or handled, or we filter it out if not needed here
            cte_query_text = """
            WITH ranked_llm_scores AS (
                SELECT
                    s.dimension,
                    s.score,
                    e.target_id,
                    e.id as evaluation_id, -- Include evaluation_id for join if needed
                    e.created_at,
                    ROW_NUMBER() OVER (
                        PARTITION BY e.target_id, s.dimension
                        ORDER BY e.created_at DESC
                    ) AS rank
                FROM scores s
                JOIN evaluations e ON e.id = s.evaluation_id
                WHERE e.evaluator_name = :evaluator_name -- 'llm'
                AND e.target_id IN :target_ids
                AND s.dimension IN :dimensions
                -- Add target_type filter if strictly needed
            )
            SELECT
                target_id,
                dimension,
                score,
                created_at
            FROM ranked_llm_scores
            WHERE rank = 1
            """

            # Prepare parameters
            target_ids = [t['target_id'] for t in target_info_list]
            dims = dimensions if dimensions else [t['dimension'] for t in target_info_list] # Fallback if needed

            if not target_ids or not dims: # Safety check
                 return []

            result = self.session.execute(
                text(cte_query_text),
                {
                    "evaluator_name": self.ground_truth_source,
                    "target_ids": tuple(target_ids),
                    "dimensions": tuple(dims)
                }
            ).fetchall()

            llm_scores = [dict(row._mapping) for row in result]
            
            self.logger.log("GroundTruthScoresFetched", {"count": len(llm_scores)})
            return llm_scores

        except Exception as e:
             self.logger.log("GroundTruthScoreFetchFailed", {"error": str(e)})
             return []

    def _generate_basic_report(self, aggregated_data: List[Dict], metadata: Dict):
        """
        Generates a simple summary report of the comparison.
        """
        try:
            if not aggregated_data:
                 report_content = "# Score Comparison Report (Empty)\n\nNo data found for comparison.\n"
                 self.logger.log("EmptyComparisonReportGenerated", {})
            else:
                # Simple aggregation: count, average delta per source
                from collections import defaultdict
                import statistics

                source_stats = defaultdict(lambda: {"count": 0, "avg_delta": 0, "deltas": []})
                
                for item in aggregated_data:
                     source = item.get('source')
                     delta = item.get('delta')
                     if source: # Ensure source is present
                          source_stats[source]["count"] += 1
                          if delta is not None:
                               source_stats[source]["deltas"].append(delta)
                
                # Calculate average deltas
                for source, stats in source_stats.items():
                     if stats["deltas"]:
                          stats["avg_delta"] = statistics.mean(stats["deltas"])
                          # Could add stddev, min, max etc.
                     del stats["deltas"] # Remove raw list for cleaner output

                timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
                report_filename = f"score_comparison_summary_{timestamp}.md"
                report_path = os.path.join(self.output_dir, report_filename)

                with open(report_path, 'w') as f:
                     f.write("# Score Comparison Summary Report\n\n")
                     f.write(f"**Generated:** {metadata.get('comparison_timestamp', 'N/A')}\n\n")
                     f.write(f"**Pipeline Runs Analyzed:** {metadata.get('pipeline_run_ids', 'N/A')}\n\n")
                     f.write(f"**Sources Compared:** {', '.join(metadata.get('sources_compared', []))}\n\n")
                     f.write(f"**Ground Truth Source:** {metadata.get('ground_truth_source', 'N/A')}\n\n")
                     f.write(f"**Dimensions:** {', '.join(metadata.get('dimensions', []))}\n\n")
                     f.write("## Summary Statistics (vs Ground Truth)\n\n")
                     f.write("| Source | Count | Avg Delta (Model - LLM) |\n")
                     f.write("| :--- | :--- | :--- |\n")
                     for source, stats in sorted(source_stats.items()):
                          f.write(f"| {source} | {stats['count']} | {stats['avg_delta']:.4f} |\n")
                
                self.logger.log("ComparisonSummaryReportSaved", {"path": report_path})

        except Exception as e:
             self.logger.log("ComparisonReportGenerationFailed", {"error": str(e)})


    def _save_comparison_csv(self, aggregated_data: List[Dict[str, Any]], metadata: Dict[str, Any]):
        """
        Saves the aggregated score comparison data to a CSV file.
        """
        try:
            if not aggregated_data:
                self.logger.log("SaveComparisonCSVWarning", {"message": "No data to save to CSV. Skipping."})
                return

            timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
            # Create a descriptive filename
            pipeline_ids_str = "_".join(map(str, metadata.get('pipeline_run_ids', ['unknown'])))
            filename = f"score_comparison_raw_{pipeline_ids_str}_{timestamp}.csv"
            file_path = os.path.join(self.output_dir, filename)

            # Define the fieldnames for the CSV. These should match the keys in your aggregated data dicts.
            # Based on the current structure in run() and _fetch_local_scores/_fetch_latest_ground_truth_scores
            fieldnames = [
                "target_id",
                "target_type",
                "dimension",
                "source", # The model that produced the score
                "score",  # The score from the model
                "llm_score", # The ground truth LLM score for the same target/dimension
                "delta"  # The difference (score - llm_score)
                # Add other fields like 'embedding_type', 'created_at' if they are included in aggregated_data
            ]
            # Dynamically add any other keys found in the first data point (for robustness)
            if aggregated_data:
                sample_keys = set(aggregated_data[0].keys())
                for key in sample_keys:
                    if key not in fieldnames:
                        fieldnames.append(key)
            # Ensure consistent order, put standard ones first
            standard_fields = [f for f in fieldnames if f in ['target_id', 'target_type', 'dimension', 'source', 'score', 'llm_score', 'delta']]
            other_fields = [f for f in fieldnames if f not in standard_fields]
            ordered_fieldnames = standard_fields + sorted(other_fields)


            with open(file_path, 'w', newline='', encoding='utf-8') as csvfile:
                writer = csv.DictWriter(csvfile, fieldnames=ordered_fieldnames)
                writer.writeheader()
                # Sort data for consistent output (optional)
                sorted_data = sorted(aggregated_data, key=lambda x: (x.get('dimension', ''), x.get('target_type', ''), x.get('target_id', 0), x.get('source', '')))
                for row in sorted_data:
                    # Handle potential serialization issues (e.g., datetime objects)
                    # Although our current data should be basic types, this is good practice.
                    safe_row = {k: v if isinstance(v, (str, int, float, type(None))) else str(v) for k, v in row.items()}
                    writer.writerow(safe_row)


            self.logger.log("ComparisonCSVSaved", {"path": file_path, "record_count": len(aggregated_data)})
            
        except Exception as e:
            self.logger.log("SaveComparisonCSVFailed", {"error": str(e), "output_dir": self.output_dir})



    def _perform_statistical_analysis(self, aggregated_data: List[Dict[str, Any]]) -> Dict[str, Any]:
        """
        Performs statistical analysis on the aggregated score comparison data.
        Calculates MAE, RMSE, Correlation, Bias, and Variance of model scores
        per source and dimension.
        """
        try:

            # --- 1. Organize Data ---
            # Group data by (source, dimension) for metric calculation
            grouped_data = defaultdict(list)
            for item in aggregated_data:
                # Only analyze non-ground-truth scores that have a corresponding LLM score/delta
                if item.get('source') and item.get('source') != self.ground_truth_source and item.get('delta') is not None:
                    key = (item['source'], item['dimension'])
                    grouped_data[key].append(item)
                
                # Also collect model scores for calculating variance of scores produced by the model
                # This uses the 'score' field for the model itself
                if item.get('source') and item.get('source') != self.ground_truth_source and item.get('score') is not None:
                    # Use a distinct key structure for model scores
                    score_key = (item['source'], item['dimension'], 'model_scores') 
                    grouped_data[score_key].append(item['score']) # Store just the score value

            # --- 2. Calculate Metrics ---
            results = {}

            # --- Calculate Main Metrics (MAE, RMSE, Correlation, Bias) ---
            for key, items in grouped_data.items():
                # Process only the main metric keys: (source, dimension)
                # Skip keys with 'model_scores' marker: (source, dimension, 'model_scores')
                if isinstance(key, tuple) and len(key) == 3 and key[2] == 'model_scores':
                    continue # This will be handled later for score variance

                if isinstance(key, tuple) and len(key) == 2:
                    source, dimension = key
                else:
                    # Handle unexpected key format gracefully
                    self.logger.log("StatisticalAnalysisWarning", {
                        "message": "Skipping unexpected key format in grouped data",
                        "key": str(key), "key_type": str(type(key))
                    })
                    continue

                if not items:
                    continue

                # Extract arrays for calculations
                deltas = np.array([item['delta'] for item in items if item['delta'] is not None])
                model_scores = np.array([item['score'] for item in items if item['score'] is not None])
                llm_scores = np.array([item['llm_score'] for item in items if item['llm_score'] is not None])

                # Ensure we have data to calculate metrics
                if len(deltas) == 0 or len(model_scores) == 0 or len(llm_scores) == 0:
                    self.logger.log("StatisticalAnalysisWarning", {
                        "message": "Insufficient data for metric calculation",
                        "source": source, "dimension": dimension,
                        "delta_count": len(deltas), "model_score_count": len(model_scores), "llm_score_count": len(llm_scores)
                    })
                    continue

                # --- Core Metrics ---
                mae = np.mean(np.abs(deltas))
                rmse = np.sqrt(np.mean(deltas**2))
                
                # Correlation: Check if variance is sufficient for meaningful correlation
                corr_coef = None
                corr_p_value = None
                if np.std(model_scores) > 1e-10 and np.std(llm_scores) > 1e-10:
                    try:
                        # Use scipy.stats.pearsonr
                        corr_result = pearsonr(model_scores, llm_scores)
                        # Handle different scipy versions
                        if hasattr(corr_result, 'statistic'):
                            corr_coef = corr_result.statistic
                            corr_p_value = corr_result.pvalue
                        else: # Older scipy versions return a tuple
                            corr_coef, corr_p_value = corr_result
                    except Exception as e:
                        self.logger.log("CorrelationCalculationWarning", {
                            "error": str(e), "source": source, "dimension": dimension
                        })

                bias = np.mean(deltas) # Average difference (Model - LLM)

                # --- Store Results ---
                result_key = f"{source}_{dimension}"
                results[result_key] = {
                    "source": source,
                    "dimension": dimension,
                    "count": len(deltas),
                    "mae": float(mae),
                    "rmse": float(rmse),
                    "correlation": float(corr_coef) if corr_coef is not None else None,
                    "correlation_p_value": float(corr_p_value) if corr_p_value is not None else None,
                    "bias": float(bias), # Positive bias = Model tends to score higher than LLM
                }

            # --- 3. Calculate Variance of Model Scores ---
            # This is the standard deviation of scores *produced by each model* for a dimension
            for key, scores_list in grouped_data.items():
                # Process only the score variance keys: (source, dimension, 'model_scores')
                if not (isinstance(key, tuple) and len(key) == 3 and key[2] == 'model_scores'):
                    continue # Skip main metric keys

                source, dimension, _ = key # Unpack the 3-tuple key

                if not scores_list:
                    continue
                
                scores_array = np.array(scores_list)
                if len(scores_array) > 1: # Need more than one value for std dev
                    score_variance = float(np.std(scores_array))
                    # Add this to the existing result dict or create a new entry if it doesn't exist
                    result_key = f"{source}_{dimension}"
                    if result_key in results:
                        results[result_key]["score_std_dev"] = score_variance
                    else:
                        # Less likely, but handle if main metrics weren't calculated for some reason
                        results[result_key] = {
                            "source": source,
                            "dimension": dimension,
                            "count": len(scores_array),
                            "score_std_dev": score_variance
                            # Other metrics will be missing
                        }
                # else: Not enough data for variance, leave it out or set to 0?

            self.logger.log("StatisticalAnalysisCompleted", {
                "unique_source_dimension_combinations_analyzed": len(results)
            })
            
            return results

        except Exception as e:
            self.logger.log("StatisticalAnalysisFailed", {"error": str(e)})
            # Depending on robustness needs, return empty dict or re-raise
            return {} # Return empty dict on error to allow pipeline to potentially continue

    def _generate_analysis_report(self, analysis_results: Dict[str, Any], comparison_metadata: Dict[str, Any]):
        """
        Generates a detailed markdown report summarizing the statistical analysis results.
        """
        try:
            if not analysis_results:
                report_content = "# Score Analysis Report (Empty)\n\nNo analysis data found.\n"
                self.logger.log("EmptyAnalysisReportGenerated", {})
            else:
                timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
                pipeline_ids_str = "_".join(map(str, comparison_metadata.get('pipeline_run_ids', ['unknown'])))
                report_filename = f"score_analysis_detailed_{pipeline_ids_str}_{timestamp}.md"
                report_path = os.path.join(self.output_dir, report_filename)

                with open(report_path, 'w', encoding='utf-8') as f:
                    f.write(f"# Detailed Score Analysis Report\n\n")
                    f.write(f"**Generated:** {comparison_metadata.get('comparison_timestamp', 'N/A')}\n\n") # Use timestamp from comparison
                    f.write(f"**Analysis Performed:** {datetime.now().isoformat()}\n\n")
                    f.write(f"**Pipeline Runs Analyzed:** {comparison_metadata.get('pipeline_run_ids', 'N/A')}\n\n")
                    f.write(f"**Sources Compared:** {', '.join(comparison_metadata.get('sources_compared', []))}\n\n")
                    f.write(f"**Ground Truth Source:** {comparison_metadata.get('ground_truth_source', 'N/A')}\n\n")
                    f.write(f"**Dimensions:** {', '.join(comparison_metadata.get('dimensions', []))}\n\n")
                    f.write("---\n\n")

                    # Group results by dimension for better organization
                    from collections import defaultdict
                    results_by_dimension = defaultdict(list)
                    for key, metrics in analysis_results.items():
                        dim = metrics.get('dimension', 'unknown')
                        results_by_dimension[dim].append(metrics)

                    # Sort dimensions and sources for consistent output
                    sorted_dimensions = sorted(results_by_dimension.keys())

                    for dimension in sorted_dimensions:
                        f.write(f"## Analysis for Dimension: `{dimension}`\n\n")
                        f.write("| Source | Count | MAE | RMSE | Correlation (p-value) | Bias | Score Std Dev |\n")
                        f.write("| :--- | ---: | ---: | ---: | ---: | ---: | ---: |\n")

                        sorted_sources_for_dim = sorted(results_by_dimension[dimension], key=lambda x: x.get('source', ''))
                        for metrics in sorted_sources_for_dim:
                            source = metrics.get('source', 'N/A')
                            count = metrics.get('count', 0)
                            mae = f"{metrics.get('mae', 0):.4f}" if metrics.get('mae') is not None else "N/A"
                            rmse = f"{metrics.get('rmse', 0):.4f}" if metrics.get('rmse') is not None else "N/A"
                            
                            corr = metrics.get('correlation')
                            p_val = metrics.get('correlation_p_value')
                            if corr is not None:
                                corr_str = f"{corr:.4f}"
                                if p_val is not None:
                                    corr_str += f" ({p_val:.2e})" # Add p-value in scientific notation
                            else:
                                corr_str = "N/A"

                            bias = f"{metrics.get('bias', 0):.4f}" if metrics.get('bias') is not None else "N/A"
                            std_dev = f"{metrics.get('score_std_dev', 0):.4f}" if metrics.get('score_std_dev') is not None else "N/A"

                            f.write(f"| {source} | {count} | {mae} | {rmse} | {corr_str} | {bias} | {std_dev} |\n")
                        f.write("\n") # Space between dimensions

                self.logger.log("DetailedAnalysisReportSaved", {"path": report_path})

        except Exception as e:
            self.logger.log("DetailedAnalysisReportGenerationFailed", {"error": str(e)})