@willwade/aac-processors 0.3.1 → 0.3.2

package/dist/utilities/analytics/competence.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Linguistic Competence Metrics
+ *
+ * Privacy-preserving analysis of AAC *spoken output* (phrase history), based on:
+ *   - Niemeijer, Sheldon & Hillary Zisk (2025), "Measuring AAC user linguistic
+ *     competence: A novel approach", AssistiveWare (Communication Matters handout).
+ *   - Frisch, Wade et al. (2026), "It's Complicated: On the Design and Evaluation
+ *     of AI-Powered AAC Interfaces", arXiv:2606.24854.
+ *
+ * DESIGN (read me):
+ *   - **Source-agnostic.** The only input is `{ text, timestampMs }[]`. It does
+ *     not know or care whether the speech history came from Grid 3, Snap,
+ *     TouchChat, OBF/OBFL logs, or anything else. See `historyEntriesToCompetence*
+ *     Utterances` (in history.ts) to adapt any `HistoryEntry[]` source.
+ *   - **Language-agnostic core.** This module contains NO word lists. Language-
+ *     specific resources (a closed-class word set, an inflection classifier) are
+ *     INJECTED via `LanguageResources`. When a resource is missing for a
+ *     language, the affected measure is reported as `unavailable` with a reason
+ *     and a warning is raised — never silently wrong.
+ *   - **Pure / no I/O.** No filesystem, no platform APIs. Runs anywhere (browser
+ *     included) and emits only aggregate statistics (never the raw text).
+ *
+ * The four dimensions of linguistic competence (Light, 1989) and the measures we
+ * use for each, following the AssistiveWare findings:
+ *
+ *   Semantic      -> MATTR-30 lexical diversity             (always available)
+ *   Syntactic     -> preposition/conjunction diversity        (needs closedClassWords)
+ *   Morphological -> inflected-form diversity                 (needs classifyInflection)
+ *   Phonological  -> proportion of unique words in a dictionary (needs a dictionary)
+ *
+ * All diversity measures use 30-word moving-average windows (Covington & McFall,
+ * 2010), making them sample-length independent and usable for the tiny, highly
+ * variable samples typical of AAC. MLU is intentionally NOT a headline (it
+ * conflates linguistic/operational/strategic/social competence in AAC); it is
+ * reported only as a distribution.
+ */
+/** A single spoken utterance with a production timestamp (epoch ms). */
+export interface CompetenceUtterance {
+    text: string;
+    timestampMs: number;
+}
+/** A tokenised word stream produced in chronological order. */
+export type WordStream = string[];
+/** Coarse inflection category used by the (injected) morphology classifier. */
+export type InflectionCategory = 'base' | 'plural' | 'possessive' | 'past' | 'progressive' | 'comparative' | 'superlative' | 'adverb';
+/**
+ * Language-specific resources, injected by the caller. Providing none leaves the
+ * language-specific measures unavailable (with explicit warnings) — the semantic
+ * measure still works for any language.
+ */
+export interface LanguageResources {
+    /** Closed-class words (prepositions, conjunctions, ...) for syntactic diversity. */
+    closedClassWords?: Set<string>;
+    /** Maps a lowercased word to an inflection category for morphological diversity. */
+    classifyInflection?: (word: string) => InflectionCategory;
+}
+export interface DiversityOptions {
+    /** Moving-average window size in words. The papers use 30. */
+    windowSize?: number;
+    /** Closed-class word set (for the syntactic measure). */
+    closedClassWords?: Set<string>;
+    /** Inflection classifier (for the morphological measure). */
+    classifyInflection?: (word: string) => InflectionCategory;
+}
+export interface DiversityResult {
+    /** Median of the per-window values (the headline figure, per the paper). */
+    median: number | null;
+    mean: number | null;
+    /** Number of windows that contributed a value (after any skipping). */
+    nWindows: number;
+    /** The window size used. */
+    windowSize: number;
+    /** Present when the measure could not be computed (e.g. missing language data). */
+    unavailable?: string;
+}
+/**
+ * Tokenise raw text into a lowercased word stream.
+ * Keeps intra-word apostrophes (don't, children's) but drops leading/trailing
+ * punctuation and pure whitespace. Accented characters are preserved (\p{L}).
+ */
+export declare function tokenize(text: string): WordStream;
+/**
+ * Moving-Average Type-Token Ratio (Covington & McFall, 2010).
+ *
+ * Slides a fixed-size window across the word stream and computes the TTR for
+ * each window. The median across windows is sample-length independent, which is
+ * exactly why it is preferred over plain TTR for highly variable AAC samples.
+ */
+export declare function movingAverageTTR(words: WordStream, windowSize?: number): DiversityResult;
+/** Convenience: MATTR-30 lexical diversity (the semantic headline). */
+export declare function lexicalDiversity(words: WordStream, windowSize?: number): DiversityResult;
+/**
+ * Closed-class diversity (generalises AssistiveWare's MA-UPC-TWR-30).
+ *
+ * For each window, compute the type-token ratio restricted to the supplied
+ * closed-class words (prepositions + conjunctions in the original paper). Windows
+ * containing none are skipped. The caller supplies the set via
+ * `closedClassWords`, so this works for any language without hardcoding here.
+ */
+export declare function syntacticDiversity(words: WordStream, options?: DiversityOptions): DiversityResult;
+/**
+ * Morphological diversity (proxy for MA-UMORPH-TLWR-30).
+ *
+ * Within each window, words the supplied classifier marks as inflected (any
+ * category other than "base") contribute their surface forms to a type-token
+ * ratio. Windows with no inflected words are skipped. The classifier is injected
+ * (`classifyInflection`) so the heuristic lives with the caller, per language.
+ *
+ * Caveat (per AssistiveWare): for symbol-supported AAC, pre-stored morphology
+ * buttons ("finished", "is", ...) heavily affect this measure — interpret trends
+ * rather than absolutes.
+ */
+export declare function morphologicalDiversity(words: WordStream, options?: DiversityOptions): DiversityResult;
+/**
+ * Proportion of unique alphabetic words present in the supplied dictionary.
+ * Unique words only, so it is not skewed by repetition or repeated misspellings.
+ * Returns null (unavailable) if no dictionary is provided.
+ */
+export declare function spellingValidity(words: WordStream, dictionary?: Set<string>): number | null;
+export interface DistributionStats {
+    median: number | null;
+    mean: number | null;
+    p25: number | null;
+    p75: number | null;
+    n: number;
+}
+export interface ActivityStats {
+    utterances: number;
+    words: number;
+    /** Distinct tokens — vocabulary breadth (count only, never the words). */
+    uniqueWords: number;
+    activeDays: number;
+    wordsPerUtterance: DistributionStats;
+}
+/** Compute engagement/activity stats for a set of utterances. */
+export declare function summarizeActivity(utterances: CompetenceUtterance[]): ActivityStats;
+export interface MonthBin {
+    /** Calendar month in local time, "YYYY-MM". */
+    month: string;
+    utterances: number;
+    words: number;
+    uniqueWords: number;
+    activeDays: number;
+    wordsPerUtterance: DistributionStats;
+    /** Semantic — the headline measure. */
+    lexicalDiversity: DiversityResult;
+    /** Syntactic. null/unavailable when no closed-class data for the language. */
+    syntacticDiversity: DiversityResult;
+    /** Morphological (proxy). null/unavailable when no classifier for the language. */
+    morphologicalDiversity: DiversityResult;
+    /** Phonological — only when a dictionary is supplied. */
+    spellingValidity: number | null;
+    /** True when the month has too little data to trust the diversity figures. */
+    suppressed: boolean;
+    suppressReason: string | null;
+}
+export interface TrendResult {
+    metric: string;
+    /** Slope of the weighted linear regression, in metric units per month. */
+    slopePerMonth: number | null;
+    firstHalf: number | null;
+    secondHalf: number | null;
+    /** secondHalf - firstHalf. */
+    delta: number | null;
+    direction: 'up' | 'down' | 'flat' | 'unknown';
+}
+export interface DimensionSupport {
+    available: boolean;
+    reason?: string;
+}
+export interface PagesetSummary {
+    label: string;
+    gridsetIncluded: boolean;
+    analysisVersion?: string;
+    totalBoards: number;
+    totalButtons: number;
+    totalWords: number;
+    grid: {
+        rows: number;
+        columns: number;
+    };
+    effort: DistributionStats;
+    hasDynamicPrediction: boolean;
+    spellingEffort: {
+        base: number | null;
+        perLetter: number | null;
+    };
+    error?: string;
+}
+export interface UserSettingsSummary {
+    startupGridSet: string | null;
+    onlineAiToolsOptIn: boolean | null;
+    accessMethods: string[];
+    personalisation: {
+        pronunciations: number;
+        capitalisations: number;
+        abbreviationExpansions: number;
+        smallWords: number;
+    };
+}
+export interface CompetenceReport {
+    schema: string;
+    generatedAt: string;
+    privacy: {
+        rawUtterancesIncluded: boolean;
+        wordListsIncluded: boolean;
+        fringeWordFrequencyIncluded: boolean;
+        minAggregationWindowDays: number;
+        notes: string[];
+    };
+    source: {
+        platform: string;
+        langCode?: string;
+        userLabel?: string;
+        dbPathIncluded: boolean;
+    };
+    config: {
+        months: number;
+        windowSize: number;
+        lang: string;
+        minWordsPerMonth: number;
+        dictionaryProvided: boolean;
+    };
+    overall: {
+        windowStart: string;
+        windowEnd: string;
+        totalUtterances: number;
+        totalWords: number;
+        monthsCovered: number;
+        monthsSuppressed: number;
+    };
+    timeline: MonthBin[];
+    trend: TrendResult;
+    /** Per-dimension availability for the detected language (no silent degradation). */
+    support: {
+        lang: string;
+        semantic: DimensionSupport;
+        syntactic: DimensionSupport;
+        morphological: DimensionSupport;
+        phonological: DimensionSupport;
+    };
+    /** Human-readable notes about anything skipped or approximate. */
+    warnings: string[];
+    /** Structural metrics for the user's default gridset (null if unavailable). */
+    pageset?: PagesetSummary | null;
+    /** System-configuration context (access method, AI opt-in, startup gridset). */
+    userSettings?: UserSettingsSummary | null;
+}
+export interface TimelineOptions {
+    /** How many trailing months to analyse. Default 12. */
+    months?: number;
+    /** Moving-average window. Default 30. */
+    windowSize?: number;
+    /** Language code. Default "en". Used for reporting only. */
+    lang?: string;
+    /** Months with fewer than this many words are flagged suppressed. Default 150. */
+    minWordsPerMonth?: number;
+    /** Optional dictionary Set for the spelling measure. */
+    dictionary?: Set<string>;
+    /** Language-specific resources (closed-class words, inflection classifier). */
+    resources?: LanguageResources;
+    /** Epoch ms for "now". Defaults to Date.now(). Mainly for tests. */
+    now?: number;
+    /** Platform label for the report. Default "Grid3". */
+    platform?: string;
+    userLabel?: string;
+    langCode?: string;
+    dbPathIncluded?: boolean;
+}
+/**
+ * Analyse a corpus of utterances as a longitudinal competence report.
+ *
+ * Utterances are filtered to the trailing `months` window, binned by calendar
+ * month, and each bin is scored on the four competence dimensions plus activity.
+ * Language-specific measures require matching `resources`; missing resources are
+ * reported under `support` and `warnings` rather than silently dropped.
+ *
+ * No raw text, word list, or fringe-vocabulary frequency is included in the
+ * returned report — only aggregate statistics.
+ */
+export declare function analyzeTimeline(utterances: CompetenceUtterance[], options?: TimelineOptions): CompetenceReport;