Implement Why Engine for decision intelligence

- Added WhyEvaluateRequest and WhyEvaluateResponse models for API interaction.
- Created /why/evaluate route to process evaluation requests.
- Integrated WhyEngine into CortexEngine for evaluating source items.
- Developed EvaluationContext and SourceItem classes for structured input.
- Implemented decision-making logic in WhyEngine, including relevance scoring and action recommendations.
- Enhanced FocusEngine to utilize insights and signals for enriched brief generation.
- Added comprehensive unit tests for Why Engine functionality and integration with existing components.

Author: pH-7

cortex_core/api/models.py

@@ -178,3 +178,30 @@ class DigestEvalResponse(BaseModel):
     context_keyword_coverage: float = 0.0
     project_fit_score: float = 0.0
     top_articles: list[ArticleScoreResponse] = Field(default_factory=list)
+
+
+# ── Why Engine ────────────────────────────────────────────────────
+
+
+class WhyEvaluateRequest(BaseModel):
+    """Input for the Why Engine. Swift clients send this."""
+
+    title: str
+    content: str = ""
+    source_type: str = "article"  # article, note, link, digest_item, project_update
+    url: str = ""
+    tags: list[str] = Field(default_factory=list)
+
+
+class WhyEvaluateResponse(BaseModel):
+    """Structured decision output. Swift clients decode this."""
+
+    summary: str = ""
+    why_it_matters: str = ""
+    impact_on_active_project: str = ""
+    contradiction_or_confirmation: str = ""  # supports, contradicts, unclear
+    recommended_action: str = ""
+    ignore_or_watch: str = ""  # act_now, watch, ignore
+    confidence: float = 0.0
+    tags: list[str] = Field(default_factory=list)
+    evaluated_at: str = ""

cortex_core/api/routes/why.py

@@ -0,0 +1,24 @@
+"""
+Why Engine API route
+---------------------
+POST /why/evaluate — evaluate a single source item through the Why Engine.
+
+Thin route. All intelligence lives in cortex_core/why_engine.py.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from cortex_core.api.models import WhyEvaluateRequest, WhyEvaluateResponse
+from cortex_core.api.server import get_engine
+
+router = APIRouter(prefix="/why", tags=["why-engine"])
+
+
+@router.post("/evaluate", response_model=WhyEvaluateResponse)
+async def evaluate_item(request: WhyEvaluateRequest) -> WhyEvaluateResponse:
+    """Evaluate a single source item and return a structured decision."""
+    engine = get_engine()
+    result = engine.evaluate_why(request.model_dump())
+    return WhyEvaluateResponse(**result)

cortex_core/api/server.py

@@ -56,10 +56,11 @@ def create_app() -> FastAPI:
     )
 
     # Register routers
-    from cortex_core.api.routes import context, digest, focus, health, knowledge, pipeline, posts, profile
+    from cortex_core.api.routes import context, digest, focus, health, knowledge, pipeline, posts, profile, why
 
     app.include_router(health.router)
     app.include_router(focus.router)  # primary feature
+    app.include_router(why.router)  # why engine — per-item intelligence
     app.include_router(context.router)  # agent context API
     app.include_router(profile.router)
     app.include_router(knowledge.router)

cortex_core/engine.py

@@ -29,6 +29,7 @@
 from cortex_core.retrieve import HybridRetriever
 from cortex_core.scoring import evaluate_digest
 from cortex_core.signals import SignalStore, detect_signals
+from cortex_core.why_engine import EvaluationContext, SourceItem, WhyEngine
 
 
 class CortexEngine:
@@ -54,6 +55,7 @@ def __init__(self, config: CortexConfig | None = None):
         self.signal_store = SignalStore(self.config.data_dir / "signals.json")
         self.decision_engine = DecisionEngine(self.config.data_dir)
         self.retriever = HybridRetriever()
+        self.why_engine = WhyEngine()
 
     # ------------------------------------------------------ knowledge CRUD
 
@@ -160,11 +162,28 @@ def generate_focus_brief(
         *,
         use_llm: bool = False,
     ) -> dict:
-        """Generate today's focus recommendations."""
+        """Generate today's focus recommendations.
+
+        Passes pre-computed scored articles, insights, and signals into
+        the FocusEngine so the brief reflects the full intelligence chain
+        instead of re-deriving everything from scratch.
+        """
+        # Gather pre-computed enrichment data
+        scored = self._latest_scored_articles() or []
+        insights_data = [i.to_dict() for i in self.insights.recent(20)]
+        signals_data = [s.to_dict() for s in self.signal_store.active_signals()]
+
+        kwargs = dict(
+            use_llm=use_llm,
+            scored_articles=scored if scored else None,
+            insights=insights_data if insights_data else None,
+            signals=signals_data if signals_data else None,
+        )
+
         if digest_path:
-            brief = self.focus.generate_from_file(Path(digest_path), use_llm=use_llm)
+            brief = self.focus.generate_from_file(Path(digest_path), **kwargs)
         else:
-            brief = self.focus.generate_from_latest(self.config.data_dir, use_llm=use_llm)
+            brief = self.focus.generate_from_latest(self.config.data_dir, **kwargs)
         self.focus.save_brief(brief, self.config.data_dir)
         return brief.to_dict()
 
@@ -465,6 +484,56 @@ def get_full_context(self) -> dict:
         """Return complete memory state for agent consumption."""
         return self.memory.full_context()
 
+    # ── Why Engine ──────────────────────────────────────────────
+
+    def evaluate_why(self, item_data: dict) -> dict:
+        """Evaluate a single source item through the Why Engine.
+
+        Assembles full evaluation context from all memory layers and
+        returns a structured DecisionResult.
+        """
+        item = SourceItem.from_dict(item_data)
+        context = self._build_evaluation_context()
+        result = self.why_engine.evaluate(item, context)
+        return result.to_dict()
+
+    def _build_evaluation_context(self) -> EvaluationContext:
+        """Assemble evaluation context from all four memory layers."""
+        profile = self.memory.profile
+
+        # Project layer: milestones, blockers from first active project
+        milestones: list[str] = []
+        blockers: list[str] = []
+        if profile.current_projects:
+            pm = self.memory.get_project(profile.current_projects[0])
+            milestones = [pm.current_milestone] if pm.current_milestone else []
+            blockers = list(pm.active_blockers)
+
+        # Decision history: recent decision descriptions
+        recent_decisions = [
+            d.decision for d in self.decision_engine.recent_decisions(10)
+        ]
+
+        # Research layer: themes
+        recent_themes = list(self.memory.research.recurring_themes)
+
+        # Assumptions: from recent decisions
+        assumptions: list[str] = []
+        for d in self.decision_engine.recent_decisions(5):
+            assumptions.extend(d.assumptions)
+
+        return EvaluationContext(
+            goals=profile.goals,
+            interests=profile.interests,
+            current_projects=profile.current_projects,
+            ignored_topics=profile.ignored_topics,
+            project_milestones=milestones,
+            project_blockers=blockers,
+            recent_decisions=recent_decisions,
+            recent_themes=recent_themes,
+            assumptions=assumptions,
+        )
+
     # ── Internal helpers ────────────────────────────────────────
 
     def _latest_scored_articles(self) -> list: