@forwardimpact/libsyntheticgen 0.1.1

package/engine/entities.js

@@ -0,0 +1,144 @@
+/**
+ * Entity generation — builds orgs, departments, teams, people, projects.
+ *
+ * @module libuniverse/engine/entities
+ */
+
+import {
+  GREEK_NAMES,
+  MANAGER_NAMES,
+  toGithubUsername,
+  toEmail,
+} from "./names.js";
+
+/**
+ * Build all entities from AST and RNG.
+ * @param {import('../dsl/parser.js').UniverseAST} ast
+ * @param {import('./rng.js').SeededRNG} rng
+ * @returns {{ orgs: object[], departments: object[], teams: object[], people: object[], projects: object[] }}
+ */
+export function buildEntities(ast, rng) {
+  const domain = ast.domain;
+  const orgs = ast.orgs.map((o) => ({
+    ...o,
+    iri: `https://${domain}/org/${o.id}`,
+  }));
+  const departments = ast.departments.map((d) => ({
+    ...d,
+    iri: `https://${domain}/department/${d.id}`,
+  }));
+  const teams = ast.teams.map((t) => ({
+    ...t,
+    repos: t.repos || [],
+    iri: `https://${domain}/team/${t.id}`,
+    getdx_team_id: `gdx_team_${t.id}`,
+  }));
+  const people = generatePeople(ast, rng, teams, domain);
+  const projects = ast.projects.map((p) => ({
+    ...p,
+    teams: p.teams || [],
+    phase: p.phase || null,
+    prose_topic: p.prose_topic || null,
+    prose_tone: p.prose_tone || null,
+    iri: `https://${domain}/project/${p.id}`,
+  }));
+
+  return { orgs, departments, teams, people, projects };
+}
+
+function generatePeople(ast, rng, teams, domain) {
+  const { count, distribution, disciplines } = ast.people;
+  const people = [];
+  const usedNames = new Set();
+
+  // Reserve manager names
+  const managerAssignments = new Map();
+  for (const team of teams) {
+    if (team.manager) {
+      const name = MANAGER_NAMES[team.manager] || team.manager;
+      managerAssignments.set(team.id, name);
+      usedNames.add(name);
+    }
+  }
+
+  const levelKeys = Object.keys(distribution);
+  const levelWeights = Object.values(distribution);
+  const discKeys = Object.keys(disciplines);
+  const discWeights = Object.values(disciplines);
+  const available = rng.shuffle(GREEK_NAMES.filter((n) => !usedNames.has(n)));
+
+  // Create managers
+  for (const team of teams) {
+    if (!team.manager) continue;
+    const name = managerAssignments.get(team.id);
+    people.push(
+      makePerson(
+        name,
+        rng.pick(["L3", "L4", "L5"]),
+        discKeys[rng.weightedPick(discWeights)] || "software_engineering",
+        team,
+        domain,
+        true,
+        null,
+      ),
+    );
+  }
+
+  // Fill remaining people
+  let idx = 0;
+  while (people.length < count && idx < available.length) {
+    const name = available[idx++];
+    const level = levelKeys[rng.weightedPick(levelWeights)];
+    const disc = discKeys[rng.weightedPick(discWeights)];
+    const team = rng.pick(teams);
+    const mgr = people.find((p) => p.is_manager && p.team_id === team.id);
+    people.push(
+      makePerson(
+        name,
+        level,
+        disc,
+        team,
+        domain,
+        false,
+        mgr?.email || null,
+        `2023-${pad2(rng.randomInt(1, 12))}-${pad2(rng.randomInt(1, 28))}`,
+      ),
+    );
+  }
+
+  return people;
+}
+
+function makePerson(
+  name,
+  level,
+  discipline,
+  team,
+  domain,
+  isManager,
+  managerEmail,
+  hireDate = "2023-01-15",
+) {
+  const id = name.toLowerCase().replace(/\s+/g, "-");
+  return {
+    id,
+    name,
+    email: toEmail(name, domain),
+    github: toGithubUsername(name),
+    github_username: toGithubUsername(name),
+    discipline,
+    level,
+    track: null,
+    team_id: team.id,
+    department: team.department,
+    is_manager: isManager,
+    manager_email: managerEmail,
+    hire_date: hireDate,
+    iri: `https://${domain}/person/${id}`,
+  };
+}
+
+/** @param {number} n */
+function pad2(n) {
+  return String(n).padStart(2, "0");
+}

