reflex-agent 0.3.0 → 0.3.3

package/packages/utilities/learn-anything/actions/generateOutline.ts

@@ -1,170 +0,0 @@
-import { reflex } from "@host/api";
-import type { TutorQA } from "./tutorAsk";
-import { callJsonAgent, snippet } from "./_json";
-import { writeCourse } from "./_store";
-
-/**
- * Build a course outline based on topic + wizard answers. Returns a
- * list of 5-9 modules each with a short title, a 1-sentence objective,
- * and an estimated duration. The course record is persisted as a KB
- * entry of kind="course"; subsequent buildModule calls hang content
- * off it module-by-module.
- */
-
-export interface OutlineModule {
-  id: string;
-  title: string;
-  objective: string;
-  estMinutes: number;
-}
-
-export interface GenerateOutlineArgs {
-  topic: string;
-  history: TutorQA[];
-}
-
-export interface CourseRecord {
-  courseId: string;
-  topic: string;
-  modules: OutlineModule[];
-  relPath: string;
-  createdAt: string;
-}
-
-export default async function generateOutline(
-  args: GenerateOutlineArgs,
-): Promise<CourseRecord> {
-  const prior = args.history
-    .map((qa) => `Q: ${qa.question}\nA: ${qa.answer}`)
-    .join("\n\n");
-  const prompt = [
-    "Design a learning course on the topic \"${TOPIC}\" tailored to a user with the following answers:".replace(
-      "${TOPIC}",
-      args.topic,
-    ),
-    "",
-    prior || "(no answers)",
-    "",
-    "Requirements:",
-    "  • 5-9 modules, from basic to advanced.",
-    "  • Each module is self-contained (can be opened and completed in one sitting).",
-    "  • objective — one precise phrase \"by the end of this module you will be able to …\".",
-    "  • estMinutes — a realistic estimate of pure study time (15-60).",
-    "  • module id — kebab-case, latin letters + digits.",
-    "Reply with JSON ONLY on a single line, no markdown:",
-    `  {"modules":[{"id":"intro","title":"…","objective":"…","estMinutes":30}, ...]}`,
-  ].join("\n");
-
-  const result = await callJsonAgent<OutlineModule[]>({
-    prompt,
-    invoke: (p) => reflex.agent.invoke({ prompt: p, timeoutMs: 4 * 60_000 }),
-    maxAttempts: 4,
-    shapeHint:
-      `{"modules":[{"id":"intro","title":"Introduction","objective":"by the end of this module you will be able to …","estMinutes":30}, ...]}\n` +
-      `At least 5 modules. id — kebab-case, no spaces, latin letters only.`,
-    validate: (parsed) => {
-      const v = parsed as { modules?: unknown };
-      const modules = sanitizeModules(v?.modules);
-      return modules.length > 0 ? modules : null;
-    },
-  });
-
-  if (!result.ok) {
-    throw new Error(
-      `Failed to build the course outline in ${result.attempts} attempts (${result.reason}). ` +
-        `Last agent reply: "${snippet(result.lastText, 200)}". Try rephrasing the topic.`,
-    );
-  }
-  const modules = result.value;
-
-  const courseId = slugify(args.topic) || `course-${Date.now()}`;
-  const today = new Date().toISOString().slice(0, 10);
-  const body = [
-    `# ${args.topic}`,
-    "",
-    "## Program",
-    "",
-    ...modules.map(
-      (mod, i) =>
-        `${i + 1}. **${mod.title}** — ${mod.objective} (~${mod.estMinutes} min)`,
-    ),
-  ].join("\n");
-
-  const nowIso = new Date().toISOString();
-  // Source of truth: sandboxed JSON. Lookup via fs.list — no YAML
-  // round-tripping headaches.
-  await writeCourse({
-    courseId,
-    topic: args.topic,
-    modules,
-    progress: {},
-    wizardAnswers: args.history,
-    createdAt: nowIso,
-    updatedAt: nowIso,
-  });
-
-  // KB entry is for human visibility (showing up in the KB tree with a
-  // "createdBy: utility" badge). Short meta only — no JSON-stringified
-  // blobs, so multi-line YAML never happens.
-  const saved = await reflex.kb.add({
-    kind: "course",
-    title: args.topic,
-    body,
-    meta: {
-      courseId,
-      topic: args.topic,
-      modulesCount: modules.length,
-      createdAt: today,
-    },
-    slug: courseId,
-    date: today,
-  });
-
-  await reflex.audit.log({
-    type: "course-outlined",
-    payload: { topic: args.topic, modulesCount: modules.length },
-  });
-
-  return {
-    courseId,
-    topic: args.topic,
-    modules,
-    relPath: saved.relPath,
-    createdAt: today,
-  };
-}
-
-function sanitizeModules(raw: unknown): OutlineModule[] {
-  if (!Array.isArray(raw)) return [];
-  const seen = new Set<string>();
-  const out: OutlineModule[] = [];
-  for (const m of raw) {
-    if (typeof m !== "object" || m === null) continue;
-    const o = m as Partial<OutlineModule>;
-    const id =
-      typeof o.id === "string" && /^[a-z0-9][a-z0-9-]*$/.test(o.id)
-        ? o.id
-        : slugify(typeof o.title === "string" ? o.title : "");
-    if (!id || seen.has(id)) continue;
-    seen.add(id);
-    out.push({
-      id,
-      title: typeof o.title === "string" ? o.title : id,
-      objective: typeof o.objective === "string" ? o.objective : "",
-      estMinutes:
-        typeof o.estMinutes === "number" && Number.isFinite(o.estMinutes)
-          ? Math.max(5, Math.min(180, Math.round(o.estMinutes)))
-          : 30,
-    });
-  }
-  return out;
-}
-
-function slugify(s: string): string {
-  return s
-    .normalize("NFKD")
-    .toLowerCase()
-    .replace(/[^\p{L}\p{N}]+/gu, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, 60);
-}

