@willwade/aac-processors 0.0.13 → 0.0.15

package/dist/utilities/translation/translationProcessor.d.ts

@@ -0,0 +1,119 @@
+/**
+ * LLM-Based Translation with Symbol Preservation
+ *
+ * This module provides utilities for translating AAC files while preserving
+ * symbol-to-word associations across different formats (gridset, OBF, Snap, etc.).
+ *
+ * The key insight: Different AAC formats have different internal structures,
+ * but they all share common concepts:
+ * - Buttons with labels and messages
+ * - Symbols attached to specific words
+ * - Need to preserve symbol positions during translation
+ *
+ * This module provides a format-agnostic way to:
+ * 1. Extract symbol information for LLM processing
+ * 2. Apply LLM translations with preserved symbols
+ *
+ * Usage:
+ * 1. Processor extracts buttons and calls extractSymbolsForLLM()
+ * 2. LLM translates and returns aligned symbols
+ * 3. Processor calls processLLMTranslations() to apply results
+ */
+/**
+ * Represents a symbol attached to text in a format-agnostic way
+ */
+export interface SymbolInfo {
+    text: string;
+    image?: string;
+    symbolLibrary?: string;
+    symbolPath?: string;
+}
+/**
+ * Button data extracted for translation (format-agnostic)
+ */
+export interface ButtonForTranslation {
+    buttonId: string;
+    pageId?: string;
+    pageName?: string;
+    label: string;
+    message: string;
+    textToTranslate: string;
+    symbols: SymbolInfo[];
+}
+/**
+ * LLM translation result with symbol mappings
+ */
+export interface LLMLTranslationResult {
+    buttonId: string;
+    translatedLabel?: string;
+    translatedMessage?: string;
+    symbols?: Array<{
+        text: string;
+        image?: string;
+    }>;
+}
+/**
+ * Extract symbols from a button for LLM-based translation.
+ *
+ * This is a format-agnostic helper that processors can use to normalize
+ * their button data into a common format for LLM processing.
+ *
+ * @param buttonId - Unique identifier for the button
+ * @param label - Button label text
+ * @param message - Button message/speak text
+ * @param symbols - Array of symbols from the button
+ * @param context - Optional page context
+ * @returns Normalized button data for translation
+ */
+export declare function normalizeButtonForTranslation(buttonId: string, label: string, message: string, symbols: SymbolInfo[], context?: {
+    pageId?: string;
+    pageName?: string;
+}): ButtonForTranslation;
+/**
+ * Extract symbols from various button formats.
+ *
+ * This helper handles different ways symbols might be stored in button data:
+ * - semanticAction.richText.symbols (gridset format)
+ * - symbolLibrary + symbolPath fields
+ * - image field with [library]path format
+ *
+ * @param button - Button object from any AAC format
+ * @returns Array of symbol info, or undefined if no symbols
+ */
+export declare function extractSymbolsFromButton(button: any): SymbolInfo[] | undefined;
+/**
+ * Extract all buttons from a file for LLM translation.
+ *
+ * This is a convenience method that processors can use to extract all
+ * translatable buttons with their symbols in a format-agnostic way.
+ *
+ * @param buttons - Array of button objects from any AAC format
+ * @param contextFn - Optional function to provide page context for each button
+ * @returns Array of normalized button data ready for LLM translation
+ */
+export declare function extractAllButtonsForTranslation(buttons: any[], contextFn?: (button: any) => {
+    pageId?: string;
+    pageName?: string;
+}): ButtonForTranslation[];
+/**
+ * Create a prompt for LLM translation with symbol preservation.
+ *
+ * This generates a structured prompt that instructs the LLM to translate
+ * while preserving symbol-to-word associations.
+ *
+ * @param buttons - Buttons to translate
+ * @param targetLanguage - Target language for translation
+ * @returns Prompt string for LLM
+ */
+export declare function createTranslationPrompt(buttons: ButtonForTranslation[], targetLanguage: string): string;
+/**
+ * Validate LLM translation results before applying.
+ *
+ * @param translations - LLM translation results
+ * @param originalButtonIds - Expected button IDs (optional, for validation)
+ * @param options - Validation options
+ * @throws Error if validation fails
+ */
+export declare function validateTranslationResults(translations: LLMLTranslationResult[], originalButtonIds?: string[], options?: {
+    allowPartial?: boolean;
+}): void;