package/engine/names.js

@@ -0,0 +1,290 @@
+/**
+ * Greek mythology name pool for synthetic people generation.
+ * Names are deterministically assigned based on seed order.
+ */
+
+export const GREEK_NAMES = [
+  // Olympians and major deities
+  "Zeus",
+  "Hera",
+  "Poseidon",
+  "Demeter",
+  "Athena",
+  "Apollo",
+  "Artemis",
+  "Ares",
+  "Aphrodite",
+  "Hephaestus",
+  "Hermes",
+  "Dionysus",
+  "Hades",
+  "Persephone",
+  "Hestia",
+  // Titans
+  "Prometheus",
+  "Epimetheus",
+  "Atlas",
+  "Cronus",
+  "Rhea",
+  "Hyperion",
+  "Theia",
+  "Coeus",
+  "Phoebe",
+  "Oceanus",
+  "Tethys",
+  "Mnemosyne",
+  "Themis",
+  "Crius",
+  "Iapetus",
+  // Heroes and mortals
+  "Achilles",
+  "Odysseus",
+  "Perseus",
+  "Heracles",
+  "Theseus",
+  "Jason",
+  "Orpheus",
+  "Atalanta",
+  "Bellerophon",
+  "Cadmus",
+  "Daedalus",
+  "Icarus",
+  "Minos",
+  "Ariadne",
+  "Andromeda",
+  "Antigone",
+  "Electra",
+  "Medea",
+  "Penelope",
+  "Telemachus",
+  "Nestor",
+  "Ajax",
+  "Agamemnon",
+  "Menelaus",
+  "Helen",
+  "Paris",
+  "Hector",
+  "Priam",
+  "Cassandra",
+  "Hecuba",
+  // Lesser deities and spirits
+  "Nike",
+  "Iris",
+  "Eros",
+  "Psyche",
+  "Tyche",
+  "Nemesis",
+  "Hecate",
+  "Selene",
+  "Eos",
+  "Helios",
+  "Pan",
+  "Triton",
+  "Proteus",
+  "Nereus",
+  "Amphitrite",
+  "Galatea",
+  "Thetis",
+  "Calliope",
+  "Clio",
+  "Erato",
+  "Euterpe",
+  "Melpomene",
+  "Polyhymnia",
+  "Terpsichore",
+  "Thalia",
+  "Urania",
+  // Physicians and wisdom
+  "Asclepius",
+  "Hygieia",
+  "Panacea",
+  "Chiron",
+  "Metis",
+  // Egyptian-Greek crossover (Thoth)
+  "Thoth",
+  "Chronos",
+  "Astraea",
+  "Plutus",
+  // More heroes and mythological
+  "Patroclus",
+  "Diomedes",
+  "Philoctetes",
+  "Pyrrhus",
+  "Aeneas",
+  "Deucalion",
+  "Pyrrha",
+  "Ganymede",
+  "Endymion",
+  "Narcissus",
+  "Echo",
+  "Adonis",
+  "Actaeon",
+  "Orion",
+  "Callisto",
+  "Io",
+  "Europa",
+  "Leda",
+  "Danae",
+  "Semele",
+  "Alcmene",
+  "Amphion",
+  "Zethus",
+  "Castor",
+  "Pollux",
+  "Clytemnestra",
+  "Iphigenia",
+  "Aegisthus",
+  "Pylades",
+  "Hermione",
+  "Neoptolemus",
+  "Astyanax",
+  "Polyxena",
+  "Briseis",
+  "Chryseis",
+  // Argonauts and companions
+  "Peleus",
+  "Teucer",
+  "Idomeneus",
+  "Meriones",
+  "Machaon",
+  "Podalirius",
+  "Antilochus",
+  "Eurypylus",
+  "Thrasymedes",
+  "Peisistratus",
+  // Mythological creatures (personified)
+  "Sphinx",
+  "Phoenix",
+  "Griffin",
+  "Pegasus",
+  "Cerberus",
+  // More names for 211 people
+  "Laertes",
+  "Autolycus",
+  "Sisyphus",
+  "Tantalus",
+  "Pelops",
+  "Atreus",
+  "Thyestes",
+  "Aegeus",
+  "Medus",
+  "Circe",
+  "Calypso",
+  "Nausicaa",
+  "Alcinous",
+  "Arete",
+  "Eumaeus",
+  "Philoetius",
+  "Melanthius",
+  "Eurycleia",
+  "Mentor",
+  "Halitherses",
+  "Tiresias",
+  "Polyphemus",
+  "Aeolus",
+  "Scylla",
+  "Charybdis",
+  "Leucothea",
+  "Phaeacian",
+  "Antiope",
+  "Hippolyta",
+  "Phaedra",
+  "Procris",
+  "Cephalus",
+  "Meleager",
+  "Althaea",
+  "Oeneus",
+  "Tydeus",
+  "Capaneus",
+  "Hippomedon",
+  "Parthenopaeus",
+  "Adrastus",
+  "Polynices",
+  "Eteocles",
+  "Ismene",
+  "Haemon",
+  "Eurydice",
+  "Creon",
+  "Jocasta",
+  "Laius",
+  "Oedipus",
+  "Chrysippus",
+  "Niobe",
+  "Amphion2",
+  "Leto",
+  "Asteria",
+  "Hecate2",
+  "Perses",
+  "Pallas",
+  "Styx",
+  "Zelus",
+  "Kratos",
+  "Bia",
+  "Boreas",
+  "Zephyrus",
+  "Notus",
+  "Eurus",
+  "Aether",
+  "Hemera",
+  "Nyx",
+  "Erebus",
+  "Gaia",
+  "Uranus",
+  "Pontus",
+  "Tartarus",
+  "Ananke",
+  "Chronos2",
+  "Phanes",
+  "Thalassa",
+  "Ourea",
+  "Nesoi",
+  "Achelous",
+];
+
+/**
+ * Stable manager name lookup (used for @references in DSL).
+ * Maps DSL @name to a canonical full name.
+ */
+export const MANAGER_NAMES = {
+  thoth: "Thoth",
+  chronos: "Chronos",
+  apollo: "Apollo",
+  hygieia: "Hygieia",
+  themis: "Themis",
+  athena: "Athena",
+  prometheus: "Prometheus",
+  hephaestus: "Hephaestus",
+  ares: "Ares",
+  hermes: "Hermes",
+  iris: "Iris",
+  demeter: "Demeter",
+  astraea: "Astraea",
+  tyche: "Tyche",
+  daedalus: "Daedalus",
+  asclepius: "Asclepius",
+  plutus: "Plutus",
+  aphrodite: "Aphrodite",
+  artemis: "Artemis",
+  hestia: "Hestia",
+  metis: "Metis",
+};
+
+/**
+ * Get a GitHub username from a person name.
+ * @param {string} name
+ * @param {string} domain - organization domain
+ * @returns {string}
+ */
+export function toGithubUsername(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]/g, "") + "-bio";
+}
+
+/**
+ * Get an email from a person name.
+ * @param {string} name
+ * @param {string} domain
+ * @returns {string}
+ */
+export function toEmail(name, domain) {
+  return `${name.toLowerCase().replace(/[^a-z0-9]/g, "")}@${domain}`;
+}

