marlarky 1.0.0

package/examples/basic-usage.ts

@@ -0,0 +1,48 @@
+/**
+ * Example A: Basic Usage (No Lexicon)
+ * Demonstrates text generation using only the built-in word lists
+ */
+
+import { TextGenerator, SimpleFakerAdapter } from '../src';
+
+// Create a generator with just the simple faker adapter
+const generator = new TextGenerator({
+  fakerAdapter: new SimpleFakerAdapter(),
+});
+
+// Set a seed for reproducible output
+generator.setSeed(42);
+
+console.log('=== Basic Text Generation (No Lexicon) ===\n');
+
+// Generate a single sentence
+console.log('Single sentence:');
+console.log(generator.sentence());
+console.log();
+
+// Generate different sentence types
+console.log('Different sentence types:');
+console.log('Simple declarative:', generator.sentence({ type: 'simpleDeclarative' }));
+console.log('Question:', generator.sentence({ type: 'question' }));
+console.log('Compound:', generator.sentence({ type: 'compound' }));
+console.log('With intro adverbial:', generator.sentence({ type: 'introAdverbial' }));
+console.log();
+
+// Generate a paragraph
+console.log('Paragraph (5 sentences):');
+console.log(generator.paragraph({ sentences: 5 }));
+console.log();
+
+// Generate multiple paragraphs
+console.log('Text block (2 paragraphs):');
+console.log(generator.textBlock({ paragraphs: 2 }));
+console.log();
+
+// Demonstrate determinism
+console.log('=== Determinism Test ===\n');
+generator.setSeed(12345);
+const text1 = generator.sentence();
+generator.setSeed(12345);
+const text2 = generator.sentence();
+console.log('Same seed produces same output:', text1 === text2);
+console.log('Output:', text1);

package/examples/corporate-lexicon.ts

@@ -0,0 +1,71 @@
+/**
+ * Example B: Lexicon-Steered Corporate Text
+ * Demonstrates text generation using a corporate lexicon
+ */
+
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { TextGenerator, SimpleFakerAdapter, loadLexiconFromString } from '../src';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Load the corporate lexicon
+const lexiconPath = join(__dirname, 'lexicons', 'corporate-min.json');
+const lexiconJson = readFileSync(lexiconPath, 'utf-8');
+const lexicon = loadLexiconFromString(lexiconJson);
+
+console.log('=== Lexicon-Steered Corporate Text ===\n');
+console.log(`Loaded lexicon: ${lexicon.id} v${lexicon.version}\n`);
+
+// Create generator with lexicon
+const generator = new TextGenerator({
+  fakerAdapter: new SimpleFakerAdapter(),
+  lexicon,
+});
+
+// Set archetype to "corporate"
+generator.setArchetype('corporate');
+generator.setSeed(42);
+
+// Generate corporate sentences
+console.log('Corporate sentences:');
+for (let i = 0; i < 5; i++) {
+  console.log(`${i + 1}. ${generator.sentence()}`);
+}
+console.log();
+
+// Generate a corporate paragraph
+console.log('Corporate paragraph:');
+console.log(generator.paragraph({ sentences: 4 }));
+console.log();
+
+// Generate corporate text block
+console.log('Corporate text block (3 paragraphs):');
+console.log(generator.textBlock({ paragraphs: 3 }));
+console.log();
+
+// Compare with non-lexicon output
+console.log('=== Comparison: With vs Without Lexicon ===\n');
+
+const withLexicon = new TextGenerator({
+  fakerAdapter: new SimpleFakerAdapter(),
+  lexicon,
+});
+withLexicon.setArchetype('corporate');
+withLexicon.setSeed(100);
+
+const withoutLexicon = new TextGenerator({
+  fakerAdapter: new SimpleFakerAdapter(),
+});
+withoutLexicon.setSeed(100);
+
+console.log('With corporate lexicon:');
+for (let i = 0; i < 3; i++) {
+  console.log(`  ${withLexicon.sentence()}`);
+}
+
+console.log('\nWithout lexicon (same seed):');
+for (let i = 0; i < 3; i++) {
+  console.log(`  ${withoutLexicon.sentence()}`);
+}