package/dist/utilities/translation/translationProcessor.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * LLM-Based Translation with Symbol Preservation
+ *
+ * This module provides utilities for translating AAC files while preserving
+ * symbol-to-word associations across different formats (gridset, OBF, Snap, etc.).
+ *
+ * The key insight: Different AAC formats have different internal structures,
+ * but they all share common concepts:
+ * - Buttons with labels and messages
+ * - Symbols attached to specific words
+ * - Need to preserve symbol positions during translation
+ *
+ * This module provides a format-agnostic way to:
+ * 1. Extract symbol information for LLM processing
+ * 2. Apply LLM translations with preserved symbols
+ *
+ * Usage:
+ * 1. Processor extracts buttons and calls extractSymbolsForLLM()
+ * 2. LLM translates and returns aligned symbols
+ * 3. Processor calls processLLMTranslations() to apply results
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeButtonForTranslation = normalizeButtonForTranslation;
+exports.extractSymbolsFromButton = extractSymbolsFromButton;
+exports.extractAllButtonsForTranslation = extractAllButtonsForTranslation;
+exports.createTranslationPrompt = createTranslationPrompt;
+exports.validateTranslationResults = validateTranslationResults;
+/**
+ * Extract symbols from a button for LLM-based translation.
+ *
+ * This is a format-agnostic helper that processors can use to normalize
+ * their button data into a common format for LLM processing.
+ *
+ * @param buttonId - Unique identifier for the button
+ * @param label - Button label text
+ * @param message - Button message/speak text
+ * @param symbols - Array of symbols from the button
+ * @param context - Optional page context
+ * @returns Normalized button data for translation
+ */
+function normalizeButtonForTranslation(buttonId, label, message, symbols, context) {
+    return {
+        buttonId,
+        label,
+        message,
+        textToTranslate: message || label, // Translate message if present, otherwise label
+        symbols,
+        ...context,
+    };
+}
+/**
+ * Extract symbols from various button formats.
+ *
+ * This helper handles different ways symbols might be stored in button data:
+ * - semanticAction.richText.symbols (gridset format)
+ * - symbolLibrary + symbolPath fields
+ * - image field with [library]path format
+ *
+ * @param button - Button object from any AAC format
+ * @returns Array of symbol info, or undefined if no symbols
+ */
+function extractSymbolsFromButton(button) {
+    const symbols = [];
+    // Method 1: Check for semanticAction.richText.symbols (gridset format)
+    if (button.semanticAction?.richText?.symbols) {
+        const richTextSymbols = button.semanticAction.richText.symbols;
+        if (Array.isArray(richTextSymbols) && richTextSymbols.length > 0) {
+            symbols.push(...richTextSymbols);
+            return symbols;
+        }
+    }
+    // Determine the text to attach symbol to
+    const text = button.label || button.message || '';
+    if (!text) {
+        return undefined;
+    }
+    // Method 2: Check for symbolLibrary + symbolPath fields
+    if (button.symbolLibrary && button.symbolPath) {
+        symbols.push({
+            text,
+            image: `[${button.symbolLibrary}]${button.symbolPath}`,
+            symbolLibrary: button.symbolLibrary,
+            symbolPath: button.symbolPath,
+        });
+        return symbols;
+    }
+    // Method 3: Check if image field contains a symbol reference
+    if (button.image && typeof button.image === 'string' && button.image.startsWith('[')) {
+        symbols.push({
+            text,
+            image: button.image,
+        });
+        return symbols;
+    }
+    // No symbols found
+    return undefined;
+}
+/**
+ * Extract all buttons from a file for LLM translation.
+ *
+ * This is a convenience method that processors can use to extract all
+ * translatable buttons with their symbols in a format-agnostic way.
+ *
+ * @param buttons - Array of button objects from any AAC format
+ * @param contextFn - Optional function to provide page context for each button
+ * @returns Array of normalized button data ready for LLM translation
+ */
+function extractAllButtonsForTranslation(buttons, contextFn) {
+    const results = [];
+    for (const button of buttons) {
+        if (!button)
+            continue;
+        const buttonId = (button.id || button.buttonId || `button_${results.length}`);
+        const label = (button.label || '');
+        const message = (button.message || '');
+        const symbols = extractSymbolsFromButton(button);
+        // Only include buttons that have text to translate
+        if (!label && !message)
+            continue;
+        const context = contextFn ? contextFn(button) : undefined;
+        results.push(normalizeButtonForTranslation(buttonId, label, message, symbols || [], context));
+    }
+    return results;
+}
+/**
+ * Create a prompt for LLM translation with symbol preservation.
+ *
+ * This generates a structured prompt that instructs the LLM to translate
+ * while preserving symbol-to-word associations.
+ *
+ * @param buttons - Buttons to translate
+ * @param targetLanguage - Target language for translation
+ * @returns Prompt string for LLM
+ */
+function createTranslationPrompt(buttons, targetLanguage) {
+    const buttonsData = JSON.stringify(buttons, null, 2);
+    return `You are a translation assistant for AAC (Augmentative and Alternative Communication) systems.
+
+Your task is to translate the following buttons to ${targetLanguage} while preserving symbol associations.
+
+Each button has:
+- label: The text shown on the button
+- message: The text spoken when the button is activated
+- textToTranslate: The actual text to translate (usually the message)
+- symbols: Visual symbols attached to specific words
+
+IMPORTANT: After translation, you MUST reattach symbols to the correct translated words based on MEANING, not position.
+
+Example:
+- Original: "I want apple" with apple symbol on "apple"
+- Spanish: "Yo quiero manzana" with apple symbol on "manzana" (NOT "Yo" or "quiero")
+- French: "Je veux une pomme" with apple symbol on "pomme"
+
+The symbols array should contain the translated word that each symbol should be attached to.
+
+Buttons to translate:
+${buttonsData}
+
+Return ONLY a JSON array with this exact structure:
+[
+  {
+    "buttonId": "...",
+    "translatedLabel": "...",
+    "translatedMessage": "...",
+    "symbols": [
+      {"text": "translated_word", "image": "[library]path"}
+    ]
+  }
+]
+
+Ensure all symbol image references are preserved exactly as provided.`;
+}
+/**
+ * Validate LLM translation results before applying.
+ *
+ * @param translations - LLM translation results
+ * @param originalButtonIds - Expected button IDs (optional, for validation)
+ * @param options - Validation options
+ * @throws Error if validation fails
+ */
+function validateTranslationResults(translations, originalButtonIds, options) {
+    if (!Array.isArray(translations)) {
+        throw new Error('Translation results must be an array');
+    }
+    const translatedIds = new Set(translations.map((t) => t.buttonId));
+    // Check that all original buttons have translations (unless partial is allowed)
+    if (originalButtonIds && !options?.allowPartial) {
+        for (const id of originalButtonIds) {
+            if (!translatedIds.has(id)) {
+                throw new Error(`Missing translation for button: ${id}`);
+            }
+        }
+    }
+    // Check each translation has required fields
+    for (const trans of translations) {
+        if (!trans.buttonId) {
+            throw new Error('Translation missing buttonId');
+        }
+        if (!trans.translatedMessage && !trans.translatedLabel) {
+            throw new Error(`Translation for ${trans.buttonId} has no translated text`);
+        }
+    }
+}

