@capsiynau/intelligence 0.2.0 → 0.4.0

package/types/speakers/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Total milliseconds the utterances cover WITHIN the transcript span
+ * `[spanStart, spanEnd]`, counted as a UNION so overlapping utterances don't
+ * double-count. Each utterance is first clipped to the span (speech entirely
+ * outside the transcript window contributes 0), then the clipped intervals are
+ * merged and their lengths summed. This is what makes coverage measure the
+ * fraction of the transcript actually overlapped by the speaker timeline,
+ * rather than total diarisation duration (which can sit outside the window
+ * when diarisation ran over the full audio but the transcript is a clip).
+ *
+ * @param {Array<{start?:number,end?:number}>} utts
+ * @param {number} spanStart inclusive lower bound (ms)
+ * @param {number} spanEnd   inclusive upper bound (ms)
+ * @returns {number} unioned, clipped duration in ms (>= 0)
+ */
+export function clampedUnionMs(utts: Array<{
+    start?: number;
+    end?: number;
+}>, spanStart: number, spanEnd: number): number;
+/**
+ * Judge whether a diarisation timeline is reliable enough to label segments.
+ *
+ * @param {Array<{start:number,end:number,speaker:string}>} utterances
+ *        diarisation timeline in milliseconds (AssemblyAI `utterances` shape).
+ * @param {Array<{start_ms:number,end_ms:number}>} segments
+ *        transcript segments in milliseconds (used to measure coverage).
+ * @param {Partial<typeof DIARISATION_GATE_DEFAULTS>} [opts] threshold overrides.
+ * @returns {{ reliable: boolean, speakerCount: number, coverage: number,
+ *             durationMs: number, reason: string }}
+ */
+export function assessDiarisation(utterances: Array<{
+    start: number;
+    end: number;
+    speaker: string;
+}>, segments: Array<{
+    start_ms: number;
+    end_ms: number;
+}>, opts?: Partial<typeof DIARISATION_GATE_DEFAULTS>): {
+    reliable: boolean;
+    speakerCount: number;
+    coverage: number;
+    durationMs: number;
+    reason: string;
+};
+/**
+ * Map acoustic diarisation speakers ("Speaker 1/2/3") to REAL names from a
+ * labelled reference timeline (platform transcript / roster), by greatest
+ * total time-overlap. Upgrades anonymous acoustic labels to real names when a
+ * labelled source exists (speaker-ID ladder rung A over C). Pure.
+ *
+ * Only confident matches are returned: the winning name must cover
+ * >= minOverlapFraction of the acoustic speaker's speaking time AND beat the
+ * runner-up by >= dominanceRatio. Ambiguous / unmatched acoustic speakers are
+ * listed in `unmapped`, so the caller keeps their anonymous label.
+ *
+ * Note: two acoustic speakers can map to the same real name (acoustic over-
+ * split one person). That is acceptable - downstream can merge. 1:1 dedup is a
+ * future refinement.
+ *
+ * @param {Array<{start:number,end:number,speaker:string}>} acoustic  utterances (ms)
+ * @param {Array<{start:number,end:number,name:string}>} labelled  real-name turns (ms)
+ * @param {Partial<typeof SPEAKER_MAP_DEFAULTS>} [opts]
+ * @returns {{ map: Record<string,string>, unmapped: string[] }}
+ */
+export function mapSpeakersToNames(acoustic: Array<{
+    start: number;
+    end: number;
+    speaker: string;
+}>, labelled: Array<{
+    start: number;
+    end: number;
+    name: string;
+}>, opts?: Partial<typeof SPEAKER_MAP_DEFAULTS>): {
+    map: Record<string, string>;
+    unmapped: string[];
+};
+export namespace DIARISATION_GATE_DEFAULTS {
+    let soleSpeakerSuspectAboveMs: number;
+    let minCoverage: number;
+    let trustAtSpeakers: number;
+}
+export namespace SPEAKER_MAP_DEFAULTS {
+    let minOverlapFraction: number;
+    let dominanceRatio: number;
+}

