Add backend coaching agent integration

.env.example

@@ -4,6 +4,9 @@ NODE_ENV=development
 FRONTEND_URL=http://localhost:8080
 BACKEND_URL=http://localhost:4000
 ANALYSIS_PROXY_SECRET=replace-with-a-random-secret-of-at-least-32-characters
+# Deploy the stateless Agent service separately and use its private URL/key here.
+AGENT_API_URL=https://your-agent-service.example.com
+AGENT_API_KEY=replace-with-the-Agent-service-secret
 # Optional: use the same random secret in the Colab notebook to register its worker.
 # COLAB_WORKER_SECRET=replace-with-a-different-random-secret-of-at-least-32-characters
 SUPABASE_URL=https://your-project.supabase.co

src/agent-session.ts

@@ -0,0 +1,96 @@
+import type { SupabaseClient } from "@supabase/supabase-js";
+import { env } from "./config.js";
+
+type ActionResult = { id: string; label: string; rawAnalytics?: Record<string, unknown>; inActionMetrics?: { name: string; value: unknown; unit?: string }[] };
+type SessionResult = { id: string; playerId: string; actions: ActionResult[] };
+
+function ageContext(profile: Record<string, unknown>) {
+  const value = profile.bdate;
+  if (typeof value !== "string") return profile;
+  const birth = new Date(`${value.slice(0, 10)}T00:00:00Z`);
+  if (Number.isNaN(birth.getTime())) return profile;
+  const now = new Date();
+  let age = now.getUTCFullYear() - birth.getUTCFullYear();
+  if (now.getUTCMonth() < birth.getUTCMonth() || (now.getUTCMonth() === birth.getUTCMonth() && now.getUTCDate() < birth.getUTCDate())) age--;
+  return { ...profile, ageYears: age };
+}
+
+async function analysisResults(sessionId: string, userId: string): Promise<SessionResult> {
+  const response = await fetch(new URL(`/api/sessions/${sessionId}`, env.ANALYSIS_API_URL), {
+    headers: { "x-sporalize-proxy-secret": env.ANALYSIS_PROXY_SECRET, "x-sporalize-user-id": userId },
+    signal: AbortSignal.timeout(120000),
+  });
+  if (!response.ok) throw new Error(`Unable to load results for session ${sessionId} (${response.status})`);
+  return await response.json() as SessionResult;
+}
+
+export async function generateSessionFeedback(db: SupabaseClient, sessionId: string, userId: string) {
+  if (!env.AGENT_API_URL || !env.AGENT_API_KEY) throw new Error("Agent service is not configured");
+  const { data: session, error: sessionError } = await db.from("sessions")
+    .select("session_id,player_id,players(player_id,bdate,height,weight,position,gender)")
+    .eq("session_id", sessionId).eq("user_id", userId).maybeSingle();
+  if (sessionError || !session) throw new Error(`Unable to load completed session context: ${sessionError?.message ?? "session missing"}`);
+  const rawPlayer = Array.isArray(session.players) ? session.players[0] : session.players;
+  const player = rawPlayer ? ageContext(rawPlayer as Record<string, unknown>) : rawPlayer;
+  if (!player) throw new Error("Session player context is missing");
+  const result = await analysisResults(sessionId, userId);
+  const actionResults = new Map(result.actions.map((action) => [action.id, action]));
+  const { data: currentActions, error: actionsError } = await db.from("actions")
+    .select("action_id,type").eq("session_id", sessionId);
+  if (actionsError) throw new Error(`Unable to load completed actions: ${actionsError.message}`);
+
+  const actions = [];
+  for (const action of currentActions ?? []) {
+    const current = actionResults.get(action.action_id);
+    if (!current) continue;
+    const { data: examples, error: examplesError } = await db.from("annotations")
+      .select("action_id,score,annotations_notes(note),actions!inner(action_id,session_id,type,sessions!inner(player_id,players!inner(gender,bdate,height,weight,position)))")
+      .eq("actions.type", action.type)
+      .eq("actions.sessions.players.gender", player.gender)
+      .neq("action_id", action.action_id)
+      .limit(10);
+    if (examplesError) throw new Error(`Unable to load human annotations: ${examplesError.message}`);
+    const referenceRows = (examples ?? []).filter((row: any) =>
+      row.score !== null || (row.annotations_notes ?? []).some((note: { note: string }) => typeof note.note === "string" && note.note.trim().length > 0));
+    const referenceSessionIds = [...new Set(referenceRows.map((row: any) => row.actions?.session_id).filter(Boolean))] as string[];
+    const referenceResults = new Map<string, SessionResult>();
+    await Promise.all(referenceSessionIds.map(async (id) => {
+      try { referenceResults.set(id, await analysisResults(id, userId)); }
+      catch (error) { console.warn("Skipping unavailable annotation reference results", { sessionId: id, error }); }
+    }));
+    const references = referenceRows.flatMap((row: any) => {
+      const related = Array.isArray(row.actions) ? row.actions[0] : row.actions;
+      const refPlayerValue = related?.sessions?.players;
+      const refPlayer = refPlayerValue ? ageContext(refPlayerValue as Record<string, unknown>) : refPlayerValue;
+      const refSession = related?.session_id ? referenceResults.get(related.session_id) : undefined;
+      const refAction = refSession?.actions.find((item) => item.id === row.action_id);
+      if (!related || !refPlayer || !refAction) return [];
+      return [{ action_id: row.action_id, action_type: related.type, player: refPlayer,
+        results: { metrics: refAction.inActionMetrics ?? [], analytics: refAction.rawAnalytics ?? {} },
+        score: row.score, notes: (row.annotations_notes ?? []).map((note: { note: string }) => note.note) }];
+    });
+    actions.push({ action_id: action.action_id, action_type: action.type,
+      results: { metrics: current.inActionMetrics ?? [], analytics: current.rawAnalytics ?? {} }, references });
+  }
+  if (!actions.length) return;
+  const response = await fetch(new URL("/api/session/generate", env.AGENT_API_URL), {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-api-key": env.AGENT_API_KEY, "x-user-id": userId },
+    body: JSON.stringify({ session_id: sessionId, player, actions }),
+    signal: AbortSignal.timeout(150000),
+  });
+  const payload = await response.json().catch(() => ({})) as { actions?: { action_id: string; feedback: string[] }[]; session_feedback?: string[]; detail?: string };
+  if (!response.ok || !payload.actions || !payload.session_feedback) throw new Error(payload.detail ?? `Agent generation failed (${response.status})`);
+  for (const item of payload.actions) {
+    const { error } = await db.from("actions_feedbacks").delete().eq("action_id", item.action_id);
+    if (error) throw new Error(`Unable to replace generated action feedback: ${error.message}`);
+    if (item.feedback.length) {
+      const inserted = await db.from("actions_feedbacks").insert(item.feedback.map((feedback) => ({ action_id: item.action_id, feedback })));
+      if (inserted.error) throw new Error(`Unable to save generated action feedback: ${inserted.error.message}`);
+    }
+  }
+  const { error: clearError } = await db.from("sessions_feedbacks").delete().eq("session_id", sessionId);
+  if (clearError) throw new Error(`Unable to replace generated session feedback: ${clearError.message}`);
+  const { error: saveError } = await db.from("sessions_feedbacks").insert(payload.session_feedback.map((feedback) => ({ session_id: sessionId, feedback })));
+  if (saveError) throw new Error(`Unable to save generated session feedback: ${saveError.message}`);
+}