package/engine/prose-keys.js

@@ -0,0 +1,182 @@
+/**
+ * Prose Keys — collects all keys that need LLM-generated prose.
+ *
+ * Each key maps to a context object that guides the LLM prompt.
+ */
+
+/**
+ * Collect all prose keys from the entity graph.
+ * @param {object} entities - Generated entity graph from tier0
+ * @returns {Map<string, object>} key → context for prose generation
+ */
+export function collectProseKeys(entities) {
+  const keys = new Map();
+
+  // Organization README prose
+  keys.set("org_readme", {
+    topic: `${entities.orgs[0]?.name || "BioNova"} company overview`,
+    tone: "corporate, informative",
+    length: "3-4 paragraphs",
+    domain: entities.domain,
+  });
+
+  // Project descriptions
+  for (const proj of entities.projects) {
+    if (proj.prose_topic) {
+      keys.set(`project_${proj.id}`, {
+        topic: proj.prose_topic,
+        tone: proj.prose_tone || "technical",
+        length: "2-3 paragraphs",
+        domain: entities.domain,
+      });
+    }
+  }
+
+  // HTML content — articles
+  const guideContent = entities.content.find((c) => c.id === "guide_html");
+  if (guideContent) {
+    for (const topic of guideContent.article_topics || []) {
+      keys.set(`article_${topic}`, {
+        topic: `${topic.replace(/_/g, " ")} in pharmaceutical industry`,
+        tone: "technical, informative",
+        length: "6-8 paragraphs",
+        domain: entities.domain,
+      });
+    }
+
+    // Blog posts
+    for (let i = 0; i < (guideContent.blogs || 0); i++) {
+      keys.set(`blog_${i}`, {
+        topic: "pharmaceutical engineering blog post",
+        tone: "conversational, technical",
+        length: "4-5 paragraphs",
+        domain: entities.domain,
+      });
+    }
+
+    // FAQs
+    for (let i = 0; i < (guideContent.faqs || 0); i++) {
+      keys.set(`faq_${i}`, {
+        topic: "pharmaceutical engineering FAQ",
+        tone: "helpful, concise",
+        length: "1 paragraph",
+        domain: entities.domain,
+      });
+    }
+
+    // HowTos
+    for (const topic of guideContent.howto_topics || []) {
+      keys.set(`howto_${topic}`, {
+        topic: `how-to guide for ${topic.replace(/_/g, " ")}`,
+        tone: "instructional",
+        length: "5-6 paragraphs",
+        domain: entities.domain,
+      });
+    }
+
+    // Reviews
+    for (let i = 0; i < (guideContent.reviews || 0); i++) {
+      keys.set(`review_${i}`, {
+        topic: "peer review comment on engineering work",
+        tone: "professional, constructive",
+        length: "1-2 sentences",
+        maxTokens: 100,
+        domain: entities.domain,
+      });
+    }
+
+    // Comments
+    for (let i = 0; i < (guideContent.comments || 0); i++) {
+      keys.set(`comment_${i}`, {
+        topic: "discussion comment on engineering topic",
+        tone: "casual, technical",
+        length: "1-2 sentences",
+        maxTokens: 80,
+        domain: entities.domain,
+      });
+    }
+  }
+
+  // Basecamp personas
+  const basecampContent = entities.content.find(
+    (c) => c.id === "basecamp_markdown",
+  );
+  if (basecampContent) {
+    const personas = selectPersonaNames(entities, basecampContent);
+    for (const persona of personas) {
+      // Briefings
+      for (let i = 0; i < (basecampContent.briefings_per_persona || 0); i++) {
+        keys.set(`briefing_${persona.name}_${i}`, {
+          topic: `daily briefing for ${persona.name}, a ${persona.level} ${persona.discipline}`,
+          tone: "professional, concise",
+          length: "2-3 paragraphs",
+          domain: entities.domain,
+          role: `${persona.level} ${persona.discipline}`,
+        });
+      }
+
+      // Notes
+      for (let i = 0; i < (basecampContent.notes_per_persona || 0); i++) {
+        keys.set(`note_${persona.name}_${i}`, {
+          topic: `engineering knowledge note by ${persona.name}`,
+          tone: "personal, technical",
+          length: "1-2 paragraphs",
+          domain: entities.domain,
+          role: `${persona.level} ${persona.discipline}`,
+        });
+      }
+    }
+  }
+
+  // Snapshot comments (GetDX engineer voice)
+  if (entities.activity?.commentKeys) {
+    for (const ck of entities.activity.commentKeys) {
+      const direction =
+        ck.trajectory === "declining" ? "declining" : "improving";
+      keys.set(
+        `snapshot_comment_${ck.snapshot_id}_${ck.email.replace(/[@.]/g, "_")}`,
+        {
+          topic: `GetDX snapshot survey comment about ${ck.driver_name.toLowerCase()}`,
+          tone: "authentic, first-person developer voice",
+          length: "1-2 sentences",
+          maxTokens: 80,
+          domain: entities.domain,
+          role: `${ck.person_level} ${ck.person_discipline.replace(/_/g, " ")} on the ${ck.team_name}`,
+          scenario: ck.scenario_name,
+          driver: ck.driver_name,
+          direction,
+          magnitude: ck.magnitude,
+        },
+      );
+    }
+  }
+
+  return keys;
+}
+
+/**
+ * Select persona representatives from people.
+ */
+function selectPersonaNames(entities, basecampContent) {
+  const levels = basecampContent.persona_levels || [
+    "L1",
+    "L2",
+    "L3",
+    "L4",
+    "L5",
+  ];
+  const personas = [];
+  for (const level of levels) {
+    const person = entities.people.find((p) => p.level === level);
+    if (person) {
+      personas.push({
+        name: person.name,
+        level: person.level,
+        discipline: person.discipline,
+        email: person.email,
+        team_id: person.team_id,
+      });
+    }
+  }
+  return personas;
+}

