@aigne/doc-smith 0.9.10 → 0.9.11-beta

package/agents/generate-images/prepare-image-generation.mjs

@@ -0,0 +1,130 @@
+import { basename } from "node:path";
+
+/**
+ * Prepare image generation parameters
+ * @param {Object} input - Input parameters
+ * @param {string} input.key - Image key
+ * @param {string} input.id - Slot id
+ * @param {string} input.desc - Slot description
+ * @param {Array} input.documents - Associated document list
+ * @param {string} input.locale - Main language
+ * @param {boolean} input.isUpdate - Whether in update mode
+ * @param {string|null} input.existingImagePath - Existing image path
+ * @returns {Object} - Object containing original input and image generation parameters
+ */
+export default function prepareImageGeneration(input) {
+  const { desc, documents, locale, isUpdate, existingImagePath } = input;
+
+  // Use content from the first document
+  const firstDoc = documents[0];
+  const documentContent = firstDoc.content;
+
+  // Prepare image generation parameters
+  const imageGenParams = {
+    documentContent,
+    desc,
+    locale,
+    size: "2K",
+    aspectRatio: "4:3",
+    useImageToImage: isUpdate || false,
+  };
+
+  // If in update mode and existing image exists, add existingImage parameter
+  if (isUpdate && existingImagePath) {
+    imageGenParams.existingImage = [
+      {
+        type: "local",
+        path: existingImagePath,
+        filename: basename(existingImagePath),
+        mimeType: "image/png",
+      },
+    ];
+  }
+
+  return {
+    ...input, // Keep all original inputs
+    ...imageGenParams, // Add image generation parameters
+  };
+}
+
+// Add description
+prepareImageGeneration.description =
+  "Prepare image generation parameters, extract content from the first associated document, " +
+  "configure image generation parameters (desc, locale, size, aspectRatio), " +
+  "if in update mode, add existing image path for image-to-image generation.";
+
+// Define input schema
+prepareImageGeneration.input_schema = {
+  type: "object",
+  properties: {
+    key: {
+      type: "string",
+      description: "Image key (directory name)",
+    },
+    id: {
+      type: "string",
+      description: "Slot id",
+    },
+    desc: {
+      type: "string",
+      description: "Slot description",
+    },
+    documents: {
+      type: "array",
+      description: "Associated document list",
+      items: {
+        type: "object",
+        properties: {
+          path: { type: "string" },
+          hash: { type: "string" },
+          content: { type: "string" },
+        },
+      },
+    },
+    locale: {
+      type: "string",
+      description: "Main language code",
+    },
+    isUpdate: {
+      type: "boolean",
+      description: "Whether in update mode",
+    },
+    existingImagePath: {
+      type: "string",
+      nullable: true,
+      description: "Existing image path (used in update mode)",
+    },
+  },
+  required: ["key", "id", "desc", "documents", "locale"],
+};
+
+// Define output schema
+prepareImageGeneration.output_schema = {
+  type: "object",
+  properties: {
+    key: { type: "string" },
+    id: { type: "string" },
+    desc: { type: "string" },
+    documents: { type: "array" },
+    locale: { type: "string" },
+    isUpdate: { type: "boolean" },
+    existingImagePath: { type: "string", nullable: true },
+    imageGenParams: {
+      type: "object",
+      description: "Parameters passed to image generation agent",
+      properties: {
+        documentContent: { type: "string" },
+        desc: { type: "string" },
+        locale: { type: "string" },
+        size: { type: "string" },
+        aspectRatio: { type: "string" },
+        useImageToImage: { type: "boolean" },
+        existingImage: {
+          type: "array",
+          nullable: true,
+          items: { type: "object" },
+        },
+      },
+    },
+  },
+};

package/{prompts/detail/diagram/generate-image-system.md → agents/generate-images/prompts/system.md}

@@ -1,8 +1,8 @@
-You are an AI assistant specialized in generating clean, modern, professional diagram images.
+You are an AI assistant specialized in generating clean, modern, professional diagram images for technical documentation.
 
-#  GLOBAL RULES — APPLY TO ALL DIAGRAMS & ALL RATIOS
+# GLOBAL RULES — APPLY TO ALL DIAGRAMS
 
-## VISUAL STYLE (Unified)
+## VISUAL STYLE
 - Modern SaaS product aesthetic
 - Flat vector style, light soft depth (Material Design 2.0 / 3.0)
 - White or light-grey background
