Add Open Board Logging (OBL) support and utilities

Introduces OBL file format types, parsing, generation, and anonymization utilities for AAC usage logs. Updates analytics and history modules to support OBL-aligned fields and semantic intent mapping. Adds documentation and analysis scripts for OBL, extends history reading for Grid 3 and TD Snap to include semantic fields, and provides comprehensive tests for OBL functionality.

Author: willwade

scripts/analysis/analyze_obl_data.ts

@@ -0,0 +1,124 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { OblUtil } from '../../src/optional/analytics/index';
+
+/**
+ * Script to bulk-analyze OBLA clinical data and extract utterances to a CSV.
+ */
+
+const OBLA_DIR = path.join(__dirname, '../../obla-improvements/small-obla/small');
+const OUTPUT_CSV = path.join(__dirname, 'obl_utterances.csv');
+
+interface UtteranceRecord {
+  file: string;
+  userId: string;
+  timestamp: string;
+  type: string;
+  content: string;
+  boardId?: string;
+}
+
+function run() {
+  console.log(`Analyzing OBLA data in: ${OBLA_DIR}...`);
+  
+  if (!fs.existsSync(OBLA_DIR)) {
+    console.error(`Directory not found: ${OBLA_DIR}`);
+    process.exit(1);
+  }
+
+  const files = fs.readdirSync(OBLA_DIR).filter(f => f.endsWith('.obla'));
+  console.log(`Found ${files.length} files.`);
+
+  const records: any[] = [];
+
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(path.join(OBLA_DIR, file), 'utf8');
+      const obl = OblUtil.parse(content);
+
+      for (const session of obl.sessions) {
+        let currentSentence: string[] = [];
+        let sentenceStartTime: string | null = null;
+
+        // Sort events within session by timestamp to be sure
+        const sortedEvents = [...session.events].sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+
+        for (let i = 0; i < sortedEvents.length; i++) {
+          const event = sortedEvents[i];
+          const nextEvent = sortedEvents[i + 1];
+          
+          if (!sentenceStartTime) sentenceStartTime = event.timestamp;
+
+          let text = '';
+          let isBoundary = false;
+
+          if (event.type === 'button') {
+            text = (event as any).label || (event as any).vocalization || '[?]';
+          } else if (event.type === 'utterance') {
+            text = (event as any).text;
+            isBoundary = true; // Utterances are usually complete sentences
+          } else if (event.type === 'action') {
+            const action = (event as any).action;
+            if (action === ':clear' || action === ':speak' || action === ':home') {
+              isBoundary = true;
+            }
+            if (action === ':backspace') {
+              currentSentence.pop();
+            } else {
+              text = `[${action}]`;
+            }
+          }
+
+          if (text) currentSentence.push(text);
+
+          // Check for time gap boundary (> 15 seconds)
+          if (nextEvent) {
+            const currentMs = new Date(event.timestamp).getTime();
+            const nextMs = new Date(nextEvent.timestamp).getTime();
+            if (nextMs - currentMs > 15000) isBoundary = true;
+          } else {
+            isBoundary = true; // End of session
+          }
+
+          if (isBoundary && currentSentence.length > 0) {
+            records.push({
+              timestamp: sentenceStartTime,
+              userId: obl.user_id,
+              sentence: currentSentence.join(' '),
+              file: file
+            });
+            currentSentence = [];
+            sentenceStartTime = null;
+          }
+        }
+      }
+    } catch (err) {
+      console.error(`Error processing ${file}:`, err);
+    }
+  }
+
+  // Sort by timestamp
+  records.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+
+  // Write CSV
+  const header = 'Timestamp,User ID,Sentence,File\n';
+  const csvLines = records.map(r => {
+    const escapedSentence = `"${r.sentence.replace(/"/g, '""')}"`;
+    return `${r.timestamp},${r.userId},${escapedSentence},${r.file}`;
+  });
+
+  fs.writeFileSync(OUTPUT_CSV, header + csvLines.join('\n'));
+  
+  console.log(`\nAnalysis complete!`);
+  console.log(`Total sentences reconstructed: ${records.length}`);
+  console.log(`Results saved to: ${OUTPUT_CSV}`);
+  
+  // Show a preview
+  console.log('\nPreview (10 Reconstructed Sentences):');
+  const preview = records.filter(r => r.sentence.length > 5 && !r.sentence.includes('000')).slice(0, 20);
+  preview.forEach(r => {
+    console.log(`[${r.timestamp}] ${r.sentence}`);
+  });
+}
+
+run();

