@aigne/doc-smith 0.9.8 → 0.9.9-beta.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.9.9-beta.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.9-beta...v0.9.9-beta.1) (2025-12-11)
+
+
+### Features
+
+* **diagram:** enhance localization with translated images ([#354](https://github.com/AIGNE-io/aigne-doc-smith/issues/354)) ([7abe041](https://github.com/AIGNE-io/aigne-doc-smith/commit/7abe04123005f72d919731b9a69ecbdfff794fb3))
+
+
+### Bug Fixes
+
+* ensure original document structure is initialized to avoid errors ([#356](https://github.com/AIGNE-io/aigne-doc-smith/issues/356)) ([885a46e](https://github.com/AIGNE-io/aigne-doc-smith/commit/885a46e83036d59df5ec41e7f034725d4ad781b0))
+
+## [0.9.9-beta](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.8...v0.9.9-beta) (2025-12-09)
+
+
+### Bug Fixes
+
+* implement robust error handling for token calculation ([#352](https://github.com/AIGNE-io/aigne-doc-smith/issues/352)) ([e7ba726](https://github.com/AIGNE-io/aigne-doc-smith/commit/e7ba726e226c05a1ac2b40c74b101e1a2d972091))
+
 ## [0.9.8](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.8-beta.1...v0.9.8) (2025-12-07)
 
 ## [0.9.8-beta.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.8-beta...v0.9.8-beta.1) (2025-12-06)

package/agents/create/aggregate-document-structure.mjs

@@ -0,0 +1,21 @@
+import { saveValueToConfig } from "../../utils/utils.mjs";
+
+export default async function aggregateDocumentStructure(input, options) {
+  options.context.userContext.originalDocumentStructure ??= [];
+  const projectName = input.projectName || options.context.userContext.projectName;
+  const projectDesc = input.projectDesc || options.context.userContext.projectDesc;
+
+  if (!input.projectDesc && projectDesc) {
+    await saveValueToConfig("projectDesc", projectDesc, "Project description");
+  }
+
+  return {
+    documentStructure: options.context.userContext.originalDocumentStructure.map((i, index) => ({
+      ...i,
+      id: i.title.toLowerCase().replace(/\s+/g, "-"),
+      index,
+    })),
+    projectName,
+    projectDesc,
+  };
+}

package/agents/create/analyze-diagram-type-llm.yaml

@@ -16,7 +16,7 @@ instructions: |
 
   Your responsibilities:
 
-  1. **Analyze Context**: Understand the document’s content, structure, and its purpose, especially around where the diagram will be inserted.
+  1. **Analyze Context**: Understand the document's content, structure, and its purpose, especially around where the diagram will be inserted.
 
   2. **Generate Document Summary**:
     **CRITICAL**: The documentSummary will be the **only input** passed to the image generation model. Preserve as much information as possible, only removing content that is truly useless for diagram generation.
@@ -157,4 +157,3 @@ output_schema:
     - diagramType
     - diagramStyle
     - aspectRatio
-

package/agents/create/analyze-diagram-type.mjs

@@ -1,4 +1,6 @@
 import { DIAGRAM_STYLES } from "../../utils/constants/index.mjs";
+import path from "node:path";
+import fs from "fs-extra";
 
 const DEFAULT_DIAGRAM_STYLE = "modern";
 const DEFAULT_DIAGRAM_TYPE = "flowchart";
@@ -76,10 +78,80 @@ const STYLE_REQUIREMENTS = {
   - Clear depth cues and perspective`,
 };
 
+/**
+ * Convert diagramInfo from analyzeFeedbackIntent to mediaFile format
+ * @param {Object} diagramInfo - Diagram info from analyzeFeedbackIntent (contains path, index, markdown)
+ * @param {string} docPath - Document path
+ * @param {string} docsDir - Documentation directory
+ * @returns {Promise<Array|null>} - Array of mediaFile objects or null if conversion fails
+ * Note: Currently each document has only one diagram, so we always use the first (and only) image
+ */
+async function convertDiagramInfoToMediaFile(diagramInfo, docPath, docsDir) {
+  if (!diagramInfo || !diagramInfo.path) {
+    return null;
+  }
+
+  try {
+    const imagePath = diagramInfo.path;
+    const docDir = path.dirname(docPath);
+
+    // Resolve absolute path
+    let absolutePath;
+    if (imagePath.startsWith("http://") || imagePath.startsWith("https://")) {
+      // Remote URL, cannot convert to local file
+      return null;
+    } else if (path.isAbsolute(imagePath)) {
+      absolutePath = imagePath;
+    } else {
+      // Relative path - resolve from document location
+      const imageRelativePath = imagePath.startsWith("../")
+        ? imagePath
+        : path.join(docDir, imagePath).replace(/\\/g, "/");
+      absolutePath = path.join(process.cwd(), docsDir, imageRelativePath);
+    }
+
+    // Normalize path
+    const normalizedPath = path.normalize(absolutePath);
+
+    // Check if file exists
+    if (!(await fs.pathExists(normalizedPath))) {
+      return null;
+    }
+
+    // Get file info
+    const ext = path.extname(normalizedPath).toLowerCase().slice(1);
+    const filename = path.basename(normalizedPath);
+
+    // Determine MIME type
+    const mimeTypes = {
+      jpg: "image/jpeg",
+      jpeg: "image/jpeg",
+      png: "image/png",
+      webp: "image/webp",
+      gif: "image/gif",
+    };
+    const mimeType = mimeTypes[ext] || "image/png";
+
+    // Return mediaFile format (array as required by input_file_key)
+    return [
+      {
+        type: "local",
+        path: normalizedPath,
+        filename,
+        mimeType,
+      },
+    ];
+  } catch (error) {
+    console.warn(`Failed to convert diagramInfo to mediaFile: ${error.message}`);
+    return null;
+  }
+}
+
 /**
  * Analyze document content to determine diagram type and select appropriate style
  * Uses LLM analysis to determine diagram type and style
  * Supports extracting style and type preferences from user feedback
+ * Now also detects existing images and determines if image-to-image generation should be used
  */
 export default async function analyzeDiagramType(
   {
@@ -89,6 +161,10 @@ export default async function analyzeDiagramType(
     diagramming,
     locale = "en",
     feedback = "",
+    path,
+    docsDir,
+    // Analysis results from first layer (analyzeFeedbackIntent)
+    intentAnalysis,
   },
   options,
 ) {
@@ -97,7 +173,7 @@ export default async function analyzeDiagramType(
     defaultStyle = diagramming.style;
   }
 
-  // Step 1: Use LLM to analyze and make final decision (LLM will analyze feedback directly)
+  // Step 1: Use LLM to analyze document content (chart detection and intent analysis already done in first layer)
   const llmAgent = options.context?.agents?.["analyzeDiagramTypeLLM"];
   let llmResult = null;
 
@@ -129,6 +205,8 @@ export default async function analyzeDiagramType(
         locale,
         feedback: feedback || "",
         defaultStyle: defaultStyle || null,
+        // Note: We only analyze current documentContent, no originalContent comparison
+        // User feedback is the only indicator for whether diagram needs update
       };
 
       llmResult = await options.context.invoke(llmAgent, llmInput);
@@ -187,7 +265,22 @@ export default async function analyzeDiagramType(
     aspectRatio = "4:3";
   }
 
-  // Step 7: Return document content and summary for image generation
+  // Step 2: Use analysis results from first layer (analyzeFeedbackIntent)
+  // Get generationMode and diagramInfo from intentAnalysis
+  const generationMode = intentAnalysis?.generationMode || "add-new";
+  const diagramInfo = intentAnalysis?.diagramInfo || null;
+
+  // Step 3: Convert diagramInfo to mediaFile format if needed for image-to-image generation
+  let existingImage = null;
+  let useImageToImage = false;
+
+  if (diagramInfo && generationMode === "image-to-image" && path && docsDir) {
+    // Convert diagramInfo to the format expected by image generation agent
+    existingImage = await convertDiagramInfoToMediaFile(diagramInfo, path, docsDir);
+    useImageToImage = existingImage !== null;
+  }
+
+  // Step 3: Return document content and summary for image generation
   return {
     diagramType,
     diagramStyle,
@@ -197,6 +290,10 @@ export default async function analyzeDiagramType(
     diagramTypeRequirements,
     diagramStyleRequirements,
     negativePromptExclusions,
+    // Image-to-image generation support (from LLM analysis)
+    existingImage, // Array of mediaFile objects or null
+    useImageToImage, // Boolean indicating if image-to-image mode should be used
+    generationMode, // Generation mode from LLM: "text-only", "image-to-image", "remove-image", "add-new"
   };
 }
 
@@ -241,6 +338,15 @@ analyzeDiagramType.input_schema = {
         "User feedback that may contain style or type preferences (e.g., 'use anthropomorphic style', 'create architecture diagram')",
       default: "",
     },
+    path: {
+      type: "string",
+      description:
+        "Document path (e.g., 'guides/getting-started.md') used for extracting existing images",
+    },
+    docsDir: {
+      type: "string",
+      description: "Documentation directory where diagram images are stored",
+    },
   },
   required: ["documentContent"],
 };
@@ -283,6 +389,57 @@ analyzeDiagramType.output_schema = {
       description:
         "A concise summary of the document content focusing on key elements needed for diagram generation. This summary is generated by the analysis LLM to ensure consistent understanding between analysis and image generation models.",
     },
+    existingImage: {
+      type: "array",
+      nullable: true,
+      description:
+        "Array of mediaFile objects for existing diagram image (for image-to-image generation). Null if no existing image or text-only regeneration requested.",
+      items: {
+        type: "object",
+        properties: {
+          type: { type: "string" },
+          path: { type: "string" },
+          filename: { type: "string" },
+          mimeType: { type: "string" },
+        },
+      },
+    },
+    useImageToImage: {
+      type: "boolean",
+      description:
+        "Whether to use image-to-image generation mode. True if existing image found and generationMode is 'image-to-image'.",
+    },
+    generationMode: {
+      type: "string",
+      description: "Generation mode determined from intentAnalysis (from analyzeFeedbackIntent).",
+    },
+    intentAnalysis: {
+      type: "object",
+      description:
+        "Analysis results from analyzeFeedbackIntent containing intentType, diagramInfo, generationMode, and changes.",
+      properties: {
+        intentType: {
+          type: "string",
+          enum: ["addDiagram", "updateDiagram", "deleteDiagram", "updateDocument"],
+        },
+        diagramInfo: {
+          type: "object",
+          nullable: true,
+          properties: {
+            path: { type: "string" },
+            index: { type: "number" },
+            markdown: { type: "string" },
+          },
+        },
+        generationMode: {
+          type: "string",
+        },
+        changes: {
+          type: "array",
+          items: { type: "string" },
+        },
+      },
+    },
   },
   required: [
     "diagramType",
@@ -293,5 +450,6 @@ analyzeDiagramType.output_schema = {
     "diagramStyleRequirements",
     "negativePromptExclusions",
     "documentContent",
+    "useImageToImage",
   ],
 };

package/agents/create/generate-diagram-image.yaml

@@ -20,6 +20,10 @@ instructions:
   - role: user
     url: ../../prompts/detail/diagram/generate-image-user.md
 
+# Support image-to-image generation by passing existing image via input_file_key
+# If existingImage is provided (array of mediaFile objects), it will be passed to the model
+input_file_key: existingImage
+
 input_schema:
   type: object
   properties:
@@ -51,6 +55,33 @@ input_schema:
       type: string
       description: Aspect ratio of the generated image (alias for ratio, used in prompt templates)
       enum: ["1:1", "5:4", "4:3", "3:2", "16:9", "21:9"]
+    existingImage:
+      type: array
+      nullable: true
+      description: Array of mediaFile objects for existing diagram image (for image-to-image generation). If provided, the model will use this as reference and update based on document content and feedback.
+      items:
+        type: object
+        properties:
+          type:
+            type: string
+            description: File type, should be "local"
+          path:
+            type: string
+            description: Absolute path to the image file
+          filename:
+            type: string
+            description: Image filename
+          mimeType:
+            type: string
+            description: MIME type of the image (e.g., "image/png", "image/jpeg")
+    useImageToImage:
+      type: boolean
+      description: Whether to use image-to-image generation mode. If true and existingImage is provided, the model will update the existing image based on document content and feedback.
+      default: false
+    feedback:
+      type: string
+      description: User feedback for diagram updates. Used in image-to-image mode to guide modifications.
+      default: ""
   required:
     - documentContent
     - diagramType

package/agents/create/generate-structure.yaml

@@ -65,18 +65,7 @@ skills:
 
       - ./utils/merge-document-structures.mjs
 
-  - type: function
-    name: aggregateDocumentStructure
-    process: |
-      return {
-        documentStructure: options.context.userContext.originalDocumentStructure.map((i, index) => ({
-          ...i,
-          id: i.title.toLowerCase().replace(/\s+/g, '-'),
-          index
-        })),
-        projectName: options.context.userContext.projectName,
-        projectDesc: options.context.userContext.projectDesc,
-      }
+  - ./aggregate-document-structure.mjs
 
   - type: ai
     name: refineStructure

package/agents/create/replace-d2-with-image.mjs

@@ -13,6 +13,7 @@ import { getContentHash, getFileName } from "../../utils/utils.mjs";
 import { getExtnameFromContentType } from "../../utils/file-utils.mjs";
 import { debug } from "../../utils/debug.mjs";
 import { compressImage } from "../../utils/image-compress.mjs";
+import { calculateImageTimestamp } from "../../utils/diagram-version-utils.mjs";
 
 const SIZE_THRESHOLD = 1 * 1024 * 1024; // 1MB
 
@@ -304,10 +305,19 @@ export default async function replaceD2WithImage({
   }
 
   // Create markdown image reference with markers for easy replacement
-  // Format: <!-- DIAGRAM_IMAGE_START:type:aspectRatio -->![alt](path)<!-- DIAGRAM_IMAGE_END -->
+  // Format: <!-- DIAGRAM_IMAGE_START:type:aspectRatio:timestamp -->![alt](path)<!-- DIAGRAM_IMAGE_END -->
   const diagramTypeTag = diagramType || "unknown";
   const aspectRatioTag = aspectRatio || "unknown";
-  const imageMarkdown = `<!-- DIAGRAM_IMAGE_START:${diagramTypeTag}:${aspectRatioTag} -->\n![${altText}](${relativePath})\n<!-- DIAGRAM_IMAGE_END -->`;
+
+  // Calculate timestamp for the saved image (for version tracking)
+  let imageTimestamp = "0";
+  try {
+    imageTimestamp = await calculateImageTimestamp(destPath);
+  } catch (error) {
+    debug(`Failed to calculate image timestamp: ${error.message}, using default 0`);
+  }
+
+  const imageMarkdown = `<!-- DIAGRAM_IMAGE_START:${diagramTypeTag}:${aspectRatioTag}:${imageTimestamp} -->\n![${altText}](${relativePath})\n<!-- DIAGRAM_IMAGE_END -->`;
 
   // Note: diagramLocations was already found above for filename generation, reuse it
 
@@ -373,31 +383,6 @@ export default async function replaceD2WithImage({
     finalContent = trimmedContent + separator + imageMarkdown;
   }
 
-  // Sync diagram images to translation files
-  // Only sync if we actually replaced/added a diagram (not just returned original content)
-  if (finalContent !== (originalContent || documentContent || content || "")) {
-    try {
-      const { syncDiagramToTranslations } = await import(
-        "../../utils/sync-diagram-to-translations.mjs"
-      );
-      const syncResult = await syncDiagramToTranslations(
-        finalContent,
-        finalDocPath,
-        finalDocsDir,
-        locale,
-        "update", // Operation type: update - skip if main has 0 diagrams
-      );
-      if (syncResult.updated > 0) {
-        debug(
-          `✅ Synced diagram images to ${syncResult.updated} translation file(s)${syncResult.errors.length > 0 ? ` (${syncResult.errors.length} error(s))` : ""}`,
-        );
-      }
-    } catch (error) {
-      // Don't fail the whole operation if sync fails
-      debug(`⚠️  Failed to sync diagram to translations: ${error.message}`);
-    }
-  }
-
   return { content: finalContent };
 }
 

package/agents/create/utils/merge-document-structures.mjs

@@ -1,4 +1,5 @@
 export default async function mergeDocumentStructures(input, options) {
+  // Save projectName and projectDesc to userContext if provided
   if (input.projectName) {
     options.context.userContext.projectName = input.projectName;
   }
@@ -6,8 +7,9 @@ export default async function mergeDocumentStructures(input, options) {
     options.context.userContext.projectDesc = input.projectDesc;
   }
 
-  input.projectName = options.context.userContext.projectName;
-  input.projectDesc = options.context.userContext.projectDesc;
+  // Get the final values (either from input or existing userContext)
+  const projectName = options.context.userContext.projectName;
+  const projectDesc = options.context.userContext.projectDesc;
 
   options.context.userContext.originalDocumentStructure ??= [];
 
@@ -26,5 +28,9 @@ export default async function mergeDocumentStructures(input, options) {
 
   options.context.userContext.originalDocumentStructure = originalStructures;
 
-  return {};
+  // Return projectName and projectDesc to ensure they flow through the pipeline
+  return {
+    projectName,
+    projectDesc,
+  };
 }

package/agents/localize/index.yaml

@@ -19,6 +19,7 @@ skills:
           'documentStructure': originalDocumentStructure
         }
       ])
+  - url: ../update/check-diagram-flag.mjs
   - url: ../utils/choose-docs.mjs
     default_input:
       isTranslate: true
@@ -55,4 +56,7 @@ input_schema:
     feedback:
       type: string
       description: Tell us how to improve the translation style
+    diagram:
+      type: boolean
+      description: Translate only diagram images without translating document content (use --diagram flag)
 mode: sequential

package/agents/localize/save-doc-translation-or-skip.mjs

@@ -0,0 +1,18 @@
+/**
+ * Save translated document
+ * Always saves the translation content, regardless of --diagram flag.
+ * In --diagram mode, the translation content may only have updated diagram images,
+ * but it still needs to be saved to persist the image changes.
+ */
+export default async function saveDocTranslationOrSkip(input, options) {
+  // Always save translation content, whether it's a full translation or just diagram image updates
+  // The translation content (from set-review-content.mjs) already contains the updated diagram images
+  const saveDocTranslationAgent = options.context?.agents?.["saveDocTranslation"];
+  if (saveDocTranslationAgent) {
+    return await options.context.invoke(saveDocTranslationAgent, input);
+  }
+
+  return {};
+}
+
+saveDocTranslationOrSkip.task_render_mode = "hide";

package/agents/localize/set-review-content.mjs

@@ -0,0 +1,58 @@
+import { debug } from "../../utils/debug.mjs";
+import { d2CodeBlockRegex, diagramImageFullRegex } from "../../utils/d2-utils.mjs";
+
+/**
+ * Replace cached diagram images in translated document and set reviewContent
+ * This step runs after translate-document-wrapper.mjs to:
+ * 1. Insert cached image translations into the translated document
+ * 2. Set reviewContent from the final translation
+ * Note: Each document has at most one diagram image
+ */
+export default async function setReviewContent(input) {
+  let translation = input.translation || "";
+  const cachedImages = input.cachedDiagramImages || null;
+
+  // Replace cached diagram image if any (each document has at most one image)
+  if (cachedImages && cachedImages.length > 0) {
+    try {
+      const cachedImage = cachedImages[0]; // Only one image per document
+
+      // Find existing image in translated content
+      // Note: Translation process may copy content from main document, so we always need to
+      // replace with cached image to ensure the final document uses the correct language-specific image
+      const imageMatch = translation.match(diagramImageFullRegex);
+
+      if (imageMatch) {
+        translation = translation.replace(diagramImageFullRegex, cachedImage.translatedMarkdown);
+        debug(`✅ Replaced diagram image in translation with language-specific image`);
+      } else {
+        const d2Match = translation.match(d2CodeBlockRegex);
+        if (d2Match) {
+          translation = translation.replace(d2CodeBlockRegex, cachedImage.translatedMarkdown);
+          debug(`✅ Replaced D2 code block in translation with language-specific image`);
+        } else {
+          // No existing image, insert at the position from main document
+          const insertIndex = Math.min(cachedImage.mainImageIndex, translation.length);
+          translation =
+            translation.slice(0, insertIndex) +
+            "\n\n" +
+            cachedImage.translatedMarkdown +
+            "\n\n" +
+            translation.slice(insertIndex);
+          debug(`✅ Inserted diagram image at index ${insertIndex}`);
+        }
+      }
+    } catch (error) {
+      debug(`⚠️  Failed to replace cached diagram image: ${error.message}`);
+      // Continue with original translation if replacement fails
+    }
+  }
+
+  return {
+    ...input,
+    translation,
+    reviewContent: translation || input.content || "",
+  };
+}
+
+setReviewContent.task_render_mode = "hide";

package/agents/localize/translate-diagram.yaml

@@ -0,0 +1,62 @@
+type: image
+name: translateDiagram
+image_model:
+  model: google/gemini-3-pro-image-preview
+  imageConfig:
+    imageSize:
+      $get: size
+    aspectRatio:
+      $get: ratio
+
+instructions: |
+  You are a multilingual diagram translator specializing in technical diagrams such as flowcharts, architecture diagrams, network topologies, and mind maps.
+
+  Your task is to regenerate the provided image by translating all label-style text into {{locale}}.
+
+  Requirements:
+  - Retain all command-style, technical, or protocol-specific terms (e.g., "API", "TCP/IP", "POST") in English;
+  - Maintain the original diagram’s structure, layout, visual style, and spatial relationships between elements;
+  - Only translate label or annotation text — all graphical elements should remain unchanged;
+  - **If {{locale}} is Simplified Chinese, Traditional Chinese, Japanese, or Korean, use the font "Microsoft YaHei" (微软雅黑)** to ensure optimal readability, proper character rendering, and consistent typographic style across Latin and CJK scripts;
+  - For other languages, use a clean sans-serif font that best fits the visual style of the original image;
+
+  Your final output should be a regenerated image identical in design but localized in text according to {{locale}}.
+
+input_file_key: existingImage
+
+input_schema:
+  type: object
+  properties:
+    existingImage:
+      type: array
+      description: Array of mediaFile objects for the source diagram image to translate
+      items:
+        type: object
+        properties:
+          type:
+            type: string
+            description: File type, should be "local"
+          path:
+            type: string
+            description: Absolute path to the image file
+          filename:
+            type: string
+            description: Image filename
+          mimeType:
+            type: string
+            description: MIME type of the image (e.g., "image/png", "image/jpeg")
+    ratio:
+      type: string
+      description: Aspect ratio of the image
+    size:
+      type: string
+      description: Size of the generated image
+      default: "1K"
+    locale:
+      type: string
+      description: Target language code for translation
+  required:
+    - existingImage
+    - ratio
+    - locale
+include_input_in_output: true

package/agents/localize/translate-document-wrapper.mjs

@@ -0,0 +1,34 @@
+/**
+ * Conditionally call translateDocument agent
+ * If translation is already set and approved (--diagram mode with existing translation), skip calling translateDocument
+ * Otherwise, call translateDocument agent normally (including --diagram mode when translation doesn't exist)
+ */
+export default async function translateDocumentWrapper(input, options) {
+  // If translation is already set and approved, skip document translation
+  // This happens in --diagram mode when translation document exists (translate-diagram-images.mjs sets isApproved: true)
+  // In --diagram mode when translation doesn't exist, translate-diagram-images.mjs sets isApproved: false to allow translation
+  if (input.translation !== undefined && input.translation !== null && input.isApproved === true) {
+    return input;
+  }
+
+  // Otherwise, call translateDocument agent (YAML-defined AI agent)
+  const translateAgent = options.context?.agents?.["translateDocument"];
+  if (!translateAgent) {
+    throw new Error("translateDocument agent not found");
+  }
+
+  try {
+    const result = await options.context.invoke(translateAgent, input);
+    return {
+      ...input,
+      ...result,
+      translation: result?.translation || result,
+      // Preserve shouldTranslateDiagramsOnly flag
+      shouldTranslateDiagramsOnly: input.shouldTranslateDiagramsOnly,
+    };
+  } catch (error) {
+    throw new Error(`Failed to invoke translateDocument agent: ${error.message}`);
+  }
+}
+
+translateDocumentWrapper.task_render_mode = "hide";