photon-grid-core 0.0.1

package/photon-ai/photon-ai-service.js

@@ -0,0 +1,165 @@
+import { normalizeInput, tokenize, canonicalizeWord } from './text-normalizer';
+import { splitClauses } from './query-splitter';
+import { IntentParser } from './intent-parser';
+import { EntityResolver } from './entity-resolver';
+import { CommandBuilder } from './command-builder';
+import { CommandExecutor } from './command-executor';
+import { PhotonAICommandRegistry } from './photon-ai-registry';
+import { PhotonAIMemoryStore, columnSignature } from './photon-ai-memory';
+import { registerBuiltinCommands } from './builtins';
+/**
+ * Pure conversational openers — no command content, so `normalizeInput`
+ * strips every word away (they're all in its filler list) and the clause
+ * would otherwise fall through to a confusing "I couldn't parse" error.
+ * Recognized straight off the raw clause, before normalization runs.
+ */
+const GREETING_WORDS = new Set(['hi', 'hello', 'hey', 'hiya', 'howdy', 'yo', 'greetings']);
+/** Same idea as {@link GREETING_WORDS}, for conversational closers ("thanks", "thank you"). */
+const THANKS_WORDS = new Set(['thanks', 'thank', 'thankyou', 'thx', 'ty']);
+const GREETING_REPLY = 'Hi! Tell me what to do — sort, filter, pin, group, hide/show columns, move columns, selection, and more — or ask me a question about the grid\'s current state (try "help" to see everything I understand).';
+const THANKS_REPLY = "You're welcome! Let me know if there's anything else you'd like to do with the grid.";
+/**
+ * The only public entry point into Photon AI. Runs the full deterministic
+ * pipeline for one prompt:
+ *
+ * ```
+ * split into clauses → (learned-phrase replay | normalize → parse intent →
+ * resolve entities → build command) → execute → learn
+ * ```
+ *
+ * A compound sentence ("hide the id column and sort by price descending")
+ * is split into independent clauses by {@link splitClauses} and each is run
+ * through the pipeline in order, so multi-step natural-language requests
+ * work without any single intent needing to know about the others.
+ *
+ * Every successfully-executed clause is remembered by a
+ * {@link PhotonAIMemoryStore}, namespaced to this grid's current columns:
+ * the *next* time the same clause is typed, it replays the learned command
+ * directly (skipping intent matching and entity resolution entirely) as
+ * long as the column it refers to still exists — this is what makes Photon
+ * AI "learn" a user's phrasing over time, including phrasings that only
+ * resolved on the first try via fuzzy/implicit matching.
+ *
+ * Every stage past clause-splitting is a small, independent, replaceable
+ * collaborator (`IntentParser`, `EntityResolver`, `CommandBuilder`,
+ * `CommandExecutor`); this class only sequences them and never contains
+ * matching or execution logic itself.
+ */
+export class PhotonAIService {
+    /**
+     * @param api - The grid's own `GridApi` — every command runs through it, never around it.
+     * @param registry - Supply a custom registry to fully replace the built-ins, or omit to get sort/filter/pin/visibility/grouping/selection out of the box.
+     */
+    constructor(api, registry) {
+        this.api = api;
+        this.parser = new IntentParser();
+        this.builder = new CommandBuilder();
+        this.registry = registry ?? PhotonAIService.createDefaultRegistry();
+        this.executor = new CommandExecutor(this.registry);
+        this.memory = new PhotonAIMemoryStore(columnSignature(api.getAllColumns().map((c) => c.colId)));
+        this.resolver = new EntityResolver(this.memory);
+    }
+    /** A registry pre-populated with every built-in intent — the default `PhotonAIService` uses when none is supplied. */
+    static createDefaultRegistry() {
+        const registry = new PhotonAICommandRegistry();
+        registerBuiltinCommands(registry);
+        return registry;
+    }
+    /** Registers additional custom intents at runtime (e.g. a third-party feature's own `registerAI()`). */
+    getRegistry() {
+        return this.registry;
+    }
+    /** Forgets every column alias and phrase this service has learned for the current grid — useful after a large schema change or for testing. */
+    forgetLearnedMemory() {
+        this.memory.clear();
+    }
+    /**
+     * Runs one prompt through the full pipeline. Always resolves —
+     * parsing/resolution failures come back as `{ success: false }`, never a
+     * thrown error. A compound sentence runs each clause independently and
+     * aggregates their results.
+     */
+    submit(rawInput) {
+        const trimmed = rawInput.trim();
+        if (!trimmed)
+            return { success: false, message: 'Type a command first.' };
+        const clauses = splitClauses(trimmed, this.clauseVerbs());
+        const results = clauses.map((clause) => this.runClause(clause));
+        if (results.length === 1)
+            return results[0];
+        return {
+            success: results.every((r) => r.success),
+            message: results.map((r, i) => `${i + 1}) ${r.message}`).join(' '),
+        };
+    }
+    runClause(clause) {
+        const normalized = normalizeInput(clause);
+        if (!normalized)
+            return this.replyToSmallTalk(clause);
+        const learned = this.memory.getPhraseCommands(normalized);
+        if (learned && learned.every((cmd) => this.commandStillValid(cmd))) {
+            return this.runCommands(learned);
+        }
+        const tokens = tokenize(normalized);
+        if (tokens.length === 0)
+            return { success: false, message: `I couldn't parse "${clause}" — try rephrasing.` };
+        const match = this.parser.parse(tokens, this.registry);
+        if (!match)
+            return { success: false, message: `I don't know how to "${clause}" yet.` };
+        const columns = this.api.getAllColumns();
+        const { command, error } = this.builder.build(match.intent, match.remainingTokens, this.resolver, columns, this.api);
+        if (error || !command)
+            return { success: false, message: error ?? 'Something went wrong building that command.' };
+        const result = this.executor.execute(command, this.api);
+        if (result.success)
+            this.memory.learnPhrase(normalized, [command]);
+        return result;
+    }
+    runCommands(commands) {
+        const messages = [];
+        for (const command of commands) {
+            const result = this.executor.execute(command, this.api);
+            messages.push(result.message);
+            if (!result.success)
+                return { success: false, message: messages.join(' ') };
+        }
+        return { success: true, message: messages.join(' ') };
+    }
+    /**
+     * Handles a clause that normalized away to nothing — every one of its
+     * words was filler. Rather than a blanket parse error, greetings and
+     * thanks get a friendly, on-brand reply; anything else (stray filler with
+     * no real words at all) still reports that it couldn't be parsed.
+     */
+    replyToSmallTalk(clause) {
+        const words = clause
+            .toLowerCase()
+            .replace(/[^\p{L}\s]/gu, ' ')
+            .split(/\s+/)
+            .filter((w) => w.length > 0);
+        if (words.length > 0 && words.every((w) => GREETING_WORDS.has(w))) {
+            return { success: true, message: GREETING_REPLY };
+        }
+        if (words.length > 0 && words.every((w) => THANKS_WORDS.has(w))) {
+            return { success: true, message: THANKS_REPLY };
+        }
+        return { success: false, message: `I couldn't parse "${clause}" — try rephrasing.` };
+    }
+    /** A learned command referencing a column that's since been removed/renamed can't be safely replayed — falls back to re-parsing the clause instead. */
+    commandStillValid(command) {
+        const colId = command.params.colId;
+        return typeof colId !== 'string' || !!this.api.getColumn(colId);
+    }
+    /** The set of verbs `splitClauses` treats as "this starts a new command" — every registered intent's leading alias word, recomputed per call so custom intents registered at runtime are picked up immediately. */
+    clauseVerbs() {
+        const verbs = new Set();
+        for (const intent of this.registry.getAll()) {
+            for (const alias of intent.aliases) {
+                if (alias[0])
+                    verbs.add(canonicalizeWord(alias[0]));
+            }
+        }
+        return verbs;
+    }
+}
+//# sourceMappingURL=photon-ai-service.js.map