package/examples/lexicons/corporate-min.json

@@ -0,0 +1,200 @@
+{
+  "id": "lexicon.corporate.min",
+  "version": "1.0.0",
+  "language": "en",
+  "termSets": {
+    "noun.business": {
+      "pos": "noun",
+      "tags": ["domain:business", "register:formal"],
+      "terms": [
+        { "value": "strategy", "weight": 5 },
+        { "value": "initiative", "weight": 4 },
+        { "value": "stakeholder", "weight": 4 },
+        { "value": "synergy", "weight": 3 },
+        { "value": "deliverable", "weight": 3 },
+        { "value": "benchmark", "weight": 3 },
+        { "value": "pipeline", "weight": 2 },
+        { "value": "bandwidth", "weight": 2 },
+        { "value": "ecosystem", "weight": 2 },
+        { "value": "leverage", "weight": 2 }
+      ]
+    },
+    "noun.meeting": {
+      "pos": "noun",
+      "tags": ["domain:business"],
+      "terms": [
+        { "value": "meeting", "weight": 5 },
+        { "value": "conference", "weight": 3 },
+        { "value": "summit", "weight": 2 },
+        { "value": "workshop", "weight": 3 },
+        { "value": "briefing", "weight": 2 },
+        { "value": "presentation", "weight": 4 },
+        { "value": "discussion", "weight": 3 }
+      ]
+    },
+    "verb.business": {
+      "pos": "verb",
+      "tags": ["domain:business"],
+      "terms": [
+        { "value": "leverage", "weight": 4 },
+        { "value": "optimize", "weight": 4 },
+        { "value": "streamline", "weight": 3 },
+        { "value": "synergize", "weight": 2 },
+        { "value": "facilitate", "weight": 3 },
+        { "value": "implement", "weight": 5 },
+        { "value": "execute", "weight": 4 },
+        { "value": "deliver", "weight": 4 },
+        { "value": "align", "weight": 3 },
+        { "value": "prioritize", "weight": 3 }
+      ]
+    },
+    "verb.meeting": {
+      "pos": "verb",
+      "tags": ["domain:business"],
+      "terms": [
+        { "value": "schedule", "weight": 4 },
+        { "value": "convene", "weight": 2 },
+        { "value": "adjourn", "weight": 2 },
+        { "value": "attend", "weight": 4 },
+        { "value": "organize", "weight": 3 },
+        { "value": "chair", "weight": 2 }
+      ]
+    },
+    "adj.business": {
+      "pos": "adj",
+      "tags": ["domain:business", "register:formal"],
+      "terms": [
+        { "value": "strategic", "weight": 5 },
+        { "value": "proactive", "weight": 4 },
+        { "value": "scalable", "weight": 3 },
+        { "value": "robust", "weight": 3 },
+        { "value": "agile", "weight": 4 },
+        { "value": "sustainable", "weight": 3 },
+        { "value": "innovative", "weight": 4 },
+        { "value": "competitive", "weight": 3 },
+        { "value": "dynamic", "weight": 3 },
+        { "value": "holistic", "weight": 2 }
+      ]
+    },
+    "adv.business": {
+      "pos": "adv",
+      "tags": ["domain:business"],
+      "terms": [
+        { "value": "strategically", "weight": 4 },
+        { "value": "proactively", "weight": 3 },
+        { "value": "effectively", "weight": 5 },
+        { "value": "efficiently", "weight": 4 },
+        { "value": "seamlessly", "weight": 3 },
+        { "value": "holistically", "weight": 2 },
+        { "value": "comprehensively", "weight": 3 }
+      ]
+    },
+    "prep.business": {
+      "pos": "prep",
+      "tags": ["domain:business"],
+      "terms": [
+        { "value": "regarding", "weight": 3 },
+        { "value": "concerning", "weight": 2 },
+        { "value": "throughout", "weight": 3 },
+        { "value": "within", "weight": 4 },
+        { "value": "across", "weight": 4 }
+      ]
+    },
+    "intj.formal": {
+      "pos": "intj",
+      "tags": ["register:formal"],
+      "terms": [
+        { "value": "indeed", "weight": 4 },
+        { "value": "certainly", "weight": 4 },
+        { "value": "naturally", "weight": 3 },
+        { "value": "accordingly", "weight": 2 },
+        { "value": "importantly", "weight": 3 }
+      ]
+    }
+  },
+  "patterns": {
+    "sentence.corporate": {
+      "type": "sentence",
+      "slots": ["NP", "VP", "PUNCT"],
+      "tags": ["domain:business"],
+      "weight": 2
+    }
+  },
+  "distributions": {
+    "sentenceTypes.corporate": [
+      { "key": "simpleDeclarative", "weight": 50 },
+      { "key": "compound", "weight": 20 },
+      { "key": "introAdverbial", "weight": 15 },
+      { "key": "subordinate", "weight": 12 },
+      { "key": "interjection", "weight": 2 },
+      { "key": "question", "weight": 1 }
+    ],
+    "termSetBias.domain:business": [
+      { "key": "noun.business", "weight": 10 },
+      { "key": "noun.meeting", "weight": 5 },
+      { "key": "verb.business", "weight": 8 },
+      { "key": "verb.meeting", "weight": 4 },
+      { "key": "adj.business", "weight": 8 },
+      { "key": "adv.business", "weight": 5 }
+    ]
+  },
+  "correlations": [
+    {
+      "when": { "chosenTermSet": "noun.business" },
+      "thenBoost": [
+        { "termSet": "verb.business", "weightDelta": 5 },
+        { "termSet": "adj.business", "weightDelta": 3 }
+      ],
+      "scope": "sentence"
+    },
+    {
+      "when": { "chosenTermSet": "noun.meeting" },
+      "thenBoost": [
+        { "termSet": "verb.meeting", "weightDelta": 5 }
+      ],
+      "scope": "sentence"
+    }
+  ],
+  "constraints": [
+    {
+      "id": "c.noRepeatNoun",
+      "level": "hard",
+      "scope": "sentence",
+      "type": "noRepeat",
+      "target": "pos:noun"
+    },
+    {
+      "id": "c.maxPP",
+      "level": "hard",
+      "scope": "phrase",
+      "type": "maxCount",
+      "target": "PP",
+      "value": 2
+    }
+  ],
+  "invariants": [
+    { "id": "inv.capitalized", "type": "capitalization", "scope": "sentence" },
+    { "id": "inv.endsWithPunct", "type": "punctuation", "scope": "sentence" },
+    { "id": "inv.noDoubleSpaces", "type": "whitespace", "scope": "text" }
+  ],
+  "archetypes": {
+    "corporate": {
+      "tags": ["register:formal", "domain:business"],
+      "distributions": {
+        "sentenceTypes": "sentenceTypes.corporate",
+        "termSetBias": "termSetBias.domain:business"
+      },
+      "overrides": {
+        "interjectionRate": 0.02,
+        "subordinateClauseRate": 0.12,
+        "questionRate": 0.01
+      }
+    }
+  },
+  "relations": [
+    { "from": "strategy", "type": "hasPart", "to": "initiative", "weight": 3 },
+    { "from": "initiative", "type": "requires", "to": "stakeholder", "weight": 2 },
+    { "from": "meeting", "type": "produces", "to": "deliverable", "weight": 2 },
+    { "from": "synergy", "type": "enables", "to": "leverage", "weight": 2 }
+  ]
+}

