feat: Claude AI intelligence layer — real reasoning on every dashboard element

Architecture: Anthropic SDK (claude-sonnet-4-6) wired into the dashboard
as a server-side intelligence layer. Every piece of text the user sees
can be AI-interpreted — not templates, real Claude reasoning.

AI endpoints:
- POST /api/ai/interpret — explain proposals, positions, approval reasoning
- POST /api/ai/chat — real conversational AI with full portfolio context
- POST /api/ai/screenshot — Claude vision extracts holdings from broker screenshots

Briefing API upgraded:
- Headline generated by Claude (personalized to portfolio state + market)
- Proposal context generated by Claude (personalized risk/reward explanation)
- Graceful fallback to templates when Claude API is unavailable

Dashboard upgrades:
- Real AI chat panel (replaces fake keyword matcher)
  "Why these stocks?" → Claude answers with your specific portfolio context
- Quick-question buttons that auto-send to Claude
- "Claude is thinking..." indicator
- "Powered by Claude" label for transparency

Cost: ~$0.01-0.03 per AI call (Sonnet). ~$0.10 per full page load.
Note: Current API key has hit workspace limit (resets Apr 1).
Fallback templates work seamlessly when Claude API is unavailable.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: wjlgatech

apps/screener-api/app/api/ai/chat/route.ts

@@ -0,0 +1,37 @@
+import { NextRequest } from "next/server";
+import { validateRequest } from "@/lib/auth";
+import { apiSuccess, apiError } from "@/lib/errors";
+import { answerQuestion } from "@/lib/ai/claude";
+
+/**
+ * POST /api/ai/chat — Real AI chat with portfolio context
+ *
+ * Not a fake keyword matcher. Real Claude reasoning about the user's
+ * specific portfolio, positions, and market situation.
+ */
+export async function POST(req: NextRequest) {
+  const authErr = validateRequest(req);
+  if (authErr) return authErr;
+
+  try {
+    const body = await req.json();
+    const { question, context } = body;
+
+    if (!question || typeof question !== "string") {
+      return apiError("question is required", 400);
+    }
+
+    const answer = await answerQuestion(question, context ?? {
+      portfolioEquity: 0,
+      positions: [],
+      pendingApprovals: [],
+      regime: "unknown",
+      vix: 0,
+      userLevel: "beginner",
+    });
+
+    return apiSuccess({ answer });
+  } catch (err) {
+    return apiError("AI chat failed", 500);
+  }
+}

apps/screener-api/app/api/ai/interpret/route.ts

@@ -0,0 +1,39 @@
+import { NextRequest } from "next/server";
+import { validateRequest } from "@/lib/auth";
+import { apiSuccess, apiError } from "@/lib/errors";
+import { explainProposal, explainPosition, generateApprovalReasoning } from "@/lib/ai/claude";
+
+/**
+ * POST /api/ai/interpret — AI interprets a specific element
+ *
+ * Called when user clicks on a stock, position, or proposal.
+ * Returns real Claude reasoning, not templates.
+ */
+export async function POST(req: NextRequest) {
+  const authErr = validateRequest(req);
+  if (authErr) return authErr;
+
+  try {
+    const body = await req.json();
+    const { type, context } = body;
+
+    if (type === "proposal") {
+      const interpretation = await explainProposal(context);
+      return apiSuccess({ interpretation });
+    }
+
+    if (type === "position") {
+      const interpretation = await explainPosition(context);
+      return apiSuccess({ interpretation });
+    }
+
+    if (type === "approval_reasoning") {
+      const reasoning = await generateApprovalReasoning(context);
+      return apiSuccess({ reasoning });
+    }
+
+    return apiError("Unknown type. Use: proposal, position, approval_reasoning", 400);
+  } catch (err) {
+    return apiError("AI interpretation failed", 500);
+  }
+}

apps/screener-api/app/api/ai/screenshot/route.ts