src/optional/analytics/docs/AAC_METRICS_GUIDE.md

@@ -111,6 +111,14 @@ page.scanBlocksConfig = [
 button.scanBlocks = [2]; 
 ```
 
+### 5. Unified History & OBL Support
+
+This implementation supports gathering and analyzing historical usage data from multiple sources:
+- **Local History**: Automatically discover and read logs from Grid 3 and TD Snap on the local machine.
+- **OBL Format**: Support for the [Open Board Logging (OBL)](./OBL_SUPPORT_GUIDE.md) standard for cross-platform log sharing.
+
+See [OBL_SUPPORT_GUIDE.md](./OBL_SUPPORT_GUIDE.md) for details on parsing and anonymizing shared AAC logs.
+
 ---
 
 ## ⚖️ Implementation vs. Original Algorithm

src/optional/analytics/docs/OBL_SUPPORT_GUIDE.md

@@ -0,0 +1,68 @@
+# Open Board Logging (OBL) Support
+
+This repository provides full support for the **.obl (Open Board Logging)** and **.obla (Anonymized OBL)** file formats. These formats are designed to standardize AAC usage logs across different platforms while protecting user privacy.
+
+## 📁 Format Overview
+
+- **.obl**: Standard JSON-based log containing sessions, events, and metadata (timestamps, names, geolocation).
+- **.obla**: Anonymized version where sensitive data is masked or transformed according to standardized protocols.
+
+## 🚀 Key Features
+
+1.  **Bidirectional Conversion**: Seamlessly convert between OBL and the internal `HistoryEntry` format used by the analytics module.
+2.  **Semantic Mapping**: Automatically maps unified `AACSemanticIntent` types to OBL-standard actions like `:home`, `:back`, and `:open_board`.
+3.  **Privacy Suite**: Built-in support for OBL anonymization protocols.
+4.  **Header Handling**: Correctly handles the recommended `/* NOTICE */` header in OBL files.
+
+## 💻 How to Use
+
+### Parsing and Generation
+
+```typescript
+import { OblUtil } from '@willwade/aac-processors/optional/analytics';
+
+// Parse an OBL file
+const content = fs.readFileSync('user_log.obl', 'utf8');
+const obl = OblUtil.parse(content);
+
+// Convert to internal history format for analysis
+const history = OblUtil.toHistoryEntries(obl);
+
+// Convert history back to OBL for sharing
+const newObl = OblUtil.fromHistoryEntries(history, 'patient_123');
+const json = OblUtil.stringify(newObl);
+```
+
+### Anonymization
+
+The `OblAnonymizer` allows you to selectively apply privacy protocols:
+
+```typescript
+import { OblAnonymizer } from '@willwade/aac-processors/optional/analytics';
+
+const anonymized = OblAnonymizer.anonymize(obl, [
+  'timestamp_shift',      // Shift logs to begin on 2000-01-01
+  'geolocation_masking',  // Remove GPS and location IDs
+  'name_masking',         // Redact user and author names
+  'url_stripping'         // Remove links to images or author profiles
+]);
+```
+
+## 🧠 Semantic Intent Mapping
+
+The OBL implementation leverages the `AACSemanticAction` system. When exporting data to OBL, the following intents are automatically mapped to standard OBL actions:
+
+| Intent | OBL Action String |
+| :--- | :--- |
+| `NAVIGATE_TO` | `:open_board` |
+| `GO_HOME` | `:home` |
+| `GO_BACK` | `:back` |
+| `CLEAR_TEXT` | `:clear` |
+| `DELETE_CHARACTER` | `:backspace` |
+| `SPEAK_TEXT` | `:speak` (if not a standard utterance) |
+
+## 📊 Analyzing OBL Data
+
+You can use the OBL utilities to feed external data into the `MetricsCalculator` or other vocabulary analysis tools by converting it to `HistoryEntry` format first.
+
+See `scripts/analysis/analyze_obl_data.ts` for an example of bulk-extracting utterances from a clinical dataset.

src/optional/analytics/history.ts

@@ -12,8 +12,9 @@ import {
   readSnapUsageForUser as readSnapUsageForUserImpl,
   SnapUserInfo,
 } from '../../processors/snap/helpers';
+import { AACSemanticCategory, AACSemanticIntent } from '../../core/treeStructure';
 
-export type HistorySource = 'Grid' | 'Snap';
+export type HistorySource = 'Grid' | 'Snap' | 'OBL' | string;
 
 export interface HistoryOccurrence {
   timestamp: Date;
@@ -22,13 +23,25 @@ export interface HistoryOccurrence {
   modeling?: boolean;
   accessMethod?: number | null;
   pageId?: string | null;
+  // OBL-aligned fields
+  buttonId?: string | null;
+  boardId?: string | null;
+  spoken?: boolean;
+  vocalization?: string;
+  imageUrl?: string;
+  actions?: any[]; // For OBL actions
+  type?: 'button' | 'action' | 'utterance' | 'note' | 'other';
+  // Semantic semantic alignment
+  intent?: AACSemanticIntent | string;
+  category?: AACSemanticCategory;
 }
 
 export interface HistoryPlatformExtras {
   label?: string;
   message?: string;
   buttonId?: string;
   contentXml?: string;
+  [key: string]: any;
 }
 
 export interface HistoryEntry {

src/optional/analytics/index.ts

@@ -21,6 +21,10 @@ export * from './utils/idGenerator';
 // Export history functionality
 export * from './history';
 
+// Export OBL logging support
+export * from './metrics/obl-types';
+export { OblUtil, OblAnonymizer } from './metrics/obl';
+
 // Export core metrics calculator
 export { MetricsCalculator } from './metrics/core';
 

src/optional/analytics/metrics/obl-types.ts

@@ -0,0 +1,107 @@
+/**
+ * .obl (Open Board Logging) File Format Types
+ *
+ * Based on the .obl specification for AAC logging.
+ */
+
+export interface OblAction {
+  action: string;
+  destination_board_id?: string;
+  text?: string;
+  modification_type?: string;
+  [key: string]: any; // Support for extensions
+}
+
+export interface OblEventBase {
+  id: string;
+  timestamp: string; // ISO 8601
+  type: 'button' | 'action' | 'utterance' | 'note' | 'other' | string;
+  locale?: string;
+  geo?: [number, number, number?]; // lat, long, alt
+  location_id?: string;
+  modeling?: boolean;
+  system?: string;
+  window_width?: number;
+  window_height?: number;
+  percent_x?: number;
+  percent_y?: number;
+  [key: string]: any; // Support for extensions
+}
+
+export interface OblButtonEvent extends OblEventBase {
+  type: 'button';
+  label: string;
+  spoken: boolean;
+  button_id?: string;
+  board_id?: string;
+  vocalization?: string;
+  image_url?: string;
+  actions?: OblAction[];
+}
+
+export interface OblActionEvent extends OblEventBase {
+  type: 'action';
+  action: string;
+  destination_board_id?: string;
+  text?: string;
+  modification_type?: string;
+}
+
+export interface OblUtteranceEvent extends OblEventBase {
+  type: 'utterance';
+  text: string;
+  buttons?: Array<{
+    id?: string;
+    label?: string;
+    board_id?: string;
+    vocalization?: string;
+    action?: string;
+    text?: string;
+  }>;
+}
+
+export interface OblNoteEvent extends OblEventBase {
+  type: 'note';
+  text: string;
+  author_name?: string;
+  author_email?: string;
+  author_url?: string;
+}
+
+export type OblEvent =
+  | OblButtonEvent
+  | OblActionEvent
+  | OblUtteranceEvent
+  | OblNoteEvent
+  | OblEventBase;
+
+export interface OblSession {
+  id: string;
+  type: 'log' | string;
+  started: string; // ISO 8601
+  ended: string; // ISO 8601
+  device_id?: string;
+  locale?: string;
+  anonymizations?: string[];
+  events: OblEvent[];
+  [key: string]: any; // Support for extensions
+}
+
+export interface OblFile {
+  format: 'open-board-log-0.1' | string;
+  user_id: string;
+  user_name?: string;
+  source?: string;
+  locale?: string;
+  anonymized?: boolean;
+  license?: {
+    type: string;
+    copyright_notice_url?: string;
+    source_url?: string;
+    author_name?: string;
+    author_url?: string;
+    author_email?: string;
+  };
+  sessions: OblSession[];
+  [key: string]: any; // Support for extensions
+}