package/types/spellcheck/core.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Check a single word against the supplied dictionary + accept-list.
+ *
+ * @param {string} word - The word to check (no punctuation, single token).
+ * @param {object} opts
+ * @param {object} opts.nspell - An nspell instance (server side, built
+ *                               from dictionary-cy or dictionary-en-gb).
+ * @param {Set<string>} [opts.accept] - Lowercased proper nouns + glossary
+ *                                       + word_boost_approved terms that
+ *                                       must never be flagged.
+ * @param {boolean} [opts.welsh] - When true, additionally try mutation
+ *                                  reversal before declaring the word
+ *                                  misspelled. Pass false for English.
+ * @returns {boolean} true if the word is considered correctly spelled.
+ */
+export function checkWord(word: string, { nspell, accept, welsh }: {
+    nspell: object;
+    accept?: Set<string>;
+    welsh?: boolean;
+}): boolean;
+/**
+ * Tokenise a string into checkable words + their positions, so a UI
+ * can underline only the wrong tokens without re-tokenising itself.
+ *
+ * Position is the offset in the original string. Tokens are word-like
+ * runs of letters/marks/apostrophes/hyphens; punctuation is skipped.
+ *
+ * @param {string} text
+ * @returns {{ word: string, start: number, end: number }[]}
+ */
+export function tokenise(text: string): {
+    word: string;
+    start: number;
+    end: number;
+}[];
+/**
+ * Check an entire string and return the misspelled tokens (if any).
+ * Convenience wrapper around tokenise + checkWord.
+ *
+ * @param {string} text
+ * @param {object} opts - same shape as checkWord opts
+ * @param {object} opts.nspell - An nspell instance.
+ * @param {Set<string>} [opts.accept] - Terms that must never be flagged.
+ * @param {boolean} [opts.welsh] - Try mutation reversal before flagging.
+ * @returns {{ word: string, start: number, end: number }[]}
+ */
+export function checkSentence(text: string, opts: {
+    nspell: object;
+    accept?: Set<string>;
+    welsh?: boolean;
+}): {
+    word: string;
+    start: number;
+    end: number;
+}[];
+/**
+ * Generate up to N suggestions for a misspelled word. Wraps
+ * nspell.suggest() but biases toward `accept` (proper nouns are
+ * surfaced first when they're close in edit distance).
+ *
+ * @param {string} word
+ * @param {object} opts
+ * @param {object} opts.nspell
+ * @param {Set<string>} [opts.accept]
+ * @param {boolean} [opts.welsh] - Bias suggestions for Welsh mutation forms.
+ * @param {number} [opts.max] - default 6
+ * @returns {string[]}
+ */
+export function suggest(word: string, { nspell, accept, welsh, max }: {
+    nspell: object;
+    accept?: Set<string>;
+    welsh?: boolean;
+    max?: number;
+}): string[];

package/types/spellcheck/index.d.ts

@@ -0,0 +1 @@
+export { checkWord, checkSentence, tokenise, suggest } from "./core.js";