@@ -0,0 +1,43 @@
+import { NextRequest } from "next/server";
+import { validateRequest } from "@/lib/auth";
+import { apiSuccess, apiError } from "@/lib/errors";
+import { extractPortfolioFromImage } from "@/lib/ai/claude";
+
+/**
+ * POST /api/ai/screenshot — Extract portfolio from broker screenshot
+ *
+ * User drops/uploads an image of their broker's positions page.
+ * Claude vision reads it and extracts all holdings.
+ */
+export async function POST(req: NextRequest) {
+  const authErr = validateRequest(req);
+  if (authErr) return authErr;
+
+  try {
+    const body = await req.json();
+    const { image, mimeType } = body;
+
+    if (!image || typeof image !== "string") {
+      return apiError("image (base64) is required", 400);
+    }
+
+    const result = await extractPortfolioFromImage(image, mimeType ?? "image/png");
+
+    // Try to parse as JSON
+    let holdings: unknown[] = [];
+    try {
+      const jsonMatch = result.match(/\[[\s\S]*\]/);
+      if (jsonMatch) {
+        holdings = JSON.parse(jsonMatch[0]);
+      }
+    } catch { /* Claude returned non-JSON, return raw text */ }
+
+    return apiSuccess({
+      holdings,
+      raw: result,
+      message: `Extracted ${holdings.length} position${holdings.length !== 1 ? "s" : ""} from screenshot`,
+    });
+  } catch (err) {
+    return apiError("Screenshot extraction failed", 500);
+  }
+}

apps/screener-api/app/api/briefing/route.ts

@@ -4,6 +4,7 @@ import { apiSuccess, apiError } from "@/lib/errors";
 import { config } from "@/lib/config";
 import { MoneyAgent } from "@/lib/agent/core";
 import { TradeExecutor } from "@/lib/broker/executor";