package/packages/utilities/learn-anything/actions/generateQuiz.ts

@@ -1,72 +0,0 @@
-import { reflex } from "@host/api";
-import { extractJson } from "./_json";
-
-/**
- * Generate a 5-question multiple-choice quiz for a module. Each item:
- * stem (question), 4 options, one correct index, explanation. Quiz
- * isn't persisted as a separate KB entry — it's transient state the UI
- * holds while the user takes it; the score lands in course.meta.progress
- * after completion.
- */
-
-export interface QuizQuestion {
-  stem: string;
-  options: string[];
-  correctIndex: number;
-  explanation: string;
-}
-
-export interface GenerateQuizArgs {
-  moduleTitle: string;
-  moduleObjective: string;
-  /** Article body — gives the LLM something to draw questions from. */
-  article: string;
-}
-
-export default async function generateQuiz(
-  args: GenerateQuizArgs,
-): Promise<{ questions: QuizQuestion[] }> {
-  const trimmed = (args.article ?? "").slice(0, 6000);
-  const prompt = [
-    `Module: "${args.moduleTitle}" — ${args.moduleObjective}.`,
-    "Compose a short knowledge-check quiz of 5 questions with 4 answer options each.",
-    "Rules:",
-    "  • Questions test understanding, not rote memorisation of trivia.",
-    "  • Exactly one correct answer; the others are plausible.",
-    "  • Explanation of why the answer is correct — 1-2 sentences.",
-    "Reply with JSON ONLY on a single line:",
-    `  {"questions":[{"stem":"...","options":["a","b","c","d"],"correctIndex":0,"explanation":"..."}, ...]}`,
-    "",
-    `## Module material\n${trimmed}`,
-  ].join("\n");
-
-  const r = await reflex.llm.complete({ task: "quick", prompt });
-  const parsed = extractJson<{ questions?: unknown[] }>(r.text);
-  if (!parsed) return { questions: [] };
-  try {
-    const out: QuizQuestion[] = [];
-    for (const q of parsed.questions ?? []) {
-      if (typeof q !== "object" || q === null) continue;
-      const o = q as Partial<QuizQuestion>;
-      if (
-        typeof o.stem !== "string" ||
-        !Array.isArray(o.options) ||
-        o.options.length < 2 ||
-        typeof o.correctIndex !== "number" ||
-        o.correctIndex < 0 ||
-        o.correctIndex >= o.options.length
-      ) {
-        continue;
-      }
-      out.push({
-        stem: o.stem,
-        options: o.options.map((x) => String(x)).slice(0, 6),
-        correctIndex: o.correctIndex,
-        explanation: typeof o.explanation === "string" ? o.explanation : "",
-      });
-    }
-    return { questions: out.slice(0, 8) };
-  } catch {
-    return { questions: [] };
-  }
-}

package/packages/utilities/learn-anything/actions/generateTrainer.ts