package/types/welsh/digraphs.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Split a Welsh word into its constituent letters, treating digraphs
+ * as single units. Case-preserving.
+ *
+ * @example
+ *   splitIntoLetters('llwybr')   // ['ll', 'w', 'y', 'b', 'r']
+ *   splitIntoLetters('CHWARAE')  // ['CH', 'W', 'A', 'R', 'A', 'E']
+ *   splitIntoLetters('rhag-')    // ['rh', 'a', 'g', '-']
+ *
+ * @param {string} word
+ * @returns {string[]}
+ */
+export function splitIntoLetters(word: string): string[];
+/**
+ * Welsh-aware character count: a digraph counts as ONE letter.
+ *
+ * @example
+ *   welshLength('llwybr')     // 5  (ll-w-y-b-r), NOT 6
+ *   welshLength('chwarae')    // 6  (ch-w-a-r-a-e)
+ *   welshLength('Eisteddfod') // 9  (e-i-s-t-e-dd-f-o-d), NOT 10
+ *
+ * @param {string} word
+ * @returns {number}
+ */
+export function welshLength(word: string): number;
+/**
+ * Reverse a Welsh word preserving digraphs (used by anagram /
+ * caption-style transforms that mirror text).
+ *
+ * @example
+ *   welshReverse('llwybr')  // 'rbywll'  (NOT 'rbywll' broken to 'rbyw ll')
+ *
+ * @param {string} word
+ * @returns {string}
+ */
+export function welshReverse(word: string): string;
+export function welshCompare(a: any, b: any): number;
+/**
+ * Check if a string position lies on a digraph boundary. Useful for
+ * cursor / selection logic: when the cursor sits after `l` in `llwybr`,
+ * a single backspace should remove BOTH letters of `ll`, not just one.
+ *
+ * Returns `true` if the character at `index` is the second half of a
+ * digraph (i.e. the digraph started at `index - 1`).
+ *
+ * @example
+ *   isDigraphContinuation('llwybr', 1) // true   ('l' completing 'll')
+ *   isDigraphContinuation('llwybr', 2) // false  ('w')
+ *   isDigraphContinuation('cath', 1)   // false  ('a')
+ *
+ * @param {string} word
+ * @param {number} index
+ * @returns {boolean}
+ */
+export function isDigraphContinuation(word: string, index: number): boolean;
+/**
+ * @capsiynau/intelligence/welsh/digraphs
+ *
+ * Welsh digraph handling. In the Welsh alphabet, these eight digraphs
+ * are SINGLE letters and must be treated as one unit for:
+ *   - character iteration
+ *   - cursor movement
+ *   - word length
+ *   - alphabetical sort
+ *   - reversal (for anagrams etc.)
+ *
+ * The eight digraphs (canonical order in the Welsh alphabet):
+ *   ch  dd  ff  ng  ll  ph  rh  th
+ *
+ * Note: `ng` is the most context-sensitive. In some words it represents
+ * a single sound (canu's "ng" is /ŋ/) but in compound words it can be
+ * `n` + `g` separately (e.g. "Bangor" is BAN+GOR phonetically but
+ * conventionally still written without splitting). For purely
+ * orthographic operations (length, indexing, anagrams), we treat every
+ * occurrence as a single digraph. Callers needing phonetic accuracy
+ * must layer their own lexicon lookup on top.
+ *
+ * Pure JS, no external deps.
+ */
+/**
+ * The eight Welsh digraphs in their canonical alphabetical order.
+ * @type {readonly string[]}
+ */
+export const WELSH_DIGRAPHS: readonly string[];
+/**
+ * Map of digraph -> alphabetical position (0-indexed within the digraph set).
+ * For full Welsh-alphabet collation, layer this on top of the single-letter
+ * position map in `WELSH_ALPHABET_ORDER` below.
+ */
+export const DIGRAPH_INDEX: Readonly<{
+    [k: string]: number;
+}>;
+/**
+ * The canonical Welsh alphabet in collation order. Note the digraphs
+ * follow their leading letter: `c` then `ch`, `d` then `dd`, etc.
+ * Letters not in Welsh (`k`, `q`, `v`, `x`, `z`) are omitted; loan words
+ * containing them are conventionally sorted as if they were English.
+ *
+ * Source: Geiriadur Prifysgol Cymru collation rules.
+ * @type {readonly string[]}
+ */
+export const WELSH_ALPHABET_ORDER: readonly string[];

package/types/welsh/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./normaliser.js";
+export * from "./digraphs.js";
+export * from "./mutations.js";

