reflex-agent 0.2.4 → 0.3.1

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

@@ -1,487 +0,0 @@
-import { reflex } from "@host/api";
-import { callJsonAgent, snippet } from "./_json";
-
-/**
- * Compile a learning module: agent writes a full markdown article, then
- * Reflex resolves the image needs (real photos via search → local
- * download, schematics via generation) and embeds permanent local URLs
- * into the body. Persisted as a `course-module` KB entry, idempotent on
- * (courseId, moduleId).
- *
- * Why image queries/prompts instead of raw URLs:
- *   The old contract asked the LLM to suggest image URLs from its
- *   training corpus. ~90% of those URLs were dead or hallucinated.
- *   Now the LLM emits *intent* (what to find / what to draw) and
- *   reflex.images.search + reflex.images.generate do the real work,
- *   yielding stable `/api/images/<rootId>/<sha>.<ext>` URLs that move
- *   with the project.
- */
-
-export interface ModuleContent {
-  courseId: string;
-  moduleId: string;
-  title: string;
-  /** Long-form markdown body for the article view. */
-  article: string;
-  videos: Array<{ title: string; url: string; note?: string }>;
-  links: Array<{ title: string; url: string; snippet?: string }>;
-  /** Resolved images: each has a permanent `/api/images/...` URL. */
-  images: Array<{
-    /** Stable id from the LLM draft; used to substitute inline `[[IMG:<id>]]` placeholders. */
-    id: string;
-    alt: string;
-    url: string;
-    source: "search" | "generated";
-    attribution?: { name: string; link: string };
-  }>;
-  /** Mermaid diagrams (kept for structural schemas like flowcharts). */
-  diagrams: Array<{ title: string; mermaid: string }>;
-  homework: string[];
-  relPath: string;
-}
-
-export interface BuildModuleArgs {
-  courseId: string;
-  moduleId: string;
-  moduleTitle: string;
-  moduleObjective: string;
-  topic: string;
-}
-
-interface LlmDraft {
-  article?: string;
-  videos?: Array<{ title: string; url: string; note?: string }>;
-  links?: Array<{ title: string; url: string; snippet?: string }>;
-  /**
-   * "Find a real photo of X". Each carries an `id` so the LLM can drop
-   * an inline `[[IMG:<id>]]` placeholder into `article` and we know
-   * where to embed the resolved image.
-   */
-  imageQueries?: Array<{ id: string; alt: string; query: string }>;
-  /** Same id-based contract as `imageQueries`, but the resolver calls
-   *  reflex.images.generate instead of search. */
-  generatedFigures?: Array<{ id: string; alt: string; prompt: string }>;
-  /** Mermaid code for diagrams that genuinely need flow/sequence syntax. */
-  diagrams?: Array<{ title: string; mermaid: string }>;
-  homework?: string[];
-}
-
-export default async function buildModule(
-  args: BuildModuleArgs,
-): Promise<ModuleContent> {
-  // 1. Pull a few web sources to ground the article — saves the agent from
-  // hallucinating sources. Best-effort; failures are silent.
-  let webContext = "";
-  try {
-    const search = await reflex.web.search({
-      query: `${args.topic} ${args.moduleTitle}`,
-    });
-    const top = (search.results ?? []).slice(0, 4);
-    webContext = top
-      .map(
-        (r, i) =>
-          `[${i + 1}] ${r.title}\n    ${r.url}\n    ${r.snippet ?? ""}`,
-      )
-      .join("\n");
-  } catch {
-    /* offline / no search — agent will rely on training data */
-  }
-
-  // 2. Ask the agent to draft the module. Note: NO bare image URLs —
-  // the LLM tells us WHAT to look for / draw; Reflex resolves it via
-  // reflex.images.search (Brave when available) + reflex.images.generate.
-  const prompt = [
-    `Курс: «${args.topic}». Модуль: «${args.moduleTitle}» — ${args.moduleObjective}.`,
-    "Подготовь учебный материал. Структура JSON-ответа:",
-    "{",
-    `  "article": "длинный markdown 800-2000 слов; используй # ## ### и плейсхолдеры [[IMG:<id>]] для inline-картинок",`,
-    `  "videos": [{"title":"...","url":"https://youtube.com/...","note":"..."}],`,
-    `  "links": [{"title":"...","url":"...","snippet":"..."}],`,
-    `  "imageQueries": [{"id":"i1","alt":"...","query":"короткий английский поисковый запрос"}],`,
-    `  "generatedFigures": [{"id":"f1","alt":"...","prompt":"подробное описание для AI-генератора, английский"}],`,
-    `  "diagrams": [{"title":"...","mermaid":"graph TD; A-->B;"}],`,
-    `  "homework": ["...","..."]`,
-    "}",
-    "",
-    "## ВИЗУАЛЬНОЕ СОПРОВОЖДЕНИЕ — ОБЯЗАТЕЛЬНО + INLINE-РАЗМЕЩЕНИЕ",
-    "",
-    "Любой учебный модуль ОБЯЗАН быть визуально насыщенным. Каждая картинка ставится **inline** в нужном месте текста через плейсхолдер.",
-    "",
-    "### Как это работает",
-    "  1. Каждому элементу в `imageQueries` и `generatedFigures` присваиваешь ШОРТ-ID (`i1`, `i2`, `f1`, `f2`, ...). i = image-search (real photo), f = figure (AI-generated). Уникальный в пределах модуля.",
-    "  2. В `article` markdown вставляешь плейсхолдер `[[IMG:i1]]` на ОТДЕЛЬНОЙ СТРОКЕ ровно там где должна стоять эта картинка (например, после абзаца который её обсуждает).",
-    "  3. Reflex автоматически:",
-    "     – ищет реальные фото/схемы через Brave Image Search (по `imageQueries`),",
-    "     – ВИЗУАЛЬНО ОЦЕНИВАЕТ кандидатов (твой chat-агент смотрит на thumbnails через Read tool) — клипарт/off-topic отклоняются по содержимому,",
-    "     – генерирует уникальные иллюстрации через Gemini Nano Banana (по `generatedFigures`),",
-    "     – заменяет `[[IMG:<id>]]` на `![alt](локальный-url)` с атрибуцией,",
-    "     – неотрезолвленные id (картинка не найдена / отклонена) удаляются из текста чисто.",
-    "",
-    "### Пример",
-    "```markdown",
-    "## Зрительная кора",
-    "Зрительная кора V1 — первая зона обработки информации от сетчатки.",
-    "",
-    "[[IMG:i1]]",
-    "",
-    "Колончатая организация V1 была описана Хьюбелом и Визелом в 1962 году...",
-    "",
-    "[[IMG:f1]]",
-    "```",
-    "...где `imageQueries: [{id:\"i1\", alt:\"Срез зрительной коры V1\", query:\"primary visual cortex V1 histology\"}]` и `generatedFigures: [{id:\"f1\", alt:\"Схема рецептивного поля\", prompt:\"educational diagram: receptive field of simple cells in V1, ON-OFF regions, labeled in English\"}]`.",
-    "",
-    "Твоя задача — заполнить два массива И расставить плейсхолдеры в article:",
-    "",
-    "### `imageQueries` (поиск реальных материалов) — МИНИМУМ 2-3 шт.",
-    "  • Для тем где есть реальные референсы (Эйфелева башня, клетка, Гражданская война, лабораторная установка, известная картина, ландшафт, исторический документ) — ВСЕГДА добавляй 2-4 query.",
-    "  • Каждый query — короткий АНГЛИЙСКИЙ поисковый запрос (Brave работает лучше на английском): \"Eiffel Tower iron lattice closeup\", \"mitochondria electron microscope\", \"American Civil War Gettysburg battlefield\".",
-    "  • `id` — короткий уникальный идентификатор: `i1`, `i2`, `i3`...",
-    "  • `alt` — короткое описание по-русски, что зритель увидит.",
-    "  • Каждому `id` соответствует ровно один плейсхолдер `[[IMG:i1]]` в `article` — ставь его в тематически подходящем месте.",
-    "",
-    "### `generatedFigures` (AI-генерация уникальных схем) — 1-2 шт когда уместно.",
-    "  • Используй для уникальных схем/иллюстраций, которых нет в сети: \"процесс N в виде наглядной схемы\", \"анатомия Х в стиле учебника\", \"таймлайн событий\", \"абстрактная визуализация концепции\".",
-    "  • `id` — короткий уникальный идентификатор: `f1`, `f2`...",
-    "  • `prompt` — подробный АНГЛИЙСКИЙ описательный prompt со стилем (\"minimalist educational diagram, white background, labeled parts in blue, isometric view\" / \"watercolor illustration, soft palette\" / \"photorealistic, studio lighting\").",
-    "  • НЕ дублируй generatedFigures с imageQueries — generate только то, что не найти готовым.",
-    "  • `alt` — короткое описание по-русски.",
-    "  • Поставь плейсхолдер `[[IMG:f1]]` в article ровно где эта схема нужна.",
-    "",
-    "### Правила для прочих полей",
-    "  • article — основной текст, 800-2000 слов. Заголовки # ## ###, плотный материал.",
-    "  • Картинки размещаются ТОЛЬКО через `[[IMG:<id>]]` на отдельной строке. Не пиши `[[ИЛЛЮСТРАЦИЯ: ...]]`, `[[СХЕМА: ...]]` — они не работают.",
-    "  • НЕ ВЫДУМЫВАЙ URL картинок. Любые bare URL в article игнорируются.",
-    "  • Каждый id, объявленный в imageQueries/generatedFigures, должен встретиться в article ровно один раз. Каждый `[[IMG:<id>]]` в тексте должен иметь соответствие в одном из массивов.",
-    "  • videos: 1-3 ссылки на youtube/youtu.be — URL юзер сам проверит.",
-    "  • links: 2-5 авторитетных статей.",
-    "  • diagrams (mermaid): только flowchart/sequence/class — где mermaid реально удобнее картинки. Для visual schemes используй generatedFigures.",
-    "  • homework: 3-5 практических заданий с проверяемым результатом.",
-    "",
-    "Верни ТОЛЬКО JSON одной строкой, без markdown-фенс.",
-    "",
-    webContext
-      ? `## Web-источники для опоры\n${webContext}`
-      : "## Web-источники недоступны — опирайся на свои знания.",
-  ].join("\n");
-
-  const result = await callJsonAgent<LlmDraft>({
-    prompt,
-    invoke: (p) => reflex.agent.invoke({ prompt: p, timeoutMs: 7 * 60_000 }),
-    maxAttempts: 4,
-    shapeHint:
-      `{"article":"...","videos":[],"links":[],"imageQueries":[],"generatedFigures":[],"diagrams":[],"homework":[]}\n` +
-      `article — markdown 800-2000 слов. Все массивы — обязательно массивы (можно пустые).`,
-    validate: (p) => {
-      const v = p as LlmDraft;
-      return typeof v?.article === "string" && v.article.trim().length > 40
-        ? v
-        : null;
-    },
-  });
-  if (!result.ok) {
-    throw new Error(
-      `Не удалось собрать модуль за ${result.attempts} попыток (${result.reason}). ` +
-        `Последний ответ: «${snippet(result.lastText, 200)}».`,
-    );
-  }
-  const draft = result.value;
-
-  // 3. Resolve image needs in parallel. Each call is best-effort —
-  // a failed search or generation just drops that image from the module
-  // (we don't want one flaky API to fail the whole build).
-  const [searchedImages, generatedImages] = await Promise.all([
-    resolveSearches(draft.imageQueries ?? [], args.topic, args.moduleTitle),
-    resolveGenerations(draft.generatedFigures ?? []),
-  ]);
-
-  // Inline-place images by substituting [[IMG:<id>]] placeholders in the
-  // article body. Any image whose id wasn't referenced (LLM forgot)
-  // falls back into the trailing Иллюстрации section so nothing gets
-  // dropped silently. Residual unknown [[...]] markers are stripped.
-  const allImages = [...searchedImages, ...generatedImages];
-  const { article: articleWithImages, placedIds } = substituteImagePlaceholders(
-    typeof draft.article === "string" ? draft.article : "",
-    allImages,
-  );
-  const articleClean = stripPlaceholderMarkers(articleWithImages);
-  const unplaced = allImages.filter((im) => !placedIds.has(im.id));
-
-  const content: Omit<ModuleContent, "relPath"> = {
-    courseId: args.courseId,
-    moduleId: args.moduleId,
-    title: args.moduleTitle,
-    article: articleClean,
-    videos: sanitizeArr(draft.videos, ["title", "url"]) as ModuleContent["videos"],
-    links: sanitizeArr(draft.links, ["title", "url"]) as ModuleContent["links"],
-    images: allImages,
-    diagrams: sanitizeArr(draft.diagrams, ["title", "mermaid"]) as ModuleContent["diagrams"],
-    homework: Array.isArray(draft.homework)
-      ? draft.homework.map(String).filter(Boolean).slice(0, 8)
-      : [],
-  };
-
-  // 4. Persist as a KB entry. Frontmatter holds the structured bits;
-  // body = article with images already inlined + optional fallback
-  // section for images the LLM declared but never referenced.
-  const body = [
-    content.article,
-    unplaced.length > 0
-      ? "\n\n## Дополнительные иллюстрации\n" +
-        unplaced
-          .map((im) => `${renderInlineImage(im)}`)
-          .join("\n\n")
-      : "",
-    content.diagrams.length > 0
-      ? "\n\n## Схемы\n" +
-        content.diagrams
-          .map(
-            (d) =>
-              `### ${d.title}\n\n\`\`\`mermaid\n${d.mermaid}\n\`\`\``,
-          )
-          .join("\n\n")
-      : "",
-  ]
-    .filter(Boolean)
-    .join("");
-
-  const saved = await reflex.kb.add({
-    kind: "course-module",
-    title: `${args.topic} · ${args.moduleTitle}`,
-    body,
-    meta: {
-      courseId: args.courseId,
-      moduleId: args.moduleId,
-      videos: JSON.stringify(content.videos),
-      links: JSON.stringify(content.links),
-      images: JSON.stringify(content.images),
-      diagrams: JSON.stringify(content.diagrams),
-      homework: JSON.stringify(content.homework),
-      title: args.moduleTitle,
-      objective: args.moduleObjective,
-    },
-    slug: `${args.courseId}-${args.moduleId}`,
-  });
-
-  await reflex.audit.log({
-    type: "module-built",
-    payload: {
-      courseId: args.courseId,
-      moduleId: args.moduleId,
-      videos: content.videos.length,
-      images: content.images.length,
-      searched: searchedImages.length,
-      generated: generatedImages.length,
-    },
-  });
-
-  return { ...content, relPath: saved.relPath };
-}
-
-/**
- * For each query: do a web image search (5 candidates), ask the LLM
- * which best fits the course material, attach the chosen one. If the
- * LLM rejects all candidates (-1), the image slot is left empty — better
- * than embedding clip-art or off-topic stock photo. Try/catch isolates
- * per-image failures from killing the module build.
- */
-async function resolveSearches(
-  queries: Array<{ id?: unknown; alt?: unknown; query?: unknown }>,
-  topic: string,
-  moduleTitle: string,
-): Promise<ModuleContent["images"]> {
-  const clean = queries
-    .filter(
-      (q) =>
-        q &&
-        typeof q.query === "string" &&
-        q.query.trim().length > 0,
-    )
-    .slice(0, 4);
-  const out = await Promise.all(
-    clean.map(async (q, idx) => {
-      try {
-        const query = q.query as string;
-        const alt = typeof q.alt === "string" ? q.alt : query;
-        const id =
-          typeof q.id === "string" && q.id.trim().length > 0
-            ? q.id.trim()
-            : `i${idx + 1}`;
-        // Default provider: Brave for breadth (real web), falls back to
-        // Unsplash/Pexels via service-router based on which key exists.
-        const search = await reflex.images.search({ query, count: 5 });
-        if (search.results.length === 0) return null;
-        // Vision-based pick: Reflex spawns the user's chat harness
-        // (Codex / Claude Code) on the candidate thumbnails and asks it
-        // to choose. The agent uses its Read tool — both runtimes get
-        // real vision content for image files, so off-topic results
-        // (clipart, mislabelled photos) are filtered by content, not
-        // metadata.
-        const pick = await reflex.images.pickBest({
-          query,
-          alt,
-          context: `${topic} → ${moduleTitle}`,
-          candidates: search.results.map((r) => ({
-            url: r.url,
-            thumb: r.thumb,
-            attribution: r.attribution,
-          })),
-        });
-        if (pick.pickIndex < 0 || pick.pickIndex >= search.results.length) {
-          void reflex.audit.log({
-            type: "image-rejected",
-            payload: { query, reason: pick.reason, via: pick.via },
-          });
-          return null;
-        }
-        const chosen = search.results[pick.pickIndex];
-        const attached = await reflex.images.attach({
-          sourceUrl: chosen.url,
-        });
-        return {
-          id,
-          alt,
-          url: attached.url,
-          source: "search" as const,
-          attribution: chosen.attribution,
-        };
-      } catch (err) {
-        // Log to audit; the module survives without this image.
-        void reflex.audit.log({
-          type: "image-search-failed",
-          payload: {
-            query: q.query,
-            error: err instanceof Error ? err.message : String(err),
-          },
-        });
-        return null;
-      }
-    }),
-  );
-  return out.filter((x): x is NonNullable<typeof x> => x !== null);
-}
-
-/**
- * Walk through the article body, find `[[IMG:<id>]]` placeholders, and
- * replace each with a markdown image reference using the resolved
- * image's URL + alt + attribution.
- *
- * Returns the rewritten article + the set of ids successfully placed.
- * Unknown placeholders (id has no matching resolved image) get stripped
- * — likely a generation/search failure that already logged to audit.
- *
- * Whitespace around inline placeholders is normalized so the image sits
- * as its own block (Markdown then renders `![](...)` as a paragraph).
- */
-function substituteImagePlaceholders(
-  article: string,
-  images: ModuleContent["images"],
-): { article: string; placedIds: Set<string> } {
-  const byId = new Map(images.map((im) => [im.id, im]));
-  const placedIds = new Set<string>();
-  // Accept variants: `[[IMG:i1]]`, `[[img:i1]]`, `[[IMG: i1 ]]`,
-  // `[[IMG i1]]`, and even single-bracket `[IMG:i1]` from sloppy LLMs.
-  const re = /\[\[?\s*IMG\s*[:\s]\s*([A-Za-z0-9_-]+)\s*\]\]?/gi;
-  const replaced = article.replace(re, (_, rawId: string) => {
-    const id = rawId.trim();
-    const img = byId.get(id);
-    if (!img) return "";
-    placedIds.add(id);
-    return `\n\n${renderInlineImage(img)}\n\n`;
-  });
-  return { article: replaced, placedIds };
-}
-
-function renderInlineImage(im: ModuleContent["images"][number]): string {
-  const safeAlt = im.alt.replace(/[\[\]\n]/g, " ").slice(0, 200);
-  const credit =
-    im.source === "search" && im.attribution?.name
-      ? `\n\n_Источник: [${im.attribution.name}](${im.attribution.link || im.url})_`
-      : im.source === "generated"
-        ? `\n\n_Сгенерировано AI_`
-        : "";
-  return `![${safeAlt}](${im.url})${credit}`;
-}
-
-/**
- * Strip residual `[[ИЛЛЮСТРАЦИЯ: ...]]` / `[[СХЕМА: ...]]` / orphan
- * `[[IMG:<unknown-id>]]` placeholders the LLM might emit despite the
- * prompt forbidding them OR after `substituteImagePlaceholders` failed
- * to find the id. Drops the marker, collapses surrounding whitespace.
- *
- * Matches Russian variants + Latin spellings for safety. Case-insensitive.
- */
-function stripPlaceholderMarkers(text: string): string {
-  const re =
-    /\[\[?\s*(?:ИЛЛЮСТРАЦИЯ|СХЕМА|ILLUSTRATION|SCHEME|IMAGE|IMG|DIAGRAM)\b[^\]]*?\]\]?/giu;
-  let out = text.replace(re, "");
-  // Clean up double blank lines + trailing whitespace the removal may
-  // have left behind.
-  out = out.replace(/[ \t]+\n/g, "\n");
-  out = out.replace(/\n{3,}/g, "\n\n");
-  return out.trim() + "\n";
-}
-
-async function resolveGenerations(
-  figures: Array<{ id?: unknown; alt?: unknown; prompt?: unknown }>,
-): Promise<ModuleContent["images"]> {
-  const clean = figures
-    .filter(
-      (f) =>
-        f &&
-        typeof f.prompt === "string" &&
-        f.prompt.trim().length > 0,
-    )
-    .slice(0, 2);
-  const out = await Promise.all(
-    clean.map(async (f, idx) => {
-      try {
-        const gen = await reflex.images.generate({
-          prompt: f.prompt as string,
-          aspectRatio: "16:9",
-        });
-        const id =
-          typeof f.id === "string" && f.id.trim().length > 0
-            ? f.id.trim()
-            : `f${idx + 1}`;
-        return {
-          id,
-          alt: typeof f.alt === "string" ? f.alt : (f.prompt as string).slice(0, 80),
-          url: gen.url,
-          source: "generated" as const,
-        };
-      } catch (err) {
-        void reflex.audit.log({
-          type: "image-generate-failed",
-          payload: {
-            prompt: f.prompt,
-            error: err instanceof Error ? err.message : String(err),
-          },
-        });
-        return null;
-      }
-    }),
-  );
-  return out.filter((x): x is NonNullable<typeof x> => x !== null);
-}
-
-function sanitizeArr(
-  v: unknown,
-  required: string[],
-): Array<Record<string, string>> {
-  if (!Array.isArray(v)) return [];
-  const out: Array<Record<string, string>> = [];
-  for (const item of v.slice(0, 12)) {
-    if (typeof item !== "object" || item === null) continue;
-    const o = item as Record<string, unknown>;
-    const ok = required.every(
-      (k) => typeof o[k] === "string" && (o[k] as string).trim() !== "",
-    );
-    if (!ok) continue;
-    const row: Record<string, string> = {};
-    for (const [k, val] of Object.entries(o)) {
-      if (typeof val === "string") row[k] = val;
-    }
-    out.push(row);
-  }
-  return out;
-}

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