+import { generateBriefing, explainProposal as aiExplainProposal } from "@/lib/ai/claude";
 
 export async function GET(req: NextRequest) {
   const authErr = validateRequest(req);
@@ -55,16 +56,26 @@ export async function GET(req: NextRequest) {
 
     const pendingCount = report?.pendingApprovals?.length ?? 0;
 
-    // Headline
+    // Headline — real Claude AI generates the briefing
     let headline: string;
-    if (portfolio.positions.length > 0 && pendingCount > 0) {
-      headline = `${greeting}. You have ${portfolio.positions.length} open position${portfolio.positions.length > 1 ? "s" : ""} and ${pendingCount} new opportunit${pendingCount > 1 ? "ies" : "y"} to review.`;
-    } else if (pendingCount > 0) {
-      headline = `${greeting}. I found ${pendingCount} opportunit${pendingCount > 1 ? "ies" : "y"} for you to review.`;
-    } else if (portfolio.positions.length > 0) {
-      headline = `${greeting}. Your ${portfolio.positions.length} position${portfolio.positions.length > 1 ? "s are" : " is"} open. No new opportunities today.`;
-    } else {
-      headline = `${greeting}. Markets are quiet. No actions taken, no new opportunities.`;
+    try {
+      headline = await generateBriefing({
+        positions: positionsWithContext.map((p) => ({ symbol: p.symbol, pnlPct: p.pnlPct, value: p.posValue })),
+        pendingCount,
+        watchCount: report?.watching?.length ?? 0,
+        regime: report?.market?.regime?.regime ?? "unknown",
+        vix: report?.market?.vix ?? 0,
+        recentActions: actionsSummary,
+        totalEquity: portfolioValue,
+        totalPnl: portfolioValue - config.initialCapital,
+      });
+      if (!headline) throw new Error("empty");
+    } catch {
+      // Fallback to template if Claude API fails
+      const greeting = new Date().getHours() < 12 ? "Good morning" : new Date().getHours() < 17 ? "Good afternoon" : "Good evening";
+      headline = portfolio.positions.length > 0
+        ? `${greeting}. ${portfolio.positions.length} positions open${pendingCount > 0 ? `, ${pendingCount} new opportunities to review` : ""}.`
+        : `${greeting}. ${pendingCount > 0 ? `${pendingCount} opportunities to review.` : "Markets are quiet."}`;
     }
 
     // Selection funnel (transparency)
@@ -89,10 +100,32 @@ export async function GET(req: NextRequest) {
         headline: "No market data yet. Run: npx tsx scripts/run-pipeline.ts",
       },
       actions: actionsSummary,
-      pendingApprovals: (report?.pendingApprovals ?? []).map((p) => ({
-        ...p,
-        aiContext: generateProposalContext(p, portfolioValue),
-      })),
+      pendingApprovals: await Promise.all(
+        (report?.pendingApprovals ?? []).map(async (p) => {
+          // Try real Claude AI interpretation, fall back to template
+          let aiContext: string;
+          try {
+            aiContext = await aiExplainProposal({
+              ticker: p.ticker,
+              shares: p.shares,
+              price: p.price,
+              stopLoss: p.stopLoss,
+              takeProfit: p.takeProfit,
+              signals: p.signals,
+              reason: p.reason,
+              portfolioEquity: portfolioValue,
+              existingPositions: portfolio.positions.map((pos) => pos.symbol),
+              regime: report?.market?.regime?.regime ?? "unknown",
+              vix: report?.market?.vix ?? 20,
+              userLevel: "intermediate",
+            });
+            if (!aiContext) throw new Error("empty");
+          } catch {
+            aiContext = generateProposalContext(p, portfolioValue);
+          }
+          return { ...p, aiContext };
+        })
+      ),
       watching: report?.watching ?? [],
       portfolio: {
         equity: portfolio.equity,

apps/screener-api/app/dashboard/page.tsx

@@ -380,26 +380,8 @@ export default function DashboardV2() {
             </div>
           </div>
 
-          {/* Quick Actions — replaces fake chat */}
-          <div style={{ flex: 1, padding: "16px 16px" }}>
-            <div style={sectionTitle}>QUICK ACTIONS</div>
-            <div style={{ color: "#52525b", fontSize: 11, marginTop: 6, marginBottom: 10 }}>
-              Open Claude and say any of these:
-            </div>
-            {[
-              { cmd: "/invest", desc: "GPS — say your goal, get a step-by-step plan" },
-              { cmd: "/screen", desc: "Scan for stocks near support/resistance" },
-              { cmd: "/strategy-lab", desc: "Test a trading idea from YouTube or a blog" },
-              { cmd: "/import-portfolio", desc: "Share a screenshot of your broker holdings" },
-              { cmd: "/signals", desc: "See today's technical signals" },
-              { cmd: "/macro-check", desc: "Market risk assessment" },
-            ].map((a) => (
-              <div key={a.cmd} style={{ padding: "6px 0", borderTop: "1px solid #1e1e2e" }}>
-                <span style={{ color: "#3b82f6", fontFamily: "monospace", fontSize: 12 }}>{a.cmd}</span>
-                <div style={{ color: "#6b7280", fontSize: 11 }}>{a.desc}</div>
-              </div>
-            ))}
-          </div>
+          {/* AI Chat — real Claude, not simulation */}
+          <AIChatPanel briefing={b} />
         </div>
       </div>
     </div>
@@ -453,3 +435,102 @@ const btnStyle: React.CSSProperties = {
   background: "#1e1e2e", border: "1px solid #2e2e3e", color: "#a1a1aa",
   padding: "5px 12px", borderRadius: 5, cursor: "pointer", fontSize: 11,
 };
+
+// ── AI Chat Panel (real Claude, not simulation) ──────────────
+
+function AIChatPanel({ briefing }: { briefing: Briefing | null }) {
+  const [messages, setMessages] = useState<Array<{ role: "user" | "ai"; text: string }>>([]);
+  const [input, setInput] = useState("");
+  const [thinking, setThinking] = useState(false);
+
+  const send = async (text?: string) => {
+    const question = text ?? input.trim();
+    if (!question) return;
+    setInput("");
+    setMessages((prev) => [...prev, { role: "user", text: question }]);
+    setThinking(true);
+
+    try {
+      const res = await fetch("/api/ai/chat", {
+        method: "POST",
+        headers: { ...authHeaders, "Content-Type": "application/json" },
+        body: JSON.stringify({
+          question,
+          context: {
+            portfolioEquity: briefing?.portfolio?.portfolioValue ?? 0,
+            positions: briefing?.portfolio?.positions?.map((p) => ({ symbol: p.symbol, pnlPct: p.pnlPct })) ?? [],
+            pendingApprovals: briefing?.pendingApprovals?.map((p) => ({ ticker: p.ticker, reason: p.reason })) ?? [],
+            regime: briefing?.market?.regime?.regime ?? "unknown",
+            vix: briefing?.market?.vix ?? 0,
+            userLevel: "intermediate",
+          },
+        }),
+      });
+      const data = await res.json();
+      setMessages((prev) => [...prev, { role: "ai", text: data.answer ?? data.error ?? "No response" }]);
+    } catch {
+      setMessages((prev) => [...prev, { role: "ai", text: "Failed to reach AI. Check that the server is running." }]);
+    }
+    setThinking(false);
+  };
+
+  return (
+    <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
+      <div style={{ padding: "12px 16px", borderBottom: "1px solid #1e1e2e" }}>
+        <div style={sectionTitle}>ASK AI</div>
+        <div style={{ color: "#52525b", fontSize: 10, marginTop: 4 }}>Powered by Claude — real reasoning about YOUR portfolio</div>
+      </div>
+
+      <div style={{ flex: 1, overflowY: "auto", padding: "8px 12px", minHeight: 120 }}>
+        {messages.length === 0 && (
+          <div style={{ color: "#3f3f46", fontSize: 11, textAlign: "center", marginTop: 16, lineHeight: 1.6 }}>
+            Ask anything about your portfolio, the market, or a specific stock.
+          </div>
+        )}
+        {messages.map((m, i) => (
+          <div key={i} style={{
+            padding: "8px 12px", marginTop: 6, borderRadius: 8, fontSize: 12, lineHeight: 1.6,
+            background: m.role === "user" ? "#1e3a5f" : "#111119",
+            color: m.role === "user" ? "#93c5fd" : "#d4d4d8",
+            marginLeft: m.role === "user" ? 30 : 0,
+            marginRight: m.role === "ai" ? 10 : 0,
+          }}>
+            {m.text}
+          </div>
+        ))}
+        {thinking && (
+          <div style={{ padding: "8px 12px", marginTop: 6, color: "#6b7280", fontSize: 11, fontStyle: "italic" }}>
+            Claude is thinking...
+          </div>
+        )}
+      </div>
+
+      {/* Quick questions */}
+      <div style={{ display: "flex", gap: 4, padding: "4px 12px", flexWrap: "wrap" }}>
+        {["Why these stocks?", "What's my risk?", "Should I approve?", "Market outlook"].map((q) => (
+          <button key={q} onClick={() => send(q)} style={{
+            background: "none", border: "1px solid #2e2e3e", color: "#6b7280",
+            padding: "4px 8px", borderRadius: 4, cursor: "pointer", fontSize: 10,
+          }}>{q}</button>
+        ))}
+      </div>
+
+      {/* Input */}
+      <div style={{ display: "flex", gap: 6, padding: "8px 12px" }}>
+        <input
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          onKeyDown={(e) => e.key === "Enter" && send()}
+          placeholder="Ask anything..."
+          style={{
+            flex: 1, background: "#111119", border: "1px solid #2e2e3e", color: "#e2e8f0",
+            padding: "8px 12px", borderRadius: 6, fontSize: 12, outline: "none",
+          }}
+        />
+        <button onClick={() => send()} disabled={thinking} style={{ ...btnStyle, background: "#3b82f6", color: "#fff" }}>
+          {thinking ? "..." : "Ask"}
+        </button>
+      </div>
+    </div>
+  );
+}