package/photon-ai/photon-ai-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"photon-ai-service.js","sourceRoot":"","sources":["../../src/photon-ai/photon-ai-service.ts"],"names":[],"mappings":"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"}

package/photon-ai/photon-ai.types.d.ts

@@ -0,0 +1,100 @@
+import type { ColumnDef } from '../types/column.types';
+import type { FilterOperator } from '../types/filter.types';
+import type { GridApi } from '../core/grid-api';
+import type { EntityResolver } from './entity-resolver';
+/**
+ * A resolved, ready-to-execute grid instruction produced by the
+ * {@link CommandBuilder}. `type` is the stable machine key of the
+ * {@link IntentDefinition} that produced it (by convention, identical to
+ * `IntentDefinition.key`); `params` carries whatever that intent's
+ * `buildCommand` decided the {@link CommandExecutor} needs.
+ *
+ * Commands are plain data — never executable code — so they can be logged,
+ * previewed, replayed, or handed to a different executor without any
+ * knowledge of how they were produced.
+ */
+export interface PhotonCommand {
+    readonly type: string;
+    readonly params: Readonly<Record<string, unknown>>;
+}
+/** Outcome of {@link PhotonAIService.submit} — always resolves, never throws. */
+export interface PhotonCommandResult {
+    readonly success: boolean;
+    /** Short, human-readable summary shown in the command bar (e.g. "Sorted Salary descending."). */
+    readonly message: string;
+    /** The command that was executed, when parsing/resolution/execution succeeded. */
+    readonly command?: PhotonCommand;
+}
+/**
+ * Entities extracted from the user's tokens for one matched intent —
+ * resolved dynamically against the grid's *current* columns, never
+ * hardcoded. Every field is optional: which ones are populated depends on
+ * what the owning {@link IntentDefinition.resolveEntities} looked for.
+ */
+export interface ResolvedEntities {
+    column?: ColumnDef;
+    columns?: ColumnDef[];
+    direction?: 'asc' | 'desc';
+    side?: 'left' | 'right' | null;
+    visible?: boolean;
+    /** Free-text value left over after intent keywords and the column name were consumed (e.g. a filter value). */
+    value?: string;
+    /** A bare integer found in the input (e.g. "select row 5"). */
+    index?: number;
+    /** Comparison operator detected from phrases like "greater than", "before", "contains" — defaults to a type-appropriate operator when absent. */
+    operator?: FilterOperator;
+    /** The coerced (typed) filter value — a `number`, `boolean`, `Date`, or `string` depending on the resolved column's data type. */
+    coercedValue?: unknown;
+    /** The upper bound for a `between`/`inRange` filter. */
+    coercedValueTo?: unknown;
+    /** `true` when the user referred to "all"/"every" columns rather than a single named one (e.g. "hide all columns"). */
+    allColumns?: boolean;
+    /** Every pin side mentioned in the sentence — e.g. `["left", "right"]` for "pin half to the left and half to the right". */
+    sides?: readonly ('left' | 'right')[];
+}
+/**
+ * A single grid feature's contribution to the Photon AI registry — the unit
+ * `PhotonAICommandRegistry.register` accepts. Each feature module owns its
+ * own intent definitions end to end (matching phrases, entity extraction,
+ * validation, command shape, and execution), so the engine classes
+ * (`IntentParser`, `EntityResolver`, `CommandBuilder`, `CommandExecutor`)
+ * never need to know about any specific feature.
+ */
+export interface IntentDefinition {
+    /** Stable machine key, e.g. `"sortAscending"`. Becomes `PhotonCommand.type`. */
+    readonly key: string;
+    /**
+     * Sets of keywords that indicate this intent. Each inner array is one
+     * *phrase*: every word in it must appear somewhere in the input's token
+     * set (order-independent — other words, like a column name, may sit
+     * between them) for that phrase to count as matched. An intent matches
+     * when any one of its phrases is fully covered; ties are broken by
+     * preferring the phrase with the most words (the more specific match).
+     *
+     * @example `[['sort', 'ascending'], ['sort', 'asc'], ['ascending']]`
+     */
+    readonly aliases: readonly (readonly string[])[];
+    /** Optional short human description — surfaced later by help/autocomplete UI. */
+    readonly description?: string;
+    /**
+     * Extracts whatever entities this intent needs from the matched input's
+     * tokens (with the matched alias words removed, see `IntentParser`).
+     * Delegates all column/value lookup to the shared {@link EntityResolver}
+     * rather than inspecting `columns` directly, so resolution logic (fuzzy
+     * matching, etc.) lives in exactly one place.
+     */
+    resolveEntities(tokens: string[], resolver: EntityResolver, columns: ColumnDef[], api: GridApi): ResolvedEntities;
+    /** Rejects entities that don't make sense for this intent (e.g. no column found). Return an error message to reject, `null` to proceed. */
+    validate?(entities: ResolvedEntities): string | null;
+    /** Builds the final command from validated entities. */
+    buildCommand(entities: ResolvedEntities): PhotonCommand;
+    /** Executes the command against the live `GridApi`, returning a short human-readable result message. */
+    execute(command: PhotonCommand, api: GridApi): string;
+}
+/** What {@link IntentParser.parse} returns for the best-matching intent. */
+export interface ParsedIntentMatch {
+    readonly intent: IntentDefinition;
+    /** The input tokens with the matched alias's words removed — what's left to resolve entities from. */
+    readonly remainingTokens: string[];
+}
+//# sourceMappingURL=photon-ai.types.d.ts.map

