@willwade/aac-processors 0.0.13 → 0.0.14

package/README.md

@@ -199,6 +199,7 @@ console.log("Translation complete!");
 The library includes an optional high-performance analytics engine for evaluating AAC board sets based on the **AAC Effort Algorithm (v0.2)**.
 
 #### **Key Metrics Features**
+
 - **Effort Scores**: Calculate the physical/cognitive cost of any word (Distance, Field Size, Motor Planning).
 - **Vocabulary Coverage**: Compare board sets against core vocabulary lists (e.g., Anderson & Bitner).
 - **Sentence Analysis**: Measure the effort required to construct common test sentences.
@@ -207,10 +208,10 @@ The library includes an optional high-performance analytics engine for evaluatin
 For detailed documentation, see the **[AAC Metrics Guide](./src/optional/analytics/docs/AAC_METRICS_GUIDE.md)** and **[Vocabulary Analysis Guide](./src/optional/analytics/docs/VOCABULARY_ANALYSIS_GUIDE.md)**.
 
 ```typescript
-import { ObfsetProcessor, Analytics } from '@willwade/aac-processors';
+import { ObfsetProcessor, Analytics } from "@willwade/aac-processors";
 
 const processor = new ObfsetProcessor();
-const tree = processor.loadIntoTree('my_pageset.obfset');
+const tree = processor.loadIntoTree("my_pageset.obfset");
 
 // Run clinical effort analysis
 const result = new Analytics.MetricsCalculator().analyze(tree);
@@ -738,6 +739,7 @@ npm run coverage:report
 ### 🛠️ Utility Scripts
 
 A wide range of utility scripts for batch processing, audio generation, and advanced analysis are available in the **[scripts/](./scripts/README.md)** directory. These include:
+
 - **Analysis**: Pageset reporting and vocabulary extraction.
 - **Audio**: Automated TTS generation and audio-enhanced pageset creation.
 - **Conversion**: TSV-to-Gridset and other format-shifting tools.
@@ -845,13 +847,10 @@ Inspired by the Python AACProcessors project
 
 - [ ] **Adaptive Metrics** - Expand scanning analysis to include dwell times and more complex switch logic configurations.
 
-
 ### Low Priority
 
-
 - [ ] **Batch processing CLI** - Process multiple files/directories in parallel.
 
-
 ### Contributing
 
 Want to help with any of these items? See our [Contributing Guidelines](#-contributing) and pick an issue that interests you!

package/dist/core/baseProcessor.d.ts

@@ -1,3 +1,44 @@
+/**
+ * Base Processor for AAC File Formats
+ *
+ * This module provides base functionality for processing AAC (Augmentative and Alternative
+ * Communication) files across various formats (gridset, OBF, Snap, TouchChat, etc.).
+ *
+ * ## LLM-Based Translation with Symbol Preservation
+ *
+ * All processor formats support LLM-based translation that preserves symbol-to-word
+ * associations across languages. This is critical for AAC systems where visual symbols
+ * are attached to specific words.
+ *
+ * ### Usage Example:
+ *
+ * ```typescript
+ * import { extractAllButtonsForTranslation, createTranslationPrompt } from '../optional/translation/translationProcessor';
+ *
+ * // 1. Extract buttons from your format
+ * const buttons = extractAllButtonsForTranslation(myFormatButtons, (button) => ({
+ *   pageId: button.pageId,
+ *   pageName: button.pageName
+ * }));
+ *
+ * // 2. Create prompt for LLM
+ * const prompt = createTranslationPrompt(buttons, 'Spanish');
+ *
+ * // 3. Send to LLM (Gemini, GPT, etc.) and get response
+ * const llmResponse = await callLLMAPI(prompt);
+ *
+ * // 4. Apply translations to your format
+ * processor.processLLMTranslations(filePath, llmResponse, outputPath);
+ * ```
+ *
+ * ### Format-Specific Implementation:
+ *
+ * Each processor should implement:
+ * - `extractSymbolsForLLM()` - Uses extractAllButtonsForTranslation() utility
+ * - `processLLMTranslations()` - Applies translations using format-specific logic
+ *
+ * See `src/utilities/translation/translationProcessor.ts` for shared utilities.
+ */
 import { AACTree, AACButton } from './treeStructure';
 import { StringCasing } from './stringCasing';
 import { ValidationResult } from '../validation/validationTypes';

package/dist/core/baseProcessor.js

@@ -1,4 +1,45 @@
 "use strict";
+/**
+ * Base Processor for AAC File Formats
+ *
+ * This module provides base functionality for processing AAC (Augmentative and Alternative
+ * Communication) files across various formats (gridset, OBF, Snap, TouchChat, etc.).
+ *
+ * ## LLM-Based Translation with Symbol Preservation
+ *
+ * All processor formats support LLM-based translation that preserves symbol-to-word
+ * associations across languages. This is critical for AAC systems where visual symbols
+ * are attached to specific words.
+ *
+ * ### Usage Example:
+ *
+ * ```typescript
+ * import { extractAllButtonsForTranslation, createTranslationPrompt } from '../optional/translation/translationProcessor';
+ *
+ * // 1. Extract buttons from your format
+ * const buttons = extractAllButtonsForTranslation(myFormatButtons, (button) => ({
+ *   pageId: button.pageId,
+ *   pageName: button.pageName
+ * }));
+ *
+ * // 2. Create prompt for LLM
+ * const prompt = createTranslationPrompt(buttons, 'Spanish');
+ *
+ * // 3. Send to LLM (Gemini, GPT, etc.) and get response
+ * const llmResponse = await callLLMAPI(prompt);
+ *
+ * // 4. Apply translations to your format
+ * processor.processLLMTranslations(filePath, llmResponse, outputPath);
+ * ```
+ *
+ * ### Format-Specific Implementation:
+ *
+ * Each processor should implement:
+ * - `extractSymbolsForLLM()` - Uses extractAllButtonsForTranslation() utility
+ * - `processLLMTranslations()` - Applies translations using format-specific logic
+ *
+ * See `src/utilities/translation/translationProcessor.ts` for shared utilities.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseProcessor = void 0;
 const treeStructure_1 = require("./treeStructure");

package/dist/index.d.ts

@@ -3,8 +3,8 @@ export * from './core/baseProcessor';
 export * from './core/stringCasing';
 export * from './processors';
 export * from './validation';
-export * as Analytics from './optional/analytics';
-export { collectUnifiedHistory, listGrid3Users as listHistoryGrid3Users, listSnapUsers as listHistorySnapUsers, } from './optional/analytics/history';
+export * as Analytics from './utilities/analytics';
+export { collectUnifiedHistory, listGrid3Users as listHistoryGrid3Users, listSnapUsers as listHistorySnapUsers, } from './utilities/analytics/history';
 import { BaseProcessor } from './core/baseProcessor';
 /**
  * Factory function to get the appropriate processor for a file extension

package/dist/index.js

@@ -36,8 +36,8 @@ __exportStar(require("./core/baseProcessor"), exports);
 __exportStar(require("./core/stringCasing"), exports);
 __exportStar(require("./processors"), exports);
 __exportStar(require("./validation"), exports);
-exports.Analytics = __importStar(require("./optional/analytics"));
-var history_1 = require("./optional/analytics/history");
+exports.Analytics = __importStar(require("./utilities/analytics"));
+var history_1 = require("./utilities/analytics/history");
 Object.defineProperty(exports, "collectUnifiedHistory", { enumerable: true, get: function () { return history_1.collectUnifiedHistory; } });
 Object.defineProperty(exports, "listHistoryGrid3Users", { enumerable: true, get: function () { return history_1.listGrid3Users; } });
 Object.defineProperty(exports, "listHistorySnapUsers", { enumerable: true, get: function () { return history_1.listSnapUsers; } });

package/dist/processors/gridset/symbolAlignment.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Symbol Alignment for Translation
+ *
+ * Utilities to preserve symbol positions during text translation.
+ * When translating AAC gridset messages that contain symbols attached
+ * to specific words, we need to maintain the symbol-to-word associations
+ * across languages.
+ *
+ * Example:
+ *   English: "I want apple juice" with apple symbol on "apple"
+ *   Spanish: "Yo quiero jugo de manzana" with apple symbol on "manzana"
+ */
+/**
+ * Represents a symbol anchored to a specific word in the text
+ */
+export interface SymbolAnchor {
+    symbolRef: string;
+    wordIndex: number;
+    originalWord: string;
+    startPos: number;
+    endPos: number;
+}
+/**
+ * Parsed message with symbol anchors
+ */
+export interface ParsedMessage {
+    text: string;
+    words: string[];
+    symbols: SymbolAnchor[];
+}
+/**
+ * Translation result with preserved symbols
+ */
+export interface TranslatedMessage {
+    text: string;
+    alignment: {
+        originalWord: string;
+        translatedWord: string;
+        originalIndex: number;
+        translatedIndex: number;
+    }[];
+}
+/**
+ * Parse a message to extract text and symbol anchors.
+ *
+ * This handles various formats:
+ * 1. Plain text with no symbols
+ * 2. Rich text with embedded symbol markers (future enhancement)
+ * 3. Text where symbols are tracked separately (via richText.symbols)
+ *
+ * For now, this assumes symbols are tracked separately in the richText structure.
+ * The text itself is plain, and we need to tokenize it to find word positions.
+ *
+ * @param message - The message text (may contain words or be plain)
+ * @param richTextSymbols - Optional symbols from richText.symbols array
+ * @returns Parsed message with word positions and symbol anchors
+ */
+export declare function parseMessageWithSymbols(message: string, richTextSymbols?: Array<{
+    text: string;
+    image?: string;
+}>): ParsedMessage;
+/**
+ * Align words from original text to translated text.
+ *
+ * This is a simple alignment strategy that works for many cases:
+ * 1. Exact word matching (for cognates, names, numbers)
+ * 2. Position-based alignment (assumes similar word order)
+ *
+ * For more accurate alignment, you could integrate with:
+ * - Translation APIs that return alignment (e.g., Google Translate's word alignment)
+ * - Statistical machine translation alignment tools
+ * - Bilingual dictionaries
+ *
+ * @param originalWords - Words from the original text
+ * @param translatedWords - Words from the translated text
+ * @returns Alignment mapping between original and translated word indices
+ */
+export declare function alignWords(originalWords: string[], translatedWords: string[]): TranslatedMessage['alignment'];
+/**
+ * Reattach symbols to translated text based on word alignment.
+ *
+ * @param translatedText - The translated plain text
+ * @param originalParsed - The original parsed message with symbols
+ * @param alignment - Word alignment between original and translation
+ * @returns Translated text with symbols embedded (as rich text structure)
+ */
+export declare function reattachSymbols(translatedText: string, originalParsed: ParsedMessage, alignment: TranslatedMessage['alignment']): {
+    text: string;
+    richTextSymbols: Array<{
+        text: string;
+        image?: string;
+    }>;
+};
+/**
+ * Complete pipeline: translate a message while preserving symbol positions.
+ *
+ * @param originalMessage - The original message text
+ * @param translatedText - The translated text (from translation API)
+ * @param richTextSymbols - Original symbols from richText.symbols
+ * @returns Object with translated text and aligned symbols
+ */
+export declare function translateWithSymbols(originalMessage: string, translatedText: string, richTextSymbols?: Array<{
+    text: string;
+    image?: string;
+}>): {
+    text: string;
+    richTextSymbols: Array<{
+        text: string;
+        image?: string;
+    }>;
+};
+/**
+ * Extract symbols from a button for use during translation.
+ *
+ * This helper extracts symbols from either:
+ * - button.semanticAction.richText.symbols
+ * - button.image (if it's a symbol library reference)
+ *
+ * @param button - The AAC button
+ * @returns Array of symbol attachments
+ */
+export declare function extractSymbolsFromButton(button: any): Array<{
+    text: string;
+    image?: string;
+}> | undefined;

package/dist/processors/gridset/symbolAlignment.js

@@ -0,0 +1,283 @@
+"use strict";
+/**
+ * Symbol Alignment for Translation
+ *
+ * Utilities to preserve symbol positions during text translation.
+ * When translating AAC gridset messages that contain symbols attached
+ * to specific words, we need to maintain the symbol-to-word associations
+ * across languages.
+ *
+ * Example:
+ *   English: "I want apple juice" with apple symbol on "apple"
+ *   Spanish: "Yo quiero jugo de manzana" with apple symbol on "manzana"
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseMessageWithSymbols = parseMessageWithSymbols;
+exports.alignWords = alignWords;
+exports.reattachSymbols = reattachSymbols;
+exports.translateWithSymbols = translateWithSymbols;
+exports.extractSymbolsFromButton = extractSymbolsFromButton;
+/**
+ * Parse a message to extract text and symbol anchors.
+ *
+ * This handles various formats:
+ * 1. Plain text with no symbols
+ * 2. Rich text with embedded symbol markers (future enhancement)
+ * 3. Text where symbols are tracked separately (via richText.symbols)
+ *
+ * For now, this assumes symbols are tracked separately in the richText structure.
+ * The text itself is plain, and we need to tokenize it to find word positions.
+ *
+ * @param message - The message text (may contain words or be plain)
+ * @param richTextSymbols - Optional symbols from richText.symbols array
+ * @returns Parsed message with word positions and symbol anchors
+ */
+function parseMessageWithSymbols(message, richTextSymbols) {
+    // Normalize whitespace for consistent tokenization
+    const normalizedMessage = message.trim().replace(/\s+/g, ' ');
+    // Tokenize into words, preserving punctuation
+    const words = [];
+    const wordPositions = [];
+    // Split by whitespace but track positions
+    let currentPos = 0;
+    const parts = normalizedMessage.split(/(\s+)/); // Keep delimiters
+    for (const part of parts) {
+        if (part.trim().length > 0) {
+            // This is a word
+            const startPos = currentPos;
+            const endPos = currentPos + part.length;
+            words.push(part);
+            wordPositions.push({ start: startPos, end: endPos, word: part });
+            currentPos = endPos;
+        }
+        else {
+            // This is whitespace
+            currentPos += part.length;
+        }
+    }
+    // Extract symbol anchors from richText.symbols if provided
+    const symbols = [];
+    if (richTextSymbols && richTextSymbols.length > 0) {
+        for (const sym of richTextSymbols) {
+            // Find which word this symbol is attached to
+            const wordIndex = words.findIndex((w) => w === sym.text);
+            if (wordIndex !== -1) {
+                const pos = wordPositions[wordIndex];
+                symbols.push({
+                    symbolRef: sym.image || '',
+                    wordIndex,
+                    originalWord: sym.text,
+                    startPos: pos.start,
+                    endPos: pos.end,
+                });
+            }
+            else {
+                // Fuzzy match - find closest word (handles case differences, punctuation)
+                const normalizedSymText = sym.text.toLowerCase().replace(/[^\w]/g, '');
+                const fuzzyIndex = words.findIndex((w) => w.toLowerCase().replace(/[^\w]/g, '') === normalizedSymText);
+                if (fuzzyIndex !== -1) {
+                    const pos = wordPositions[fuzzyIndex];
+                    symbols.push({
+                        symbolRef: sym.image || '',
+                        wordIndex: fuzzyIndex,
+                        originalWord: words[fuzzyIndex],
+                        startPos: pos.start,
+                        endPos: pos.end,
+                    });
+                }
+            }
+        }
+    }
+    return {
+        text: normalizedMessage,
+        words,
+        symbols,
+    };
+}
+/**
+ * Align words from original text to translated text.
+ *
+ * This is a simple alignment strategy that works for many cases:
+ * 1. Exact word matching (for cognates, names, numbers)
+ * 2. Position-based alignment (assumes similar word order)
+ *
+ * For more accurate alignment, you could integrate with:
+ * - Translation APIs that return alignment (e.g., Google Translate's word alignment)
+ * - Statistical machine translation alignment tools
+ * - Bilingual dictionaries
+ *
+ * @param originalWords - Words from the original text
+ * @param translatedWords - Words from the translated text
+ * @returns Alignment mapping between original and translated word indices
+ */
+function alignWords(originalWords, translatedWords) {
+    const alignment = [];
+    // Strategy 1: Try to match identical words (numbers, names, cognates)
+    const matchedTranslatedIndices = new Set();
+    for (let origIdx = 0; origIdx < originalWords.length; origIdx++) {
+        const origWord = originalWords[origIdx];
+        const normalizedOrig = origWord.toLowerCase().replace(/[^\w]/g, '');
+        // Try to find this word in the translation
+        for (let transIdx = 0; transIdx < translatedWords.length; transIdx++) {
+            if (matchedTranslatedIndices.has(transIdx))
+                continue;
+            const transWord = translatedWords[transIdx];
+            const normalizedTrans = transWord.toLowerCase().replace(/[^\w]/g, '');
+            // Exact match (case-insensitive, ignoring punctuation)
+            if (normalizedOrig === normalizedTrans && normalizedOrig.length > 0) {
+                alignment.push({
+                    originalWord: origWord,
+                    translatedWord: transWord,
+                    originalIndex: origIdx,
+                    translatedIndex: transIdx,
+                });
+                matchedTranslatedIndices.add(transIdx);
+                break;
+            }
+        }
+    }
+    // Strategy 2: For unmatched words, use positional alignment
+    // This is a simple fallback that assumes similar word order
+    for (let origIdx = 0; origIdx < originalWords.length; origIdx++) {
+        if (alignment.find((a) => a.originalIndex === origIdx))
+            continue; // Already matched
+        // Find the closest unmatched position in translation
+        let bestTransIdx = -1;
+        let minDistance = Infinity;
+        for (let transIdx = 0; transIdx < translatedWords.length; transIdx++) {
+            if (matchedTranslatedIndices.has(transIdx))
+                continue;
+            // Calculate relative position
+            const relativeOrigPos = origIdx / originalWords.length;
+            const relativeTransPos = transIdx / translatedWords.length;
+            const distance = Math.abs(relativeOrigPos - relativeTransPos);
+            if (distance < minDistance) {
+                minDistance = distance;
+                bestTransIdx = transIdx;
+            }
+        }
+        if (bestTransIdx !== -1) {
+            alignment.push({
+                originalWord: originalWords[origIdx],
+                translatedWord: translatedWords[bestTransIdx],
+                originalIndex: origIdx,
+                translatedIndex: bestTransIdx,
+            });
+            matchedTranslatedIndices.add(bestTransIdx);
+        }
+    }
+    return alignment;
+}
+/**
+ * Reattach symbols to translated text based on word alignment.
+ *
+ * @param translatedText - The translated plain text
+ * @param originalParsed - The original parsed message with symbols
+ * @param alignment - Word alignment between original and translation
+ * @returns Translated text with symbols embedded (as rich text structure)
+ */
+function reattachSymbols(translatedText, originalParsed, alignment) {
+    // Tokenize the translated text
+    const translatedWords = translatedText
+        .trim()
+        .replace(/\s+/g, ' ')
+        .split(/\s+/)
+        .filter((w) => w.length > 0);
+    // Create the rich text symbols array
+    const richTextSymbols = [];
+    for (const symbol of originalParsed.symbols) {
+        // Find the alignment for this word
+        const wordAlignment = alignment.find((a) => a.originalIndex === symbol.wordIndex);
+        if (wordAlignment && wordAlignment.translatedIndex < translatedWords.length) {
+            const translatedWord = translatedWords[wordAlignment.translatedIndex];
+            // Attach the symbol to the translated word
+            richTextSymbols.push({
+                text: translatedWord,
+                image: symbol.symbolRef,
+            });
+        }
+        else {
+            // Fallback: keep symbol on original word if no alignment found
+            richTextSymbols.push({
+                text: symbol.originalWord,
+                image: symbol.symbolRef,
+            });
+        }
+    }
+    return {
+        text: translatedText,
+        richTextSymbols,
+    };
+}
+/**
+ * Complete pipeline: translate a message while preserving symbol positions.
+ *
+ * @param originalMessage - The original message text
+ * @param translatedText - The translated text (from translation API)
+ * @param richTextSymbols - Original symbols from richText.symbols
+ * @returns Object with translated text and aligned symbols
+ */
+function translateWithSymbols(originalMessage, translatedText, richTextSymbols) {
+    // Step 1: Parse original message
+    const parsedOriginal = parseMessageWithSymbols(originalMessage, richTextSymbols);
+    // If no symbols, return as-is
+    if (parsedOriginal.symbols.length === 0) {
+        return {
+            text: translatedText,
+            richTextSymbols: [],
+        };
+    }
+    // Step 2: Tokenize translated text
+    const translatedWords = translatedText
+        .trim()
+        .replace(/\s+/g, ' ')
+        .split(/\s+/)
+        .filter((w) => w.length > 0);
+    // Step 3: Align words
+    const alignment = alignWords(parsedOriginal.words, translatedWords);
+    // Step 4: Reattach symbols
+    const result = reattachSymbols(translatedText, parsedOriginal, alignment);
+    return result;
+}
+/**
+ * Extract symbols from a button for use during translation.
+ *
+ * This helper extracts symbols from either:
+ * - button.semanticAction.richText.symbols
+ * - button.image (if it's a symbol library reference)
+ *
+ * @param button - The AAC button
+ * @returns Array of symbol attachments
+ */
+function extractSymbolsFromButton(button) {
+    // First check richText structure
+    if (button.semanticAction?.richText?.symbols) {
+        return button.semanticAction.richText.symbols;
+    }
+    // Check if button has a symbol library reference as image
+    if (button.symbolLibrary && button.symbolPath) {
+        // Create a symbol attachment for the label/message
+        const text = button.label || button.message || '';
+        if (text) {
+            return [
+                {
+                    text,
+                    image: `[${button.symbolLibrary}]${button.symbolPath}`,
+                },
+            ];
+        }
+    }
+    // Check if image field contains a symbol reference
+    if (button.image && button.image.startsWith('[')) {
+        const text = button.label || button.message || '';
+        if (text) {
+            return [
+                {
+                    text,
+                    image: button.image,
+                },
+            ];
+        }
+    }
+    return undefined;
+}

package/dist/processors/gridsetProcessor.d.ts

@@ -1,5 +1,6 @@
 import { BaseProcessor, ProcessorOptions, ExtractStringsResult, TranslatedString, SourceString } from '../core/baseProcessor';
 import { AACTree } from '../core/treeStructure';
+import { type ButtonForTranslation, type LLMLTranslationResult } from '../utilities/translation/translationProcessor';
 import { ValidationResult } from '../validation/validationTypes';
 declare class GridsetProcessor extends BaseProcessor {
     constructor(options?: ProcessorOptions);
@@ -18,6 +19,31 @@ declare class GridsetProcessor extends BaseProcessor {
     extractTexts(filePathOrBuffer: string | Buffer): string[];
     loadIntoTree(filePathOrBuffer: string | Buffer): AACTree;
     processTexts(filePathOrBuffer: string | Buffer, translations: Map<string, string>, outputPath: string): Buffer;
+    /**
+     * Extract symbol information from a gridset for LLM-based translation.
+     * Returns a structured format showing which buttons have symbols and their context.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to gridset file or buffer
+     * @returns Array of symbol information for LLM processing
+     */
+    extractSymbolsForLLM(filePathOrBuffer: string | Buffer): ButtonForTranslation[];
+    /**
+     * Apply LLM translations with symbol information.
+     * The LLM should provide translations with symbol attachments in the correct positions.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to gridset file or buffer
+     * @param llmTranslations - Array of LLM translations with symbol info
+     * @param outputPath - Where to save the translated gridset
+     * @param options - Translation options (e.g., allowPartial for testing)
+     * @returns Buffer of the translated gridset
+     */
+    processLLMTranslations(filePathOrBuffer: string | Buffer, llmTranslations: LLMLTranslationResult[], outputPath: string, options?: {
+        allowPartial?: boolean;
+    }): Buffer;
     saveFromTree(tree: AACTree, outputPath: string): void;
     private calculateColumnDefinitions;
     private calculateRowDefinitions;