@learnpack/learnpack 5.0.352 → 5.0.354

package/src/utils/descriptions/generateCourseDescriptions.ts

@@ -0,0 +1,311 @@
+import { Lesson, Syllabus } from "../../models/creator"
+import { PackageManifest } from "../packageManifest"
+import {
+  generateStepDescriptions,
+  TGenerateStepDescriptionsParams,
+  TGenerateStepDescriptionsResult,
+} from "../rigoActions"
+import { mapWithConcurrency } from "../s3/packageManifestBackfill"
+import {
+  SyllabusSyncStorage,
+  synchronizeSyllabusWithBucket,
+} from "../syllabusSync"
+import {
+  buildDescriptionWorkList,
+  countWorkItems,
+  CourseExercise,
+  CourseReadmes,
+  StepWork,
+} from "./workList"
+
+/**
+ * Generate and persist the step descriptions of one published course.
+ *
+ * This is the single implementation behind every flow that produces
+ * descriptions: the background stage that runs after publishing, the sweep that
+ * recovers interrupted publications, and the one-off backfill over the
+ * historical catalogue. They differ only in what triggers them.
+ *
+ * Storage is a port so the service can be driven against the published bucket
+ * (the real case) or an in-memory double (tests), and so the manifest
+ * re-projection stays where the storage-specific knowledge lives.
+ */
+
+export const DEFAULT_DESCRIPTIONS_CONCURRENCY = 5
+
+export interface CourseDescriptionsStorage {
+  readSyllabus(courseSlug: string): Promise<Syllabus | null>;
+  writeSyllabus(courseSlug: string, syllabus: Syllabus): Promise<void>;
+  listExercises(courseSlug: string): Promise<CourseExercise[]>;
+  readReadme(
+    courseSlug: string,
+    exerciseSlug: string,
+    fileName: string
+  ): Promise<string | null>;
+  /** Re-generate `package-manifest.json` from the syllabus and invalidate the CDN. */
+  reprojectManifest?(courseSlug: string): Promise<void>;
+  /** Read the stored manifest, to report the updated one in the event. */
+  readManifest?(courseSlug: string): Promise<PackageManifest | null>;
+  /** Enables the provisional additive syllabus reconciliation. */
+  syllabusSyncStorage?: SyllabusSyncStorage;
+}
+
+export type GenerateCourseDescriptionsOptions = {
+  token: string;
+  dryRun?: boolean;
+  force?: boolean;
+  concurrency?: number;
+  targetWordCount?: number;
+  promptVersion?: number;
+  /** Additive syllabus reconciliation before computing the work list. */
+  reconcile?: boolean;
+  /** Injection point for tests. */
+  generate?: (
+    token: string,
+    params: TGenerateStepDescriptionsParams
+  ) => Promise<TGenerateStepDescriptionsResult | null>;
+};
+
+export type GenerateCourseDescriptionsResult = {
+  /** `skipped` means there was nothing to do, not that something went wrong. */
+  status: "skipped" | "processed" | "failed";
+  steps: number;
+  /** (step, language) pairs written. */
+  generated: number;
+  /** Steps whose completion failed outright. */
+  failed: number;
+  /** (step, language) pairs the model never answered; retried later. */
+  missing: number;
+  errors: string[];
+  /** Completion durations, to watch how close we run to the request limits. */
+  durationsSeconds: number[];
+  /**
+   * Whether `package-manifest.json` was re-projected; null when the storage does
+   * not project at all. A failed projection is not a failed run — the syllabus,
+   * which is the source of truth, is already saved — but callers that announce
+   * the manifest downstream must not report success on it.
+   */
+  manifestProjected: boolean | null;
+};
+
+function emptyResult(
+  status: GenerateCourseDescriptionsResult["status"]
+): GenerateCourseDescriptionsResult {
+  return {
+    status,
+    steps: 0,
+    generated: 0,
+    failed: 0,
+    missing: 0,
+    errors: [],
+    durationsSeconds: [],
+    manifestProjected: null,
+  }
+}
+
+/** Read every README of the course, keyed by exercise slug and language. */
+export async function readCourseReadmes(
+  storage: CourseDescriptionsStorage,
+  courseSlug: string,
+  exercises: CourseExercise[],
+  concurrency: number
+): Promise<CourseReadmes> {
+  const readmes: CourseReadmes = {}
+
+  const targets: Array<{ exerciseSlug: string; lang: string; file: string }> =
+    []
+  for (const exercise of exercises) {
+    for (const [lang, file] of Object.entries(exercise.translations || {})) {
+      targets.push({ exerciseSlug: exercise.slug, lang, file })
+    }
+  }
+
+  const contents = await mapWithConcurrency(targets, concurrency, target =>
+    storage.readReadme(courseSlug, target.exerciseSlug, target.file)
+  )
+
+  for (const [index, target] of targets.entries()) {
+    const content = contents[index]
+    if (typeof content !== "string") {
+      continue
+    }
+
+    if (!readmes[target.exerciseSlug]) {
+      readmes[target.exerciseSlug] = {}
+    }
+
+    readmes[target.exerciseSlug][target.lang] = content
+  }
+
+  return readmes
+}
+
+/** Ensure the translation slot exists before writing a description into it. */
+function ensureSlot(
+  lesson: Lesson,
+  lang: string
+): NonNullable<Lesson["translations"]>[string] {
+  if (!lesson.translations) {
+    lesson.translations = {}
+  }
+
+  if (!lesson.translations[lang]) {
+    lesson.translations[lang] = { completionId: 0, startedAt: Date.now() }
+  }
+
+  return lesson.translations[lang]
+}
+
+function applyStepResult(
+  step: StepWork,
+  result: TGenerateStepDescriptionsResult
+): { generated: number; missing: number } {
+  let generated = 0
+
+  for (const language of step.languages) {
+    if (!(language.lang in result.descriptionsByLanguage)) {
+      // Never answered: leave the slot untouched so a later run retries it.
+      // Writing a null plus a fingerprint here would look settled forever.
+      continue
+    }
+
+    const slot = ensureSlot(step.lesson, language.lang)
+    if (slot.descriptionSource === "human") {
+      continue
+    }
+
+    const description = result.descriptionsByLanguage[language.lang]
+    slot.description = description
+    slot.descriptionStatus = description ? "generated" : "none"
+    slot.descriptionSource = "auto"
+    slot.descriptionPromptVersion = result.promptVersion
+    slot.sourceContentHash = language.fingerprint.sha256
+    slot.sourceSimHash = language.fingerprint.simhash
+    generated += 1
+  }
+
+  return { generated, missing: result.missingLanguages.length }
+}
+
+export async function generateCourseDescriptions(
+  storage: CourseDescriptionsStorage,
+  courseSlug: string,
+  options: GenerateCourseDescriptionsOptions
+): Promise<GenerateCourseDescriptionsResult> {
+  const concurrency = options.concurrency ?? DEFAULT_DESCRIPTIONS_CONCURRENCY
+  const generate = options.generate ?? generateStepDescriptions
+
+  const syllabus = await storage.readSyllabus(courseSlug)
+  if (!syllabus) {
+    return emptyResult("skipped")
+  }
+
+  const exercises = await storage.listExercises(courseSlug)
+  if (exercises.length === 0) {
+    return emptyResult("skipped")
+  }
+
+  if (options.reconcile && storage.syllabusSyncStorage) {
+    try {
+      await synchronizeSyllabusWithBucket(
+        storage.syllabusSyncStorage,
+        courseSlug,
+        syllabus,
+        { prune: false }
+      )
+    } catch (error) {
+      // Provisional patch: never let reconciliation block generation.
+      console.error(
+        `[descriptions] Reconciliation failed for "${courseSlug}":`,
+        (error as Error).message
+      )
+    }
+  }
+
+  const readmes = await readCourseReadmes(
+    storage,
+    courseSlug,
+    exercises,
+    concurrency
+  )
+
+  const work = buildDescriptionWorkList({
+    syllabus,
+    exercises,
+    readmes,
+    promptVersion: options.promptVersion,
+    force: options.force,
+  })
+
+  if (work.length === 0) {
+    return emptyResult("skipped")
+  }
+
+  const result = emptyResult("processed")
+  result.steps = work.length
+
+  if (options.dryRun) {
+    result.generated = countWorkItems(work)
+    return result
+  }
+
+  // One completion per step, several in flight: a slow step never stalls the
+  // course and Rigobot is never hit with an unbounded burst.
+  const outcomes = await mapWithConcurrency(
+    work,
+    concurrency,
+    async step => ({
+      step,
+      generated: await generate(options.token, {
+        readmeContent: step.baseContent,
+        sourceLanguage: step.baseLanguage,
+        outputLanguages: step.languages.map(language => language.lang),
+        lessonTitle: step.lesson.title,
+        courseTitle: syllabus.courseInfo?.title,
+        targetWordCount: options.targetWordCount,
+        promptVersion: options.promptVersion,
+      }),
+    })
+  )
+
+  for (const outcome of outcomes) {
+    if (!outcome.generated) {
+      result.failed += 1
+      result.errors.push(
+        `generation failed for "${outcome.step.exerciseSlug}"`
+      )
+      continue
+    }
+
+    if (outcome.generated.durationSeconds !== null) {
+      result.durationsSeconds.push(outcome.generated.durationSeconds)
+    }
+
+    const applied = applyStepResult(outcome.step, outcome.generated)
+    result.generated += applied.generated
+    result.missing += applied.missing
+  }
+
+  if (result.generated === 0 && result.failed > 0) {
+    result.status = "failed"
+    return result
+  }
+
+  await storage.writeSyllabus(courseSlug, syllabus)
+
+  if (storage.reprojectManifest) {
+    try {
+      await storage.reprojectManifest(courseSlug)
+      result.manifestProjected = true
+    } catch (error) {
+      // The syllabus (the source of truth) is already saved; a failed
+      // projection is recoverable and must not lose the generated text.
+      result.manifestProjected = false
+      result.errors.push(
+        `manifest projection failed: ${(error as Error).message}`
+      )
+    }
+  }
+
+  return result
+}

