@thanh01.pmt/curriculum-kit 1.0.0

package/dist/media/index.cjs

@@ -0,0 +1,1238 @@
+'use strict';
+
+var fs = require('fs');
+var path2 = require('path');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var fs__default = /*#__PURE__*/_interopDefault(fs);
+var path2__default = /*#__PURE__*/_interopDefault(path2);
+
+// src/media/types.ts
+var MediaError = class extends Error {
+  constructor(message, provider, status) {
+    super(message);
+    this.provider = provider;
+    this.status = status;
+    this.name = "MediaError";
+  }
+};
+function buildImagePrompt(options) {
+  const { prompt, context, style = "educational-diagram" } = options;
+  const parts = [];
+  const styleMap = {
+    "educational-diagram": "clean educational diagram, labeled parts, high contrast, suitable for K-12 textbook",
+    "realistic-photo": "realistic photograph, natural lighting, educational context",
+    "flat-illustration": "flat vector illustration, friendly shapes, modern educational style",
+    "technical-schematic": "precise technical schematic, wiring-style clarity, engineering drawing conventions"
+  };
+  parts.push(prompt);
+  if (context?.concept) parts.push(`Subject concept: ${context.concept}`);
+  if (context?.lessonTitle) parts.push(`From lesson: ${context.lessonTitle}`);
+  if (context?.gradeBand) {
+    const band = Array.isArray(context.gradeBand) ? context.gradeBand : [context.gradeBand, context.gradeBand];
+    parts.push(`Audience: grade ${band[0]}-${band[1]} students, age-appropriate, no scary or unsafe imagery`);
+  }
+  if (context?.styleGuideExcerpt) parts.push(`Visual style guide: ${context.styleGuideExcerpt.slice(0, 200)}`);
+  parts.push(styleMap[style] || styleMap["educational-diagram"]);
+  if (options.aspectRatio === "16:9") parts.push("wide 16:9 composition");
+  return parts.join(". ");
+}
+
+// src/media/imageProviders.ts
+function resolveApiKey(options) {
+  const provider = options.provider || "openai";
+  const key = options.apiKey || (provider === "openai" ? process.env.OPENAI_API_KEY : void 0) || (provider === "gemini" ? process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY : void 0) || "";
+  if (!key) {
+    throw new MediaError(`API key missing for image provider '${provider}'. Set GEMINI_API_KEY or OPENAI_API_KEY.`, provider);
+  }
+  return { provider, key };
+}
+async function generateWithGemini(options, key) {
+  const finalPrompt = buildImagePrompt(options);
+  const model = "gemini-2.0-flash-exp";
+  const res = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${key}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      contents: [{ parts: [{ text: finalPrompt }] }],
+      generationConfig: { responseModalities: ["TEXT", "IMAGE"] }
+    }),
+    signal: AbortSignal.timeout(9e4)
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new MediaError(`Gemini image API ${res.status}: ${body.slice(0, 300)}`, "gemini", res.status);
+  }
+  const data = await res.json();
+  const parts = data?.candidates?.[0]?.content?.parts || [];
+  const imagePart = parts.find((p) => p.inlineData?.data);
+  if (!imagePart) {
+    throw new MediaError("Gemini returned no image part (may have refused prompt).", "gemini");
+  }
+  const textPart = parts.find((p) => p.text);
+  return {
+    base64: imagePart.inlineData.data,
+    mimeType: imagePart.inlineData.mimeType || "image/png",
+    provider: "gemini",
+    prompt: finalPrompt,
+    revisedPrompt: textPart?.text
+  };
+}
+async function generateWithOpenAI(options, key) {
+  const finalPrompt = buildImagePrompt(options);
+  const sizeMap = { "1:1": "1024x1024", "16:9": "1536x1024", "4:3": "1024x1024", "3:4": "1024x1536" };
+  const res = await fetch("https://api.openai.com/v1/images/generations", {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
+    body: JSON.stringify({
+      model: "gpt-image-1",
+      prompt: finalPrompt,
+      size: sizeMap[options.aspectRatio || "1:1"] || "1024x1024",
+      n: 1
+    }),
+    signal: AbortSignal.timeout(9e4)
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new MediaError(`OpenAI image API ${res.status}: ${body.slice(0, 300)}`, "openai", res.status);
+  }
+  const data = await res.json();
+  const item = data?.data?.[0];
+  if (!item?.b64_json) {
+    throw new MediaError("OpenAI returned no image data.", "openai");
+  }
+  return {
+    base64: item.b64_json,
+    mimeType: "image/png",
+    provider: "openai",
+    prompt: finalPrompt,
+    revisedPrompt: item.revised_prompt
+  };
+}
+async function generateEducationalImage(options) {
+  const { provider, key } = resolveApiKey(options);
+  if (provider === "openai") return generateWithOpenAI(options, key);
+  return generateWithGemini(options, key);
+}
+
+// src/media/stockSearch.ts
+async function searchEducationalImages(options) {
+  const key = options.apiKey || process.env.PEXELS_API_KEY || "";
+  if (!key) throw new MediaError("Pexels API key missing. Set PEXELS_API_KEY.", "pexels");
+  const params = new URLSearchParams({
+    query: options.query,
+    per_page: String(options.perPage ?? 6),
+    orientation: options.orientation || "landscape"
+  });
+  const res = await fetch(`https://api.pexels.com/v1/search?${params}`, {
+    headers: { Authorization: key },
+    signal: AbortSignal.timeout(3e4)
+  });
+  if (!res.ok) {
+    throw new MediaError(`Pexels image search ${res.status}`, "pexels", res.status);
+  }
+  const data = await res.json();
+  return (data?.photos || []).map((p) => ({
+    url: p.src?.large2x || p.src?.large || p.src?.original,
+    thumbnailUrl: p.src?.medium,
+    width: p.width,
+    height: p.height,
+    photographer: p.photographer,
+    source: "pexels",
+    license: "Pexels License (free to use, attribution appreciated)",
+    pageUrl: p.url,
+    altText: p.alt
+  }));
+}
+async function searchEducationalVideos(options) {
+  const key = options.apiKey || process.env.PEXELS_API_KEY || "";
+  if (!key) throw new MediaError("Pexels API key missing. Set PEXELS_API_KEY.", "pexels");
+  const params = new URLSearchParams({
+    query: options.query,
+    per_page: String(options.perPage ?? 4),
+    orientation: "landscape"
+  });
+  const res = await fetch(`https://api.pexels.com/videos/search?${params}`, {
+    headers: { Authorization: key },
+    signal: AbortSignal.timeout(3e4)
+  });
+  if (!res.ok) {
+    throw new MediaError(`Pexels video search ${res.status}`, "pexels", res.status);
+  }
+  const data = await res.json();
+  return (data?.videos || []).map((v) => {
+    const files = v.video_files || [];
+    const best = files.filter((f) => f.quality === "hd").sort((a, b) => (a.width || 0) - (b.width || 0))[0] || files[0];
+    return {
+      url: best?.link,
+      thumbnailUrl: v.image,
+      durationSeconds: v.duration,
+      width: best?.width,
+      height: best?.height,
+      source: "pexels",
+      license: "Pexels License (free to use, attribution appreciated)",
+      pageUrl: v.url
+    };
+  });
+}
+var MediaLedger = class {
+  filePath;
+  entries = /* @__PURE__ */ new Map();
+  constructor(projectDir, lessonId) {
+    this.filePath = path2__default.default.join(projectDir, "_media", `ledger-${lessonId.toUpperCase()}.jsonl`);
+    this.load();
+  }
+  load() {
+    this.entries.clear();
+    if (!fs__default.default.existsSync(this.filePath)) return;
+    const lines = fs__default.default.readFileSync(this.filePath, "utf-8").split("\n");
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const e = JSON.parse(trimmed);
+        this.entries.set(e.slug, e);
+      } catch {
+      }
+    }
+  }
+  persist() {
+    fs__default.default.mkdirSync(path2__default.default.dirname(this.filePath), { recursive: true });
+    fs__default.default.writeFileSync(this.filePath, Array.from(this.entries.values()).map((e) => JSON.stringify(e)).join("\n") + "\n", "utf-8");
+  }
+  /** Agent tạo artifact ghi entry mới (hoặc cập nhật nếu slug đã có và chưa done) */
+  upsert(input) {
+    const existing = this.entries.get(input.slug);
+    if (existing && existing.status === "done") return existing;
+    const entry = { ...input, status: input.status ?? "pending", updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+    this.entries.set(input.slug, entry);
+    this.persist();
+    return entry;
+  }
+  get(slug) {
+    return this.entries.get(slug);
+  }
+  list() {
+    return Array.from(this.entries.values());
+  }
+  listByStatus(status) {
+    return this.list().filter((e) => e.status === status);
+  }
+  pending() {
+    return this.listByStatus("pending");
+  }
+  setStatus(slug, status, patch = {}) {
+    const e = this.entries.get(slug);
+    if (!e) return void 0;
+    Object.assign(e, patch, { status, updatedAt: (/* @__PURE__ */ new Date()).toISOString() });
+    if (status === "failed") e.retryCount = (e.retryCount ?? 0) + 1;
+    this.entries.set(slug, e);
+    this.persist();
+    return e;
+  }
+  /** Đếm ảnh đã done trong lesson — để Curator tôn trọng maxImages */
+  doneCount() {
+    return this.listByStatus("done").length;
+  }
+};
+
+// src/errors/index.ts
+var CurriculumError = class _CurriculumError extends Error {
+  detail;
+  constructor(detail) {
+    super(`[${detail.errorCode}] ${detail.message}`);
+    this.name = "CurriculumError";
+    this.detail = {
+      ...detail,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    Object.setPrototypeOf(this, _CurriculumError.prototype);
+  }
+  get errorCode() {
+    return this.detail.errorCode;
+  }
+  get retryable() {
+    return this.detail.retryable;
+  }
+  get suggestedAction() {
+    return this.detail.suggestedAction;
+  }
+  toJSON() {
+    return this.detail;
+  }
+};
+function createAiInferenceError(params) {
+  const {
+    errorCode,
+    message,
+    provider,
+    statusCode,
+    agent,
+    artifactType,
+    lessonId,
+    rawError,
+    suggestedAction = getSuggestedActionForCode(errorCode),
+    retryable = isCodeRetryable(errorCode)
+  } = params;
+  return new CurriculumError({
+    errorCode,
+    message,
+    provider,
+    statusCode,
+    agent,
+    artifactType,
+    lessonId,
+    suggestedAction,
+    retryable,
+    rawError: typeof rawError === "string" ? rawError : rawError?.message || JSON.stringify(rawError)
+  });
+}
+function getSuggestedActionForCode(code) {
+  switch (code) {
+    case "ERR_AI_NO_API_KEY":
+      return "V\xE0o Settings > API Keys \u0111\u1EC3 c\u1EA5u h\xECnh \xEDt nh\u1EA5t m\u1ED9t kh\xF3a API (Gemini, DeepSeek, OpenRouter, Alibaba ho\u1EB7c NVIDIA).";
+    case "ERR_AI_RATE_LIMIT":
+      return "API \u0111\xE3 v\u01B0\u1EE3t qu\xE1 gi\u1EDBi h\u1EA1n l\u01B0\u1EE3t g\u1ECDi (Rate Limit HTTP 429). H\xE3y ch\u1EDD 30-60 gi\xE2y r\u1ED3i b\u1EA5m Rerun ho\u1EB7c chuy\u1EC3n sang Provider d\u1EF1 ph\xF2ng.";
+    case "ERR_AI_AUTH_FAILED":
+      return "API Key kh\xF4ng h\u1EE3p l\u1EC7 ho\u1EB7c \u0111\xE3 h\u1EBFt h\u1EA1n (HTTP 401/403). Vui l\xF2ng ki\u1EC3m tra l\u1EA1i Key trong m\u1EE5c C\xE0i \u0111\u1EB7t.";
+    case "ERR_AI_NETWORK_TIMEOUT":
+      return "K\u1EBFt n\u1ED1i m\u1EA1ng t\u1EDBi m\xE1y ch\u1EE7 AI b\u1ECB qu\xE1 th\u1EDDi gian ch\u1EDD (Timeout). Vui l\xF2ng ki\u1EC3m tra \u0111\u01B0\u1EDDng truy\u1EC1n v\xE0 b\u1EA5m Rerun.";
+    case "ERR_AI_RESPONSE_MALFORMED":
+      return "M\xF4 h\xECnh AI tr\u1EA3 v\u1EC1 k\u1EBFt qu\u1EA3 r\u1ED7ng ho\u1EB7c kh\xF4ng \u0111\xFAng \u0111\u1ECBnh d\u1EA1ng markdown. B\u1EA5m Rerun \u0111\u1EC3 y\xEAu c\u1EA7u AI sinh l\u1EA1i.";
+    case "ERR_AI_ALL_PROVIDERS_FAILED":
+      return "To\xE0n b\u1ED9 c\xE1c nh\xE0 cung c\u1EA5p trong chu\u1ED7i Fallback \u0111\u1EC1u th\u1EA5t b\u1EA1i. Vui l\xF2ng ki\u1EC3m tra k\u1EBFt n\u1ED1i Internet v\xE0 h\u1EA1n m\u1EE9c Token.";
+    case "ERR_SOT_MISSING":
+      return "Thi\u1EBFu t\xE0i li\u1EC7u n\u1EC1n t\u1EA3ng SOT (CURRICULUM_FRAMEWORK.md ho\u1EB7c LEARNER_PROFILE.md). H\xE3y ch\u1EA1y workflow Kh\u1EDFi t\u1EA1o d\u1EF1 \xE1n tr\u01B0\u1EDBc.";
+    case "ERR_TASK_GATE_BLOCKED":
+      return "H\u1ECDc li\u1EC7u ph\xEDa sau b\u1ECB ch\u1EB7n do Gi\xE1o \xE1n (LESSON) ph\xEDa tr\u01B0\u1EDBc ch\u01B0a \u0111\u01B0\u1EE3c Ph\xEA duy\u1EC7t (Approval Gate). H\xE3y b\u1EA5m Ph\xEA duy\u1EC7t Gi\xE1o \xE1n \u0111\u1EC3 m\u1EDF kh\xF3a.";
+    case "ERR_METERED_LIMIT_EXCEEDED":
+      return "Ch\xEDnh s\xE1ch Metered Execution gi\u1EDBi h\u1EA1n t\u1ED1i \u0111a 2 b\xE0i h\u1ECDc m\u1ED7i \u0111\u1EE3t. Vui l\xF2ng ph\xEA duy\u1EC7t c\xE1c b\xE0i hi\u1EC7n t\u1EA1i tr\u01B0\u1EDBc khi t\u1EA1o th\xEAm.";
+    case "ERR_SCHEMA_CONTRACT_VIOLATION":
+      return "N\u1ED9i dung sinh ra thi\u1EBFu c\xE1c ph\u1EA7n b\u1EAFt bu\u1ED9c [REQUIRED]. H\xE3y k\xEDch ho\u1EA1t ki\u1EC3m th\u1EED ho\u1EB7c b\u1EA5m Rerun.";
+    case "ERR_STORAGE_IO_FAILED":
+      return "L\u1ED7i \u0111\u1ECDc/ghi t\u1EC7p tin tr\xEAn h\u1EC7 th\u1ED1ng l\u01B0u tr\u1EEF. Ki\u1EC3m tra quy\u1EC1n ghi th\u01B0 m\u1EE5c output/projects.";
+    default:
+      return "B\u1EA5m Rerun \u0111\u1EC3 th\u1EED l\u1EA1i ho\u1EB7c ki\u1EC3m tra nh\u1EADt k\xFD h\u1EC7 th\u1ED1ng.";
+  }
+}
+function isCodeRetryable(code) {
+  switch (code) {
+    case "ERR_AI_RATE_LIMIT":
+    case "ERR_AI_NETWORK_TIMEOUT":
+    case "ERR_AI_RESPONSE_MALFORMED":
+    case "ERR_STORAGE_IO_FAILED":
+      return true;
+    case "ERR_AI_NO_API_KEY":
+    case "ERR_AI_AUTH_FAILED":
+    case "ERR_SOT_MISSING":
+    case "ERR_TASK_GATE_BLOCKED":
+    case "ERR_METERED_LIMIT_EXCEEDED":
+    case "ERR_SCHEMA_CONTRACT_VIOLATION":
+      return false;
+    default:
+      return true;
+  }
+}
+function resolveApiKey2(keyName, explicitKey) {
+  if (explicitKey && explicitKey.trim()) return explicitKey.trim();
+  if (typeof process !== "undefined" && process.env && process.env[keyName]) {
+    return process.env[keyName];
+  }
+  try {
+    const currentDir = process.cwd();
+    const envPaths = [
+      path2__default.default.resolve(currentDir, ".env.local"),
+      path2__default.default.resolve(currentDir, ".env"),
+      path2__default.default.resolve(currentDir, "apps/web/.env.local"),
+      path2__default.default.resolve(currentDir, "packages/learnwell-platform/.env"),
+      path2__default.default.resolve(currentDir, "..", ".env.local"),
+      path2__default.default.resolve(currentDir, "..", ".env"),
+      path2__default.default.resolve(currentDir, "../..", ".env.local"),
+      path2__default.default.resolve(currentDir, "../..", ".env")
+    ];
+    for (const envPath of envPaths) {
+      if (fs__default.default.existsSync(envPath)) {
+        const content = fs__default.default.readFileSync(envPath, "utf-8");
+        for (const line of content.split("\n")) {
+          const trimmed = line.trim();
+          if (trimmed && !trimmed.startsWith("#") && trimmed.startsWith(keyName + "=")) {
+            return trimmed.substring(keyName.length + 1).trim().replace(/^["']|["']$/g, "");
+          }
+        }
+      }
+    }
+  } catch {
+  }
+  return "";
+}
+function isProviderEnabled(provider) {
+  const p = provider.toLowerCase();
+  const explicitVal = resolveApiKey2(`ENABLE_${p.toUpperCase()}`);
+  if (explicitVal !== "") {
+    return explicitVal === "true" || explicitVal === "1";
+  }
+  const allowedList = resolveApiKey2("ALLOWED_AI_PROVIDERS");
+  if (allowedList && allowedList.trim()) {
+    const allowed = allowedList.split(",").map((s) => s.trim().toLowerCase());
+    return allowed.includes(p);
+  }
+  const disabledList = resolveApiKey2("DISABLED_AI_PROVIDERS");
+  if (disabledList && disabledList.trim()) {
+    const disabled = disabledList.split(",").map((s) => s.trim().toLowerCase());
+    if (disabled.includes(p)) return false;
+  }
+  return true;
+}
+function isModelAllowed(model) {
+  const allowedList = resolveApiKey2("ALLOWED_AI_MODELS");
+  if (!allowedList || !allowedList.trim()) return true;
+  const patterns = allowedList.split(",").map((s) => s.trim());
+  return patterns.some((pattern) => {
+    if (pattern === "*" || pattern === model) return true;
+    if (pattern.endsWith("*") && model.startsWith(pattern.slice(0, -1))) return true;
+    if (pattern.startsWith("*") && model.endsWith(pattern.slice(1))) return true;
+    return false;
+  });
+}
+function getDesignatedFallbackChain() {
+  const rawProviders = resolveApiKey2("FALLBACK_AI_PROVIDER") || resolveApiKey2("FALLBACK_AI_PROVIDERS") || resolveApiKey2("DEFAULT_AI_PROVIDER") || "nvidia,openrouter";
+  const rawModels = resolveApiKey2("FALLBACK_AI_MODEL") || resolveApiKey2("FALLBACK_AI_MODELS") || resolveApiKey2("DEFAULT_AI_MODEL") || "nvidia/nemotron-3-ultra-550b-a55b,@preset/coding-free,deepseek/deepseek-chat:free";
+  const providerList = rawProviders.split(",").map((p) => p.trim().toLowerCase()).filter((p) => p.length > 0 && isProviderEnabled(p));
+  const modelList = rawModels.split(",").map((m) => m.trim()).filter((m) => m.length > 0 && isModelAllowed(m));
+  const chain = [];
+  for (const provider of providerList) {
+    let providerModels = [];
+    if (provider === "nvidia") {
+      providerModels = modelList.filter((m) => m.startsWith("nvidia/") || m.startsWith("meta/") || m.startsWith("mistralai/"));
+      if (providerModels.length === 0) {
+        providerModels = ["nvidia/nemotron-3-ultra-550b-a55b", "nvidia/nemotron-3.5-lightning-30b-a3b"];
+      }
+    } else if (provider === "openrouter") {
+      providerModels = modelList.filter((m) => m.startsWith("@") || m.includes("/") || m.includes(":"));
+      if (providerModels.length === 0) {
+        providerModels = ["@preset/coding-free", "deepseek/deepseek-chat:free", "meta-llama/llama-3.3-70b-instruct:free"];
+      }
+    } else if (provider === "alibaba" || provider === "dashscope") {
+      providerModels = modelList.filter((m) => m.startsWith("qwen") || m.includes("deepseek"));
+      if (providerModels.length === 0) {
+        providerModels = ["deepseek-v4-flash-0731", "qwen-plus", "qwen3.7-plus"];
+      }
+    } else if (provider === "google" || provider === "gemini") {
+      providerModels = modelList.filter((m) => m.startsWith("gemini"));
+      if (providerModels.length === 0) {
+        providerModels = ["gemini-2.0-flash", "gemini-1.5-flash"];
+      }
+    } else if (provider === "deepseek") {
+      providerModels = modelList.filter((m) => m.startsWith("deepseek"));
+      if (providerModels.length === 0) {
+        providerModels = ["deepseek-chat", "deepseek-reasoner"];
+      }
+    } else {
+      providerModels = modelList.length > 0 ? modelList : ["default"];
+    }
+    for (const model of providerModels) {
+      if (!chain.some((c) => c.provider === provider && c.model === model)) {
+        chain.push({ provider, model });
+      }
+    }
+  }
+  return chain;
+}
+function extractThoughtAndContent(rawText) {
+  let text = rawText || "";
+  let thought = "";
+  const thinkMatch = text.match(/<think>([\s\S]*?)<\/think>/i);
+  if (thinkMatch) {
+    thought = thinkMatch[1].trim();
+    text = text.replace(/<think>[\s\S]*?<\/think>/gi, "").trim();
+  } else if (text.includes("<think>")) {
+    const parts = text.split("<think>");
+    text = parts[0].trim();
+    thought = parts[1].trim();
+  }
+  if (!thought && (text.startsWith("Here's a thinking process:") || text.startsWith("Thinking Process:"))) {
+    const splitRegex = /\n(?=(?:#|##|###|🎯|🧭|📋|🚀|1\.\s+[A-Z\u00C0-\u1EF9]|---))/m;
+    const match = text.search(splitRegex);
+    if (match > 0) {
+      thought = text.slice(0, match).trim();
+      text = text.slice(match).trim();
+    }
+  }
+  let content = text.trim();
+  if (content.startsWith("```markdown")) {
+    content = content.replace(/^```markdown\s*\n/i, "").replace(/\n```\s*$/i, "");
+  } else if (content.startsWith("```md")) {
+    content = content.replace(/^```md\s*\n/i, "").replace(/\n```\s*$/i, "");
+  } else if (content.startsWith("```") && content.endsWith("```") && !content.includes("---")) {
+    content = content.replace(/^```\w*\s*\n/i, "").replace(/\n```\s*$/i, "");
+  }
+  return {
+    thought: thought.trim(),
+    content: content.trim()
+  };
+}
+function createIdleAbortController(idleMs) {
+  const controller = new AbortController();
+  let timer = null;
+  const arm = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(
+      () => controller.abort(new Error(`Idle timeout: no data for ${Math.round(idleMs / 1e3)}s`)),
+      idleMs
+    );
+    timer?.unref?.();
+  };
+  arm();
+  return {
+    signal: controller.signal,
+    /** Reset the idle window (call on every received chunk). */
+    kick: arm,
+    /** Clear the pending timer once the request lifecycle is over. */
+    dispose: () => {
+      if (timer) clearTimeout(timer);
+      timer = null;
+    }
+  };
+}
+async function processOpenAISSEStream(response, onChunk, idle, toolCallCollector) {
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let fullRaw = "";
+  let buffer = "";
+  let insideThinkTag = false;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    idle?.kick();
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split("\n");
+    buffer = lines.pop() || "";
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith(":")) continue;
+      if (trimmed === "data: [DONE]") continue;
+      if (trimmed.startsWith("data: ")) {
+        try {
+          const json = JSON.parse(trimmed.substring(6));
+          if (json.usage) {
+            const promptTokens = json.usage.prompt_tokens || json.usage.input_tokens || 0;
+            const completionTokens = json.usage.completion_tokens || json.usage.output_tokens || 0;
+            const totalTokens = json.usage.total_tokens || promptTokens + completionTokens;
+            const reasoningTokens = json.usage.completion_tokens_details?.reasoning_tokens || 0;
+            if (onChunk) ;
+          }
+          const delta = json.choices?.[0]?.delta;
+          if (!delta) continue;
+          const reasoning = delta.reasoning_content || delta.thought || delta.reasoning || delta.thought_process || "";
+          if (reasoning) {
+            if (onChunk) ;
+          }
+          if (delta.tool_calls) {
+            const toolStr = JSON.stringify(delta.tool_calls);
+            if (onChunk) ;
+            if (toolCallCollector) ;
+          }
+          let content = delta.content || "";
+          if (content) {
+            fullRaw += content;
+            if (content.includes("<think>")) {
+              insideThinkTag = true;
+              const parts = content.split("<think>");
+              if (parts[0] && onChunk) onChunk(parts[0], "content");
+              content = parts[1] || "";
+            }
+            if (content.includes("</think>")) {
+              insideThinkTag = false;
+              const parts = content.split("</think>");
+              if (parts[0] && onChunk) ;
+              content = parts[1] || "";
+            }
+            if (insideThinkTag) {
+              if (onChunk && content) ;
+            } else if (content) {
+              if (onChunk) ;
+            }
+          }
+        } catch {
+        }
+      }
+    }
+  }
+  idle?.dispose();
+  const extracted = extractThoughtAndContent(fullRaw);
+  return extracted.content || fullRaw;
+}
+async function processGeminiSSEStream(response, onChunk, idle) {
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let fullText = "";
+  let buffer = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    idle?.kick();
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split("\n");
+    buffer = lines.pop() || "";
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith(":")) continue;
+      if (trimmed.startsWith("data: ")) {
+        try {
+          const json = JSON.parse(trimmed.substring(6));
+          if (json.usageMetadata) {
+            const promptTokens = json.usageMetadata.promptTokenCount || 0;
+            const completionTokens = json.usageMetadata.candidatesTokenCount || 0;
+            const totalTokens = json.usageMetadata.totalTokenCount || promptTokens + completionTokens;
+            if (onChunk) ;
+          }
+          const parts = json.candidates?.[0]?.content?.parts || [];
+          for (const part of parts) {
+            if (part.thought) {
+              if (onChunk) ;
+            } else if (part.text) {
+              fullText += part.text;
+              if (onChunk) ;
+            }
+          }
+        } catch {
+        }
+      }
+    }
+  }
+  idle?.dispose();
+  return fullText;
+}
+async function streamCurriculumAIInference(messages, projectContext, options = {}, onChunk) {
+  const openrouterKey = resolveApiKey2("OPENROUTER_API_KEY", options.openrouterKey);
+  const deepseekKey = resolveApiKey2("DEEPSEEK_API_KEY", options.deepseekKey);
+  const alibabaKey = resolveApiKey2("ALIBABA_API_KEY", options.alibabaKey) || resolveApiKey2("DASHSCOPE_API_KEY");
+  const geminiKey = resolveApiKey2("GEMINI_API_KEY", options.geminiKey) || resolveApiKey2("NEXT_PUBLIC_GEMINI_API_KEY");
+  const nvidiaKey = resolveApiKey2("NVIDIA_API_KEY", options.nvidiaKey);
+  const temperature = options.temperature ?? 0.3;
+  const maxTokens = options.maxTokens ?? 32768;
+  const basePersona = options.systemPersona || "You are Curriculum OS Assistant \u2014 Senior AI Technical Curriculum Architect & Educational Content Specialist.";
+  const systemInstruction = `${basePersona}
+
+Project Context:
+${projectContext}
+
+Guidelines:
+1. You have full context of the project hierarchy, syllabus, lessons, and learning objectives. Answer precisely, deeply, and directly.
+2. Complete responses fully without truncation. When generating tables or roadmaps, include all sections/milestones.
+3. Keep technical terminology and official API symbols intact.
+4. Format output using clean Markdown, clear sections, bullet points, and code blocks where required.
+5. Do NOT use emojis in headings, tab titles, or UI navigation labels.`;
+  const formattedMessages = [
+    { role: "system", content: systemInstruction },
+    ...messages.map((m) => ({
+      role: m.role === "assistant" || m.role === "model" ? "assistant" : "user",
+      content: m.content
+    }))
+  ];
+  const providerErrors = {};
+  const requestedModel = options.model || "@preset/coding-free";
+  const isNvidiaPreferred = requestedModel.startsWith("nvidia/") || Boolean(nvidiaKey && !openrouterKey) && isProviderEnabled("nvidia");
+  if (nvidiaKey && isProviderEnabled("nvidia")) {
+    const candidateNemotronModels = [
+      requestedModel.startsWith("nvidia/") ? requestedModel : "nvidia/nemotron-3-ultra-550b-a55b",
+      "nvidia/nemotron-3-ultra-550b-a55b",
+      "nvidia/nemotron-3.5-lightning-30b-a3b",
+      "nvidia/nemotron-3-super-120b-a12b",
+      "nvidia/llama-3.1-nemotron-70b-instruct"
+    ].filter((m) => isModelAllowed(m));
+    const uniqueNvidiaModels = Array.from(new Set(candidateNemotronModels));
+    if (isNvidiaPreferred || uniqueNvidiaModels.length > 0) {
+      for (const model of uniqueNvidiaModels) {
+        try {
+          const idle = createIdleAbortController(18e4);
+          const res = await fetch("https://integrate.api.nvidia.com/v1/chat/completions", {
+            method: "POST",
+            headers: {
+              "Authorization": `Bearer ${nvidiaKey}`,
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+              model,
+              messages: formattedMessages,
+              max_tokens: maxTokens,
+              temperature,
+              stream: true,
+              stream_options: { include_usage: true }
+            }),
+            signal: idle.signal
+          });
+          if (res.ok) {
+            const text = await processOpenAISSEStream(res, onChunk, idle);
+            if (text && text.trim()) return text;
+          } else {
+            const errText = await res.text().catch(() => "");
+            providerErrors[`nvidia_${model}`] = `HTTP ${res.status}: ${errText.slice(0, 120)}`;
+          }
+        } catch (e) {
+          providerErrors[`nvidia_${model}`] = e?.message || "Network error";
+          console.warn(`[NVIDIA Stream] Failover for ${model}:`, e?.message || e);
+        }
+      }
+    }
+  }
+  if (openrouterKey && isProviderEnabled("openrouter")) {
+    const openrouterModels = [
+      requestedModel,
+      "openrouter/free",
+      "nvidia/nemotron-3-super-120b-a12b:free",
+      "nvidia/nemotron-3-ultra-550b-a55b:free",
+      "nvidia/nemotron-3.5-lightning:free",
+      "minimax/minimax-m3:free",
+      "cohere/north-mini-code:free"
+    ].filter((m) => isModelAllowed(m));
+    const uniqueOrModels = Array.from(new Set(openrouterModels));
+    for (const model of uniqueOrModels) {
+      try {
+        const idle = createIdleAbortController(18e4);
+        const res = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+          method: "POST",
+          headers: {
+            "Authorization": `Bearer ${openrouterKey}`,
+            "Content-Type": "application/json",
+            "HTTP-Referer": "https://orchable.composer",
+            "X-Title": "Curriculum OS Studio"
+          },
+          body: JSON.stringify({
+            model,
+            messages: formattedMessages,
+            max_tokens: maxTokens,
+            temperature,
+            stream: true,
+            stream_options: { include_usage: true }
+          }),
+          signal: idle.signal
+        });
+        if (res.ok) {
+          const text = await processOpenAISSEStream(res, onChunk, idle);
+          if (text && text.trim()) return text;
+        } else {
+          const errText = await res.text().catch(() => "");
+          providerErrors[`openrouter_${model}`] = `HTTP ${res.status}: ${errText.slice(0, 120)}`;
+          if (res.status === 429) {
+            console.warn(`[OpenRouter] Rate limited (429) for ${model}, trying fallback...`);
+          }
+        }
+      } catch (e) {
+        providerErrors[`openrouter_${model}`] = e?.message || "Network error";
+        console.warn(`[OpenRouter Stream] Failover for ${model}:`, e?.message || e);
+      }
+    }
+  }
+  if (deepseekKey && isProviderEnabled("deepseek")) {
+    const dsModel = options.model?.includes("deepseek-reasoner") ? "deepseek-reasoner" : "deepseek-chat";
+    if (isModelAllowed(dsModel)) {
+      try {
+        const idle = createIdleAbortController(18e4);
+        const res = await fetch("https://api.deepseek.com/chat/completions", {
+          method: "POST",
+          headers: {
+            "Authorization": `Bearer ${deepseekKey}`,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify({
+            model: dsModel,
+            messages: formattedMessages,
+            max_tokens: maxTokens,
+            temperature,
+            stream: true,
+            stream_options: { include_usage: true }
+          }),
+          signal: idle.signal
+        });
+        if (res.ok) {
+          const text = await processOpenAISSEStream(res, onChunk, idle);
+          if (text && text.trim()) return text;
+        } else {
+          const errText = await res.text().catch(() => "");
+          providerErrors["deepseek"] = `HTTP ${res.status}: ${errText.slice(0, 120)}`;
+        }
+      } catch (e) {
+        providerErrors["deepseek"] = e?.message || "Network error";
+        console.warn(`[DeepSeek Stream] Failover:`, e?.message || e);
+      }
+    }
+  }
+  if (alibabaKey && isProviderEnabled("alibaba")) {
+    const qwenModels = (options.model?.startsWith("qwen") ? [options.model, "qwen3.7-plus", "qwen3.6-flash"] : ["qwen3.7-plus", "qwen3.6-flash"]).filter((m) => isModelAllowed(m));
+    const baseUrl = alibabaKey.startsWith("sk-sp-") ? "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions" : "https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions";
+    for (const qwenModel of qwenModels) {
+      try {
+        const idle = createIdleAbortController(18e4);
+        const payload = {
+          model: qwenModel,
+          messages: formattedMessages,
+          max_tokens: maxTokens,
+          temperature,
+          stream: true,
+          stream_options: { include_usage: true }
+        };
+        const res = await fetch(baseUrl, {
+          method: "POST",
+          headers: {
+            "Authorization": `Bearer ${alibabaKey}`,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(payload),
+          signal: idle.signal
+        });
+        if (res.ok) {
+          const text = await processOpenAISSEStream(res, onChunk, idle);
+          if (text && text.trim()) return text;
+        } else {
+          const errText = await res.text().catch(() => "");
+          providerErrors[`alibaba_${qwenModel}`] = `HTTP ${res.status}: ${errText.slice(0, 120)}`;
+        }
+      } catch (e) {
+        providerErrors[`alibaba_${qwenModel}`] = e?.message || "Network error";
+        console.warn(`[Alibaba Stream] Failover for ${qwenModel}:`, e?.message || e);
+      }
+    }
+  }
+  if (geminiKey && (isProviderEnabled("gemini") || isProviderEnabled("google"))) {
+    const geminiModels = (options.model?.startsWith("gemini") ? [options.model, "gemini-1.5-flash", "gemini-2.0-flash"] : ["gemini-1.5-flash", "gemini-2.0-flash"]).filter((m) => isModelAllowed(m));
+    const geminiContents = [
+      { role: "user", parts: [{ text: systemInstruction }] },
+      { role: "model", parts: [{ text: "T\xF4i \u0111\xE3 hi\u1EC3u r\xF5 to\xE0n b\u1ED9 b\u1ED1i c\u1EA3nh d\u1EF1 \xE1n v\xE0 s\u1EB5n s\xE0ng h\u1ED7 tr\u1EE3 b\u1EA1n m\u1ED9t c\xE1ch chuy\xEAn s\xE2u, ch\xEDnh x\xE1c nh\u1EA5t." }] },
+      ...messages.map((m) => ({
+        role: m.role === "assistant" || m.role === "model" ? "model" : "user",
+        parts: [{ text: m.content }]
+      }))
+    ];
+    for (const gModel of geminiModels) {
+      try {
+        const idle = createIdleAbortController(18e4);
+        const res = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${gModel}:streamGenerateContent?alt=sse&key=${geminiKey}`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            contents: geminiContents,
+            generationConfig: {
+              temperature,
+              maxOutputTokens: maxTokens
+            }
+          }),
+          signal: idle.signal
+        });
+        if (res.ok) {
+          const text = await processGeminiSSEStream(res, onChunk, idle);
+          if (text && text.trim()) return text;
+        } else {
+          const errText = await res.text().catch(() => "");
+          providerErrors[`gemini_${gModel}`] = `HTTP ${res.status}: ${errText.slice(0, 120)}`;
+        }
+      } catch (e) {
+        providerErrors[`gemini_${gModel}`] = e?.message || "Network error";
+        console.warn(`[Gemini Stream] Failover for ${gModel}:`, e?.message || e);
+      }
+    }
+  }
+  const fallbackChain = getDesignatedFallbackChain();
+  if (fallbackChain.length > 0) {
+    console.log(
+      `[streamRunner] \u{1F6E1}\uFE0F Primary routes failed/exhausted. Invoking designated last-resort fallback chain:`,
+      fallbackChain.map((c) => `${c.provider}(${c.model})`).join(" -> ")
+    );
+    for (const target of fallbackChain) {
+      const { provider, model } = target;
+      if (provider === "nvidia" && nvidiaKey && isProviderEnabled("nvidia")) {
+        try {
+          const idle = createIdleAbortController(18e4);
+          const res = await fetch("https://integrate.api.nvidia.com/v1/chat/completions", {
+            method: "POST",
+            headers: {
+              "Authorization": `Bearer ${nvidiaKey}`,
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+              model,
+              messages: formattedMessages,
+              max_tokens: maxTokens,
+              temperature,
+              stream: true,
+              stream_options: { include_usage: true }
+            }),
+            signal: idle.signal
+          });
+          if (res.ok) {
+            const text = await processOpenAISSEStream(res, onChunk, idle);
+            if (text && text.trim()) {
+              console.log(`[streamRunner] \u2705 Designated fallback NVIDIA (${model}) succeeded!`);
+              return text;
+            }
+          } else {
+            const errText = await res.text().catch(() => "");
+            providerErrors[`designated_fallback_nvidia_${model}`] = `HTTP ${res.status}: ${errText.slice(0, 120)}`;
+          }
+        } catch (e) {
+          providerErrors[`designated_fallback_nvidia_${model}`] = e?.message || "Network error";
+        }
+      } else if (provider === "openrouter" && openrouterKey && isProviderEnabled("openrouter")) {
+        try {
+          const idle = createIdleAbortController(18e4);
+          const res = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+            method: "POST",
+            headers: {
+              "Authorization": `Bearer ${openrouterKey}`,
+              "Content-Type": "application/json",
+              "HTTP-Referer": "https://orchable.composer",
+              "X-Title": "Curriculum OS Studio"
+            },
+            body: JSON.stringify({
+              model,
+              messages: formattedMessages,
+              max_tokens: maxTokens,
+              temperature,
+              stream: true,
+              stream_options: { include_usage: true }
+            }),
+            signal: idle.signal
+          });
+          if (res.ok) {
+            const text = await processOpenAISSEStream(res, onChunk, idle);
+            if (text && text.trim()) {
+              console.log(`[streamRunner] \u2705 Designated fallback OpenRouter (${model}) succeeded!`);
+              return text;
+            }
+          } else {
+            const errText = await res.text().catch(() => "");
+            providerErrors[`designated_fallback_openrouter_${model}`] = `HTTP ${res.status}: ${errText.slice(0, 120)}`;
+          }
+        } catch (e) {
+          providerErrors[`designated_fallback_openrouter_${model}`] = e?.message || "Network error";
+        }
+      } else if ((provider === "alibaba" || provider === "dashscope") && alibabaKey && isProviderEnabled("alibaba")) {
+        const baseUrl = alibabaKey.startsWith("sk-sp-") ? "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions" : "https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions";
+        try {
+          const idle = createIdleAbortController(18e4);
+          const res = await fetch(baseUrl, {
+            method: "POST",
+            headers: {
+              "Authorization": `Bearer ${alibabaKey}`,
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+              model,
+              messages: formattedMessages,
+              max_tokens: maxTokens,
+              temperature,
+              stream: true,
+              stream_options: { include_usage: true }
+            }),
+            signal: idle.signal
+          });
+          if (res.ok) {
+            const text = await processOpenAISSEStream(res, onChunk, idle);
+            if (text && text.trim()) {
+              console.log(`[streamRunner] \u2705 Designated fallback Alibaba (${model}) succeeded!`);
+              return text;
+            }
+          } else {
+            const errText = await res.text().catch(() => "");
+            providerErrors[`designated_fallback_alibaba_${model}`] = `HTTP ${res.status}: ${errText.slice(0, 120)}`;
+          }
+        } catch (e) {
+          providerErrors[`designated_fallback_alibaba_${model}`] = e?.message || "Network error";
+        }
+      } else if ((provider === "google" || provider === "gemini") && geminiKey && (isProviderEnabled("gemini") || isProviderEnabled("google"))) {
+        try {
+          const idle = createIdleAbortController(18e4);
+          const res = await fetch(
+            `https://generativelanguage.googleapis.com/v1beta/models/${model}:streamGenerateContent?alt=sse&key=${geminiKey}`,
+            {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({
+                contents: [
+                  { role: "user", parts: [{ text: systemInstruction }] },
+                  { role: "model", parts: [{ text: "Understood. I will follow the project context and guidelines." }] },
+                  ...messages.map((m) => ({
+                    role: m.role === "assistant" || m.role === "model" ? "model" : "user",
+                    parts: [{ text: m.content }]
+                  }))
+                ],
+                generationConfig: {
+                  temperature,
+                  maxOutputTokens: maxTokens
+                }
+              }),
+              signal: idle.signal
+            }
+          );
+          if (res.ok) {
+            const text = await processGeminiSSEStream(res, onChunk, idle);
+            if (text && text.trim()) {
+              console.log(`[streamRunner] \u2705 Designated fallback Gemini (${model}) succeeded!`);
+              return text;
+            }
+          } else {
+            const errText = await res.text().catch(() => "");
+            providerErrors[`designated_fallback_gemini_${model}`] = `HTTP ${res.status}: ${errText.slice(0, 120)}`;
+          }
+        } catch (e) {
+          providerErrors[`designated_fallback_gemini_${model}`] = e?.message || "Network error";
+        }
+      }
+    }
+  }
+  const isRateLimited = Object.values(providerErrors).some((msg) => msg.includes("429"));
+  const isAuthFailed = Object.values(providerErrors).some((msg) => msg.includes("401") || msg.includes("403"));
+  const errorCode = isRateLimited ? "ERR_AI_RATE_LIMIT" : isAuthFailed ? "ERR_AI_AUTH_FAILED" : "ERR_AI_ALL_PROVIDERS_FAILED";
+  throw createAiInferenceError({
+    errorCode,
+    message: `Kh\xF4ng th\u1EC3 k\u1EBFt n\u1ED1i t\u1EDBi c\xE1c nh\xE0 cung c\u1EA5p AI trong chu\u1ED7i Fallback. Chi ti\u1EBFt: ${JSON.stringify(providerErrors)}`,
+    rawError: providerErrors
+  });
+}
+async function runCurriculumAIInference(messages, projectContext, options = {}, onChunk) {
+  return await streamCurriculumAIInference(messages, projectContext, options, onChunk);
+}
+
+// src/media/curator.ts
+async function curateMediaLedger(options) {
+  const { ledger, artifactContent, policy, context } = options;
+  const pendingEntries = ledger.pending();
+  if (pendingEntries.length === 0) return [];
+  const genQuota = Math.max(0, (policy.maxGenImagesPerArtifact ?? 3) - ledger.doneCount());
+  const entriesBrief = pendingEntries.map((e) => `- slug=${e.slug} | mode=${e.mode} | name=${e.name} | desc=${e.description.slice(0, 300)}`).join("\n");
+  const prompt = `B\u1EA1n l\xE0 Media Curator cho h\u1ECDc li\u1EC7u gi\xE1o d\u1EE5c. S\u1ED5 c\xE1i c\xF3 ${pendingEntries.length} \u1EA3nh \u0111\u1EC1 xu\u1EA5t (pending), \u0111\xE3 c\xF3 ${ledger.doneCount()} \u1EA3nh ho\xE0n t\u1EA5t, quota GEN t\u1ED1i \u0111a ${policy.maxGenImagesPerArtifact} \u1EA3nh/b\xE0i (search kho \u1EA3nh KH\xD4NG t\u1ED1n quota \u2014 x\u1EED \u1EDF t\u1EA7ng th\u1EF1c thi).
+${context.lessonTitle ? `B\xE0i h\u1ECDc: ${context.lessonTitle}` : ""}
+${context.gradeBand ? `Grade band: ${context.gradeBand[0]}-${context.gradeBand[1]}` : ""}
+
+C\xE1c \u1EA3nh \u0111\u1EC1 xu\u1EA5t (s\u1ED5 c\xE1i):
+${entriesBrief}
+
+N\u1ED9i dung b\xE0i (\u0111\xE3 duy\u1EC7t):
+${artifactContent.slice(0, 12e3)}
+
+QUY T\u1EAEC PH\xC2N B\u1ED4 THEO 2 TR\u01AF\u1EDCNG H\u1EE2P:
+A) N\u1EBFu ${pendingEntries.length} <= ${genQuota}: APPROVE T\u1EA4T C\u1EA2 \u2014 tr\u1EEB khi c\xF3 l\xFD do C\u1EE8NG:
+   - duplicate: 2+ \u1EA3nh c\xF9ng ch\u1EE7 \u0111\u1EC1 (ch\u1EC9 gi\u1EEF 1, c\xE1i c\xF2n l\u1EA1i action=drop reasonCode=duplicate)
+   - content_mismatch: m\xF4 t\u1EA3 kh\xF4ng li\xEAn quan g\xEC \u0111\u1EBFn n\u1ED9i dung b\xE0i
+   - low_quality_description: m\xF4 t\u1EA3 m\u01A1 h\u1ED3 \u0111\u1EBFn m\u1EE9c kh\xF4ng th\u1EC3 t\u1EA1o \u1EA3nh d\xF9ng \u0111\u01B0\u1EE3c (vd "\u1EA3nh minh h\u1ECDa chung")
+   KH\xD4NG \u0111\u01B0\u1EE3c drop v\xEC "c\u1EA3m th\u1EA5y kh\xF4ng c\u1EA7n" \u2014 agent t\u1EA1o \u0111\xE3 l\u1ECDc t\u1EEB \u0111\u1EA7u.
+B) V\u1EC1 quota GEN (t\u1ED1i \u0111a ${policy.maxGenImagesPerArtifact} \u1EA3nh AI/b\xE0i): KH\xD4NG drop \u1EDF b\u01B0\u1EDBc n\xE0y v\xEC quota \u2014
+   t\u1EA7ng th\u1EF1c thi s\u1EBD search kho \u1EA3nh tr\u01B0\u1EDBc cho m\u1ECDi slot, ch\u1EC9 nh\u1EEFng slot search-miss m\u1EDBi \u0111\u01B0\u1EE3c x\u1EBFp h\u1EA1ng \u0111\u1EC3 gen.
+   Vi\u1EC7c c\u1EE7a b\u1EA1n \u1EDF \u0111\xE2y: approve/re-describe/drop theo 3 l\xFD do C\u1EE8NG \u1EDF tr\xEAn.
+
+V\u1EDBi m\u1ED7i \u1EA3nh approve/re-describe: vi\u1EBFt enrichedPrompt TI\u1EBENG ANH chi ti\u1EBFt (subject, layout, labeled parts, educational-diagram style, age-appropriate).
+KH\xD4NG BAO GI\u1EDC approve v\u01B0\u1EE3t ${genQuota}.
+
+Tr\u1EA3 v\u1EC1 CH\xCDNH X\xC1C JSON (kh\xF4ng markdown fence) cho T\u1EA4T C\u1EA2 c\xE1c slug:
+[{"slug":"...","action":"approve|drop|re-describe","reasonCode":"duplicate|content_mismatch|low_quality_description|over_quota","enrichedPrompt":"...","reason":"..."}]`;
+  const raw = await runCurriculumAIInference(
+    [{ role: "user", content: prompt }],
+    "",
+    options.llm || {}
+  );
+  const jsonMatch = raw.match(/\[[\s\S]*\]/);
+  if (!jsonMatch) throw new MediaError(`Curator LLM tr\u1EA3 v\u1EC1 kh\xF4ng parse \u0111\u01B0\u1EE3c JSON: ${raw.slice(0, 200)}`, "curator");
+  let decisions;
+  try {
+    decisions = JSON.parse(jsonMatch[0]);
+  } catch (e) {
+    throw new MediaError(`Curator JSON invalid: ${e?.message}`, "curator");
+  }
+  const validSlugs = new Set(pendingEntries.map((e) => e.slug));
+  decisions = decisions.filter((d) => validSlugs.has(d.slug));
+  const approved = decisions.filter((d) => d.action === "approve" || d.action === "re-describe");
+  const overflow = approved.slice(genQuota);
+  for (const d of overflow) {
+    d.action = "drop";
+    d.reasonCode = "over_quota";
+    d.reason = "V\u01B0\u1EE3t maxImagesPerArtifact sau ki\u1EC3m tra server-side";
+  }
+  for (const d of decisions) {
+    if (d.action === "drop" && !d.reasonCode) d.reasonCode = "none_needed";
+  }
+  for (const d of decisions) {
+    if (d.action === "drop") {
+      ledger.setStatus(d.slug, "rejected", { decisionReasonCode: d.reasonCode, decisionReason: d.reason, lastError: d.reason });
+    } else {
+      ledger.setStatus(d.slug, "approved", { decisionReasonCode: void 0, decisionReason: d.reason, finalPrompt: d.enrichedPrompt });
+    }
+  }
+  return decisions;
+}
+async function rankGenCandidates(candidates, quota, context, llm) {
+  if (candidates.length <= quota) {
+    return { selected: candidates.map((c) => c.slug), dropped: [] };
+  }
+  const brief = candidates.map((c, i) => `${i + 1}. slug=${c.slug} | name=${c.name} | desc=${c.description.slice(0, 250)}`).join("\n");
+  const prompt = `X\u1EBFp h\u1EA1ng ${candidates.length} \u1EA3nh minh h\u1ECDa gi\xE1o d\u1EE5c, ch\u1ECDn \u0110\xDANG ${quota} \u1EA3nh \u01B0u ti\xEAn gen (\u1EA3nh AI t\u1ED1n k\xE9m).
+${context.lessonTitle ? `B\xE0i h\u1ECDc: ${context.lessonTitle}` : ""}
+${context.gradeBand ? `Grade band: ${context.gradeBand[0]}-${context.gradeBand[1]}` : ""}
+
+Candidates:
+${brief}
+
+Th\u1EE9 t\u1EF1 \u01B0u ti\xEAn:
+1. Diagram/s\u01A1 \u0111\u1ED3 gi\u1EA3i th\xEDch kh\xE1i ni\u1EC7m tr\u1EEBu t\u01B0\u1EE3ng ho\u1EB7c quy tr\xECnh nhi\u1EC1u b\u01B0\u1EDBc (thi\u1EBFu l\xE0 kh\xF3 hi\u1EC3u nh\u1EA5t)
+2. Minh h\u1ECDa step-by-step th\u1EF1c h\xE0nh (wiring, thao t\xE1c, UI)
+3. \u1EA2nh b\u1ED1i c\u1EA3nh/\u0111\u1ED9ng l\u1EF1c (\xEDt c\u1EA7n nh\u1EA5t)
+
+Tr\u1EA3 CH\xCDNH X\xC1C JSON (kh\xF4ng fence): {"selected":["slug1","slug2",...]} \u2014 \u0111\xFAng ${quota} slugs, theo th\u1EE9 t\u1EF1 \u01B0u ti\xEAn.`;
+  try {
+    const raw = await runCurriculumAIInference([{ role: "user", content: prompt }], "", llm || {});
+    const m = raw.match(/\{[\s\S]*\}/);
+    if (!m) throw new Error("no JSON in response");
+    const parsed = JSON.parse(m[0]);
+    const valid = (parsed.selected || []).filter((s) => candidates.some((c) => c.slug === s)).slice(0, quota);
+    if (valid.length === 0) throw new Error("empty selection");
+    const selectedSet = new Set(valid);
+    for (const c of candidates) {
+      if (valid.length >= quota) break;
+      if (!selectedSet.has(c.slug)) {
+        valid.push(c.slug);
+        selectedSet.add(c.slug);
+      }
+    }
+    const dropped = candidates.filter((c) => !selectedSet.has(c.slug)).map((c, i) => ({ slug: c.slug, rank: i + 1 }));
+    return { selected: valid, dropped };
+  } catch (err) {
+    console.warn("[curator] rankGenCandidates LLM failed \u2014 fallback first-come order:", err?.message || err);
+    const selected = candidates.slice(0, quota).map((c) => c.slug);
+    const dropped = candidates.slice(quota).map((c, i) => ({ slug: c.slug, rank: i + 1 }));
+    return { selected, dropped };
+  }
+}
+async function fulfillMediaLedger(options) {
+  const { ledger, projectDir, policy } = options;
+  const maxRetries = options.maxRetries ?? 2;
+  const approved = ledger.listByStatus("approved");
+  const result = { done: [], failed: [], skipped: [] };
+  const mediaDir = path2__default.default.join(projectDir, "_media");
+  fs__default.default.mkdirSync(mediaDir, { recursive: true });
+  const mode = policy.mode ?? "auto";
+  const canSearch = mode === "search_only" || mode === "auto";
+  const canGen = mode === "gen_only" || mode === "auto";
+  const searchMisses = [];
+  if (canSearch) {
+    for (const entry of approved) {
+      if ((entry.retryCount ?? 0) >= maxRetries) {
+        result.skipped.push(entry.slug);
+        continue;
+      }
+      options.onProgress?.(entry.slug, "searching");
+      try {
+        const images = await searchEducationalImages({
+          query: entry.finalPrompt || entry.description,
+          perPage: 1,
+          apiKey: options.apiKeyOverrides?.pexels
+        });
+        const target = images[0];
+        if (target) {
+          ledger.setStatus(entry.slug, "done", { relPath: target.url, provider: "pexels" });
+          result.done.push(entry.slug);
+          options.onProgress?.(entry.slug, "done", "source: pexels");
+        } else {
+          searchMisses.push(entry);
+        }
+      } catch (err) {
+        if (mode === "search_only") {
+          const msg = err?.message || String(err);
+          ledger.setStatus(entry.slug, "failed", { lastError: msg });
+          options.onProgress?.(entry.slug, "failed", msg);
+          result.failed.push(entry.slug);
+        } else {
+          searchMisses.push(entry);
+        }
+      }
+    }
+  } else {
+    for (const entry of approved) {
+      if ((entry.retryCount ?? 0) >= maxRetries) {
+        result.skipped.push(entry.slug);
+        continue;
+      }
+      searchMisses.push(entry);
+    }
+  }
+  if (canGen && searchMisses.length > 0) {
+    const genQuota = Math.max(0, (policy.maxGenImagesPerArtifact ?? 3) - ledger.doneCount());
+    let toGen = [];
+    if (searchMisses.length > genQuota) {
+      const ranking = await rankGenCandidates(
+        searchMisses.map((e) => ({ slug: e.slug, name: e.name, description: e.finalPrompt || e.description })),
+        genQuota,
+        options.rankingContext || {},
+        options.llm
+      );
+      const allowed = new Set(ranking.selected);
+      toGen = searchMisses.filter((e) => allowed.has(e.slug));
+      for (const dropped of ranking.dropped) {
+        const entry = searchMisses.find((e) => e.slug === dropped.slug);
+        if (!entry) continue;
+        ledger.setStatus(entry.slug, "failed", {
+          lastError: `V\u01B0\u1EE3t quota gen (${policy.maxGenImagesPerArtifact}/b\xE0i) \u2014 h\u1EA1ng ${dropped.rank} khi x\u1EBFp h\u1EA1ng theo m\u1EE9c c\u1EA7n thi\u1EBFt cho vi\u1EC7c hi\u1EC3u b\xE0i`
+        });
+        result.failed.push(entry.slug);
+        options.onProgress?.(entry.slug, "failed", "over gen quota");
+      }
+    } else {
+      toGen = searchMisses;
+    }
+    for (const entry of toGen) {
+      options.onProgress?.(entry.slug, "generating");
+      try {
+        const provider = policy.preferredProvider || "openai";
+        const image = await generateEducationalImage({
+          prompt: entry.finalPrompt || entry.description,
+          aspectRatio: options.defaultAspect || "4:3",
+          provider,
+          apiKey: provider === "openai" ? options.apiKeyOverrides?.openai : options.apiKeyOverrides?.gemini
+        });
+        const ext = image.mimeType === "image/jpeg" ? "jpg" : "png";
+        const filename = `${entry.slug}-${Date.now()}.${ext}`;
+        fs__default.default.writeFileSync(path2__default.default.join(mediaDir, filename), Buffer.from(image.base64, "base64"));
+        ledger.setStatus(entry.slug, "done", { relPath: `_media/${filename}`, provider: image.provider });
+        result.done.push(entry.slug);
+        options.onProgress?.(entry.slug, "done", `source: ${image.provider}`);
+      } catch (err) {
+        const msg = err?.message || String(err);
+        ledger.setStatus(entry.slug, "failed", { lastError: msg });
+        options.onProgress?.(entry.slug, "failed", msg);
+        result.failed.push(entry.slug);
+      }
+    }
+  }
+  return result;
+}
+function injectMediaIntoMarkdown(markdown, ledger) {
+  let out = markdown;
+  const entries = Array.isArray(ledger) ? ledger : ledger.list();
+  for (const entry of entries) {
+    if (entry.status !== "done" || !entry.relPath) continue;
+    const placeholder = new RegExp(`\\[IMAGE\\s*:\\s*${entry.slug}\\]`, "g");
+    out = out.replace(placeholder, `![${entry.name}](${entry.relPath})`);
+  }
+  return out;
+}
+function renderMediaPlaceholder(entry) {
+  if (entry.status === "failed") {
+    return `> \u26A0\uFE0F [\u1EA2nh ${entry.name} ch\u01B0a t\u1EA1o \u0111\u01B0\u1EE3c (${entry.lastError || "l\u1ED7i kh\xF4ng r\xF5"}) \u2014 b\u1EA5m "T\u1EA1o \u1EA3nh b\xF9" \u0111\u1EC3 th\u1EED l\u1EA1i]`;
+  }
+  return `> \u{1F5BC}\uFE0F [\u1EA2nh \u0111ang ch\u1EDD: ${entry.name} \u2014 s\u1EBD \u0111\u01B0\u1EE3c t\u1EA1o sau khi duy\u1EC7t media]`;
+}
+
+exports.MediaError = MediaError;
+exports.MediaLedger = MediaLedger;
+exports.buildImagePrompt = buildImagePrompt;
+exports.curateMediaLedger = curateMediaLedger;
+exports.fulfillMediaLedger = fulfillMediaLedger;
+exports.generateEducationalImage = generateEducationalImage;
+exports.injectMediaIntoMarkdown = injectMediaIntoMarkdown;
+exports.rankGenCandidates = rankGenCandidates;
+exports.renderMediaPlaceholder = renderMediaPlaceholder;
+exports.searchEducationalImages = searchEducationalImages;
+exports.searchEducationalVideos = searchEducationalVideos;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map