glost-dialogue

Dialogue and conversation support for GLOST documents with turn-based structure and gender variants.

Features

• Turn-based dialogue structure - Explicit turns vs sentence-level speaker attribution
• Gender variant support - Parse and apply gender-specific text variants (e.g., Thai ครับ/ค่ะ)
• Cultural notes - Embedded cultural context within dialogues
• Upstream compatibility - Bidirectional conversion with flat dialogue format
• Type-safe - Full TypeScript support with strict typing

Installation

pnpm add glost-dialogue glost-core

Usage

Creating a dialogue

import {
  createDialogueRoot,
  createDialogueTurn,
  createCulturalNote,
} from "glost-dialogue";

const dialogue = createDialogueRoot({
  lang: "th-TH",
  script: "thai",
  participants: [
    { id: "me", gender: "masculine" },
    { id: "other", name: "Friend", gender: "feminine" }
  ],
  children: [
    createDialogueTurn({
      speakerId: "me",
      text: "สวัสดี{ครับ|ค่ะ}",
      lang: "th-TH",
      script: "thai"
    }),
    createDialogueTurn({
      speakerId: "other",
      text: "สวัสดีค่ะ",
      lang: "th-TH",
      script: "thai"
    })
  ],
  culturalNotes: [
    createCulturalNote({
      content: "In Thai, ครับ is used by male speakers and ค่ะ by female speakers",
      topics: ["politeness", "gender"]
    })
  ]
});

Gender variants

Gender variants allow you to write text once with markers for gender-specific particles:

import { parseGenderVariants, applyGender } from "glost-dialogue";

const text = "สวัสดี{ครับ|ค่ะ}";
const variants = parseGenderVariants(text);
// {
//   hasVariants: true,
//   masculine: "สวัสดีครับ",
//   feminine: "สวัสดีค่ะ"
// }

const masculine = applyGender(text, "masculine"); // "สวัสดีครับ"
const feminine = applyGender(text, "feminine");   // "สวัสดีค่ะ"

Working with upstream format

Convert between turn-based and flat (upstream) formats:

import {
  toUpstreamDialogue,
  fromUpstreamDialogue,
} from "glost-dialogue";

// Convert to upstream flat format
const flatDialogue = toUpstreamDialogue(turnBasedDialogue);

// Convert from upstream format
const turnBased = fromUpstreamDialogue(flatDialogue);

API

Types

• GLOSTDialogueRoot - Root node for a complete dialogue
• GLOSTDialogueTurn - Single speaker's utterance
• GLOSTCulturalNote - Cultural note node
• DialogueParticipant - Participant with gender and metadata
• GenderVariants - Gender-specific text variants

Builders

• createDialogueRoot(options) - Create a dialogue root
• createDialogueTurn(options) - Create a dialogue turn
• createCulturalNote(options) - Create a cultural note

Utilities

• addTurn(dialogue, turn) - Add a turn (immutable)
• addParticipant(dialogue, participant) - Add a participant (immutable)
• addCulturalNote(dialogue, note) - Add a cultural note (immutable)
• getTurnsBySpeaker(dialogue, speakerId) - Get turns by speaker
• getParticipant(dialogue, speakerId) - Get participant by ID
• getTurnCount(dialogue) - Get total turn count
• getSpeakerIds(dialogue) - Get unique speaker IDs

Gender Variant Utilities

• parseGenderVariants(text) - Parse gender variants from text
• applyGender(text, gender) - Apply gender to text with variants

Adapters

• toUpstreamDialogue(dialogue) - Convert to upstream flat format
• fromUpstreamDialogue(dialogue) - Convert from upstream format
• toUpstreamParticipant(participant) - Convert participant to upstream
• fromUpstreamParticipant(participant) - Convert participant from upstream

Architecture

This package extends the upstream glost-dialogue package with:

1. Turn-based structure - Explicit GLOSTDialogueTurn nodes instead of sentence-level speaker attribution
2. Gender variants - Parse and apply gender-specific text (e.g., Thai polite particles)
3. Cultural notes - Embedded cultural context nodes
4. Extended participant metadata - Formality, relationship, and more specific gender types

The upstream flat format is still supported via adapters for interoperability.

License

MIT