package/dist/validation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Validation Namespace
+ *
+ * All validation functionality for AAC processors.
+ * Provides consistent validation across all supported formats.
+ */
+export { ValidationError, ValidationCheck, ValidationResult, ValidationOptions, ValidationRule, } from './validation/validationTypes';
+export { BaseValidator } from './validation/baseValidator';
+export { ObfValidator } from './validation/obfValidator';
+export { GridsetValidator } from './validation/gridsetValidator';
+export { SnapValidator } from './validation/snapValidator';
+export { TouchChatValidator } from './validation/touchChatValidator';
+export { getValidatorForFormat, getValidatorForFile } from './validation/index';

package/dist/validation.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Validation Namespace
+ *
+ * All validation functionality for AAC processors.
+ * Provides consistent validation across all supported formats.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getValidatorForFile = exports.getValidatorForFormat = exports.TouchChatValidator = exports.SnapValidator = exports.GridsetValidator = exports.ObfValidator = exports.BaseValidator = exports.ValidationError = void 0;
+// Validation types and interfaces
+var validationTypes_1 = require("./validation/validationTypes");
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return validationTypes_1.ValidationError; } });
+// Base validator
+var baseValidator_1 = require("./validation/baseValidator");
+Object.defineProperty(exports, "BaseValidator", { enumerable: true, get: function () { return baseValidator_1.BaseValidator; } });
+// Format-specific validators
+var obfValidator_1 = require("./validation/obfValidator");
+Object.defineProperty(exports, "ObfValidator", { enumerable: true, get: function () { return obfValidator_1.ObfValidator; } });
+var gridsetValidator_1 = require("./validation/gridsetValidator");
+Object.defineProperty(exports, "GridsetValidator", { enumerable: true, get: function () { return gridsetValidator_1.GridsetValidator; } });
+var snapValidator_1 = require("./validation/snapValidator");
+Object.defineProperty(exports, "SnapValidator", { enumerable: true, get: function () { return snapValidator_1.SnapValidator; } });
+var touchChatValidator_1 = require("./validation/touchChatValidator");
+Object.defineProperty(exports, "TouchChatValidator", { enumerable: true, get: function () { return touchChatValidator_1.TouchChatValidator; } });
+// Validator factory functions
+var index_1 = require("./validation/index");
+Object.defineProperty(exports, "getValidatorForFormat", { enumerable: true, get: function () { return index_1.getValidatorForFormat; } });
+Object.defineProperty(exports, "getValidatorForFile", { enumerable: true, get: function () { return index_1.getValidatorForFile; } });

