Update app.py

app.py

@@ -10,7 +10,7 @@ from scipy.linalg import expm
 
 from fastapi import FastAPI, HTTPException
 from pydantic import BaseModel, Field
-from pydantic import ConfigDict  # para evitar warning de protected_namespaces
+from pydantic import ConfigDict  # para evitar warning con model_id
 
 from sentence_transformers import SentenceTransformer
 from huggingface_hub import hf_hub_download
@@ -25,12 +25,13 @@ import torch.nn as nn
 # ============================
 
 HF_TOKEN = os.environ.get("HF_TOKEN", "")
+os.environ["HF_TOKEN"] = HF_TOKEN  # por si algún cliente interno lo espera
 
 ENCODER_MODEL_ID     = "antonypamo/RRFSAVANTMADE"
 META_LOGIT_REPO      = "antonypamo/RRFSavantMetaLogit"
-META_LOGIT_FILENAME  = "logreg_rrf_savant_15.joblib"
+META_LOGIT_FILENAME  = "logreg_rrf_savant_15.joblib"  # versión 15 features
 
-# Dataset central con TODOS los artefactos
+# Dataset central con TODOS los artefactos RRF/Savant
 RRF_DATASET_REPO     = "antonypamo/savant_rrf1_curated"
 
 
@@ -81,7 +82,7 @@ except Exception as e:
 
 
 # ============================
-# Rutas a artefactos desde el dataset central
+# Artefactos desde savant_rrf1_curated
 # ============================
 
 def safe_hf(path_name: str) -> Optional[str]:
@@ -112,32 +113,34 @@ PHYS_ADJ_13               = safe_hf("adjacency_13.csv")
 
 
 # ============================
-# Savant CNN + nodos RRF (para futura integración)
+# Savant CNN + nodos RRF (demo futura)
 # ============================
 
 class SavantCNN(nn.Module):
     """
-    CNN tal como fue entrenada originalmente:
+    CNN compatible con el checkpoint:
     - conv1: [1 -> 32]
     - conv2: [32 -> 64]
     - conv3: [64 -> 128]
-    - fc:   [512 -> 64]  (según checkpoint original)
+    - pool: AdaptiveAvgPool1d(4)  => 128 * 4 = 512
+    - fc:   [512 -> 64]
     """
     def __init__(self, in_channels: int = 1, out_dim: int = 64):
         super().__init__()
         self.conv1 = nn.Conv1d(in_channels, 32, kernel_size=3, padding=1)
         self.conv2 = nn.Conv1d(32, 64, kernel_size=3, padding=1)
         self.conv3 = nn.Conv1d(64, 128, kernel_size=3, padding=1)
-        self.pool = nn.AdaptiveAvgPool1d(1)
-        self.fc   = nn.Linear(512, out_dim)  # mantiene compatibilidad con checkpoint
+        self.pool = nn.AdaptiveAvgPool1d(4)
+        self.fc   = nn.Linear(512, out_dim)
 
     def forward(self, x: torch.Tensor) -> torch.Tensor:
         # x: [batch, channels, length]
         x = torch.relu(self.conv1(x))
         x = torch.relu(self.conv2(x))
         x = torch.relu(self.conv3(x))
-        x = self.pool(x).squeeze(-1)  # [batch, 128] en este diseño simplificado
-        x = self.fc(x)
+        x = self.pool(x)              # [batch, 128, 4]
+        x = x.view(x.size(0), -1)     # [batch, 512]
+        x = self.fc(x)                # [batch, out_dim]
         return x
 
 
@@ -181,8 +184,8 @@ else:
 
 def fuse_cnn_with_node(example_length: int = 64):
     """
-    Utilidad interna: ejemplo de cómo fusionar la CNN con un nodo RRF.
-    No se expone aún como endpoint, pero sirve para demos técnicas.
+    Utilidad interna de demo: fusionar embedding CNN + nodo RRF.
+    No expuesta aún como endpoint público.
     """
     if savant_cnn is None or rrf_nodes is None:
         print("Fusion not available – missing CNN or RRF nodes snapshot.")
