feat: enhance children's book agent with character consistency and dialog integration

- Add CharacterDesignAgent for detailed, consistent character descriptions across illustrations
- Implement dialog text overlay on DALL-E generated images for immersive reading experience
- Enhance IllustrationAgent with character consistency prompts and dialog integration
- Add unique book naming with topic-based filenames and timestamps
- Improve story generation with real narrative content instead of placeholders
- Add verbose logging to track dialog text processing and character design
- Update workflow with 5-step process: character design → story outline → content refinement → illustrations → PDF
- Enhance prompts to ensure actual story progression rather than generic content
- Add text cleaning and formatting for optimal readability on illustrations

Key improvements:
- Character appears identical across all pages (same face, hair, clothing, etc.)
- Story dialog text displays directly on illustration bottom with readable formatting
- Each book gets unique filename: topic-timestamp.pdf format
- Real story content with meaningful dialog and narrative progression

Author: rokon12

step-11-agent/src/main/java/ca/bazlur/agent/BookCreationOrchestrator.java

@@ -75,18 +75,30 @@ public interface BookOrchestrationService {
             3. Educational element
             4. Interactive suggestion
 
-            Format the response as:
+            Format the response EXACTLY as follows (no deviation):
             TITLE: [book title]
-            MAIN_CHARACTER: [character description]
+            MAIN_CHARACTER: [Detailed physical description including: age, gender, hair color/style, eye color, skin tone, height, clothing style, distinctive features - BE VERY SPECIFIC for consistency]
             SETTING: [setting description]
 
             PAGE_1:
-            TEXT: [page text]
-            ILLUSTRATION: [detailed description]
+            TEXT: [Actual story dialog/narration for the page - make it engaging and specific to the story]
+            ILLUSTRATION: [detailed scene description]
             EDUCATIONAL: [educational element]
             INTERACTIVE: [interactive suggestion]
 
-            [Continue for all pages...]
+            PAGE_2:
+            TEXT: [Actual story dialog/narration for the page - make it engaging and specific to the story]
+            ILLUSTRATION: [detailed scene description]
+            EDUCATIONAL: [educational element]
+            INTERACTIVE: [interactive suggestion]
+
+            PAGE_3:
+            TEXT: [Actual story dialog/narration for the page - make it engaging and specific to the story]
+            ILLUSTRATION: [detailed scene description]
+            EDUCATIONAL: [educational element]
+            INTERACTIVE: [interactive suggestion]
+
+            CRITICAL: Write actual story content for each page TEXT field, not placeholders. Each page should advance the story with specific dialog or narration.
             """)
         String createRawBookOutline(@V("topic") String topic,
                                    @V("targetAge") String targetAge,
@@ -158,15 +170,15 @@ private BookOutline parseRawOutline(String rawOutline, int expectedPageCount) {
                         currentEducational, currentInteractive);
         }
 
-        // Ensure we have the expected number of pages
+        // If we don't have enough pages, create meaningful content
         while (pages.size() < expectedPageCount) {
             var pageNum = pages.size() + 1;
             pages.add(PageOutline.builder()
                 .pageNumber(pageNum)
-                .text("Continue the adventure...")
-                .illustrationDescription("Scene showing the story continuation")
-                .educationalElement("Continued learning")
-                .interactiveElement("Ask questions about what happens next")
+                .text("\"Our adventure continues with new discoveries!\"")
+                .illustrationDescription("The main character exploring a new scene with wonder and excitement")
+                .educationalElement("Discovery and exploration")
+                .interactiveElement("What do you think happens next?")
                 .build());
         }
 

step-11-agent/src/main/java/ca/bazlur/agent/CharacterDesignAgent.java

@@ -0,0 +1,77 @@
+package ca.bazlur.agent;
+
+import ca.bazlur.config.BookCreationConfig;
+import dev.langchain4j.model.openai.OpenAiChatModel;
+import dev.langchain4j.service.AiServices;
+import dev.langchain4j.service.SystemMessage;
+import dev.langchain4j.service.UserMessage;
+import dev.langchain4j.service.V;
+
+public class CharacterDesignAgent {
+
+    private final CharacterDesignService service;
+
+    public CharacterDesignAgent(String apiKey, BookCreationConfig config) {
+        var model = OpenAiChatModel.builder()
+            .apiKey(apiKey)
+            .modelName(config.modelName())
+            .temperature(0.8) // Higher creativity for character design
+            .maxTokens(800)
+            .build();
+
+        this.service = AiServices.builder(CharacterDesignService.class)
+            .chatModel(model)
+            .build();
+    }
+
+    public interface CharacterDesignService {
+
+        @SystemMessage("""
+            You are a professional children's book character designer. You create detailed,
+            vivid character descriptions that ensure visual consistency across illustrations.
+
+            Your descriptions must be:
+            - Extremely specific about physical features
+            - Age-appropriate for the target audience
+            - Culturally diverse and inclusive
+            - Memorable and distinctive
+            - Suitable for the story theme
+
+            Include details about: age, gender, hair (color, style, length), eyes (color, shape),
+            skin tone, height/build, clothing style and colors, distinctive features, personality
+            traits that show in appearance.
+            """)
+
+        @UserMessage("""
+            Create a detailed character description for the main character of a children's book with:
+
+            Story Topic: {{topic}}
+            Target Age: {{targetAge}}
+            Character Role: {{role}}
+
+            Return ONLY the character description, being extremely specific about every visual detail
+            for illustration consistency. Make the character engaging and relatable for {{targetAge}} year olds.
+            """)
+        String createDetailedCharacterDescription(@V("topic") String topic,
+                                                 @V("targetAge") String targetAge,
+                                                 @V("role") String role);
+    }
+
+    public String generateCharacterDescription(String topic, String targetAge, String role) {
+        try {
+            return service.createDetailedCharacterDescription(topic, targetAge, role);
+        } catch (Exception e) {
+            System.err.println("⚠️  Failed to generate character description: " + e.getMessage());
+            return createFallbackCharacterDescription(targetAge, role);
+        }
+    }
+
+    private String createFallbackCharacterDescription(String targetAge, String role) {
+        return switch (targetAge) {
+            case "2-3" -> "A cheerful 3-year-old toddler with curly brown hair, bright green eyes, rosy cheeks, wearing a red striped shirt and blue overalls";
+            case "4-5" -> "A curious 5-year-old child with shoulder-length blonde hair, brown eyes, freckles on nose, wearing a purple t-shirt and jeans";
+            case "6-8" -> "An adventurous 7-year-old with black hair in a ponytail, dark brown eyes, confident smile, wearing a green adventure vest and khaki shorts";
+            default -> "A friendly child with brown hair, kind eyes, and colorful clothing suitable for adventures";
+        };
+    }
+}

step-11-agent/src/main/java/ca/bazlur/agent/IllustrationAgent.java

@@ -40,28 +40,35 @@ public IllustrationAgent(String apiKey, String illustrationStyle) {
 
     public ImagePrompt createImagePrompt(String sceneDescription,
                                        String characterDescription,
+                                       String dialogText,
                                        int pageNumber) {
         var prompt = """
             Children's book illustration in %s style.
 
             Scene: %s
 
-            Characters: %s
+            Main Character (MUST maintain exact same appearance): %s
 
-            Visual requirements:
-            - Child-friendly and cheerful
+            Dialog text to include at bottom: "%s"
+
+            CRITICAL REQUIREMENTS:
+            - Keep the EXACT same character appearance as described above in every detail
+            - Same face shape, eye color, hair style, clothing, body proportions
+            - Include the dialog text clearly readable at the bottom of the illustration
+            - Text should be in a clean, child-friendly font
+            - Text background should be semi-transparent or white for readability
+            - Child-friendly and cheerful scene
             - Bright, warm colors
-            - No text or words in the image
             - Safe for children ages 2-8
             - High quality digital art
-            - Consistent character appearance
             - Professional children's book illustration quality
 
-            Style: %s children's book illustration, professional quality
+            Style: %s children's book illustration with dialog text, professional quality
             """.formatted(
                 style,
                 sceneDescription,
                 characterDescription,
+                dialogText,
                 style
             );
 

step-11-agent/src/main/java/ca/bazlur/cli/BookCreationCLI.java

@@ -13,6 +13,8 @@
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.Paths;
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
 import java.util.concurrent.Callable;
 
 @Command(name = "book-creator",
@@ -39,8 +41,7 @@ public class BookCreationCLI implements Callable<Integer> {
     private String educationalGoals;
 
     @Option(names = {"-o", "--output"},
-            description = "Output PDF file path",
-            defaultValue = "generated-book.pdf")
+            description = "Output PDF file path (auto-generated if not specified)")
     private String outputPath;
 
     @Option(names = {"-s", "--style"},
@@ -104,8 +105,9 @@ public Integer call() throws Exception {
             // Execute workflow with progress updates
             var book = workflow.executeWithProgress(request);
 
-            // Save PDF using modern Path API
-            var outputFile = Paths.get(outputPath);
+            // Generate unique filename if not specified
+            var finalOutputPath = outputPath != null ? outputPath : generateUniqueFileName(topic, book.getTitle());
+            var outputFile = Paths.get(finalOutputPath);
             Files.write(outputFile, book.getPdfContent());
 
             printSuccess(outputFile, book);
@@ -160,6 +162,21 @@ private void printSuccess(Path outputFile, CompleteBook book) throws IOException
         System.out.println(summary);
     }
 
+    private String generateUniqueFileName(String topic, String bookTitle) {
+        // Clean the topic/title for filename
+        var cleanName = (bookTitle != null && !bookTitle.equals("A Wonderful Story")) ? bookTitle : topic;
+        cleanName = cleanName.toLowerCase()
+            .replaceAll("[^a-z0-9\\s-]", "")
+            .replaceAll("\\s+", "-")
+            .replaceAll("-+", "-")
+            .replaceAll("^-|-$", "");
+
+        // Add timestamp for uniqueness
+        var timestamp = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMdd-HHmmss"));
+
+        return String.format("%s-%s.pdf", cleanName, timestamp);
+    }
+
     public static void main(String[] args) {
         var exitCode = new CommandLine(new BookCreationCLI()).execute(args);
         System.exit(exitCode);

step-11-agent/src/main/java/ca/bazlur/workflow/BookCreationWorkflow.java

@@ -16,6 +16,7 @@ public class BookCreationWorkflow {
     private final BookCreationOrchestrator orchestrator;
     private final IllustrationAgent illustrationAgent;
     private final ContentRefinementAgent refinementAgent;
+    private final CharacterDesignAgent characterDesignAgent;
     private final PDFGenerationAgent pdfAgent;
     private final BookCreationConfig config;
     private final boolean verbose;
@@ -25,6 +26,7 @@ public BookCreationWorkflow(String apiKey, BookCreationConfig config, boolean ve
         this.orchestrator = new BookCreationOrchestrator(apiKey, config);
         this.illustrationAgent = new IllustrationAgent(apiKey, "watercolor");
         this.refinementAgent = new ContentRefinementAgent(apiKey, config);
+        this.characterDesignAgent = new CharacterDesignAgent(apiKey, config);
         this.pdfAgent = new PDFGenerationAgent();
         this.verbose = verbose;
     }
@@ -34,15 +36,31 @@ public CompleteBook executeWithProgress(BookRequest request) throws Exception {
         var pages = new ArrayList<BookPage>();
 
         try {
-            // Step 1: Generate book outline
-            printStep(1, "Generating story outline");
+            // Step 1: Generate detailed character design
+            printStep(1, "Creating detailed character design");
+            var detailedCharacter = characterDesignAgent.generateCharacterDescription(
+                request.getTopic(),
+                request.getTargetAge(),
+                "main character"
+            );
+            System.out.println("  ✓ Character design: " +
+                (detailedCharacter.length() > 100 ?
+                    detailedCharacter.substring(0, 100) + "..." :
+                    detailedCharacter));
+
+            // Step 2: Generate book outline
+            printStep(2, "Generating story outline");
             var outline = orchestrator.generateOutline(request);
             System.out.println("  ✓ Title: " + outline.getTitle());
             System.out.println("  ✓ Main character: " + outline.getMainCharacter());
             System.out.println("  ✓ Setting: " + outline.getSetting());
 
-            // Step 2: Refine content for each page
-            printStep(2, "Refining content for " + request.getPageCount() + " pages");
+            // Use the detailed character design for illustrations
+            var finalCharacterDescription = detailedCharacter.isEmpty() ?
+                outline.getMainCharacter() : detailedCharacter;
+
+            // Step 3: Refine content for each page
+            printStep(3, "Refining content for " + request.getPageCount() + " pages");
             var refinementTasks = new ArrayList<CompletableFuture<BookPage>>();
 
             try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
@@ -56,7 +74,7 @@ public CompleteBook executeWithProgress(BookRequest request) throws Exception {
                                 var preview = pageOutline.getText().length() > 50 ?
                                     pageOutline.getText().substring(0, 50) + "..." :
                                     pageOutline.getText();
-                                System.out.println("  📄 Page " + (pageIndex + 1) + ": " + preview);
+                                System.out.println("  📄 Page " + (pageIndex + 1) + " original: " + preview);
                             }
 
                             // Refine text for age appropriateness
@@ -65,6 +83,13 @@ public CompleteBook executeWithProgress(BookRequest request) throws Exception {
                                 request.getTargetAge()
                             );
 
+                            if (verbose) {
+                                var refinedPreview = refinedText.length() > 50 ?
+                                    refinedText.substring(0, 50) + "..." :
+                                    refinedText;
+                                System.out.println("  📝 Page " + (pageIndex + 1) + " refined: " + refinedPreview);
+                            }
+
                             return BookPage.builder()
                                 .pageNumber(pageIndex + 1)
                                 .text(refinedText)
@@ -91,16 +116,16 @@ public CompleteBook executeWithProgress(BookRequest request) throws Exception {
                 }
             }
 
-            // Step 3: Generate illustrations (unless dry run)
+            // Step 4: Generate illustrations (unless dry run)
             if (!request.isDryRun()) {
-                printStep(3, "Generating illustrations");
-                generateIllustrations(pages, outline.getMainCharacter());
+                printStep(4, "Generating illustrations with dialog text");
+                generateIllustrations(pages, finalCharacterDescription);
             } else {
-                printStep(3, "Skipping image generation (dry run mode)");
+                printStep(4, "Skipping image generation (dry run mode)");
             }
 
-            // Step 4: Generate PDF
-            printStep(4, "Creating PDF");
+            // Step 5: Generate PDF
+            printStep(5, "Creating PDF");
             var book = CompleteBook.builder()
                 .title(outline.getTitle())
                 .author("Generated by AI Book Creator")
@@ -131,9 +156,17 @@ public CompleteBook executeWithProgress(BookRequest request) throws Exception {
     private void generateIllustrations(List<BookPage> pages, String mainCharacter) {
         for (var page : pages) {
             try {
+                // Clean and format the dialog text for display
+                var dialogText = cleanDialogText(page.getText());
+
+                if (verbose) {
+                    System.out.println("  🎭 Dialog for page " + page.getPageNumber() + ": \"" + dialogText + "\"");
+                }
+
                 var prompt = illustrationAgent.createImagePrompt(
                     page.getIllustrationDescription(),
                     mainCharacter,
+                    dialogText,
                     page.getPageNumber()
                 );
 
@@ -151,6 +184,32 @@ private void generateIllustrations(List<BookPage> pages, String mainCharacter) {
         }
     }
 
+    private String cleanDialogText(String text) {
+        if (text == null || text.trim().isEmpty()) {
+            return "Let's continue our adventure!";
+        }
+
+        // Remove extra whitespace and limit length for readability on image
+        var cleaned = text.trim().replaceAll("\\s+", " ");
+
+        // Limit to about 60 characters for good readability on illustration
+        if (cleaned.length() > 60) {
+            var words = cleaned.split(" ");
+            var result = new StringBuilder();
+            for (var word : words) {
+                if (result.length() + word.length() + 1 <= 60) {
+                    if (result.length() > 0) result.append(" ");
+                    result.append(word);
+                } else {
+                    break;
+                }
+            }
+            cleaned = result.toString() + "...";
+        }
+
+        return cleaned;
+    }
+
     private BookPage createFallbackPage(PageOutline pageOutline, int pageNumber) {
         return BookPage.builder()
             .pageNumber(pageNumber)