Upload alpha_factory/infra/factor_store.py

alpha_factory/infra/factor_store.py

@@ -80,6 +80,8 @@ class FactorStore:
         iteration: int = 1,
     ):
         """Insert a new alpha candidate (before BRAIN results arrive)."""
+        # NOTE: All SQL uses parameterized queries (? placeholders) to prevent injection.
+        # The expression field is user-controlled (from LLM output) but is passed as a param.
         self.conn.execute("""
             INSERT OR REPLACE INTO alphas (alpha_id, expression, neutralization, decay,
                 fields_used, operators_used, archetype, theme, anomaly_tag,
@@ -107,38 +109,47 @@ class FactorStore:
                   metrics.margin_pct, fitness_score, alpha_id])
 
     def update_verdict(self, alpha_id: str, verdict: Verdict, memo: str = ""):
+        """Set the final verdict for an alpha."""
         self.conn.execute("""
             UPDATE alphas SET verdict = ?, gatekeeper_memo = ? WHERE alpha_id = ?
         """, [verdict.value, memo, alpha_id])
 
     def update_correlation(self, alpha_id: str, max_corr: float):
+        """Update max correlation to library."""
         self.conn.execute("""
             UPDATE alphas SET max_corr_to_library = ? WHERE alpha_id = ?
         """, [max_corr, alpha_id])
 
     def get_all_themes(self) -> list[str]:
+        """Get themes of all alphas in the store."""
         result = self.conn.execute("SELECT theme FROM alphas WHERE theme IS NOT NULL").fetchall()
         return [r[0] for r in result]
 
     def get_all_anomaly_tags(self) -> list[str]:
+        """Get anomaly tags of all alphas."""
         result = self.conn.execute("SELECT anomaly_tag FROM alphas WHERE anomaly_tag IS NOT NULL").fetchall()
         return [r[0] for r in result]
 
     def get_dead_themes(self) -> list[str]:
+        """Get themes that are in cooldown."""
         result = self.conn.execute("""
             SELECT theme FROM dead_themes WHERE cooldown_until > CURRENT_TIMESTAMP
         """).fetchall()
         return [r[0] for r in result]
 
     def exists(self, alpha_id: str) -> bool:
+        """Check if an alpha already exists (dedup)."""
         result = self.conn.execute("SELECT 1 FROM alphas WHERE alpha_id = ?", [alpha_id]).fetchone()
         return result is not None
 
     def get_expression_hashes(self) -> set[str]:
+        """Get all alpha_ids for dedup."""
         result = self.conn.execute("SELECT alpha_id FROM alphas").fetchall()
         return {r[0] for r in result}
 
     def count_consecutive_kills(self) -> int:
+        """Count consecutive kills from most recent (for kill switch)."""
+        # Use rowid as tiebreaker for deterministic ordering when timestamps are equal
         results = self.conn.execute("""
             SELECT verdict FROM alphas
             ORDER BY submitted_at DESC, rowid DESC
@@ -153,12 +164,14 @@ class FactorStore:
         return count
 
     def kill_theme(self, theme: str, last_sharpe: float, reason: str, cooldown_days: int = 180):
+        """Add a theme to the dead list with cooldown."""
         self.conn.execute("""
             INSERT INTO dead_themes (theme, universe, last_sharpe, reason, cooldown_until)
             VALUES (?, 'TOP3000', ?, ?, CURRENT_TIMESTAMP + INTERVAL ? DAY)
         """, [theme, last_sharpe, reason, cooldown_days])
 
     def get_library_stats(self) -> dict:
+        """Summary statistics for the factor store."""
         total = self.conn.execute("SELECT COUNT(*) FROM alphas").fetchone()[0]
         promoted = self.conn.execute("SELECT COUNT(*) FROM alphas WHERE verdict = 'promote'").fetchone()[0]
         killed = self.conn.execute("SELECT COUNT(*) FROM alphas WHERE verdict = 'kill'").fetchone()[0]