package/types/welsh/mutations.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Apply a mutation to a Welsh word. Returns the mutated form.
+ * Preserves the case of the first character.
+ *
+ * Soft mutation of `g` is DELETION — the word loses its initial `g`.
+ * e.g. 'gardd' -> soft -> 'ardd' (the garden, after 'yr' for feminine).
+ *
+ * If the word's initial consonant is not subject to the given mutation,
+ * returns the word unchanged.
+ *
+ * @param {string} word
+ * @param {'soft'|'nasal'|'aspirate'} kind
+ * @returns {string}
+ *
+ * @example
+ *   applyMutation('cath',  'soft')      // 'gath'
+ *   applyMutation('Tad',   'soft')      // 'Dad'    (case preserved)
+ *   applyMutation('ci',    'nasal')     // 'nghi'
+ *   applyMutation('Pen',   'aspirate')  // 'Phen'
+ *   applyMutation('gardd', 'soft')      // 'ardd'   (g-deletion)
+ *   applyMutation('llaw',  'soft')      // 'law'
+ *   applyMutation('siop',  'soft')      // 'siop'   (s not subject)
+ */
+export function applyMutation(word: string, kind: "soft" | "nasal" | "aspirate"): string;
+/**
+ * Reverse a mutation: given an observed (possibly mutated) word,
+ * return all candidate root forms. The caller can intersect this
+ * with a dictionary lookup to pick the real root.
+ *
+ * If `kind` is provided, only candidates from that mutation are
+ * returned. If omitted, candidates from all three mutations.
+ *
+ * The observed word itself is ALWAYS included as the first candidate
+ * (it might not actually be mutated).
+ *
+ * @param {string} word
+ * @param {'soft'|'nasal'|'aspirate'} [kind]
+ * @returns {{ root: string, kind: string | null }[]}
+ *
+ * @example
+ *   possibleRoots('gath')   // [
+ *                            //   { root: 'gath', kind: null },     // as-is
+ *                            //   { root: 'cath', kind: 'soft' },   // c -> g
+ *                            // ]
+ *   possibleRoots('phen', 'aspirate') // [
+ *                            //   { root: 'phen', kind: null },
+ *                            //   { root: 'pen',  kind: 'aspirate' },
+ *                            // ]
+ */
+export function possibleRoots(word: string, kind?: "soft" | "nasal" | "aspirate"): {
+    root: string;
+    kind: string | null;
+}[];
+/**
+ * Best-effort classification: does this word LOOK mutated?
+ *
+ * Returns the mutation kind if the word starts with a sequence
+ * characteristic of one specific mutation (e.g. 'ph' / 'th' / 'ch' are
+ * aspirate-only; 'mh' / 'nh' / 'ngh' are nasal-only). Returns null if
+ * the word either isn't mutated or its surface form is ambiguous.
+ *
+ * NOT a reliable mutation detector on its own. Use with caller context.
+ *
+ * @param {string} word
+ * @returns {'soft'|'nasal'|'aspirate'|null}
+ */
+export function classifyMutation(word: string): "soft" | "nasal" | "aspirate" | null;
+/**
+ * The three mutation kinds as a const enum-ish object.
+ * @type {Readonly<{soft:'soft', nasal:'nasal', aspirate:'aspirate'}>}
+ */
+export const MUTATION: Readonly<{
+    soft: "soft";
+    nasal: "nasal";
+    aspirate: "aspirate";
+}>;

package/types/welsh/normaliser.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Normalise raw Welsh/English transcript text.
+ * Repairs broken contractions, fixes encoding, removes zero-width chars.
+ * Safe to apply to English too — repairs are Welsh-specific patterns unlikely
+ * to match English text.
+ */
+export function normaliseWelsh(text: any): any;
+/**
+ * Get a dialect-specific system prompt fragment for AI calls.
+ * @param {'broadcast'|'north'|'south'|'formal'} dialect
+ * @returns {string}
+ */
+export function getDialectSystemPrompt(dialect: "broadcast" | "north" | "south" | "formal"): string;