@@ -192,7 +195,7 @@ def fuse_cnn_with_node(example_length: int = 64):
     cnn_emb = savant_cnn(x)  # [1, 64]
 
     try:
-        # asumir que el primer nodo es algo como rrf_nodes["node_0"]
+        # asumir primer nodo tipo rrf_nodes["node_0"]
         node0_key = list(rrf_nodes.keys())[0]
         node0 = rrf_nodes[node0_key]
         if isinstance(node0, dict) and "linguistic" in node0:
@@ -217,13 +220,13 @@ def fuse_cnn_with_node(example_length: int = 64):
 # ============================
 
 phi = (1 + np.sqrt(5)) / 2
-nodes = np.array([
+nodes_geom = np.array([
     [0, 1, phi], [0, -1, phi], [0, 1, -phi], [0, -1, -phi],
     [1, phi, 0], [-1, phi, 0], [1, -phi, 0], [-1, -phi, 0],
     [phi, 0, 1], [phi, 0, -1], [-phi, 0, 1], [-phi, 0, -1]
 ], dtype=float)
-nodes /= norm(nodes, axis=1, keepdims=True)
-N = nodes.shape[0]  # 12 nodos
+nodes_geom /= norm(nodes_geom, axis=1, keepdims=True)
+N = nodes_geom.shape[0]  # 12 nodos
 
 sigma_x = np.array([[0, 1], [1, 0]], dtype=complex)
 sigma_y = np.array([[0, -1j], [1j, 0]], dtype=complex)
@@ -244,12 +247,11 @@ def geodesic_kernel(nodes, sigma=0.618, alpha_log=0.10):
     diff = nodes[:, None, :] - nodes[None, :, :]
     dist = norm(diff, axis=-1)
 
-    W = np.exp(-(dist ** 2) / (sigma ** 2))
+    W = np.exp(-(dist**2) / (sigma**2))
     np.fill_diagonal(W, 0.0)
 
     if alpha_log > 0.0:
-        corr = 1.0 + alpha_log * np.log1p(dist ** 2)
-        # mantener diagonal en 1 para evitar log(0)
+        corr = 1.0 + alpha_log * np.log1p(dist**2)
         corr[range(N), range(N)] = 1.0
         W = W / corr
 
@@ -275,10 +277,10 @@ def build_dirac_hamiltonian(
     flux_vector=(0.0, 0.0, 0.0),
     gauge_scale=0.0,
 ):
-    W = geodesic_kernel(nodes, sigma=sigma, alpha_log=alpha_log)
+    W = geodesic_kernel(nodes_geom, sigma=sigma, alpha_log=alpha_log)
 
     if gauge_scale != 0.0 and any(flux_vector):
-        theta = u1_edge_phases(nodes, flux_vector=flux_vector,
+        theta = u1_edge_phases(nodes_geom, flux_vector=flux_vector,
                                q=q, gauge_scale=gauge_scale)
         U = np.exp(1j * theta)
     else:
@@ -286,7 +288,7 @@ def build_dirac_hamiltonian(
 
     H = np.kron(np.eye(N, dtype=complex), m * sigma_z)
 
-    diff = nodes[:, None, :] - nodes[None, :, :]
+    diff = nodes_geom[:, None, :] - nodes_geom[None, :, :]
     dist = norm(diff, axis=-1) + 1e-12
     d_hat = diff / dist[..., None]
 
@@ -308,7 +310,7 @@ def site_probs(psi):
     N2 = psi.shape[0]
     n = N2 // 2
     psi_mat = psi.reshape(n, 2)
-    return np.sum(np.abs(psi_mat) ** 2, axis=1).real
+    return np.sum(np.abs(psi_mat)**2, axis=1).real
 
 
 def chirality(psi):
@@ -325,7 +327,12 @@ def spatial_entropy(p):
     return float(-np.sum(p * np.log(p)).real)
 
 
-def evolve_dirac_shell(psi0, H, dt=0.05, steps=100, record_every=25):
+def evolve_dirac_shell(psi0, H, dt=0.05, steps=200, record_every=20):
+    """
+    Evolución unitaria sobre la red icosaédrica.
+    steps=200 da buena resolución para el feature set; los endpoints
+    pueden usar menos pasos si se quiere.
+    """
     U = expm(-1j * dt * H)
     psi = psi0.copy()
 
@@ -365,14 +372,20 @@ def get_embedding(text: str) -> np.ndarray:
 
 
 def compute_rrf_features(prompt: str, answer: str) -> Dict[str, float]:
+    """
+    Genera las 15 features que espera el meta-logit:
+    - embeddings + Dirac shell + derivadas (entropía, energía, longitud, etc.)
+    """
+    # Embeddings
     e_p = get_embedding(prompt)
     e_a = get_embedding(answer)
 
     cosine_pa = float(np.dot(e_p, e_a))
     len_ratio = len(answer) / (len(prompt) + 1.0)
 
-    rng = np.random.default_rng(abs(hash(prompt + answer)) % (2 ** 32))
-    vec = rng.normal(0, 1, (2 * N,)) + 1j * rng.normal(0, 1, (2 * N,))
+    # Simulación Dirac shell determinista (semilla por prompt+answer)
+    rng = np.random.default_rng(abs(hash(prompt + answer)) % (2**32))
+    vec = rng.normal(0, 1, (2*N,)) + 1j * rng.normal(0, 1, (2*N,))
     vec /= np.sqrt(np.vdot(vec, vec))
     psi0 = vec
 
@@ -406,6 +419,7 @@ def compute_rrf_features(prompt: str, answer: str) -> Dict[str, float]:
         "dirac_energy_std": E_std,
     }
 
+    # Derivadas extra para llegar a 15 features
     S_max = math.log(N)
     feats["entropy_norm"]      = feats["dirac_entropy_final"] / S_max
     feats["entropy_abs_delta"] = abs(feats["dirac_entropy_delta"])
@@ -440,7 +454,11 @@ def features_to_vector(feats: Dict[str, float]) -> np.ndarray:
     return np.array([feats[k] for k in keys], dtype=float)
 
 
-def compute_scores_srff_crff_ephi(prompt: str, answer: str):
+def compute_scores_srff_crrf_ephi(prompt: str, answer: str):
+    """
+    Usa el meta-logit para obtener p_good y derivar:
+    - SRRF, CRRF, E_phi
+    """
     feats = compute_rrf_features(prompt, answer)
     x = features_to_vector(feats).reshape(1, -1)
 
@@ -464,7 +482,7 @@ def compute_scores_srff_crff_ephi(prompt: str, answer: str):
 
 
 # ============================
-# Role profiles
+# Role profiles (perfiles de evaluación)
 # ============================
 
 ROLE_PROFILES: Dict[str, Dict[str, float]] = {
@@ -487,6 +505,9 @@ ROLE_PROFILES: Dict[str, Dict[str, float]] = {
 
 
 def apply_role_profile(scores: Dict[str, float], role_name: Optional[str]) -> Dict[str, Any]:
+    """
+    Calcula un composite_score según el perfil de rol.
+    """
     if not role_name:
         role_name = "default"
 
@@ -600,9 +621,11 @@ def rrf_tutor_build_answer(query: str, retrieved_examples):
 # ============================
 
 class EvaluateRequest(BaseModel):
-    prompt: str
-    answer: str
-    model_label: Optional[str] = None
+    prompt: str = Field(..., description="Pregunta / instrucción original.")
+    answer: str = Field(..., description="Respuesta generada por un LLM.")
+    model_label: Optional[str] = Field(
+        None, description="Etiqueta opcional de rol/modelo (default/creative/precise o custom)."
+    )
 
 
 class EvaluateResponse(BaseModel):
@@ -613,6 +636,7 @@ class EvaluateResponse(BaseModel):
 
 
 class QualityRemoteRequest(EvaluateRequest):
+    """Alias de EvaluateRequest para /quality_remote."""
     pass
 
 
@@ -626,6 +650,9 @@ class RoleProfilesResponse(BaseModel):
 
 
 class RerankRequest(BaseModel):
+    """
+    Petición para /v1/rerank
+    """
     query: str = Field(..., description="Query de búsqueda o pregunta del usuario.")
     documents: List[str] = Field(..., description="Lista de documentos candidatos a rerankear.")
     alpha: float = Field(
@@ -685,7 +712,7 @@ class RRFTutorResponse(BaseModel):
 
 app = FastAPI(
     title="Savant RRF Φ12.0 API",
-    description="Dirac-Resonant conceptual quality layer + reranking + RRF Tutor (+ CNN/nodes listos).",
+    description="Dirac-Resonant conceptual quality + role profiles + reranking + RRF Tutor (+ CNN/nodes).",
     version="1.2.0",
 )
 
@@ -763,9 +790,9 @@ def list_roles():
 
 
 @app.post("/evaluate", response_model=EvaluateResponse)
-def evaluate(req: EvaluateRequest):
+def evaluate_endpoint(req: EvaluateRequest):
     try:
-        scores, feats = compute_scores_srff_crff_ephi(req.prompt, req.answer)
+        scores, feats = compute_scores_srff_crrf_ephi(req.prompt, req.answer)
 
         role_profile = apply_role_profile(scores, req.model_label)
 
@@ -775,10 +802,8 @@ def evaluate(req: EvaluateRequest):
             flux_vector=(0.0, 0.0, 0.0),
             gauge_scale=0.0,
         )
-        rng = np.random.default_rng(
-            abs(hash(req.prompt + req.answer + "sim")) % (2 ** 32)
-        )
-        vec = rng.normal(0, 1, (2 * N,)) + 1j * rng.normal(0, 1, (2 * N,))
+        rng = np.random.default_rng(abs(hash(req.prompt + req.answer + "sim")) % (2**32))
+        vec = rng.normal(0, 1, (2*N,)) + 1j * rng.normal(0, 1, (2*N,))
         vec /= np.sqrt(np.vdot(vec, vec))
         psi0 = vec
         sim = evolve_dirac_shell(psi0, H, dt=0.05, steps=60, record_every=20)
@@ -800,25 +825,34 @@ def evaluate(req: EvaluateRequest):
             role_profile=role_profile,
         )
     except Exception as e:
-        print(f"❌ [Runtime] Error en /evaluate: {e}", file=sys.stderr, flush=True)
+        print(f"❌ [Runtime] Error en /evaluate: {e}", flush=True)
         raise HTTPException(status_code=500, detail="Internal server error")
 
 
 @app.post("/quality_remote", response_model=EvaluateResponse)
 def quality_remote(req: QualityRemoteRequest):
-    return evaluate(req)
+    """Alias remoto de /evaluate."""
+    return evaluate_endpoint(req)
 
 
 @app.post("/quality", response_model=EvaluateResponse)
 def quality_alias(req: QualityRemoteRequest):
-    """
-    Alias directo de /evaluate para compatibilidad con clientes previos.
-    """
-    return evaluate(req)
+    """Alias directo de /evaluate (compatibilidad hacia atrás)."""
+    return evaluate_endpoint(req)
 
 
 @app.post("/v1/rerank", response_model=RerankResponse)
 def rerank_endpoint(req: RerankRequest):
+    """
+    Endpoint Savant Seek:
+    POST /v1/rerank
+    {
+        "query": "...",
+        "documents": ["doc1", "doc2", ...],
+        "alpha": 0.2,
+        "query_embedding_norm": true
+    }
+    """
     results = _compute_rerank_scores(
         query=req.query,
         docs=req.documents,