calliope-ts 0.0.1

package/src/tagfix.ts

@@ -0,0 +1,104 @@
+// tagfix.ts — Pre-parse POS-tag correction layer.
+//
+// FinNLP's en-pos tagger is structurally sound but carries a small tail of
+// SYSTEMATIC tag errors that matter enormously for verse analysis, because a
+// wrong tag flips a word's content/function status (→ its stress tier) and
+// derails the en-parse dependency tree built from the tags.  This pass runs
+// BETWEEN en-pos and en-parse (see parseDocument in parser.ts), so corrected
+// tags repair both the tagging AND the resulting dependency structure — a
+// post-hoc fix of the parse could never do that.
+//
+// Every rule below targets an error class actually observed in this repo's
+// trials; rules are deliberately narrow (anti-gaming: each must be justified
+// by the error it fixes, not by benchmark deltas).
+
+/** Zero-derived irregular past participles that en-pos tags NN/VBP after a
+ *  have-auxiliary ("had quit", "has put", "have read").  Only forms whose
+ *  participle is identical to the base/noun spelling — the -en/-ed forms tag
+ *  fine on their own. */
+const ZERO_PARTICIPLES = new Set([
+  'quit', 'put', 'set', 'cut', 'hit', 'let', 'shut', 'cast', 'cost', 'hurt',
+  'burst', 'split', 'spread', 'bet', 'wed', 'read', 'rid', 'shed', 'thrust',
+  'slit', 'bid', 'broadcast', 'upset', 'sunburst',
+]);
+
+const HAVE_FORMS = new Set(['have', 'has', 'had', 'having', "'ve", "'d"]);
+
+/** Archaic / Early-Modern-English forms en-pos has no lexicon entries for —
+ *  ubiquitous in the verse this toolkit exists to scan. */
+const ARCHAIC_TAGS: Record<string, string> = {
+  thou: 'PRP', thee: 'PRP', ye: 'PRP',
+  thy: 'PRP$', thine: 'PRP$',
+  art: 'VBP', wert: 'VBD', wast: 'VBD',
+  doth: 'VBZ', hath: 'VBZ', dost: 'VBZ', hast: 'VBZ', saith: 'VBZ',
+  didst: 'VBD', hadst: 'VBD', wouldst: 'MD', couldst: 'MD', shouldst: 'MD',
+  shalt: 'MD', wilt: 'MD', canst: 'MD', mayst: 'MD', 'mightst': 'MD',
+  wherefore: 'WRB', whither: 'WRB', whence: 'WRB',
+  hither: 'RB', thither: 'RB', yon: 'JJ', yonder: 'RB',
+  ere: 'IN', oft: 'RB', anon: 'RB',
+};
+
+/**
+ * Correct a sentence's tags in place-safe fashion (returns a new array).
+ * `tokens` and `tags` are the en-pos outputs, index-aligned.
+ */
+export function correctTags(tokens: string[], tags: string[]): string[] {
+  const out = tags.slice();
+  for (let i = 0; i < tokens.length; i++) {
+    const w = tokens[i].toLowerCase();
+
+    // 1. The pronoun "I".  en-norm lowercases sentence-initial "I" → "i",
+    //    which en-pos then reads as a foreign word / letter name (FW).
+    if (w === 'i' && out[i] === 'FW') out[i] = 'PRP';
+
+    // 2. Archaic forms (thou/thy/doth/shalt/wherefore…): en-pos guesses
+    //    NN/JJ/FW for these, wrecking both stress class and the parse.
+    //    Guard "art": only when a pronoun precedes ("thou art"), since the
+    //    noun reading ("the art of…") is the modern default.
+    const archaic = ARCHAIC_TAGS[w];
+    if (archaic && !/^(NNP|NNPS)$/.test(out[i])) {
+      if (w === 'art') {
+        const prev = i > 0 ? tokens[i - 1].toLowerCase() : '';
+        if (prev === 'thou' || prev === 'ye' || prev === 'you') out[i] = 'VBP';
+      } else {
+        out[i] = archaic;
+      }
+    }
+
+    // 3. Perfect-tense zero participles: have-form + ("quit"/"put"/"read"…)
+    //    tagged as NN/VBP/VBD → VBN, so en-parse builds the verb chain
+    //    instead of treating the participle as a direct-object noun
+    //    ("I had quit the programming paradigm").  An intervening adverb
+    //    ("had just quit") is allowed.
+    if (ZERO_PARTICIPLES.has(w) && /^(NN|NNS|VBP|VBD|VB)$/.test(out[i])) {
+      const prev1 = i > 0 ? tokens[i - 1].toLowerCase() : '';
+      const prev2 = i > 1 ? tokens[i - 2].toLowerCase() : '';
+      const prev1IsAdv = i > 0 && /^RB/.test(out[i - 1]);
+      if (HAVE_FORMS.has(prev1) || (prev1IsAdv && HAVE_FORMS.has(prev2))) {
+        out[i] = 'VBN';
+      }
+    }
+
+    // 4. Impossible gerunds: a VBG tag on a token that does not end in
+    //    -ing/-in' cannot be a gerund/present participle — it is an en-pos
+    //    lexicon glitch.  The right tag depends on context: before a noun it
+    //    is a noun modifier ("wisdom"/VBG teeth → NN); after a subject
+    //    pronoun it is a finite verb ("as they bicycle/VBG through" → VBP,
+    //    which keeps "through" a phrasal particle in the parse).  With no
+    //    deciding context, leave the tag alone (en-parse treats VBG
+    //    verb-ishly, the safer default).
+    if (out[i] === 'VBG' && !/in[g'’]?$/.test(w)) {
+      const prevTag = i > 0 ? out[i - 1] : '';
+      const nextTag = i + 1 < tokens.length ? out[i + 1] : '';
+      if (/^NNS?$/.test(nextTag)) out[i] = 'NN';
+      else if (prevTag === 'PRP') out[i] = 'VBP';
+    }
+
+    // 5. Vocative "O" ("O wild West Wind"): en-pos gives NNP/JJ; it is an
+    //    interjection (and must not become a content word with a beat by
+    //    default).  Only the bare capital O — "o'er" etc. are handled by the
+    //    aphaeresis lexicon in stress.ts.
+    if (tokens[i] === 'O' && i + 1 < tokens.length && out[i] !== 'UH') out[i] = 'UH';
+  }
+  return out;
+}

package/src/types.ts

@@ -0,0 +1,230 @@
+// types.ts — Complete type declarations for Calliope_TS pipeline
+// Reflects McAleese’s class diagrams (Figure 14) and additional phonological /
+// metrical types required by stress, phonological hierarchy, scansion, and Scandroid modules.
+
+/**
+ * Stress levels in McAleese’s relative system, in ascending order
+ * `x < w < n < m < s`.  `x` is the "Zero Provision" tier (Hayes; Lerdahl &
+ * Jackendoff 1983): a level *weaker than a stressless overt syllable*, borne by
+ * maximally-reduced clitics (the/a/of/and…) and unfilled positions.
+ */
+export type StressLevel = 'x' | 'w' | 'n' | 'm' | 's';
+
+/** A single syllable within a word, with phonetic and stress information */
+export interface Syllable {
+  text: string;                       // the orthographic syllable (or entire word if unsplit)
+  phones: string;                     // CMU phonetic transcription (per-syllable ARPAbet)
+  weight?: 'H' | 'L';                 // syllable weight (Heavy/Light)
+  stress: number;                     // numeric stress from CMU; modified by compound + nuclear rules
+  lexicalStress?: number;             // stress before nuclear rule; used for relative mapping / meter detection
+  relativeStress?: StressLevel;       // assigned after phrase‑stress rules and relative adjustment
+  extrametrical?: 'morphological' | 'light_noun' | 'derivational';  // extrametricality classification
+}
+
+/** Represents a word in the dependency‑parse graph */
+export interface ClsWord {
+  index: number;                      // 1‑based index in the sentence (matching Antelope’s XML)
+  lexicalClass: string;               // POS tag, e.g., 'VBD', 'NN', 'PRP'
+  lexicalDetails: string;             // additional morphological info (empty if none)
+  lexicalPlural: boolean;             // true if plural
+  position: string;                   // textual position (not always used)
+  word: string;                       // the surface form of the word
+  absoluteIndex: number;              // 0‑based index among all words in the text
+  isContent: boolean; 
+  // extended properties
+  syllables: Syllable[];              // array of syllables for the word
+  morphSuffix?: string;               // productive suffix split off for OOV stress (e.g. 'est'); guides display syllabification
+  phraseStress: number;               // numeric phrase‑level stress after Nuclear Stress Rule
+  dependency?: ClsDependency;         // back‑reference to dependency edge (if any)
+  node?: ClsNode;                     // back‑reference to the constituent node (if any)
+}
+
+/** A typed dependency edge between two words (as in Antelope’s XML) */
+export interface ClsDependency {
+  index: number;                      // 1‑based dependency index
+  governorIndex: number;              // word index of the governor (head)
+  dependentIndex: number;             // word index of the dependent
+  dependentType: string;             // type label: 'aux','nsubj','dobj','prep','det','poss','possessive','pobj',…
+  governorName: string;              // surface form of the governor
+  dependentName: string;             // surface form of the dependent
+  governor: ClsWord;                 // reference to the governor word object
+  dependent: ClsWord;                // reference to the dependent word object
+}
+
+/** A constituent node in the parse tree (mirrors Figure 14) */
+export interface ClsNode {
+  index: string;                      // node identifier, e.g., '1', '1.2'
+  nodeName: string;                   // label (e.g., 'SQ', 'NP', 'VP', 'PP', or a word index)
+  parent: ClsNode | null;             // parent node, null for root
+  contains: (ClsNode | ClsWord)[];   // children: either sub‑nodes or words
+}
+
+/** A single parsed sentence */
+export interface ClsSentence {
+  index: number;                      // sentence number (1‑based)
+  nodes: ClsNode | null;             // root node of the parse tree
+  dependencies: ClsDependency[];     // all dependency edges in this sentence
+  words: ClsWord[];                  // word objects in order
+  xml: string;                        // serialised XML representation (optional)
+}
+
+/** Top‑level document containing parsed sentences */
+export interface ClsDocument {
+  sentences: ClsSentence[];          // list of parsed sentences
+  xml: string;                        // full XML document (optional)
+}
+
+// ─── Phonological Hierarchy (CP, PP, IU) ────────────────────────────
+
+/** A clitic group: one content word plus its attached function words */
+export interface CliticGroup {
+  tokens: ClsWord[];
+}
+
+/** A phonological phrase: one or more clitic groups related syntactically */
+export interface PhonologicalPhrase {
+  cliticGroups: CliticGroup[];
+}
+
+/** An intonational unit: one or more phonological phrases bounded by punctuation/line‑end */
+export interface IntonationalUnit {
+  phonologicalPhrases: PhonologicalPhrase[];
+}
+
+// ─── Metre‑ and scansion‑related types ─────────────────────────────
+
+/** Recognised metre names */
+export type MetreName =
+  | 'iambic'
+  | 'trochaic'
+  | 'spondaic'
+  | 'pyrrhic'
+  | 'anapestic'
+  | 'dactylic'
+  | 'amphibrachic'
+  | 'bacchic';
+
+/** Definition of a metre candidate: its foot shape and syllable count per foot */
+export interface MetreCandidate {
+  name: MetreName;
+  foot: string;          // e.g., 'ws', 'sw', 'wws'
+  syllableCount: number; // number of syllables in one foot (2 or 3)
+}
+
+/** A key‑stress pattern extracted from one unit of the phonological hierarchy */
+export interface KeyStress {
+  unitType: 'PW' | 'CP' | 'PP' | 'IU';  // type of prosodic unit
+  pattern: string;                       // stress pattern, e.g., 'ws', 'sw', 'wsw'
+  weight: number;                        // importance weight (1–3) as per McAleese’s scoring
+  positions: number[];        // global syllable indices involved in this key stress
+
+}
+
+/** Result of scansion for a single line */
+export interface ScansionResult {
+  meter: MetreName | 'free verse';       // identified metre, or free verse if below threshold
+  scansion: string;                      // the foot‑delimited scansion string, e.g., "ws|ws|ws|ws|ws"
+  certainty: number;                     // percentage of maximum possible weighted score
+  weightScore: number;                   // actual accumulated weight
+  maxPossibleWeight: number;             // theoretical maximum weight for the line
+  algorithm?: string;                    // optional, to distinguish Phonological vs Scandroid results
+}
+
+/** One candidate meter's overall fit score (internal composite, not a probability) */
+export interface MeterScore {
+  meter: MetreName | 'free verse';
+  score: number;       // scoreMeters' finalScore — a relative fit score, higher = better
+}
+
+/** Detailed phonological scansion for a single line */
+export interface PhonologicalScansionDetail {
+  all: string;          // hierarchical string, e.g. "<{[nm/ws\n]}mn/sw\]m]}>"
+  keyStresses: string;  // key‑stress string, e.g. "<{[xx/ws\n]}xx/sw\]m]}>"
+  meter: string;        // e.g. "iambic pentameter"
+  meterName: MetreName | 'free verse'; // enum value for tests
+  footCount: number;    // e.g. 5
+  summary: string;      // e.g. "IU=1 PP=1 PW=1" counts per metre direction
+  scansion: string;     // foot‑separated, e.g. "xx/ws|nx/xs/wm"
+  certainty: number;    // 0‑100
+  weightScore: number;
+  maxPossibleWeight: number;
+  ranking?: MeterScore[]; // candidate meters ranked by fit score (best first); optional
+  consensusMeter?: string; // set by applyStanzaConsensus when this line's standalone meter
+                           // diverges from, yet closely fits, the stanza's dominant meter.
+                           // The continuity-rename pass (index.ts) then normally CONVERTS
+                           // this annotation: the line adopts the dominant meter as its BASE
+                           // reading (meter/scansion/footCount/certainty re-fitted under it),
+                           // consensusMeter is cleared, and standaloneMeter records the
+                           // numerically-best standalone reading.  consensusMeter survives
+                           // only when the forced re-fit fails.
+  standaloneMeter?: string; // the line's numerically best standalone meter (e.g. "dactylic
+                           // tetrameter"), kept when stanza/poem continuity renamed the base
+                           // reading to the dominant meter.
+  rhythmNote?: string;     // non-classical rhythm classification (Russian-metrics taxonomy):
+                           // "4-ictus dolnik", "3-ictus taktovik", "4-beat accentual",
+                           // "alternating 4·3-ictus accentual" — set at stanza level when
+                           // beat counts are regular but syllable counts vary and no
+                           // classical meter dominates; or per-line to refine a free-verse
+                           // reading.  NOT a form verdict: "ballad" etc. belong to the
+                           // rhyme-aware form layer (rhyme.ts).
+  rhyme?: {                // end-rhyme annotation (rhyme.ts), LYRICAL-compatible typology
+    endWord: string;
+    letter: string;        // scheme letter 'A'/'B'/…, or '·' when unrhymed
+    type?: string;         // perfect/rich/family/assonant/consonant/augmented/
+                           // diminished/wrenched/eye/identical
+    matchedLine?: number;  // 0-based stanza line this one rhymes with
+  };
+  formNote?: string;       // stanza/poem FORM verdict (rhyme-aware): "ballad stanza
+                           // (ABCB, 4·3)", "blank verse", "Shakespearean Sonnet",
+                           // "terza rima (ABA BCB CDC…)", "limerick"…
+}
+
+/** Complete per‑line result from the pipeline */
+export interface LineResult {
+  sentence: ClsSentence;                 // parsed sentence with words, dependencies, nodes
+  phonologicalHierarchy: IntonationalUnit[]; // CP/PP/IU structure
+  keyStresses: KeyStress[];              // extracted key patterns with weights
+  phonologicalScansion: PhonologicalScansionDetail;  // scansion via phonological scoring
+  scandroidCorral?: ScansionResult;      // optional, scansion via Scandroid's 'Corral the Weird'
+  scandroidMaximise?: ScansionResult;    // optional, scansion via Scandroid's 'Maximise the Normal'
+}
+
+// ─── Display formatting types ──────────────────────────────────────
+
+/** Per-syllable information for display rendering */
+export interface SyllableDisplayEntry {
+  wordText: string;
+  sylText: string;             // orthographic text of this syllable
+  sylIndex: number;           // 0‑based index within the word
+  sylCount: number;           // total syllables in the word
+  relativeStress: StressLevel;
+  globalIndex: number;
+  wordIndex: number;          // 0‑based index among non-punctuation words
+}
+
+/** A single foot in the display, mapping scansion pattern to its syllables */
+export interface FootDisplayEntry {
+  footIndex: number;
+  footPattern: string;        // raw foot pattern from scansion, e.g., 'ws', '-ms'
+  syllables: SyllableDisplayEntry[];
+}
+
+/** All formatted display representations for a single line */
+export interface FormattedDisplay {
+  originalText: string;
+  diacriticText: string;
+  uppercaseText: string;
+  ansiText: string;
+  sylColoredText: string;
+  footAligned: string;
+  syllableBreakdown: string;
+}
+
+/** Options controlling display formatting */
+export interface DisplayOptions {
+  ansi: boolean;
+  diacritics: boolean;
+  footAligned: boolean;
+  verbose: boolean;
+  phrasal: boolean;
+}