feat: 🚀 upgrade architecture to SOTA (Pydantic models + Instructor strict JSON schema)

Author: Arena AI Agent

epistemic_forge/llm.py

@@ -1,15 +1,39 @@
-"""Robust LLM Wrapper with Retry Logic and Logging."""
-from litellm import completion
+"""SOTA LLM Engine using Instructor and Pydantic for Strict Structured Outputs."""
+import instructor
+from openai import OpenAI
+from pydantic import BaseModel
 from loguru import logger
 from tenacity import retry, stop_after_attempt, wait_exponential
 
+try:
+    client = instructor.from_openai(OpenAI())
+except Exception as e:
+    logger.warning(f"OpenAI client init failed (missing key?): {e}")
+    client = None
+
 @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2, max=10))
-def call_llm(messages: list, model: str = "gpt-4o-mini", temperature: float = 0.7) -> str:
-    """Call an LLM with automatic retries, fallback, and tracking."""
+def generate_structured(
+    messages: list, 
+    response_model: type[BaseModel], 
+    model: str = "gpt-4o-2024-08-06", 
+    temperature: float = 0.0
+) -> BaseModel:
+    """
+    State-of-the-Art Structured Extraction.
+    Guarantees the output strictly matches the Pydantic schema using JSON Mode / Tool Calls.
+    """
+    if not client:
+        raise ValueError("LLM Client is not initialized. Please set OPENAI_API_KEY.")
+        
     try:
-        logger.debug(f"Initiating neural call to {model}...")
-        response = completion(model=model, messages=messages, temperature=temperature)
-        return response.choices[0].message.content
+        logger.debug(f"Initiating strict structured call to {model} for schema [{response_model.__name__}]...")
+        response = client.chat.completions.create(
+            model=model,
+            messages=messages,
+            response_model=response_model,
+            temperature=temperature,
+        )
+        return response
     except Exception as e:
-        logger.error(f"LLM API Critical Failure: {str(e)}")
+        logger.error(f"SOTA LLM API Critical Failure: {str(e)}")
         raise

epistemic_forge/models.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from dataclasses import asdict, dataclass, field
+from pydantic import BaseModel, Field
 from enum import Enum
 from typing import Any, Dict, List, Optional
 
@@ -23,47 +23,36 @@ class Confidence(str, Enum):
     WEAK = "weak"
 
 
-@dataclass
-class ProjectSpec:
+class ProjectSpec(BaseModel):
     """User-facing project request."""
 
     title: str
     question: str
     domain: Domain = Domain.HYBRID
     audience: str = "technical peer / client"
-    constraints: List[str] = field(default_factory=list)
-    keywords: List[str] = field(default_factory=list)
+    constraints: List[str] = Field(default_factory=list)
+    keywords: List[str] = Field(default_factory=list)
     budget_tokens: int = 8000
     max_trials: int = 3
     enable_opro_style: bool = True
     enable_skills: bool = True
 
-    def to_dict(self) -> Dict[str, Any]:
-        d = asdict(self)
-        d["domain"] = self.domain.value
-        return d
 
 
-@dataclass
-class Claim:
+class Claim(BaseModel):
     """Atomic epistemic unit."""
 
     id: str
     text: str
-    support: List[str] = field(default_factory=list)
-    objections: List[str] = field(default_factory=list)
+    support: List[str] = Field(default_factory=list)
+    objections: List[str] = Field(default_factory=list)
     confidence: Confidence = Confidence.LIKELY
-    sources: List[str] = field(default_factory=list)
-    tags: List[str] = field(default_factory=list)
+    sources: List[str] = Field(default_factory=list)
+    tags: List[str] = Field(default_factory=list)
 
-    def to_dict(self) -> Dict[str, Any]:
-        d = asdict(self)
-        d["confidence"] = self.confidence.value
-        return d
 
 
-@dataclass
-class RouteDecision:
+class RouteDecision(BaseModel):
     """L0 router output."""
 
     families: List[str]
@@ -72,64 +61,49 @@ class RouteDecision:
     l1_mode: str = "ape"  # ape | opro | cascade | off
     l3_mode: str = "tot"  # tot | lats | cascade | off
 
-    def to_dict(self) -> Dict[str, Any]:
-        return asdict(self)
 
 
-@dataclass
-class SearchNode:
+class SearchNode(BaseModel):
     """L3 deliberate-search node."""
 
     id: str
     thought: str
     value: float
     parent_id: Optional[str] = None
-    children: List[str] = field(default_factory=list)
-    meta: Dict[str, Any] = field(default_factory=dict)
+    children: List[str] = Field(default_factory=list)
+    meta: Dict[str, Any] = Field(default_factory=dict)
 
-    def to_dict(self) -> Dict[str, Any]:
-        return asdict(self)
 
 
-@dataclass
-class Reflection:
+class Reflection(BaseModel):
     """L5 verbal memory unit (Reflexion-style)."""
 
     trial: int
     failure_summary: str
     lesson: str
     next_action: str
 
-    def to_dict(self) -> Dict[str, Any]:
-        return asdict(self)
 
 
-@dataclass
-class Skill:
+class Skill(BaseModel):
     """L5 procedural memory unit (Voyager-style)."""
 
     name: str
     description: str
     code: str
-    tags: List[str] = field(default_factory=list)
+    tags: List[str] = Field(default_factory=list)
 
-    def to_dict(self) -> Dict[str, Any]:
-        return asdict(self)
 
 
-@dataclass
-class StageArtifact:
+class StageArtifact(BaseModel):
     name: str
     content: str
     kind: str  # markdown | python | json | notebook-md
     path_hint: str = ""
 
-    def to_dict(self) -> Dict[str, Any]:
-        return asdict(self)
 
 
-@dataclass
-class ForgeResult:
+class ForgeResult(BaseModel):
     """Full pipeline output."""
 
     spec: ProjectSpec
@@ -141,20 +115,6 @@ class ForgeResult:
     skills_used: List[str]
     artifacts: List[StageArtifact]
     peer_review: Dict[str, Any]
-    trial_log: List[Dict[str, Any]] = field(default_factory=list)
+    trial_log: List[Dict[str, Any]] = Field(default_factory=list)
     final_score: float = 0.0
 
-    def to_dict(self) -> Dict[str, Any]:
-        return {
-            "spec": self.spec.to_dict(),
-            "route": self.route.to_dict(),
-            "instruction": self.instruction,
-            "claims": [c.to_dict() for c in self.claims],
-            "search_trace": [n.to_dict() for n in self.search_trace],
-            "reflections": [r.to_dict() for r in self.reflections],
-            "skills_used": self.skills_used,
-            "artifacts": [a.to_dict() for a in self.artifacts],
-            "peer_review": self.peer_review,
-            "trial_log": self.trial_log,
-            "final_score": self.final_score,
-        }

pyproject.toml

@@ -31,7 +31,7 @@ classifiers = [
   "Topic :: Scientific/Engineering :: Artificial Intelligence",
   "Topic :: Text Processing :: Linguistic",
 ]
-dependencies = ["litellm>=1.0.0", "loguru>=0.7.0", "tenacity>=8.0.0"]
+dependencies = ["instructor>=1.3.0", "openai>=1.30.0", "pydantic>=2.0.0", "loguru>=0.7.0", "tenacity>=8.0.0"]
 
 [project.optional-dependencies]
 dev = ["pytest>=7.0"]