package/src/utils/descriptions/mirrorDescriptions.ts

@@ -0,0 +1,191 @@
+import { Syllabus } from "../../models/creator"
+import { fingerprintReadme } from "../descriptionHash"
+import { DESCRIPTION_PROMPT_VERSION } from "../packageManifest"
+import {
+  CourseDescriptionsStorage,
+  readCourseReadmes,
+  DEFAULT_DESCRIPTIONS_CONCURRENCY,
+} from "./generateCourseDescriptions"
+import { CourseExercise, CourseReadmes, findSyllabusLesson } from "./workList"
+
+/**
+ * Copy descriptions from the published syllabus back into the draft one.
+ *
+ * Descriptions are generated against the published package because it is an
+ * immutable snapshot. The draft in GCS, meanwhile, keeps moving: between the
+ * publication and the moment the descriptions land, steps may have been added,
+ * removed, renamed, reordered or edited.
+ *
+ * The guard against that drift is the content hash, not a timestamp or a
+ * position: a description is copied only when the draft README hashes to the
+ * very content the description was generated from. Anything that moved simply
+ * misses and waits for the next publication — a stale description is never
+ * written onto content it does not describe.
+ *
+ * Without this mirror the draft would never hold a description, and every
+ * publication would regenerate the whole course from scratch: the freshness
+ * check reads the fingerprints stored in the syllabus that travels inside the
+ * zip.
+ */
+
+export type MirrorResult = {
+  /** (step, language) pairs copied into the draft. */
+  copied: number;
+  /** Pairs with no reusable description: content moved on, or none published. */
+  missed: number;
+  /** Pairs the draft already had up to date. */
+  fresh: number;
+};
+
+export type MirrorOptions = {
+  promptVersion?: number;
+  dryRun?: boolean;
+  concurrency?: number;
+};
+
+function emptyMirrorResult(): MirrorResult {
+  return { copied: 0, missed: 0, fresh: 0 }
+}
+
+/**
+ * Pure core: writes into `targetSyllabus` in place. Callers own the I/O, which
+ * keeps the drift rules testable without a bucket.
+ */
+export function mirrorDescriptionsIntoSyllabus(input: {
+  sourceSyllabus: Syllabus | null;
+  targetSyllabus: Syllabus;
+  exercises: CourseExercise[];
+  /** READMEs of the TARGET (draft), which is what must match the hash. */
+  readmes: CourseReadmes;
+  promptVersion?: number;
+}): MirrorResult {
+  const result = emptyMirrorResult()
+  if (!input.sourceSyllabus) {
+    return result
+  }
+
+  const promptVersion = input.promptVersion ?? DESCRIPTION_PROMPT_VERSION
+
+  for (const exercise of input.exercises) {
+    const targetLesson = findSyllabusLesson(
+      input.targetSyllabus,
+      exercise.slug
+    )
+    if (!targetLesson) {
+      // The step is not in the draft (removed, or renamed after publishing).
+      continue
+    }
+
+    const sourceLesson = findSyllabusLesson(
+      input.sourceSyllabus,
+      exercise.slug
+    )
+    const exerciseReadmes = input.readmes[exercise.slug] || {}
+
+    for (const lang of Object.keys(exercise.translations || {})) {
+      const content = exerciseReadmes[lang]
+      if (typeof content !== "string") {
+        continue
+      }
+
+      const fingerprint = fingerprintReadme(content)
+      const targetSlot = targetLesson.translations?.[lang]
+
+      if (targetSlot?.descriptionSource === "human") {
+        result.fresh += 1
+        continue
+      }
+
+      if (
+        targetSlot?.sourceContentHash === fingerprint.sha256 &&
+        (targetSlot?.descriptionPromptVersion ?? 0) >= promptVersion
+      ) {
+        result.fresh += 1
+        continue
+      }
+
+      const sourceSlot = sourceLesson?.translations?.[lang]
+      // The hash guard: only reuse a description generated from exactly this
+      // content. Note a published `description: null` is reusable too — it is a
+      // real answer ("not enough content to describe"), not a missing one.
+      const reusable =
+        sourceSlot !== undefined &&
+        sourceSlot.sourceContentHash === fingerprint.sha256 &&
+        (sourceSlot.descriptionPromptVersion ?? 0) >= promptVersion &&
+        sourceSlot.descriptionStatus !== "error"
+
+      if (!reusable) {
+        result.missed += 1
+        continue
+      }
+
+      if (!targetLesson.translations) {
+        targetLesson.translations = {}
+      }
+
+      if (!targetLesson.translations[lang]) {
+        targetLesson.translations[lang] = {
+          completionId: 0,
+          startedAt: Date.now(),
+        }
+      }
+
+      const destination = targetLesson.translations[lang]
+      destination.description = sourceSlot.description ?? null
+      destination.descriptionStatus = sourceSlot.description ?
+        "generated" :
+        "none"
+      destination.descriptionSource = "auto"
+      destination.descriptionPromptVersion =
+        sourceSlot.descriptionPromptVersion ?? promptVersion
+      destination.sourceContentHash = fingerprint.sha256
+      destination.sourceSimHash = fingerprint.simhash
+      result.copied += 1
+    }
+  }
+
+  return result
+}
+
+/** Read the draft, mirror into it, and save it when something changed. */
+export async function mirrorDescriptionsToDraft(
+  storage: CourseDescriptionsStorage,
+  courseSlug: string,
+  sourceSyllabus: Syllabus | null,
+  options: MirrorOptions = {}
+): Promise<MirrorResult> {
+  if (!sourceSyllabus) {
+    return emptyMirrorResult()
+  }
+
+  const targetSyllabus = await storage.readSyllabus(courseSlug)
+  if (!targetSyllabus) {
+    return emptyMirrorResult()
+  }
+
+  const exercises = await storage.listExercises(courseSlug)
+  if (exercises.length === 0) {
+    return emptyMirrorResult()
+  }
+
+  const readmes = await readCourseReadmes(
+    storage,
+    courseSlug,
+    exercises,
+    options.concurrency ?? DEFAULT_DESCRIPTIONS_CONCURRENCY
+  )
+
+  const result = mirrorDescriptionsIntoSyllabus({
+    sourceSyllabus,
+    targetSyllabus,
+    exercises,
+    readmes,
+    promptVersion: options.promptVersion,
+  })
+
+  if (result.copied > 0 && !options.dryRun) {
+    await storage.writeSyllabus(courseSlug, targetSyllabus)
+  }
+
+  return result
+}