package/package.json

@@ -1,9 +1,63 @@
 {
   "name": "@willwade/aac-processors",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "A comprehensive TypeScript library for processing AAC (Augmentative and Alternative Communication) file formats with translation support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./gridset": {
+      "types": "./dist/gridset.d.ts",
+      "default": "./dist/gridset.js"
+    },
+    "./snap": {
+      "types": "./dist/snap.d.ts",
+      "default": "./dist/snap.js"
+    },
+    "./obf": {
+      "types": "./dist/obf.d.ts",
+      "default": "./dist/obf.js"
+    },
+    "./obfset": {
+      "types": "./dist/obfset.d.ts",
+      "default": "./dist/obfset.js"
+    },
+    "./touchchat": {
+      "types": "./dist/touchchat.d.ts",
+      "default": "./dist/touchchat.js"
+    },
+    "./dot": {
+      "types": "./dist/dot.d.ts",
+      "default": "./dist/dot.js"
+    },
+    "./excel": {
+      "types": "./dist/excel.d.ts",
+      "default": "./dist/excel.js"
+    },
+    "./opml": {
+      "types": "./dist/opml.d.ts",
+      "default": "./dist/opml.js"
+    },
+    "./applePanels": {
+      "types": "./dist/applePanels.d.ts",
+      "default": "./dist/applePanels.js"
+    },
+    "./astericsGrid": {
+      "types": "./dist/astericsGrid.d.ts",
+      "default": "./dist/astericsGrid.js"
+    },
+    "./translation": {
+      "types": "./dist/translation.d.ts",
+      "default": "./dist/translation.js"
+    },
+    "./validation": {
+      "types": "./dist/validation.d.ts",
+      "default": "./dist/validation.js"
+    }
+  },
   "files": [
     "dist/**/*",
     "docs/**/*",
@@ -69,8 +123,8 @@
   },
   "homepage": "https://github.com/willwade/AACProcessors-nodejs#readme",
   "engines": {
-    "node": ">=16.0.0",
-    "npm": ">=8.0.0"
+    "node": ">=20.0.0",
+    "npm": ">=9.0.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.7",
@@ -96,7 +150,7 @@
     "@types/xml2js": "^0.4.14",
     "adm-zip": "^0.5.16",
     "axios": "^1.11.0",
-    "better-sqlite3": "^11.9.1",
+    "better-sqlite3": "^12.5.0",
     "commander": "^13.1.0",
     "exceljs": "^4.4.0",
     "fast-xml-parser": "^5.2.0",

package/dist/utilities/screenshotConverter.d.ts

@@ -1,69 +0,0 @@
-import { AACPage, AACTree } from '../core/treeStructure';
-export interface ScreenshotCell {
-    text: string;
-    row: number;
-    col: number;
-    isCategory?: boolean;
-    isNavigation?: boolean;
-    isEmpty?: boolean;
-    imageUrl?: string;
-}
-export interface ScreenshotGrid {
-    rows: number;
-    cols: number;
-    cells: ScreenshotCell[];
-    categories: string[];
-    metadata?: {
-        timestamp?: string;
-        battery?: string;
-        date?: string;
-    };
-}
-export interface ScreenshotPage {
-    filename: string;
-    grid: ScreenshotGrid;
-    extractedAt: Date;
-    pageName?: string;
-    parentPath?: string;
-    pageTitle?: string;
-}
-export interface PageHierarchy {
-    [pageId: string]: {
-        page: ScreenshotPage;
-        children: string[];
-        parent?: string;
-    };
-}
-export interface ScreenshotConversionOptions {
-    includeEmptyCells: boolean;
-    generateIds: boolean;
-    targetPlatform?: 'grid3' | 'asterics' | 'snap' | 'touchchat';
-    language: string;
-    fallbackCategory: string;
-    filenameDelimiter?: string;
-}
-export declare class ScreenshotConverter {
-    private static defaultOptions;
-    /**
-     * Parse filename to extract page hierarchy and names
-     * Examples:
-     * - "Home.png" → pageName: "Home", parentPath: ""
-     * - "Home->Fragen.png" → pageName: "Fragen", parentPath: "Home"
-     * - "Home->Settings->Profile.jpg" → pageName: "Profile", parentPath: "Home->Settings"
-     */
-    static parseFilename(filename: string, delimiter?: string): {
-        pageName: string;
-        parentPath: string;
-    };
-    /**
-     * Build page hierarchy from an array of screenshots
-     */
-    static buildPageHierarchy(screenshots: ScreenshotPage[]): PageHierarchy;
-    static parseOCRText(ocrResult: string): ScreenshotGrid;
-    private static isCategoryToken;
-    private static isNavigationToken;
-    static convertToAACPage(screenshotPage: ScreenshotPage, pageHierarchy?: PageHierarchy, options?: Partial<ScreenshotConversionOptions>): AACPage;
-    private static createSemanticAction;
-    static convertToAACTree(screenshotPages: ScreenshotPage[], options?: Partial<ScreenshotConversionOptions>): AACTree;
-    private static sanitizePageId;
-}