@@ -21,7 +21,7 @@ You are an AI assistant specialized in generating clean, modern, professional di
 - Connectors: blue (#2196F3 or #1976D2), straight or orthogonal
 
 ## TYPOGRAPHY & TEXT RULES
-- English only
+- Use the language specified by {{ locale }}
 - Short labels: 2–5 words, action-oriented
 - No long sentences
 - No text outside nodes
@@ -34,8 +34,7 @@ You are an AI assistant specialized in generating clean, modern, professional di
 - Icons optional (thin-line, ≤20% node area)
 - Architecture diagrams may use larger icons (30–50%)
 
-## FLOW RULES (Universal)
-- ONE start → sequential flow → ONE end
+## FLOW RULES
 - Clear, unobstructed main flow
 - Minimal branching
 - Avoid crossings; use orthogonal routing
@@ -47,7 +46,7 @@ You are an AI assistant specialized in generating clean, modern, professional di
 - If >10: merge related steps, use grouping containers
 - Must preserve complete logical flow
 
-#  ASPECT RATIO RULES — SELECTED VIA aspectRatio
+# ASPECT RATIO RULES
 
 {% if aspectRatio == "1:1" %}
 ## SQUARE (1:1)
@@ -57,9 +56,9 @@ You are an AI assistant specialized in generating clean, modern, professional di
 - Use the full square; avoid tiny central clusters
 
 {% elif aspectRatio == "4:3" or aspectRatio == "5:4" %}
-## PORTRAIT (4:3 or 5:4)
+## PORTRAIT/STANDARD (4:3 or 5:4)
 - Canvas: ~1280×1024 or ~1365×1024
-- Primary layout: vertical (top→bottom)
+- Primary layout: vertical (top→bottom) or balanced grid
 - Use height generously; avoid large top/bottom gaps
 - 4:3 supports longer text wrapping
 
@@ -83,53 +82,20 @@ You are an AI assistant specialized in generating clean, modern, professional di
 
 {% endif %}
 
-#  DIAGRAM TYPE RULES — SELECT BASED ON diagramType
-
-{% if diagramType == "flowchart" %}
-## FLOWCHART
-- ONE start → ONE end
-- Dominant main flow, minimal branches
-- Logical grouping recommended:
-  - Initialization
-  - Processing
-  - Validation
-  - Output
-- Optional group containers
-
-{% elif diagramType == "architecture" %}
-## ARCHITECTURE DIAGRAM
-- Layout flexible: horizontal, vertical layers, or radial
-- Use containers or zones for modules/services
-- Icons may be larger and more expressive
-- Emphasize structure and relationships
-
-{% elif diagramType == "intro" %}
-## INTRO / CONCEPT OVERVIEW
-- Radial or hierarchical layout
-- One central idea + surrounding concepts
-- Few connectors required
-
-{% elif diagramType == "guide" %}
-## GUIDE DIAGRAM
-- Simple linear progression
-- Horizontal or vertical based on aspectRatio
-
-{% elif diagramType == "sequence" %}
-## SEQUENCE DIAGRAM
-- Horizontal timeline
-- Vertical lifelines for actors
-- Horizontal message arrows
-
-{% elif diagramType == "network" %}
-## NETWORK DIAGRAM
-- Node-based topology
-- Minimize crossing connections
-- Use relative spatial placement to show relationships
+# DIAGRAM TYPE GUIDELINES
 
-{% endif %}
+## Common Diagram Types:
+- **Architecture**: System components, modules, layers, relationships
+- **Flowchart**: Process flow, decision points, sequential steps
+- **Sequence**: Time-based interactions, message flow between actors
+- **Concept/Overview**: Central idea with surrounding concepts
+- **Guide**: Simple linear progression
+- **Network**: Node-based topology, connections
+
+**Note:** Based on the description provided, automatically determine the most appropriate diagram type and layout.
 
-#  NEGATIVE PROMPT (Unified)
-(no dark background), (no neon colors), (no clutter),  
-(no overcrowding), (no messy lines), (no spaghetti diagram),  
-(no confusing flow), (no diagram title), (no captions),  
+# NEGATIVE PROMPT
+(no dark background), (no neon colors), (no clutter),
+(no overcrowding), (no messy lines), (no spaghetti diagram),
+(no confusing flow), (no diagram title), (no captions),
 (no long sentences), (no step numbers)

package/agents/generate-images/prompts/user.md

@@ -0,0 +1,85 @@
+{% if useImageToImage and existingImage %}
+# Image-to-Image Generation Mode
+
+Your task is to **update an existing diagram** based on the current document content{% if feedback %} and user feedback{% endif %}.
+
+**CRITICAL INSTRUCTIONS:**
+1. **Use the existing image as the primary reference** - maintain its overall structure, layout, and visual style
+2. **Analyze the document content** to understand what changes are needed
+{% if feedback %}3. **Apply user feedback** - follow the user's specific modification requests while maintaining visual consistency
+4. **Maintain visual consistency** - keep the same style, color scheme, and general layout (unless feedback requests otherwise)
+5. **Make necessary updates** - update content, add/remove elements, adjust relationships based on the document and feedback
+6. **Preserve what works** - keep elements that are still accurate and relevant
+{% else %}3. **Maintain visual consistency** - keep the same style, color scheme, and general layout
+4. **Make necessary updates** - update content, add/remove elements, adjust relationships based on the document
+5. **Preserve what works** - keep elements that are still accurate and relevant
+{% endif %}
+
+**Task Parameters:**
+- **Description:** {{ desc }}
+- **Visual Style:** modern (maintain consistency with existing image)
+- **Aspect Ratio:** {{ aspectRatio }}
+- **Language:** {{ locale }}
+
+**Existing Diagram:**
+[The existing diagram image is provided as input to the model]
+
+{% if feedback %}
+**User Feedback:**
+```
+{{ feedback }}
+```
+
+**Important:** The user feedback above contains specific modification requests. Please carefully apply these changes to the diagram while maintaining visual consistency with the existing image.
+{% endif %}
+
+**Document Content:**
+{{ documentContent }}
+
+**Your responsibilities:**
+1. Analyze the existing diagram structure, style, and layout
+2. Review the document content to identify what needs to be updated
+{% if feedback %}3. Carefully apply the user feedback to make the requested modifications
+4. Maintain visual consistency with the original design (unless feedback requests style changes)
+5. Update the diagram to accurately reflect the current document content and user feedback
+6. Make necessary changes while preserving the overall visual style and structure
+{% else %}3. Maintain visual consistency with the original design
+4. Update the diagram to accurately reflect the current document content
+5. Make necessary changes while preserving the overall visual style and structure
+{% endif %}
+
+{% else %}
+# Standard Text-to-Image Generation Mode
+
+Your task is to create a professional diagram image based on the document content and description below.
+
+Please follow **all global rules, styles, aspect ratio logic, and diagram-type guidelines** defined in the system prompt.
+
+# Task Parameters:
+- **Description:** {{ desc }}
+- **Visual Style:** modern
+- **Aspect Ratio:** {{ aspectRatio }}
+- **Language:** {{ locale }}
+
+# Your responsibilities:
+1. Read and analyze the description and document content
+2. Automatically determine the most appropriate diagram type (architecture, flowchart, sequence, concept, etc.)
+3. Extract key concepts, steps, relationships, or flow sequences
+4. Generate a diagram that accurately represents these elements
+5. Apply all rules from the system prompt
+6. Labels must be concise (2–5 words) in {{ locale }}
+7. No titles or explanations outside nodes
+8. Maintain clarity, structure, and proper layout based on the aspect ratio
+
+# Description:
+{{ desc }}
+
+# Document Content:
+
+Now analyze the following document content to understand the context and details:
+
+{{ documentContent }}
+
+**Task:** Based on the description "{{ desc }}" and the document content above, determine the appropriate diagram type and create a professional diagram that clearly illustrates the concepts, flow, or architecture described.
+
+{% endif %}

package/agents/generate-images/save-image-result.mjs

@@ -0,0 +1,247 @@
+import { writeFile, mkdir, copyFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { stringify as yamlStringify } from "yaml";
+import { PATHS, ERROR_CODES } from "../../utils/agent-constants.mjs";
+import { getExtensionFromMimeType } from "../../utils/image-utils.mjs";
+
+/**
+ * Save image file
+ * @param {string} key - Image key
+ * @param {string} locale - Language code
+ * @param {Object} imageInfo - Image information { path, mimeType, ... }
+ * @returns {Promise<string>} - Saved image path
+ */
+async function saveImage(key, locale, imageInfo) {
+  const ext = getExtensionFromMimeType(imageInfo.mimeType);
+  const imagePath = join(PATHS.ASSETS_DIR, key, "images", `${locale}.${ext}`);
+
+  // Ensure directory exists
+  await mkdir(dirname(imagePath), { recursive: true });
+
+  // Copy from temporary file to target location
+  await copyFile(imageInfo.path, imagePath);
+
+  return imagePath;
+}
+
+/**
+ * Generate or update .meta.yaml
+ * @param {string} key - Image key
+ * @param {string} id - Slot id
+ * @param {string} desc - Slot description
+ * @param {Array} documents - Associated document list
+ * @param {string} locale - Main language
+ * @param {string} model - Model used
+ * @returns {Promise<void>}
+ */
+async function saveMeta(key, id, desc, documents, locale, model) {
+  const metaPath = join(PATHS.ASSETS_DIR, key, ".meta.yaml");
+
+  const meta = {
+    kind: "image",
+    slot: {
+      id,
+      key,
+      desc,
+    },
+    generation: {
+      model,
+      createdAt: new Date().toISOString(),
+      shared: false, // Default false, determined by LLM during translation
+    },
+    documents: documents.map((doc) => ({
+      path: doc.path,
+      hash: doc.hash,
+    })),
+    languages: [locale],
+  };
+
+  // Ensure directory exists
+  await mkdir(dirname(metaPath), { recursive: true });
+
+  // Save meta
+  await writeFile(metaPath, yamlStringify(meta), "utf8");
+}
+
+/**
+ * Save image generation result
+ * @param {Object} input - Input parameters (containing generation result)
+ * @returns {Promise<Object>} - Save result
+ */
+export default async function saveImageResult(input) {
+  try {
+    const { key, id, desc, documents, locale, isUpdate, imageGenParams } = input;
+
+    // Validate parameters
+    if (!key || !id || !desc || !documents || !locale) {
+      return {
+        success: false,
+        key,
+        error: "MISSING_PARAMETERS",
+        message: "Missing required parameters",
+        suggestion: "Please ensure key, id, desc, documents, locale are provided",
+      };
+    }
+
+    if (!Array.isArray(documents) || documents.length === 0) {
+      return {
+        success: false,
+        key,
+        error: "INVALID_DOCUMENTS",
+        message: "documents parameter is invalid or empty",
+        suggestion: "Please ensure at least one associated document exists",
+      };
+    }
+
+    // Get generation result from input.images
+    // Format: [{ filename, mimeType, type, path }, ...]
+    const images = input.images;
+
+    if (!images || !Array.isArray(images) || images.length === 0) {
+      return {
+        success: false,
+        key,
+        error: "GENERATION_FAILED",
+        message: "Generated image data not found",
+        suggestion: "Please check the image generation agent output format, expecting images array",
+        availableKeys: Object.keys(input),
+      };
+    }
+
+    // Use the first image
+    const imageInfo = images[0];
+    if (!imageInfo.path) {
+      return {
+        success: false,
+        key,
+        error: "INVALID_IMAGE_DATA",
+        message: "Image data missing path field",
+        suggestion: "Please check the images format returned by the image generation agent",
+      };
+    }
+
+    const model = imageGenParams?.model;
+
+    // Save image (copy from temporary path to assets directory)
+    const imagePath = await saveImage(key, locale, imageInfo);
+
+    // Save or update meta
+    await saveMeta(key, id, desc, documents, locale, model);
+
+    return {
+      success: true,
+      key,
+      imagePath,
+      isUpdate,
+      message: `Successfully ${isUpdate ? "updated" : "generated"} image: ${imagePath}`,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      key: input.key,
+      error: ERROR_CODES.UNEXPECTED_ERROR,
+      message: `Error saving image: ${error.message}`,
+      suggestion: "Please check file system permissions and image generation agent configuration",
+      stack: error.stack,
+    };
+  }
+}
+
+// Add description
+saveImageResult.description =
+  "Save image generation agent results to assets directory, " +
+  "including image file and .meta.yaml metadata file.";
+
+// Define input schema
+saveImageResult.input_schema = {
+  type: "object",
+  properties: {
+    key: {
+      type: "string",
+      description: "Image key (directory name)",
+    },
+    id: {
+      type: "string",
+      description: "Slot id",
+    },
+    desc: {
+      type: "string",
+      description: "Slot description",
+    },
+    documents: {
+      type: "array",
+      description: "Associated document list",
+      items: {
+        type: "object",
+        properties: {
+          path: { type: "string" },
+          hash: { type: "string" },
+          content: { type: "string" },
+        },
+      },
+    },
+    locale: {
+      type: "string",
+      description: "Main language code",
+    },
+    isUpdate: {
+      type: "boolean",
+      description: "Whether in update mode",
+    },
+    imageGenParams: {
+      type: "object",
+      description: "Parameters passed to image generation agent",
+    },
+    // Following fields are returned by image generation agent
+    images: {
+      type: "array",
+      description: "Image list returned by image generation agent",
+      items: {
+        type: "object",
+        properties: {
+          filename: { type: "string", description: "Filename" },
+          mimeType: { type: "string", description: "MIME type" },
+          type: { type: "string", description: "Type (local)" },
+          path: { type: "string", description: "Temporary file path" },
+        },
+      },
+    },
+  },
+  required: ["key", "id", "desc", "documents", "locale"],
+};
+
+// Define output schema
+saveImageResult.output_schema = {
+  type: "object",
+  required: ["success", "key"],
+  properties: {
+    success: {
+      type: "boolean",
+      description: "Whether operation succeeded",
+    },
+    key: {
+      type: "string",
+      description: "Image key",
+    },
+    imagePath: {
+      type: "string",
+      description: "Generated image path",
+    },
+    isUpdate: {
+      type: "boolean",
+      description: "Whether this is an update operation",
+    },
+    message: {
+      type: "string",
+      description: "Operation result description",
+    },
+    error: {
+      type: "string",
+      description: "Error code (present on failure)",
+    },
+    suggestion: {
+      type: "string",
+      description: "Suggested action (present on failure)",
+    },
+  },
+};