@willwade/aac-processors 0.2.3 → 0.2.4

package/dist/utilities/analytics/metrics/core.js

@@ -12,6 +12,7 @@ exports.MetricsCalculator = void 0;
 const treeStructure_1 = require("../../../core/treeStructure");
 const aac_1 = require("../../../types/aac");
 const effort_1 = require("./effort");
+const morphology_1 = require("../morphology");
 class MetricsCalculator {
     constructor() {
         this.locale = 'en';
@@ -83,9 +84,11 @@ class MetricsCalculator {
         });
         // Update buttons using dynamic spelling effort if applicable
         const buttons = Array.from(knownButtons.values()).sort((a, b) => a.effort - b.effort);
-        // Calculate metrics for word forms (smart grammar predictions) if enabled
-        // Default to true if not specified
-        const useSmartGrammar = options.useSmartGrammar !== false;
+        // Expand morphological predictions from POS tags if enabled or auto-detected
+        const useSmartGrammar = options.useSmartGrammar === true || this.treeHasPosTags(tree);
+        if (useSmartGrammar) {
+            this.expandMorphologicalPredictions(tree, options);
+        }
         if (useSmartGrammar) {
             const { wordFormMetrics, replacedLabels } = this.calculateWordFormMetrics(tree, buttons, options);
             // Remove buttons that were replaced by lower-effort word forms
@@ -154,13 +157,21 @@ class MetricsCalculator {
                 }) || null;
         }
         if (!spellingPage)
-            return { spellingPage: null, spellingBaseEffort: 10, spellingAvgLetterEffort: 2.5 };
+            return {
+                spellingPage: null,
+                spellingBaseEffort: 10,
+                spellingAvgLetterEffort: 2.5,
+            };
         // Calculate effort to reach this page from root
         const rootBoard = tree.rootId
             ? tree.pages[tree.rootId]
             : Object.values(tree.pages).find((p) => !p.parentId);
         if (!rootBoard)
-            return { spellingPage, spellingBaseEffort: 10, spellingAvgLetterEffort: 2.5 };
+            return {
+                spellingPage,
+                spellingBaseEffort: 10,
+                spellingAvgLetterEffort: 2.5,
+            };
         // Analyze specifically to find the lowest effort path to the spelling page
         const result = this.analyzeFrom(tree, rootBoard, setPcts, true, options);
         const spellingBaseEffort = result.visitedBoardEfforts.get(spellingPage.id) ?? 10;
@@ -574,6 +585,157 @@ class MetricsCalculator {
         boardPcts['all'] = totalLinks;
         return boardPcts;
     }
