refactor(architecture): ♻️ implement SOLID principles and Strategy Pattern for experts to maximize code clarity and maintainability

Author: Arena AI Agent

epistemic_forge/experts/__init__.py

@@ -1,4 +1,10 @@
-from . import claim_expert, dialectic_expert, freelance_expert, kaggle_expert, writing_expert
+from . import (
+    claim_expert,
+    dialectic_expert,
+    freelance_expert,
+    kaggle_expert,
+    writing_expert,
+)
 
 __all__ = [
     "claim_expert",

epistemic_forge/experts/base.py

@@ -0,0 +1,35 @@
+"""Abstract Interface for Neuro-Symbolic Experts.
+
+This module enforces the Strategy Pattern (SOLID Principles).
+Every expert MUST implement this interface to guarantee uniform execution
+and predictable structured outputs within the L2 Conductor.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+from pydantic import BaseModel
+from epistemic_forge.models import ProjectSpec
+
+
+class EpistemicExpert(ABC):
+    """Base class defining the contract for all cognitive experts."""
+
+    @property
+    @abstractmethod
+    def expert_name(self) -> str:
+        """The formal identifier of the expert (e.g., 'RigorSentinel')."""
+        pass
+
+    @abstractmethod
+    def analyze(self, spec: ProjectSpec, context: Dict[str, Any]) -> BaseModel:
+        """
+        Executes the expert's specific neuro-symbolic logic.
+
+        Args:
+            spec: The user's project specifications and constraints.
+            context: The accumulated epistemic state (prior claims, history).
+
+        Returns:
+            A strictly typed Pydantic BaseModel representing the expert's conclusion.
+        """
+        pass

epistemic_forge/experts/claim_expert.py

@@ -29,7 +29,10 @@ def extract_claims(spec: ProjectSpec, instruction: str) -> Dict[str, Any]:
     support_c = Claim(
         id="C2",
         text=f"Working support: a structured approach to «{title}» improves decision quality under uncertainty.",
-        support=["Decomposition reduces hidden tradeoffs.", "Explicit objections prevent one-sided writing."],
+        support=[
+            "Decomposition reduces hidden tradeoffs.",
+            "Explicit objections prevent one-sided writing.",
+        ],
         objections=["Structure without domain data can become cargo-cult rigor."],
         confidence=Confidence.POSSIBLE,
         tags=["support"],

epistemic_forge/experts/dialectic_expert.py

@@ -1,27 +1,43 @@
-"""L2 Epistemic Synthesis Engine: Hegelian Dialectic."""
+"""Hegelian Synthesis Expert Implementation."""
+
+from typing import Dict, Any
+from pydantic import BaseModel
+
+from epistemic_forge.experts.base import EpistemicExpert
 from epistemic_forge.models import ProjectSpec, HegelianDialecticOutput
 from epistemic_forge.llm import generate_structured
-from typing import Dict, Any
 
-def run_dialectic(spec: ProjectSpec, claims_bundle: Dict[str, Any]) -> Dict[str, Any]:
-    """Execute Hegelian Synthesis to destroy weak assumptions."""
-    thesis = spec.question
-    
-    messages = [
-        {"role": "system", "content": "You are a ruthless Hegelian philosopher and logician. Your goal is to take a premise, construct the most devastating 'Steelman' antithesis possible, and forge a synthesis that represents the nuanced truth."},
-        {"role": "user", "content": f"Core Premise/Thesis: {thesis}\nProject Domain: {spec.domain.value}\nDestroy this premise with logic, then synthesize."}
-    ]
-    
-    # Neuro-Symbolic Call: Forcing GPT to return the strict Hegelian schema
-    result: HegelianDialecticOutput = generate_structured(
-        messages=messages,
-        response_model=HegelianDialecticOutput,
-        model="gpt-4o-mini" # Cost-aware baseline
-    )
-    
-    return {
-        "thesis": thesis,
-        "antithesis": result.steelmanned_antithesis,
-        "synthesis": result.synthesis_resolution,
-        "open_questions": result.remaining_uncertainties,
-    }
+
+class HegelianExpert(EpistemicExpert):
+    """Applies Hegelian dialectic (Thesis -> Antithesis -> Synthesis) to premises."""
+
+    @property
+    def expert_name(self) -> str:
+        return "Hegelian_Dialectic_Engine"
+
+    def analyze(
+        self, spec: ProjectSpec, context: Dict[str, Any]
+    ) -> HegelianDialecticOutput:
+        """Synthesizes the core question by forcing a steelmanned antithesis."""
+        messages = [
+            {
+                "role": "system",
+                "content": (
+                    "You are a ruthless Hegelian philosopher. Take the user's premise, "
+                    "construct the most devastating 'Steelman' antithesis possible, "
+                    "and forge a synthesis that represents the nuanced truth."
+                ),
+            },
+            {
+                "role": "user",
+                "content": f"Core Thesis: {spec.question}\nDomain: {spec.domain}\nDestroy and synthesize.",
+            },
+        ]
+
+        # The universal Hermes router handles the LLM complexity internally
+        return generate_structured(
+            messages=messages,
+            response_model=HegelianDialecticOutput,
+            model=spec.target_model,
+            api_base=spec.api_base,
+        )

epistemic_forge/experts/freelance_expert.py

@@ -7,7 +7,9 @@
 from epistemic_forge.models import ProjectSpec
 
 
-def build_client_pack(spec: ProjectSpec, claims_bundle: Dict[str, Any]) -> Dict[str, Any]:
+def build_client_pack(
+    spec: ProjectSpec, claims_bundle: Dict[str, Any]
+) -> Dict[str, Any]:
     return {
         "client_brief": {
             "goal": spec.question,

epistemic_forge/experts/kaggle_expert.py

@@ -1,29 +1,41 @@
-"""L2 Epistemic Synthesis Engine: Leakage & Rigor Sentinel."""
+"""Data Leakage and Scientific Rigor Expert Implementation."""
+
+from typing import Dict, Any
+from pydantic import BaseModel
+
+from epistemic_forge.experts.base import EpistemicExpert
 from epistemic_forge.models import ProjectSpec, RigorSentinelOutput
 from epistemic_forge.llm import generate_structured
-from typing import Dict, Any
 
-def build_competition_kit(spec: ProjectSpec, claims_bundle: Dict[str, Any], skills: list) -> Dict[str, Any]:
-    """Audit the premise for epistemic blind spots and target leakage."""
-    
-    messages = [
-        {"role": "system", "content": "You are a Grandmaster ML Auditor. Your job is to look at a proposed research or data problem and identify 'target leakage'—where the answer is implicitly baked into the question—and propose strict falsification metrics."},
-        {"role": "user", "content": f"Problem Statement: {spec.question}\nKeywords: {spec.keywords}\nFind the blind spots and establish a robust baseline."}
-    ]
-    
-    # Neuro-Symbolic Call
-    result: RigorSentinelOutput = generate_structured(
-        messages=messages,
-        response_model=RigorSentinelOutput,
-        model="gpt-4o-mini"
-    )
-    
-    return {
-        "checklist": result.epistemic_blind_spots,
-        "metric_alignment": result.falsification_metric,
-        "baseline_architecture": result.robust_baseline,
-        "experiment_log_template": {
-            "status": "Audited by Rigor Sentinel",
-            "notes": "Ensure no data from the future is used."
-        }
-    }
+
+class RigorSentinelExpert(EpistemicExpert):
+    """Audits data science/research premises for methodological flaws and leakage."""
+
+    @property
+    def expert_name(self) -> str:
+        return "Rigor_And_Leakage_Sentinel"
+
+    def analyze(
+        self, spec: ProjectSpec, context: Dict[str, Any]
+    ) -> RigorSentinelOutput:
+        """Identifies target leakage and establishes strict falsification metrics."""
+        messages = [
+            {
+                "role": "system",
+                "content": (
+                    "You are a Grandmaster ML Auditor. Identify 'target leakage' "
+                    "or hidden assumptions in the premise, and propose strict falsification metrics."
+                ),
+            },
+            {
+                "role": "user",
+                "content": f"Problem Statement: {spec.question}\nKeywords: {spec.keywords}\nFind blind spots.",
+            },
+        ]
+
+        return generate_structured(
+            messages=messages,
+            response_model=RigorSentinelOutput,
+            model=spec.target_model,
+            api_base=spec.api_base,
+        )

epistemic_forge/experts/semitic_expert.py

@@ -1,24 +1,32 @@
 """L2 Epistemic Synthesis Engine: Semitic NLP & Arabic Logic Expert."""
+
 from epistemic_forge.models import ProjectSpec, HegelianDialecticOutput
 from epistemic_forge.llm import generate_structured
 from typing import Dict, Any
 
-def run_semitic_dialectic(spec: ProjectSpec, claims_bundle: Dict[str, Any]) -> Dict[str, Any]:
+
+def run_semitic_dialectic(
+    spec: ProjectSpec, claims_bundle: Dict[str, Any]
+) -> Dict[str, Any]:
     """Execute dialectic reasoning specifically optimized for Arabic/Semitic morphological logic."""
     thesis = spec.question
-    
+
     messages = [
-        {"role": "system", "content": "You are a master of Semitic NLP, Arabic logic, and the Scattering Law. Your goal is to analyze the premise in its native Arabic/Semitic context, find morphological or logical blind spots, and synthesize a culturally and logically grounded truth."},
-        {"role": "user", "content": f"الفرضية الأساسية (Thesis): {thesis}\n\nقم بنسف هذه الفرضية بالمنطق السامي/العربي، ثم استخرج الحقيقة المركبة."}
+        {
+            "role": "system",
+            "content": "You are a master of Semitic NLP, Arabic logic, and the Scattering Law. Your goal is to analyze the premise in its native Arabic/Semitic context, find morphological or logical blind spots, and synthesize a culturally and logically grounded truth.",
+        },
+        {
+            "role": "user",
+            "content": f"الفرضية الأساسية (Thesis): {thesis}\n\nقم بنسف هذه الفرضية بالمنطق السامي/العربي، ثم استخرج الحقيقة المركبة.",
+        },
     ]
-    
+
     # Using Claude 3.5 Sonnet or GPT-4o which are great at Arabic logic
     result: HegelianDialecticOutput = generate_structured(
-        messages=messages,
-        response_model=HegelianDialecticOutput,
-        model="gpt-4o" 
+        messages=messages, response_model=HegelianDialecticOutput, model="gpt-4o"
     )
-    
+
     return {
         "thesis": thesis,
         "antithesis_arabic": result.steelmanned_antithesis,

epistemic_forge/experts/writing_expert.py

@@ -1,28 +1,35 @@
 """L2 Epistemic Synthesis Engine: Chain of Density Architect."""
+
 from epistemic_forge.models import ProjectSpec, ChainOfDensityOutput
 from epistemic_forge.llm import generate_structured
 from typing import Dict, Any
 
-def outline_and_draft(spec: ProjectSpec, claims_bundle: Dict[str, Any], instruction: str) -> Dict[str, Any]:
+
+def outline_and_draft(
+    spec: ProjectSpec, claims_bundle: Dict[str, Any], instruction: str
+) -> Dict[str, Any]:
     """Compress the dialectic into a hyper-dense, falsifiable artifact."""
-    
+
     # Gather previous context to compress
-    raw_context = f"Question: {spec.question}\nClaims: {claims_bundle.get('claims', [])}"
-    
+    raw_context = (
+        f"Question: {spec.question}\nClaims: {claims_bundle.get('claims', [])}"
+    )
+
     messages = [
-        {"role": "system", "content": "You are a Chain-of-Density Architect. Your goal is to take raw thoughts and compress them into a highly dense, signal-rich artifact stripped of all rhetorical fluff and confident mush. Every word must carry epistemic weight."},
-        {"role": "user", "content": f"Raw Context:\n{raw_context}\nCompress this."}
+        {
+            "role": "system",
+            "content": "You are a Chain-of-Density Architect. Your goal is to take raw thoughts and compress them into a highly dense, signal-rich artifact stripped of all rhetorical fluff and confident mush. Every word must carry epistemic weight.",
+        },
+        {"role": "user", "content": f"Raw Context:\n{raw_context}\nCompress this."},
     ]
-    
+
     # Neuro-Symbolic Call
     result: ChainOfDensityOutput = generate_structured(
-        messages=messages,
-        response_model=ChainOfDensityOutput,
-        model="gpt-4o-mini"
+        messages=messages, response_model=ChainOfDensityOutput, model="gpt-4o-mini"
     )
-    
+
     return {
         "density_score": result.information_density_score,
         "draft_markdown": f"# Crystallized Artifact\n\n{result.crystallized_claim}\n\n*Density Score: {result.information_density_score}/10*",
-        "outline": ["Crystallized Core"]
+        "outline": ["Crystallized Core"],
     }