package/engine/rng.js

@@ -0,0 +1,43 @@
+import seedrandom from "seedrandom";
+
+/**
+ * Create a seeded RNG with convenience methods.
+ * @param {number|string} seed
+ * @returns {{ random: () => number, randomInt: (min: number, max: number) => number, pick: <T>(arr: T[]) => T, shuffle: <T>(arr: T[]) => T[], weightedPick: (items: Array<{weight: number}>) => number, gaussian: (mean: number, std: number) => number }}
+ */
+export function createSeededRNG(seed) {
+  const rng = seedrandom(String(seed));
+
+  const random = () => rng();
+  const randomInt = (min, max) => Math.floor(random() * (max - min + 1)) + min;
+  const pick = (arr) => arr[Math.floor(random() * arr.length)];
+
+  const shuffle = (arr) => {
+    const result = [...arr];
+    for (let i = result.length - 1; i > 0; i--) {
+      const j = Math.floor(random() * (i + 1));
+      [result[i], result[j]] = [result[j], result[i]];
+    }
+    return result;
+  };
+
+  const weightedPick = (weights) => {
+    const total = weights.reduce((s, w) => s + w, 0);
+    let r = random() * total;
+    for (let i = 0; i < weights.length; i++) {
+      r -= weights[i];
+      if (r <= 0) return i;
+    }
+    return weights.length - 1;
+  };
+
+  const gaussian = (mean, std) => {
+    const u1 = random();
+    const u2 = random();
+    const z =
+      Math.sqrt(-2 * Math.log(u1 || 1e-10)) * Math.cos(2 * Math.PI * u2);
+    return mean + z * std;
+  };
+
+  return { random, randomInt, pick, shuffle, weightedPick, gaussian };
+}