@@ -1,106 +0,0 @@
-import { reflex } from "@host/api";
-
-/**
- * Ask the agent to write an interactive trainer (small standalone HTML
- * page with inline JS) that practices a specific skill from a module —
- * e.g. simulation of a binary tree, drag-shapes-on-canvas exercise,
- * flashcard drill. The HTML runs inside a nested sandboxed iframe in
- * the utility UI; it has NO host-RPC access — strictly client-only.
- *
- * Persisted as KB kind="course-trainer" so it survives between sessions
- * and the user can re-open.
- */
-
-export interface TrainerSpec {
-  trainerId: string;
-  courseId: string;
-  moduleId: string;
-  title: string;
-  /** Self-contained HTML — head/body/script all inline. Loaded via
-   *  iframe srcdoc inside the utility. */
-  html: string;
-  relPath: string;
-}
-
-export interface GenerateTrainerArgs {
-  courseId: string;
-  moduleId: string;
-  moduleTitle: string;
-  moduleObjective: string;
-  prompt?: string; // user idea
-}
-
-export default async function generateTrainer(
-  args: GenerateTrainerArgs,
-): Promise<TrainerSpec> {
-  const userBrief =
-    (args.prompt ?? "").trim() ||
-    `Design a trainer that helps reinforce "${args.moduleObjective}".`;
-  const prompt = [
-    `Course/module: "${args.moduleTitle}".`,
-    "Build an interactive trainer — a standalone HTML file with inline JS.",
-    "Requirements:",
-    "  • One full <!doctype html> file: <head>, <body>, <script>, optional <style>.",
-    "  • NO external resources: no CDN scripts, no image URLs, no fetch calls. Everything inline.",
-    "  • Use <canvas> where appropriate (drawing, physics, geometry).",
-    "  • Size ≈ 600×400 px (responsive).",
-    "  • Clear interface: what is shown, what to do, instant feedback (right/wrong, score).",
-    "  • No navigator/window globals that break inside a sandbox iframe (no localStorage, no parent).",
-    "  • THE CODE MUST WORK. No placeholder functions.",
-    "Reply with HTML ONLY (no JSON wrapper, no markdown fence).",
-    "",
-    `## Trainer idea\n${userBrief}`,
-  ].join("\n");
-
-  // Trainer HTML is long — give the agent a generous 7 minutes; worker
-  // timeout (8 min in manifest) is the outer guardrail.
-  const r = await reflex.agent.invoke({ prompt, timeoutMs: 7 * 60_000 });
-  const text = r.text ?? "";
-  const html = extractHtml(text);
-  if (!html) {
-    throw new Error("Agent did not return valid HTML — please try again");
-  }
-
-  const trainerId = `${args.moduleId}-${Date.now().toString(36)}`;
-  const saved = await reflex.kb.add({
-    kind: "course-trainer",
-    title: `Trainer · ${args.moduleTitle}`,
-    body: "```html\n" + html.slice(0, 30_000) + "\n```",
-    meta: {
-      courseId: args.courseId,
-      moduleId: args.moduleId,
-      trainerId,
-      title: args.moduleTitle,
-      // Full HTML in meta is bulky but allows quick re-open without re-parsing.
-      // Capped at ~60KB to keep frontmatter sane.
-      html: html.slice(0, 60_000),
-    },
-    slug: `trainer-${trainerId}`,
-  });
-
-  return {
-    trainerId,
-    courseId: args.courseId,
-    moduleId: args.moduleId,
-    title: args.moduleTitle,
-    html,
-    relPath: saved.relPath,
-  };
-}
-
-/** Pluck HTML from possibly-fenced agent output. */
-function extractHtml(text: string): string {
-  // Fence-bound: ```html ... ```
-  const fenced = /```(?:html)?\s*([\s\S]+?)\s*```/.exec(text);
-  if (fenced) {
-    const inner = fenced[1]!.trim();
-    if (looksLikeHtml(inner)) return inner;
-  }
-  if (looksLikeHtml(text)) return text.trim();
-  return "";
-}
-
-function looksLikeHtml(s: string): boolean {
-  const lower = s.toLowerCase();
-  return lower.includes("<!doctype html") || lower.includes("<html");
-}

package/packages/utilities/learn-anything/actions/refreshCourseCard.ts