package/photon-ai/photon-ai.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"photon-ai.types.d.ts","sourceRoot":"","sources":["../../src/photon-ai/photon-ai.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACpD;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,iGAAiG;IACjG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+GAA+G;IAC/G,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iJAAiJ;IACjJ,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,kIAAkI;IAClI,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,wDAAwD;IACxD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,uHAAuH;IACvH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,4HAA4H;IAC5H,KAAK,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IACjD,iFAAiF;IACjF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;OAMG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAAC;IAClH,2IAA2I;IAC3I,QAAQ,CAAC,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAAC;IACrD,wDAAwD;IACxD,YAAY,CAAC,QAAQ,EAAE,gBAAgB,GAAG,aAAa,CAAC;IACxD,wGAAwG;IACxG,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC;CACvD;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,sGAAsG;IACtG,QAAQ,CAAC,eAAe,EAAE,MAAM,EAAE,CAAC;CACpC"}

package/photon-ai/photon-ai.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=photon-ai.types.js.map

package/photon-ai/photon-ai.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"photon-ai.types.js","sourceRoot":"","sources":["../../src/photon-ai/photon-ai.types.ts"],"names":[],"mappings":""}

package/photon-ai/query-splitter.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Splits one raw prompt into independently-executable clauses so a single
+ * compound sentence can drive multiple grid commands in one submission
+ * (e.g. *"hide the id column, sort by price descending and group by
+ * category"* → three clauses). Punctuation (`,`/`;`) and connector words
+ * ("and", "then", "also", "plus") are only treated as a split point when the
+ * word(s) immediately following are recognized as a *different* command's
+ * verb (from `verbs`, typically every registered intent's leading alias
+ * word) — otherwise they're kept as part of the current clause, since they
+ * more likely mean "and also this column" (e.g. "pin price and income", or
+ * "unpin status, income and year") rather than "and now do something else".
+ *
+ * Two additional guards keep genuinely ambiguous cases from mis-splitting:
+ * a connector inside a "between X and Y" range is never a split point, and
+ * "select and copy/cut ..." is always kept whole (see
+ * {@link NEVER_SPLIT_AFTER}), since those verbs share one implicit target
+ * rather than describing two unrelated actions.
+ *
+ * @param verbs - Canonicalized (see {@link canonicalizeWord}) leading verb words for every registered intent, e.g. `{"pin", "sort", "filter", "group", ...}`.
+ */
+export declare function splitClauses(raw: string, verbs: ReadonlySet<string>): string[];
+//# sourceMappingURL=query-splitter.d.ts.map

package/photon-ai/query-splitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-splitter.d.ts","sourceRoot":"","sources":["../../src/photon-ai/query-splitter.ts"],"names":[],"mappings":"AAmCA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CA+B9E"}

package/photon-ai/query-splitter.js

@@ -0,0 +1,81 @@
+import { canonicalizeWord } from './text-normalizer';
+/** Words that *can* introduce a new clause in a compound sentence — but only when what follows is actually a new action (see {@link splitClauses}). */
+const SOFT_CONNECTORS = new Set([',', 'and', 'then', 'also', 'plus']);
+/**
+ * A connector is *not* a split point when the clause-so-far already contains
+ * a range word ("between"/"from") — e.g. "filter salary between 4000 and
+ * 8000" must keep "and" as part of the range, not split it in half.
+ */
+const RANGE_PREFIXES = new Set(['between', 'from']);
+/**
+ * "select and copy/cut" is idiomatically one action ("select, then copy
+ * what's selected"), not two independent commands sharing no context — so a
+ * bare "select"/"deselect" clause-so-far never splits, regardless of what
+ * verb follows. Every other verb pairing splits normally.
+ */
+const NEVER_SPLIT_AFTER = new Set(['select', 'deselect']);
+/**
+ * Only the word *immediately* after a connector is checked — not a wider
+ * window. A 2+ word lookahead sounds like it'd also catch "and then group by
+ * X", but with the built-in Q&A intents' generic leading alias words ("row",
+ * "column", "count", "which", "what", …) in `verbs`, a wider window false-
+ * -positives constantly: "unpin status, income and year columns" would spot
+ * "columns" two words after "and" and wrongly split before "year". "and
+ * then X" still splits correctly with a 1-word window — "then" is itself a
+ * connector, so it gets its own immediate-next-word check on the following
+ * loop iteration.
+ */
+function isUpcomingVerb(words, atIndex, verbs) {
+    return atIndex < words.length && verbs.has(canonicalizeWord(words[atIndex]));
+}
+/**
+ * Splits one raw prompt into independently-executable clauses so a single
+ * compound sentence can drive multiple grid commands in one submission
+ * (e.g. *"hide the id column, sort by price descending and group by
+ * category"* → three clauses). Punctuation (`,`/`;`) and connector words
+ * ("and", "then", "also", "plus") are only treated as a split point when the
+ * word(s) immediately following are recognized as a *different* command's
+ * verb (from `verbs`, typically every registered intent's leading alias
+ * word) — otherwise they're kept as part of the current clause, since they
+ * more likely mean "and also this column" (e.g. "pin price and income", or
+ * "unpin status, income and year") rather than "and now do something else".
+ *
+ * Two additional guards keep genuinely ambiguous cases from mis-splitting:
+ * a connector inside a "between X and Y" range is never a split point, and
+ * "select and copy/cut ..." is always kept whole (see
+ * {@link NEVER_SPLIT_AFTER}), since those verbs share one implicit target
+ * rather than describing two unrelated actions.
+ *
+ * @param verbs - Canonicalized (see {@link canonicalizeWord}) leading verb words for every registered intent, e.g. `{"pin", "sort", "filter", "group", ...}`.
+ */
+export function splitClauses(raw, verbs) {
+    const spaced = raw.replace(/[,;]+/g, ' , ');
+    const words = spaced.trim().split(/\s+/).filter((w) => w.length > 0);
+    if (words.length === 0)
+        return [];
+    const clauses = [];
+    let current = [];
+    for (let i = 0; i < words.length; i++) {
+        const word = words[i];
+        const lower = word.toLowerCase();
+        const isComma = lower === ',';
+        if (!isComma && !SOFT_CONNECTORS.has(lower)) {
+            current.push(word);
+            continue;
+        }
+        const inRangeContext = current.some((w) => RANGE_PREFIXES.has(w.toLowerCase()));
+        const currentIsNeverSplit = current.length === 1 && NEVER_SPLIT_AFTER.has(canonicalizeWord(current[0]));
+        const nextIsVerb = isUpcomingVerb(words, i + 1, verbs);
+        if (current.length > 0 && !inRangeContext && !currentIsNeverSplit && nextIsVerb) {
+            clauses.push(current.join(' '));
+            current = [];
+        }
+        else if (!isComma) {
+            current.push(word);
+        }
+    }
+    if (current.length > 0)
+        clauses.push(current.join(' '));
+    return clauses.length > 0 ? clauses : [raw.trim()];
+}
+//# sourceMappingURL=query-splitter.js.map

package/photon-ai/query-splitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-splitter.js","sourceRoot":"","sources":["../../src/photon-ai/query-splitter.ts"],"names":[],"mappings":"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"}

package/photon-ai/text-normalizer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Reduces a plural English noun to its singular form using a small set of
+ * common suffix rules — not a full stemmer, just enough to make alias
+ * matching plural-insensitive (e.g. "columns"/"filters"/"rows" all reduce to
+ * the singular form every built-in alias is written against). Never touches
+ * pure numbers or short/exception words where stripping "s" would be wrong.
+ */
+export declare function stemWord(word: string): string;
+/** Splits already-normalized (lowercase, punctuation-free) text into words. */
+export declare function tokenize(text: string): string[];
+/**
+ * Reduces one raw word to the canonical form every alias/filler check is
+ * written against: lowercased, singularized, then synonym-mapped (e.g.
+ * "Resetting" → "reset" → "clear"). Exposed separately from
+ * {@link normalizeInput} so callers that need to test a *single* word
+ * against a keyword set (e.g. `query-splitter`'s clause-boundary detector)
+ * get identical canonicalization without re-tokenizing a whole sentence.
+ */
+export declare function canonicalizeWord(raw: string): string;
+/**
+ * Normalizes a raw prompt for intent matching: lowercase, strip punctuation
+ * (while preserving `.`/`-`/`:`/`/` inside numbers and dates), singularize
+ * plurals, canonicalize synonyms, collapse whitespace, and drop filler
+ * words. `EntityResolver` still receives the *original* remaining words
+ * (this never reorders anything), so column names and values downstream are
+ * unaffected beyond casing/punctuation/pluralization.
+ *
+ * @example normalizeInput("Hey Photon, please pin the salary column to the left side.")
+ *   // => "pin salary column left"
+ * @example normalizeInput("reset all filters") // => "clear all filter"
+ */
+export declare function normalizeInput(raw: string): string;
+//# sourceMappingURL=text-normalizer.d.ts.map

package/photon-ai/text-normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-normalizer.d.ts","sourceRoot":"","sources":["../../src/photon-ai/text-normalizer.ts"],"names":[],"mappings":"AAuEA;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO7C;AAED,+EAA+E;AAC/E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAE/C;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAalD"}

package/photon-ai/text-normalizer.js

@@ -0,0 +1,132 @@
+/**
+ * Words stripped before intent matching: conversational filler ("hey",
+ * "please"), the assistant's own name, common function/linking words, and
+ * connector words that natural sentences use but that carry no command
+ * meaning on their own (e.g. "whose", "who", "is", "are"). Intentionally
+ * broad — `IntentParser`'s alias matching only requires a phrase's *own*
+ * keywords to be present, so over-stripping here is safe; it can never
+ * remove a word an alias needs, since alias keywords (e.g. "sort", "left",
+ * "hide") are never in this list.
+ */
+const FILLER_WORDS = new Set([
+    'hi', 'hello', 'hey', 'please', 'can', 'could', 'would', 'you', 'quickly', 'thanks', 'thank',
+    'photon', 'ai', 'assistant',
+    // Deliberately NOT "of" — it's stripped everywhere else, but it's also a
+    // real word inside dropdown/enum option labels ("Out of Stock", "Point of
+    // Sale"); stripping it from the user's query but not from the option
+    // label being matched against would make those options unmatchable.
+    'to', 'the', 'a', 'an', 'in', 'on', 'at', 'is', 'are', 'was', 'were', 'be', 'me', 'my',
+    'side', 'now', 'just',
+    'them', 'it', 'their', 'order', 'whose', 'who', 'that', 'with', 'having',
+    'value', 'currently', 'kindly', 'want', 'need', 'like', 'this', 'these',
+]);
+/**
+ * Canonicalizes synonyms down to the single keyword every `IntentDefinition`
+ * alias is actually written against, so a feature only has to declare one
+ * spelling (e.g. `"clear"`) while users can type any of several equivalent
+ * words (e.g. "reset", "erase", "wipe"). Applied per-word, after stemming.
+ */
+const SYNONYMS = new Map([
+    ['reset', 'clear'],
+    ['erase', 'clear'],
+    ['wipe', 'clear'],
+    ['delete', 'remove'],
+    ['drop', 'remove'],
+    ['freeze', 'pin'],
+    ['unfreeze', 'unpin'],
+    ['display', 'show'],
+    ['reveal', 'show'],
+    ['everything', 'all'],
+    ['every', 'all'],
+    ['entire', 'all'],
+    ['ascend', 'ascending'],
+    ['descend', 'descending'],
+    ['increasing', 'ascending'],
+    ['decreasing', 'descending'],
+    ['newest', 'descending'],
+    ['oldest', 'ascending'],
+    ['biggest', 'largest'],
+    ['smaller', 'smallest'],
+    ['bigger', 'largest'],
+    ['grouping', 'group'],
+    ['filtering', 'filter'],
+    ['sorting', 'sort'],
+    ['hiding', 'hide'],
+    ['showing', 'show'],
+    ['pinning', 'pin'],
+    // Past-participle forms used in questions ("what's currently sorted?", "which columns are hidden?").
+    ['pinned', 'pin'],
+    ['hidden', 'hide'],
+    ['filtered', 'filter'],
+    ['sorted', 'sort'],
+    ['grouped', 'group'],
+    ['selected', 'select'],
+]);
+/** Word endings that must never be singularized — stripping their trailing "s" would corrupt the word. */
+const STEM_EXCEPTIONS = new Set([
+    'status', 'address', 'series', 'analysis', 'this', 'his', 'is', 'was', 'has', 'as', 'gas',
+]);
+/**
+ * Reduces a plural English noun to its singular form using a small set of
+ * common suffix rules — not a full stemmer, just enough to make alias
+ * matching plural-insensitive (e.g. "columns"/"filters"/"rows" all reduce to
+ * the singular form every built-in alias is written against). Never touches
+ * pure numbers or short/exception words where stripping "s" would be wrong.
+ */
+export function stemWord(word) {
+    if (word.length <= 3 || /^\d+$/.test(word) || STEM_EXCEPTIONS.has(word))
+        return word;
+    if (word.endsWith('ies'))
+        return `${word.slice(0, -3)}y`;
+    if (/(?:s|x|z|ch|sh)es$/.test(word))
+        return word.slice(0, -2);
+    if (word.endsWith('ss'))
+        return word;
+    if (word.endsWith('s'))
+        return word.slice(0, -1);
+    return word;
+}
+/** Splits already-normalized (lowercase, punctuation-free) text into words. */
+export function tokenize(text) {
+    return text.split(' ').filter((w) => w.length > 0);
+}
+/**
+ * Reduces one raw word to the canonical form every alias/filler check is
+ * written against: lowercased, singularized, then synonym-mapped (e.g.
+ * "Resetting" → "reset" → "clear"). Exposed separately from
+ * {@link normalizeInput} so callers that need to test a *single* word
+ * against a keyword set (e.g. `query-splitter`'s clause-boundary detector)
+ * get identical canonicalization without re-tokenizing a whole sentence.
+ */
+export function canonicalizeWord(raw) {
+    const stemmed = stemWord(raw.toLowerCase());
+    return SYNONYMS.get(stemmed) ?? stemmed;
+}
+/**
+ * Normalizes a raw prompt for intent matching: lowercase, strip punctuation
+ * (while preserving `.`/`-`/`:`/`/` inside numbers and dates), singularize
+ * plurals, canonicalize synonyms, collapse whitespace, and drop filler
+ * words. `EntityResolver` still receives the *original* remaining words
+ * (this never reorders anything), so column names and values downstream are
+ * unaffected beyond casing/punctuation/pluralization.
+ *
+ * @example normalizeInput("Hey Photon, please pin the salary column to the left side.")
+ *   // => "pin salary column left"
+ * @example normalizeInput("reset all filters") // => "clear all filter"
+ */
+export function normalizeInput(raw) {
+    const lowered = raw.toLowerCase();
+    // Keep '.', '-', ':', '/' so decimals ("12.5"), negative numbers ("-5"),
+    // and dates ("2024-01-15", "01/15/2024") survive as single tokens.
+    const noPunctuation = lowered.replace(/[^\p{L}\p{N}\s.\-:/]/gu, ' ');
+    const words = noPunctuation.split(/\s+/).filter((w) => w.length > 0);
+    const kept = [];
+    for (const word of words) {
+        const canonical = canonicalizeWord(word);
+        if (FILLER_WORDS.has(canonical))
+            continue;
+        kept.push(canonical);
+    }
+    return kept.join(' ');
+}
+//# sourceMappingURL=text-normalizer.js.map

package/photon-ai/text-normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-normalizer.js","sourceRoot":"","sources":["../../src/photon-ai/text-normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAC;IAChD,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO;IAC5F,QAAQ,EAAE,IAAI,EAAE,WAAW;IAC3B,yEAAyE;IACzE,0EAA0E;IAC1E,qEAAqE;IACrE,oEAAoE;IACpE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;IACtF,MAAM,EAAE,KAAK,EAAE,MAAM;IACrB,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ;IACxE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;CACxE,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,QAAQ,GAAgC,IAAI,GAAG,CAAC;IACpD,CAAC,OAAO,EAAE,OAAO,CAAC;IAClB,CAAC,OAAO,EAAE,OAAO,CAAC;IAClB,CAAC,MAAM,EAAE,OAAO,CAAC;IACjB,CAAC,QAAQ,EAAE,QAAQ,CAAC;IACpB,CAAC,MAAM,EAAE,QAAQ,CAAC;IAClB,CAAC,QAAQ,EAAE,KAAK,CAAC;IACjB,CAAC,UAAU,EAAE,OAAO,CAAC;IACrB,CAAC,SAAS,EAAE,MAAM,CAAC;IACnB,CAAC,QAAQ,EAAE,MAAM,CAAC;IAClB,CAAC,YAAY,EAAE,KAAK,CAAC;IACrB,CAAC,OAAO,EAAE,KAAK,CAAC;IAChB,CAAC,QAAQ,EAAE,KAAK,CAAC;IACjB,CAAC,QAAQ,EAAE,WAAW,CAAC;IACvB,CAAC,SAAS,EAAE,YAAY,CAAC;IACzB,CAAC,YAAY,EAAE,WAAW,CAAC;IAC3B,CAAC,YAAY,EAAE,YAAY,CAAC;IAC5B,CAAC,QAAQ,EAAE,YAAY,CAAC;IACxB,CAAC,QAAQ,EAAE,WAAW,CAAC;IACvB,CAAC,SAAS,EAAE,SAAS,CAAC;IACtB,CAAC,SAAS,EAAE,UAAU,CAAC;IACvB,CAAC,QAAQ,EAAE,SAAS,CAAC;IACrB,CAAC,UAAU,EAAE,OAAO,CAAC;IACrB,CAAC,WAAW,EAAE,QAAQ,CAAC;IACvB,CAAC,SAAS,EAAE,MAAM,CAAC;IACnB,CAAC,QAAQ,EAAE,MAAM,CAAC;IAClB,CAAC,SAAS,EAAE,MAAM,CAAC;IACnB,CAAC,SAAS,EAAE,KAAK,CAAC;IAClB,qGAAqG;IACrG,CAAC,QAAQ,EAAE,KAAK,CAAC;IACjB,CAAC,QAAQ,EAAE,MAAM,CAAC;IAClB,CAAC,UAAU,EAAE,QAAQ,CAAC;IACtB,CAAC,QAAQ,EAAE,MAAM,CAAC;IAClB,CAAC,SAAS,EAAE,OAAO,CAAC;IACpB,CAAC,UAAU,EAAE,QAAQ,CAAC;CACvB,CAAC,CAAC;AAEH,0GAA0G;AAC1G,MAAM,eAAe,GAAwB,IAAI,GAAG,CAAC;IACnD,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK;CAC1F,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACrF,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IACzD,IAAI,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9D,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACjD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC;IAC5C,OAAO,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,MAAM,OAAO,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IAClC,yEAAyE;IACzE,mEAAmE;IACnE,MAAM,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,wBAAwB,EAAE,GAAG,CAAC,CAAC;IACrE,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrE,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,SAAS,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,SAAS;QAC1C,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC"}