src/analysis.ts

@@ -30,7 +30,7 @@ export function actionRows(sessionId: string, reports: z.infer<typeof reportSche
   });
 }
 
-export function analysisRouter(db: SupabaseClient, secret: string) {
+export function analysisRouter(db: SupabaseClient, secret: string, onCompleted?: (sessionId: string, userId: string) => Promise<void>) {
   const router = express.Router();
   router.use((req, res, next) => {
     const supplied = Buffer.from(req.header("x-sporalize-proxy-secret") ?? "");
@@ -189,6 +189,7 @@ export function analysisRouter(db: SupabaseClient, secret: string) {
             const { error } = await db.from("actions").upsert(rows, { onConflict: "action_id" });
             if (error) return res.status(503).json({ error: "Unable to save analysis actions." });
           }
+          if (onCompleted) void onCompleted(sessionId, res.locals.userId as string).catch((error) => console.error("Automatic Agent feedback generation failed", { sessionId, error }));
         }
         return res.json({ ok: true });
       }
@@ -200,6 +201,9 @@ export function analysisRouter(db: SupabaseClient, secret: string) {
         console.error("Unable to save analysis results", { code: error.code, message: error.message });
         return res.status(error.code === "P0001" ? 409 : 503).json({ error: "Unable to save analysis" });
       }
+      if (input.status === "completed" && onCompleted) {
+        void onCompleted(sessionId, res.locals.userId as string).catch((generationError) => console.error("Automatic Agent feedback generation failed", { sessionId, generationError }));
+      }
       return res.json({ ok: true });
     } catch (error) { next(error); }
   });

