incremnt 0.8.7 → 0.8.8

package/src/ask-coach/evidence-plan.js

@@ -0,0 +1,342 @@
+import { classifyAskIntent } from './routing.js';
+import {
+  dateOnlyString,
+  observationExerciseCandidates,
+  relativeDateString,
+  uniqueArray
+} from '../queries.js';
+
+const ASK_FACT_KIND_BY_ROUTE = Object.freeze({
+  general: ['goal_signal', 'preference', 'constraint', 'injury', 'tone'],
+  progress_review: ['goal_signal', 'preference', 'constraint', 'injury', 'tone'],
+  exercise_progress: ['goal_signal', 'injury', 'constraint', 'preference', 'tone'],
+  exercise_progress_summary: ['goal_signal', 'injury', 'constraint', 'preference', 'tone'],
+  program_progress: ['goal_signal', 'preference', 'constraint', 'injury', 'tone'],
+  program_schedule_action: ['goal_signal', 'preference', 'constraint', 'injury', 'tone'],
+  training_profile: ['goal_signal', 'preference', 'constraint', 'injury', 'tone'],
+  program_design: ['goal_signal', 'preference', 'constraint', 'injury', 'tone'],
+  next_session: ['constraint', 'injury', 'preference', 'goal_signal', 'tone'],
+  recent_session: ['injury', 'constraint', 'goal_signal', 'tone'],
+  recovery: ['injury', 'constraint', 'tone'],
+  body_weight: ['goal_signal', 'tone'],
+  volume: ['goal_signal', 'constraint', 'tone'],
+  records: ['goal_signal', 'tone'],
+  score: ['goal_signal', 'constraint', 'tone']
+});
+
+const ASK_ROUTE_REQUIRED_TOOLS = Object.freeze({
+  general: ['get_recent_sessions'],
+  progress_review: ['get_athlete_snapshot', 'get_recent_sessions', 'get_weekly_volume', 'get_records', 'get_body_weight_snapshot', 'get_readiness_snapshot'],
+  volume: ['get_weekly_volume'],
+  next_session: ['get_next_session'],
+  exercise_progress: ['get_exercise_history'],
+  exercise_progress_summary: ['get_exercise_progress_summary'],
+  program_progress: ['get_program_progress', 'get_exercise_progress_summary', 'get_cycle_progression_summary'],
+  program_history: ['get_program_change_history'],
+  program_schedule_action: ['get_program_progress', 'get_recent_sessions', 'get_readiness_snapshot'],
+  training_profile: ['get_training_profile'],
+  records: ['get_records'],
+  recent_session: ['get_recent_sessions'],
+  recovery: ['get_readiness_snapshot', 'get_recent_sessions'],
+  body_weight: ['get_body_weight_snapshot'],
+  score: ['get_increment_score'],
+  program_design: ['get_recent_sessions']
+});
+
+const ASK_OBSERVATION_FOLLOW_UP_INTENTS = new Set(['successor_plan', 'plan_adjustment']);
+
+const ASK_DYNAMIC_EVIDENCE_MAX_TOOLS = 4;
+const ASK_DYNAMIC_EVIDENCE_ROUTES = new Set(['general', 'recovery', 'training_profile']);
+
+const READINESS_OBSERVATION_KINDS = new Set([
+  'recovery_load_spacing_pattern',
+  'health_recovery_drift',
+  'health_recovery_uptrend'
+]);
+
+const BODY_WEIGHT_OBSERVATION_KINDS = new Set([
+  'growth_bodyweight_mismatch',
+  'growth_bodyweight_aligned'
+]);
+
+export function coachFactKindsForAskRoute(route) {
+  return ASK_FACT_KIND_BY_ROUTE[route] ?? ASK_FACT_KIND_BY_ROUTE.general;
+}
+
+export function coachFactKindsForAskQuestion(snapshot, question, options = {}) {
+  const intent = classifyAskIntent(snapshot, question, options);
+  const effectiveRoute = intent.effectiveRoute ?? intent.route ?? 'general';
+  return coachFactKindsForAskRoute(effectiveRoute);
+}
+
+export function requiredToolsForAskRoute(route) {
+  return ASK_ROUTE_REQUIRED_TOOLS[route] ?? ASK_ROUTE_REQUIRED_TOOLS.general;
+}
+
+function askObservationCheckPlan({ exclude = new Set(), route } = {}) {
+  if (exclude.has('coach_observations')) return [];
+  const checks = [
+    {
+      kind: 'current_observations',
+      toolName: 'get_current_coach_observations',
+      status: 'planned'
+    }
+  ];
+  if (route === 'recent_session') {
+    checks.push({
+      kind: 'session_observation_reconciliation',
+      toolName: 'compare_session_to_observations',
+      status: 'conditional',
+      requires: ['current_observations']
+    });
+  }
+  return checks;
+}
+
+export function shouldUseReadinessForObservation(observation) {
+  return READINESS_OBSERVATION_KINDS.has(String(observation?.kind ?? '').trim());
+}
+
+export function shouldUseBodyWeightForObservation(observation) {
+  return BODY_WEIGHT_OBSERVATION_KINDS.has(String(observation?.kind ?? '').trim());
+}
+
+export function askObservationFollowUpRequiredTools(observation) {
+  const tools = ['get_recent_sessions', 'compare_session_to_observations'];
+  const exercises = observationExerciseCandidates(observation);
+  if (exercises.length > 0) tools.push('get_exercise_history');
+  if (shouldUseReadinessForObservation(observation)) tools.push('get_readiness_snapshot');
+  if (shouldUseBodyWeightForObservation(observation)) tools.push('get_body_weight_snapshot');
+  return uniqueArray(tools);
+}
+
+export function normalizeObservationFollowUpIntent(intent) {
+  const normalized = String(intent ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/[\s-]+/g, '_');
+  return ASK_OBSERVATION_FOLLOW_UP_INTENTS.has(normalized) ? normalized : null;
+}
+
+export function observationFollowUpChecks(requiredTools) {
+  return requiredTools.map((toolName) => ({
+    kind: 'observation_followup_verification',
+    toolName,
+    status: 'planned'
+  }));
+}
+
+function askRouteMissingDataFlagsForTool(tool) {
+  if (tool?.toolName === 'get_athlete_snapshot') return [];
+  return tool?.missingDataFlags ?? [];
+}
+
+function evidenceGapsFromTools(tools = []) {
+  return uniqueArray(tools.flatMap(askRouteMissingDataFlagsForTool));
+}
+
+export function immutableArray(values = []) {
+  return Object.freeze([...values]);
+}
+
+export function immutableObservationChecks(checks = []) {
+  return immutableArray(checks.map((check) => Object.freeze({ ...check })));
+}
+
+function executedObservationChecks(plan, tools = []) {
+  const toolByName = new Map(tools.map((tool) => [tool.toolName, tool]));
+  return (plan.observationChecks ?? []).map((check) => {
+    const tool = toolByName.get(check.toolName);
+    if (!tool) return check;
+    const hasEvidence = ['get_current_coach_observations', 'compare_session_to_observations'].includes(check.toolName)
+      ? (tool.rows?.length ?? 0) > 0
+      : (tool.rows?.length ?? 0) > 0 || Object.keys(tool.facts ?? {}).length > 0;
+    return {
+      ...check,
+      status: hasEvidence ? 'executed' : 'no_evidence'
+    };
+  });
+}
+
+export function finalizeEvidencePlan(plan, tools = []) {
+  const required = new Set(plan.requiredTools ?? []);
+  const requiredTools = tools.filter((tool) => required.has(tool.toolName));
+  const dynamic = new Set((plan.dynamicTools ?? []).map((item) => item.toolName));
+  const expansive = new Set((plan.expansiveTools ?? []).map((item) => item.toolName));
+  return {
+    ...plan,
+    requiredTools: immutableArray(plan.requiredTools),
+    optionalTools: immutableArray(plan.optionalTools),
+    dynamicTools: immutableArray(plan.dynamicTools),
+    expansiveTools: immutableArray(plan.expansiveTools ?? []),
+    observationChecks: immutableObservationChecks(executedObservationChecks(plan, tools)),
+    executedTools: immutableArray(uniqueArray(tools.map((tool) => tool.toolName))),
+    executedDynamicTools: immutableArray(uniqueArray(tools
+      .filter((tool) => dynamic.has(tool.toolName))
+      .map((tool) => tool.toolName))),
+    executedExpansiveTools: immutableArray(uniqueArray(tools
+      .filter((tool) => expansive.has(tool.toolName))
+      .map((tool) => tool.toolName))),
+    evidenceGaps: immutableArray(evidenceGapsFromTools(requiredTools))
+  };
+}
+
+function athleteSnapshotExclude(exclude = new Set()) {
+  const mapped = new Set(exclude);
+  if (exclude.has('bodyWeight')) mapped.add('bodyWeight');
+  if (exclude.has('recovery_metrics')) mapped.add('recovery_metrics');
+  return [...mapped];
+}
+
+function planDynamicAskEvidence({ effectiveRoute, question, exclude = new Set(), since = null, today = new Date() } = {}) {
+  if (!ASK_DYNAMIC_EVIDENCE_ROUTES.has(effectiveRoute)) return [];
+  const text = String(question ?? '').toLowerCase();
+  const plans = [];
+  const add = (toolName, section, params, reason) => {
+    if (plans.length >= ASK_DYNAMIC_EVIDENCE_MAX_TOOLS) return;
+    if (plans.some((item) => item.toolName === toolName)) return;
+    plans.push(Object.freeze({ toolName, section, params, reason }));
+  };
+
+  add('get_athlete_snapshot', 'athlete_snapshot', {
+    today,
+    windowDays: since ? 60 : 35,
+    exclude: athleteSnapshotExclude(exclude)
+  }, 'broad_warm_start');
+
+  if (/\b(focus|next|priority|prioritise|prioritize|story|honest|doing|bigger|coaching|read|balance|balanced|volume|muscle|coverage|training)\b/i.test(text)) {
+    add('get_muscle_volume_trend', 'muscle_volume_trend', { today, weeks: 4 }, 'training_balance_or_focus_question');
+  }
+
+  if (/\b(tired|fatigue|recovery|recover|readiness|strain|hard|too much|sick|sleep|hrv|resting)\b/i.test(text)) {
+    add('get_readiness_snapshot', 'readiness', {
+      recentDays: 14,
+      exclude: [...exclude],
+      today
+    }, 'recovery_or_load_question');
+  }
+
+  if (/\b(progress|stronger|strength|moving|stall|stalled|pr|prs|record|records|improve|improving)\b/i.test(text)) {
+    add('get_records', 'records', {
+      exercises: [],
+      limit: 10,
+      recentSince: since ?? relativeDateString(today, -35),
+      today
+    }, 'progress_or_records_question');
+  }
+
+  if (/\b(body ?weight|weight|lean|bulk|cut|scale)\b/i.test(text)) {
+    add('get_body_weight_snapshot', 'body_weight', {
+      recentDays: 30,
+      exclude: [...exclude],
+      today
+    }, 'body_weight_question');
+  }
+
+  return plans;
+}
+
+export function planExpansiveAskEvidence({
+  enabled = false,
+  namedExercises = [],
+  existingSections = [],
+  omitSections = [],
+  exclude = new Set(),
+  today = new Date()
+} = {}) {
+  if (!enabled) return [];
+  const sections = new Set(existingSections);
+  const omitted = new Set(omitSections);
+  const plans = [];
+  const add = (toolName, section, params, reason) => {
+    if (sections.has(section) || omitted.has(section)) return;
+    if (plans.some((item) => item.toolName === toolName)) return;
+    plans.push(Object.freeze({ toolName, section, params, reason }));
+    sections.add(section);
+  };
+
+  add('get_weekly_volume', 'weekly_volume', { today }, 'expansive_profile');
+  add('get_records', 'records', {
+    exercises: namedExercises,
+    limit: namedExercises.length > 0 ? Math.max(5, namedExercises.length) : 10,
+    today
+  }, 'expansive_profile');
+  add('get_body_weight_snapshot', 'body_weight', {
+    recentDays: 30,
+    exclude: [...exclude],
+    today
+  }, 'expansive_profile');
+  add('get_readiness_snapshot', 'readiness', {
+    recentDays: 14,
+    exclude: [...exclude],
+    today
+  }, 'expansive_profile');
+
+  return plans;
+}
+
+export function withExpansiveAskEvidencePlan(plan, expansiveTools = []) {
+  return {
+    ...plan,
+    expansiveTools: immutableArray(expansiveTools),
+    optionalTools: immutableArray(uniqueArray([
+      ...(plan.optionalTools ?? []),
+      ...expansiveTools.map((item) => item.toolName)
+    ]))
+  };
+}
+
+export function planAskEvidence(snapshot, question, {
+  exclude = new Set(),
+  coachObservations = null,
+  history = [],
+  today = new Date()
+} = {}) {
+  const contextSnapshot = Array.isArray(coachObservations)
+    ? { ...snapshot, coachObservations }
+    : snapshot;
+  const intent = classifyAskIntent(contextSnapshot, question, { history, today });
+  const route = intent.route;
+  const namedExerciseItems = intent.entities.exercises;
+  const sessionLabel = intent.entities.sessionLabel ?? null;
+  const sessionReference = intent.entities.sessionReference ?? (sessionLabel ? { label: sessionLabel, setHints: [] } : null);
+  const since = intent.timeframe?.since ?? null;
+  const effectiveRoute = route === 'exercise_progress' && namedExerciseItems.length === 0 ? 'general' : route;
+  const fallbackRoute = effectiveRoute === route ? null : effectiveRoute;
+  const requiredTools = requiredToolsForAskRoute(effectiveRoute);
+  const observationChecks = askObservationCheckPlan({
+    exclude,
+    route: effectiveRoute
+  });
+  const requiredToolSet = new Set(requiredTools);
+  const dynamicTools = planDynamicAskEvidence({
+    effectiveRoute,
+    question,
+    exclude,
+    since,
+    today
+  }).filter((tool) => !requiredToolSet.has(tool.toolName));
+  const optionalTools = uniqueArray([
+    ...dynamicTools.map((item) => item.toolName),
+    ...observationChecks.map((check) => check.toolName)
+  ]);
+
+  return {
+    route,
+    effectiveRoute,
+    fallbackRoute,
+    namedExercises: namedExerciseItems.map((exercise) => exercise.canonical),
+    namedExerciseLabels: namedExerciseItems.map((exercise) => exercise.displayName),
+    sessionLabel,
+    sessionReference,
+    since,
+    intent,
+    requiredTools: immutableArray(requiredTools),
+    optionalTools: immutableArray(optionalTools),
+    dynamicTools: immutableArray(dynamicTools),
+    expansiveTools: immutableArray([]),
+    observationChecks: immutableObservationChecks(observationChecks),
+    evidenceGaps: immutableArray([]),
+    plannedAt: dateOnlyString(today)
+  };
+}

package/src/ask-coach/observations.js

@@ -0,0 +1,8 @@
+export {
+  askMissingObservationFollowUpContext,
+  askObservationFollowUpContext
+} from './orchestrator.js';
+
+export {
+  normalizeObservationFollowUpIntent
+} from './evidence-plan.js';