+    /**
+     * Quick check whether any button in the tree has a POS tag.
+     * Used to auto-enable smart grammar without requiring explicit opt-in.
+     */
+    treeHasPosTags(tree) {
+        for (const page of Object.values(tree.pages)) {
+            for (const row of page.grid) {
+                for (const btn of row) {
+                    if (btn?.pos && btn.pos !== 'Unknown' && btn.pos !== 'Ignore') {
+                        return true;
+                    }
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Expand morphological predictions from POS tags on buttons
+     *
+     * For each button that has a POS tag (e.g., 'Verb', 'Noun'), use the
+     * MorphologyEngine to generate inflected word forms and populate the
+     * button's predictions array. This is done as a pre-processing step
+     * before calculateWordFormMetrics assigns effort to each form.
+     */
+    expandMorphologicalPredictions(tree, options) {
+        const locale = options.morphologyLocale || 'en-gb';
+        const morph = new morphology_1.MorphologyEngine(locale);
+        // Words that should never be POS-inferred (function words, determiners, etc.)
+        const skipInference = new Set([
+            'a',
+            'an',
+            'the',
+            'to',
+            'in',
+            'on',
+            'at',
+            'of',
+            'for',
+            'and',
+            'or',
+            'but',
+            'not',
+            'no',
+            'yes',
+            'is',
+            'am',
+            'are',
+            'was',
+            'were',
+            'be',
+            'been',
+            'being',
+            'has',
+            'have',
+            'had',
+            'do',
+            'does',
+            'did',
+            'will',
+            'would',
+            'could',
+            'should',
+            'shall',
+            'may',
+            'might',
+            'can',
+            'must',
+            'with',
+            'from',
+            'by',
+            'up',
+            'down',
+            'out',
+            'off',
+            'over',
+            'under',
+            'again',
+            'then',
+            'than',
+            'so',
+            'if',
+            'when',
+            'where',
+            'how',
+            'what',
+            'who',
+            'which',
+            'that',
+            'this',
+            'these',
+            'those',
+            'here',
+            'there',
+            'now',
+            'very',
+            'just',
+            'more',
+            'also',
+            'too',
+            'please',
+            'thank',
+            'hi',
+            'hello',
+            'bye',
+            'goodbye',
+            'okay',
+            'oh',
+            'wow',
+            'sorry',
+        ]);
+        for (const page of Object.values(tree.pages)) {
+            for (const row of page.grid) {
+                for (const btn of row) {
+                    if (!btn || !btn.label)
+                        continue;
+                    let pos = btn.pos;
+                    // If no POS tag (or Unknown/Ignore), attempt POS inference.
+                    // Many content words on topic pages lack POS tags even though
+                    // they are clearly nouns (e.g., "bird", "tree", "cloud").
+                    // Strategy: check irregular tables first for confident POS,
+                    // then fall back to Noun for single-word content labels.
+                    if (!pos || pos === 'Unknown' || pos === 'Ignore') {
+                        const lower = btn.label.toLowerCase();
+                        // Skip function words and multi-word labels
+                        if (!skipInference.has(lower) && !lower.includes(' ') && lower.length > 1) {
+                            // Check irregular tables for confident POS assignment
+                            const inferredPOS = morph.inferPOS(lower);
+                            if (inferredPOS) {
+                                pos = inferredPOS;
+                                btn.pos = inferredPOS;
+                            }
+                            else {
+                                // Default to Noun for untagged content words.
+                                // This generates plurals (e.g., bird → birds, tree → trees).
+                                pos = 'Noun';
+                                btn.pos = 'Noun';
+                            }
+                        }
+                    }
+                    if (!pos || pos === 'Unknown' || pos === 'Ignore')
+                        continue;
+                    const forms = morph.inflect(btn.label, pos);
+                    if (forms.length > 0) {
+                        const existing = btn.predictions || [];
+                        const merged = new Set([...existing, ...forms]);
+                        btn.predictions = Array.from(merged);
+                    }
+                }
+            }
+        }
+    }
     /**
      * Calculate metrics for word forms (smart grammar predictions)
      *
@@ -596,14 +758,53 @@ class MetricsCalculator {
         // Track buttons by label to compare efforts
         const existingLabels = new Map();
         buttons.forEach((btn) => existingLabels.set(btn.label.toLowerCase(), btn));
+        // Build a map of POS tags from ALL tree buttons, keyed by lowercase label.
+        // This ensures words on BFS-unreachable pages still contribute POS data.
+        const treePosMap = new Map();
+        const treePredictionsMap = new Map();
+        Object.values(tree.pages).forEach((page) => {
+            page.grid.forEach((row) => {
+                row.forEach((btn) => {
+                    if (!btn || !btn.label)
+                        return;
+                    const lower = btn.label.toLowerCase();
+                    if (btn.pos && btn.pos !== 'Unknown' && btn.pos !== 'Ignore') {
+                        treePosMap.set(lower, btn.pos);
+                    }
+                    if (btn.predictions && btn.predictions.length > 0) {
+                        const existing = treePredictionsMap.get(lower);
+                        if (!existing || btn.predictions.length > existing.length) {
+                            treePredictionsMap.set(lower, btn.predictions);
+                        }
+                    }
+                });
+            });
+        });
+        // For metrics buttons that lack POS but have a tree counterpart with POS,
+        // propagate the POS tag so it's available in the output.
+        buttons.forEach((btn) => {
+            const lower = btn.label.toLowerCase();
+            if (!btn.pos || btn.pos === 'Unknown' || btn.pos === 'Ignore') {
+                const treePos = treePosMap.get(lower);
+                if (treePos)
+                    btn.pos = treePos;
+            }
+        });
+        // Note: buttons on pages unreachable via BFS from the root page are
+        // intentionally excluded. If there is no navigation path to a page,
+        // those buttons are not accessible to the user and should not count
+        // as available vocabulary.
         // Iterate through all pages to find buttons with predictions
         Object.values(tree.pages).forEach((page) => {
             page.grid.forEach((row) => {
                 row.forEach((btn) => {
                     if (!btn || !btn.predictions || btn.predictions.length === 0)
                         return;
-                    // Find the parent button's metrics
-                    const parentMetrics = buttons.find((b) => b.id === btn.id);
+                    // Find the parent button's metrics (by id first, then by label)
+                    let parentMetrics = buttons.find((b) => b.id === btn.id);
+                    if (!parentMetrics && btn.label) {
+                        parentMetrics = existingLabels.get(btn.label.toLowerCase());
+                    }
                     if (!parentMetrics)
                         return;
                     // Calculate effort for each word form
@@ -701,7 +902,11 @@ class MetricsCalculator {
             // If no block assigned, treat as its own block at the end (fallback)
             if (blockId === null) {
                 const loop = board.grid.length + (board.grid[0]?.length || 0);
-                return { steps: rowIndex + colIndex + 1, selections: 1, loopSteps: loop };
+                return {
+                    steps: rowIndex + colIndex + 1,
+                    selections: 1,
+                    loopSteps: loop,
+                };
             }
             const blockConfig = board.scanBlocksConfig?.find((c) => c.id === blockId);
             const blockOrder = blockConfig?.order ?? blockId;

package/dist/utilities/analytics/metrics/types.d.ts

@@ -21,6 +21,7 @@ export interface ButtonMetrics {
     is_word_form?: boolean;
     parent_button_id?: string;
     parent_button_label?: string;
+    pos?: string;
 }
 /**
  * Board/page level analysis result
@@ -120,17 +121,31 @@ export interface MetricsOptions {
     /**
      * Whether to include smart grammar word forms in metrics
      *
-     * When true (default): Word forms from smart grammar predictions are included
+     * When true: Word forms from smart grammar predictions are included
      * in the metrics. If a word exists as both a regular button and a word form,
      * the version with lower effort is used.
      *
      * When false: Smart grammar word forms are excluded from metrics. Only actual
      * buttons in the tree are analyzed.
      *
-     * Only applicable to systems that support smart grammar (e.g., Grid 3).
-     * Default is true.
+     * Auto-detected by default: if any button in the tree has a POS tag (e.g.,
+     * from Grid 3's Action.InsertText), smart grammar is enabled automatically.
+     * For non-Grid-3 formats (TD Snap, TouchChat, OBF), no buttons have POS tags,
+     * so smart grammar is automatically disabled with zero overhead.
+     *
+     * Set explicitly to `true` to force-enable, or `false` to force-disable.
      */
     useSmartGrammar?: boolean;
+    /**
+     * Locale for morphological inflection rules
+     *
+     * When provided, the MorphologyEngine will generate inflected word forms
+     * (e.g., "going", "went" for "go") based on the POS tags extracted from
+     * the gridset. Defaults to 'en-gb'.
+     *
+     * Only used when useSmartGrammar is true.
+     */
+    morphologyLocale?: string;
 }
 /**
  * Comparison result between two board sets

package/dist/utilities/analytics/metrics/vocabulary.d.ts

@@ -60,6 +60,9 @@ export declare class VocabularyAnalyzer {
     getWordEffort(word: string, metrics: MetricsResult): number;
     /**
      * Check if a word is in the board set
+     *
+     * Checks both direct button labels and smart grammar word forms
+     * (morphological inflections stored as predictions).
      */
     hasWord(word: string, metrics: MetricsResult): boolean;
 }

package/dist/utilities/analytics/metrics/vocabulary.js

@@ -134,9 +134,21 @@ class VocabularyAnalyzer {
     }
     /**
      * Check if a word is in the board set
+     *
+     * Checks both direct button labels and smart grammar word forms
+     * (morphological inflections stored as predictions).
      */
     hasWord(word, metrics) {
-        return metrics.buttons.some((b) => b.label.toLowerCase() === word.toLowerCase());
+        const lower = word.toLowerCase();
+        return metrics.buttons.some((b) => {
+            if (b.label.toLowerCase() === lower)
+                return true;
+            if (b.is_word_form && b.parent_button_label) {
+                if (b.label.toLowerCase() === lower)
+                    return true;
+            }
+            return false;
+        });
     }
 }
 exports.VocabularyAnalyzer = VocabularyAnalyzer;

package/dist/utilities/analytics/morphology/engine.d.ts

@@ -0,0 +1,30 @@
+import { MorphRuleSet } from './types';
+import type { Grid3VerbForms } from './grid3VerbsParser';
+export declare class MorphologyEngine {
+    private ruleSet;
+    private grid3Verbs?;
+    private cache;
+    constructor(ruleSetOrLocale: string | MorphRuleSet);
+    static fromGrid3Verbs(verbForms: Grid3VerbForms): MorphologyEngine;
+    get locale(): string;
+    inflect(base: string, pos: string): string[];
+    isFormOf(word: string, base: string, pos: string): boolean;
+    expandVocabulary(buttons: Array<{
+        label: string;
+        pos?: string;
+        predictions?: string[];
+    }>): Map<string, string[]>;
+    inflectWithSlots(base: string, pos: string): Array<{
+        slot: string;
+        form: string;
+    }>;
+    private computeForms;
+    private applyRules;
+    /**
+     * Infer the most likely POS for a word by checking the irregular tables.
+     * Returns the POS if found in any irregular table, or null if not found.
+     * Priority: Verb > Noun > Adjective > Pronoun
+     */
+    inferPOS(word: string): string | null;
+    private loadBundled;
+}