src/config.ts

@@ -8,6 +8,8 @@ const envSchema = z.object({
   FRONTEND_URL: z.string().url(),
   BACKEND_URL: z.string().url(),
   ANALYSIS_API_URL: z.string().url().default("http://127.0.0.1:8000"),
+  AGENT_API_URL: z.string().url().optional(),
+  AGENT_API_KEY: z.string().min(16).optional(),
   ANALYSIS_PROXY_SECRET: z.string().min(32),
   COLAB_WORKER_SECRET: z.string().optional(),
   SUPABASE_URL: z.string().url(),

src/server.ts

@@ -9,6 +9,7 @@ import { pipeline } from "node:stream/promises";
 import { z } from "zod";
 import { authPublicOrigin, env } from "./config.js";
 import { analysisRouter } from "./analysis.js";
+import { generateSessionFeedback } from "./agent-session.js";
 import { authenticatedUser, clearPasswordRecoveryCookie, clearSessionCookies, hasPasswordRecoveryCookie, safeRedirect, setPasswordRecoveryCookie, setSessionCookies } from "./auth.js";
 import { hashPassword, oauthClient, supabaseAdmin, supabaseAuth, syncProfile, userHasPassword, userPayload } from "./supabase.js";
 import { registerProfileImageRoutes } from "./profile-images.js";
@@ -24,7 +25,8 @@ app.use(cors({
   credentials: true,
   methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
 }));
-app.use("/internal/analysis", analysisRouter(supabaseAdmin, env.ANALYSIS_PROXY_SECRET));
+app.use("/internal/analysis", analysisRouter(supabaseAdmin, env.ANALYSIS_PROXY_SECRET,
+  (sessionId, userId) => generateSessionFeedback(supabaseAdmin, sessionId, userId)));
 app.use(express.json({ limit: "32kb", type: ["application/json", "text/plain"] }));
 app.use("/internal/colab-worker", colabWorkerRouter(env.ANALYSIS_PROXY_SECRET, env.COLAB_WORKER_SECRET));
 app.use(cookieParser());
@@ -735,6 +737,70 @@ app.get("/api/sessions/:sessionId/feedbacks", async (req, res, next) => {
   } catch (error) { next(error); }
 });
 
+app.post("/api/agent/chat", async (req, res, next) => {
+  try {
+    const current = await authenticatedUser(req, res);
+    if (!current) return res.status(401).json({ error: "Authentication required." });
+    if (!env.AGENT_API_URL || !env.AGENT_API_KEY) {
+      return res.status(503).json({ error: "The coaching Agent is not configured." });
+    }
+    const input = z.object({
+      message: z.string().trim().min(1).max(6000),
+      history: z.array(z.object({ role: z.enum(["user", "assistant"]), content: z.string().min(1).max(6000) })).max(30).default([]),
+      sessionId: z.uuid().optional(), actionId: z.uuid().optional(), playerId: z.uuid().optional(),
+    }).strict().parse(req.body);
+    if (input.actionId && !input.sessionId) return res.status(400).json({ error: "A session is required for action context." });
+    const context: Record<string, unknown> = {};
+    if (input.sessionId) {
+      const { data: session, error } = await supabaseAdmin.from("sessions")
+        .select("session_id,user_id,name,player_id,players(fname,lname,bdate,gender,position,height,weight)")
+        .eq("session_id", input.sessionId).maybeSingle();
+      if (error) throw new Error(`Unable to verify chat session: ${error.message}`);
+      if (!session) return res.sendStatus(404);
+      if (session.user_id !== current.user.id && !await userIsAdmin(current.user.id) && !await activeSubscriptionFor(current.user.id, { refresh: true })) {
+        return res.status(403).json({ error: "An active subscription is required to discuss shared sessions.", code: "subscription_required" });
+      }
+      context.session = { name: session.name, player: session.players };
+      const { data: sessionFeedback, error: sessionFeedbackError } = await supabaseAdmin.from("sessions_feedbacks")
+        .select("feedback").eq("session_id", input.sessionId).order("feedback");
+      if (sessionFeedbackError) throw new Error(`Unable to load chat feedback: ${sessionFeedbackError.message}`);
+      context.sessionFeedback = (sessionFeedback ?? []).map((row) => row.feedback);
+      if (!input.actionId) {
+        const { data: sessionActions, error: sessionActionsError } = await supabaseAdmin.from("actions")
+          .select("action_id,type,start_frame,end_frame,actions_feedbacks(feedback),annotations(score,annotations_notes(note))")
+          .eq("session_id", input.sessionId).limit(30);
+        if (sessionActionsError) throw new Error(`Unable to load session action context: ${sessionActionsError.message}`);
+        context.actions = sessionActions ?? [];
+      }
+      if (input.actionId) {
+        const { data: action, error: actionError } = await supabaseAdmin.from("actions")
+          .select("action_id,type,start_frame,end_frame,annotations(score,annotations_notes(note))").eq("session_id", input.sessionId).eq("action_id", input.actionId).maybeSingle();
+        if (actionError) throw new Error(`Unable to verify chat action: ${actionError.message}`);
+        if (!action) return res.sendStatus(404);
+        const { data: feedback, error: feedbackError } = await supabaseAdmin.from("actions_feedbacks")
+          .select("feedback").eq("action_id", input.actionId).order("feedback");
+        if (feedbackError) throw new Error(`Unable to load chat feedback: ${feedbackError.message}`);
+        context.action = { ...action, feedback: (feedback ?? []).map((row) => row.feedback) };
+      }
+    }
+    if (input.playerId && !input.sessionId) {
+      const { data: player, error } = await supabaseAdmin.from("players")
+        .select("fname,lname,bdate,height,weight,position,gender").eq("player_id", input.playerId).maybeSingle();
+      if (error) throw new Error(`Unable to load chat player context: ${error.message}`);
+      if (!player) return res.sendStatus(404);
+      context.player = player;
+    }
+    const upstream = await fetch(new URL("/api/chat", env.AGENT_API_URL), {
+      method: "POST", headers: { "content-type": "application/json", "x-api-key": env.AGENT_API_KEY, "x-user-id": current.user.id },
+      body: JSON.stringify({ actions: [], context, message: input.message, history: input.history }),
+      signal: AbortSignal.timeout(95000),
+    });
+    const result = await upstream.json().catch(() => ({}));
+    if (!upstream.ok) return res.status(upstream.status).json({ error: typeof result.detail === "string" ? result.detail : "The coaching Agent could not answer." });
+    return res.json(result);
+  } catch (error) { next(error); }
+});
+
 app.put("/api/sessions/:sessionId/actions/:actionId/review", async (req, res, next) => {
   try {
     const current = await requireActiveSubscription(req, res);