package/engine/tier0.js

@@ -0,0 +1,63 @@
+/**
+ * Tier 0 — Deterministic Entity & Activity Generation (no LLM).
+ *
+ * @module libuniverse/engine/tier0
+ */
+
+import { createSeededRNG } from "./rng.js";
+import { buildEntities } from "./entities.js";
+import { generateActivity } from "./activity.js";
+
+/**
+ * Entity generator that wraps deterministic generation from a parsed AST.
+ */
+export class EntityGenerator {
+  /**
+   * @param {Function} rngFactory - Factory function that creates a seeded RNG
+   * @param {object} logger - Logger instance
+   */
+  constructor(rngFactory, logger) {
+    if (!rngFactory) throw new Error("rngFactory is required");
+    if (!logger) throw new Error("logger is required");
+    this.rngFactory = rngFactory;
+    this.logger = logger;
+  }
+
+  /**
+   * Generate all entities and activity from a parsed AST.
+   * @param {import('../dsl/parser.js').UniverseAST} ast
+   * @returns {object} Entity graph with activity data
+   */
+  generate(ast) {
+    const rng = this.rngFactory(ast.seed);
+    const { orgs, departments, teams, people, projects } = buildEntities(
+      ast,
+      rng,
+    );
+    const activity = generateActivity(ast, rng, people, teams);
+
+    return {
+      orgs,
+      departments,
+      teams,
+      people,
+      projects,
+      scenarios: ast.scenarios,
+      snapshots: ast.snapshots,
+      framework: { ...ast.framework, seed: ast.seed },
+      content: ast.content,
+      activity,
+      domain: ast.domain,
+      industry: ast.industry,
+    };
+  }
+}
+
+/**
+ * Creates an EntityGenerator with the built-in seeded RNG factory.
+ * @param {object} logger - Logger instance
+ * @returns {EntityGenerator}
+ */
+export function createEntityGenerator(logger) {
+  return new EntityGenerator(createSeededRNG, logger);
+}