package/examples/with-tracing.ts

@@ -0,0 +1,85 @@
+/**
+ * Example C: Generation with Tracing
+ * Demonstrates the tracing/metadata output feature
+ */
+
+import { TextGenerator, SimpleFakerAdapter, GeneratedText } from '../src';
+
+// Create generator with tracing enabled
+const generator = new TextGenerator({
+  fakerAdapter: new SimpleFakerAdapter(),
+  enableTrace: true,
+});
+
+generator.setSeed(42);
+
+console.log('=== Text Generation with Tracing ===\n');
+
+// Generate a sentence with trace
+const result = generator.sentence() as GeneratedText;
+
+console.log('Generated text:', result.text);
+console.log();
+
+console.log('Metadata:');
+console.log('  Archetype:', result.meta.archetype);
+console.log('  Seed:', result.meta.seed);
+if (result.meta.lexiconId) {
+  console.log('  Lexicon ID:', result.meta.lexiconId);
+  console.log('  Lexicon Version:', result.meta.lexiconVersion);
+}
+console.log();
+
+if (result.trace) {
+  console.log('Trace:');
+  const sentence = result.trace.paragraphs[0]?.sentences[0];
+  if (sentence) {
+    console.log('  Template:', sentence.template);
+    console.log('  Retry count:', sentence.retryCount);
+    console.log('  Token count:', sentence.tokens.length);
+    console.log();
+
+    console.log('  Tokens:');
+    for (const token of sentence.tokens.slice(0, 10)) {
+      console.log(`    "${token.value}" - source: ${token.source}${token.pos ? `, pos: ${token.pos}` : ''}`);
+    }
+    if (sentence.tokens.length > 10) {
+      console.log(`    ... and ${sentence.tokens.length - 10} more tokens`);
+    }
+    console.log();
+
+    console.log('  Constraints evaluated:');
+    for (const c of sentence.constraintsEvaluated) {
+      console.log(`    ${c.id}: ${c.passed ? 'PASS' : 'FAIL'}`);
+    }
+  }
+
+  console.log();
+  console.log('  Invariants checked:');
+  for (const inv of result.trace.invariantsChecked) {
+    console.log(`    ${inv.id}: ${inv.passed ? 'PASS' : 'FAIL'}`);
+  }
+
+  if (result.trace.correlationsApplied.length > 0) {
+    console.log();
+    console.log('  Correlations applied:', result.trace.correlationsApplied);
+  }
+}
+
+// Generate a paragraph with trace
+console.log('\n\n=== Paragraph with Tracing ===\n');
+
+const paragraphResult = generator.paragraph({ sentences: 3 }) as GeneratedText;
+
+console.log('Generated text:');
+console.log(paragraphResult.text);
+console.log();
+
+if (paragraphResult.trace) {
+  const sentences = paragraphResult.trace.paragraphs[0]?.sentences || [];
+  console.log(`Trace: ${sentences.length} sentences`);
+  for (let i = 0; i < sentences.length; i++) {
+    const s = sentences[i]!;
+    console.log(`  Sentence ${i + 1}: template=${s.template}, tokens=${s.tokens.length}, retries=${s.retryCount}`);
+  }
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "marlarky",
+  "version": "1.0.0",
+  "description": "Marlarky - A faker-like library for generating syntactically plausible English text",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "marlarky": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./cli": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "examples"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src --ext .ts",
+    "example:basic": "tsx examples/basic-usage.ts",
+    "example:corporate": "tsx examples/corporate-lexicon.ts",
+    "cli": "node dist/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "faker",
+    "text-generation",
+    "english",
+    "nlp",
+    "lexicon",
+    "syntax",
+    "grammar",
+    "pig-latin",
+    "ubbidubbi",
+    "leetspeak",
+    "pirate-speak",
+    "redaction",
+    "emoji",
+    "mock-case",
+    "reverse-words",
+    "biz-jargon"
+  ],
+  "author": "JPaulDuncan <jpaulduncan@gmail.com> (https://github.com/jpaulduncan)",
+  "license": "MIT",
+  "devDependencies": {
+    "@faker-js/faker": "^9.0.0",
+    "@types/node": "^22.0.0",
+    "eslint": "^9.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "peerDependencies": {
+    "@faker-js/faker": ">=8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@faker-js/faker": {
+      "optional": true
+    }
+  }
+}