@@ -1,76 +0,0 @@
-import { reflex } from "@host/api";
-
-/**
- * Update the dashboard card: number of active courses + average
- * progress %. Called after key events (course created, module
- * completed, quiz passed). Idempotent.
- */
-export default async function refreshCourseCard(): Promise<{ courses: number; avg: number }> {
-  const list = (await reflex.kb.list({ kind: "course" })) ?? [];
-  let total = 0;
-  let avgSum = 0;
-  for (const c of list) {
-    try {
-      const { content } = await reflex.kb.read({ relPath: c.relPath });
-      const m = /^---\n([\s\S]*?)\n---/.exec(content);
-      if (!m) continue;
-      const meta = parseFrontmatter(m[1]!);
-      const modules = jsonOf(meta.modules);
-      const progress = jsonOf(meta.progress);
-      if (!Array.isArray(modules) || modules.length === 0) continue;
-      total++;
-      const done = Object.values(
-        progress as Record<string, { completed?: boolean }>,
-      ).filter((p) => p && (p as { completed?: boolean }).completed).length;
-      avgSum += done / modules.length;
-    } catch {
-      /* skip */
-    }
-  }
-  const courses = total;
-  const avg = total > 0 ? Math.round((avgSum / total) * 100) : 0;
-  await reflex.cards.update({
-    snapshot: {
-      kind: "kpi",
-      title: "🎓 Learning",
-      data: {
-        items: [
-          { label: "Active courses", value: String(courses) },
-          {
-            label: "Progress",
-            value: courses === 0 ? "—" : `${avg}%`,
-            hint: "average across courses",
-            ...(avg >= 60
-              ? ({ delta: "up" } as const)
-              : avg < 30 && courses > 0
-                ? ({ delta: "down" } as const)
-                : ({ delta: "flat" } as const)),
-          },
-        ],
-      },
-    },
-  });
-  return { courses, avg };
-}
-
-function jsonOf(v: unknown): unknown {
-  if (typeof v !== "string") return v;
-  try {
-    return JSON.parse(v);
-  } catch {
-    return null;
-  }
-}
-
-function parseFrontmatter(s: string): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  for (const line of s.split("\n")) {
-    const i = line.indexOf(":");
-    if (i < 0) continue;
-    out[line.slice(0, i).trim()] = line
-      .slice(i + 1)
-      .trim()
-      .replace(/^["']|["']$/g, "");
-  }
-  return out;
-}

package/packages/utilities/learn-anything/actions/tutorAsk.ts

@@ -1,93 +0,0 @@
-import { reflex } from "@host/api";
-import { extractJson } from "./_json";
-
-/**
- * Wizard step. Given the topic + prior Q&A, the agent decides whether
- * it needs more context or has enough to design a course. Returns
- * either the next question (open-ended or multiple-choice) or
- * `{done:true}` so the UI advances to outline generation.
- *
- * Keeping the wizard agent-driven means we don't hardcode "3 questions
- * about level/focus/format" — for "I want to learn pencil drawing"
- * the agent will ask different questions than for "I want to learn
- * Python". The UI just renders whatever comes back.
- */
-
-export interface TutorQA {
-  question: string;
-  answer: string;
-}
-
-export interface TutorAskArgs {
-  topic: string;
-  history: TutorQA[];
-  /** Force-finish even if the agent wants more. UI uses this when the
-   *  user clicks "Enough questions — build the course already". */
-  forceFinish?: boolean;
-}
-
-export interface TutorAskResult {
-  done: boolean;
-  /** Free-form question; UI renders a textarea. */
-  question?: string;
-  /** Optional pre-baked choices for a multiple-choice ask. */
-  choices?: string[];
-  /** Hint to UI: short label like "level", "format", "goal". */
-  header?: string;
-}
-
-const MAX_TURNS = 5;
-
-export default async function tutorAsk(
-  args: TutorAskArgs,
-): Promise<TutorAskResult> {
-  const turns = args.history.length;
-  if (args.forceFinish || turns >= MAX_TURNS) {
-    return { done: true };
-  }
-
-  const prior = args.history
-    .map((qa, i) => `Q${i + 1}: ${qa.question}\nA${i + 1}: ${qa.answer}`)
-    .join("\n\n");
-
-  const prompt = [
-    "You are a tutor who is about to design a personalised course for the user.",
-    `Topic: "${args.topic}".`,
-    "You need to gather the minimum information required to choose a good program: level, goal, time budget, format, specifics.",
-    "Ask ONE question at a time. Decide what to ask yourself — whatever is most important right now given the topic and prior answers.",
-    "If it makes sense to offer answer options — add up to 5 short choices.",
-    "If you already know enough (usually after 2-4 questions) — return done=true.",
-    "Reply with JSON ONLY on a single line, no markdown:",
-    `  {"done":false,"question":"...","header":"level|goal|time|format|...","choices":["...","..."]}`,
-    "  or",
-    `  {"done":true}`,
-    "",
-    prior ? `## Previous answers\n${prior}` : "## This is the first question",
-    `\nQuestions asked so far: ${turns} (maximum ${MAX_TURNS}).`,
-  ].join("\n");
-
-  const r = await reflex.llm.complete({ task: "quick", prompt });
-  const parsed = extractJson<TutorAskResult>(r.text);
-  if (!parsed) return { done: true };
-  try {
-    if (parsed.done) return { done: true };
-    if (typeof parsed.question !== "string" || !parsed.question.trim()) {
-      return { done: true };
-    }
-    return {
-      done: false,
-      question: parsed.question.trim(),
-      ...(parsed.header ? { header: parsed.header } : {}),
-      ...(Array.isArray(parsed.choices) && parsed.choices.length > 0
-        ? {
-            choices: parsed.choices
-              .map((c) => String(c).trim())
-              .filter(Boolean)
-              .slice(0, 5),
-          }
-        : {}),
-    };
-  } catch {
-    return { done: true };
-  }
-}