@@ -1,64 +0,0 @@
-import { reflex } from "@host/api";
-
-/**
- * "Explain this" feature: user highlights a snippet inside the module
- * article and asks for a deeper explanation. The agent gets the
- * surrounding paragraph as context so it understands what "это" means.
- *
- * Two modes:
- *   1. Default — `question` omitted, agent gives a generic 2-5 paragraph
- *      breakdown of the selected fragment.
- *   2. Custom — `question` supplied (book-style margin annotation), agent
- *      answers that specific question with the selection as the focal
- *      point. Lets the reader say things like "при чём тут N?" or
- *      "дай пример" instead of always getting the same boilerplate.
- */
-
-export interface ExplainSelectionArgs {
-  selection: string;
-  /** ~400-1000 chars around the selection for context. */
-  context: string;
-  topic: string;
-  moduleTitle: string;
-  /** Optional user question about the selection. */
-  question?: string;
-}
-
-export default async function explainSelection(
-  args: ExplainSelectionArgs,
-): Promise<{ text: string }> {
-  const userQuestion = (args.question ?? "").trim();
-  const promptLines: string[] = [
-    `Курс: «${args.topic}». Модуль: «${args.moduleTitle}».`,
-  ];
-
-  if (userQuestion) {
-    promptLines.push(
-      "Пользователь выделил фрагмент и задал конкретный вопрос про этот фрагмент.",
-      "Ответь именно на его вопрос, опираясь на выделение + окружающий контекст. 2-4 абзаца, без воды, по делу.",
-      "Markdown без заголовков; короткие фразы, пример если уместен.",
-    );
-  } else {
-    promptLines.push(
-      "Пользователь выделил фрагмент и просит объяснить подробнее.",
-      "Дай развёрнутое объяснение в 2-5 абзацах: что это значит, как работает,",
-      "почему именно так, конкретный пример. Без воды. Markdown без заголовков.",
-    );
-  }
-
-  promptLines.push(
-    "",
-    `## Окружающий контекст\n${args.context.slice(0, 1500)}`,
-    "",
-    `## Выделение пользователя\n«${args.selection.slice(0, 800)}»`,
-  );
-  if (userQuestion) {
-    promptLines.push("", `## Вопрос пользователя\n${userQuestion.slice(0, 600)}`);
-  }
-
-  const r = await reflex.llm.complete({
-    task: "quick",
-    prompt: promptLines.join("\n"),
-  });
-  return { text: (r.text ?? "").trim() };
-}