@forwardimpact/libsyntheticgen 0.1.1

package/tools/faker.js

@@ -0,0 +1,83 @@
+/**
+ * Faker tool — generates datasets using @faker-js/faker in-process.
+ */
+
+import { faker } from "@faker-js/faker";
+
+export class FakerTool {
+  /**
+   * @param {object} deps
+   * @param {object} deps.logger
+   */
+  constructor({ logger }) {
+    if (!logger) throw new Error("FakerTool requires logger");
+    this.logger = logger;
+  }
+
+  /**
+   * Faker is always available (JS dependency).
+   * @returns {Promise<boolean>}
+   */
+  async checkAvailability() {
+    return true;
+  }
+
+  /**
+   * Generate a dataset from field definitions.
+   * @param {object} config
+   * @param {string} config.name - Dataset name from DSL
+   * @param {number} config.rows - Number of records to generate
+   * @param {Object<string, string>} config.fields - Field name → Faker provider path
+   * @param {number} config.seed - RNG seed
+   * @returns {Promise<Dataset[]>}
+   */
+  async generate(config) {
+    faker.seed(config.seed);
+    this.logger.info(
+      "faker",
+      `Generating ${config.rows} rows for ${config.name}`,
+    );
+    const records = [];
+    for (let i = 0; i < config.rows; i++) {
+      const record = {};
+      for (const [field, provider] of Object.entries(config.fields)) {
+        record[field] = this.callProvider(provider);
+      }
+      records.push(record);
+    }
+    return [
+      {
+        name: config.name,
+        schema: null,
+        records,
+        metadata: { tool: "faker", fields: config.fields },
+      },
+    ];
+  }
+
+  /**
+   * Resolve a dotted provider path like "person.fullName" to a Faker call.
+   * @param {string} provider
+   * @returns {*}
+   */
+  callProvider(provider) {
+    const parts = provider.split(".");
+    let fn = faker;
+    for (const part of parts) {
+      fn = fn[part];
+      if (!fn) throw new Error(`Unknown Faker provider: ${provider}`);
+    }
+    if (typeof fn !== "function") {
+      throw new Error(`Faker provider "${provider}" is not a function`);
+    }
+    return fn();
+  }
+}
+
+/**
+ * @param {object} logger
+ * @returns {FakerTool}
+ */
+export function createFakerTool(logger) {
+  return new FakerTool({ logger });
+}

package/tools/sdv.js

@@ -0,0 +1,93 @@
+/**
+ * SDV tool — generates statistically representative tabular data via Python subprocess.
+ */
+
+import { join } from "path";
+import { tmpdir } from "os";
+import { randomUUID } from "crypto";
+
+export class SdvTool {
+  /**
+   * @param {object} deps
+   * @param {object} deps.logger
+   * @param {Function} deps.execFileFn - async (cmd, args) => { stdout }
+   * @param {object} deps.fsFns - { writeFile, rm }
+   */
+  constructor({ logger, execFileFn, fsFns }) {
+    if (!logger) throw new Error("SdvTool requires logger");
+    if (!execFileFn) throw new Error("SdvTool requires execFileFn");
+    if (!fsFns) throw new Error("SdvTool requires fsFns");
+    this.logger = logger;
+    this.execFileFn = execFileFn;
+    this.fsFns = fsFns;
+    this.scriptPath = join(import.meta.dirname, "sdv_generate.py");
+  }
+
+  /**
+   * Check that Python 3 with SDV is available.
+   * @returns {Promise<boolean>}
+   */
+  async checkAvailability() {
+    try {
+      await this.execFileFn("python3", ["-c", "import sdv"]);
+      return true;
+    } catch {
+      throw new Error(
+        "SDV requires Python 3 with the sdv package. " +
+          "Install with: pip install sdv",
+      );
+    }
+  }
+
+  /**
+   * Generate tabular data preserving statistical properties from sample data.
+   * @param {object} config
+   * @param {string} config.name - Dataset name from DSL
+   * @param {string} config.metadata - Path to SDV metadata JSON
+   * @param {Object<string, string>} config.data - Map of table name → CSV path
+   * @param {number} [config.rows=1000] - Number of rows to generate
+   * @param {number} config.seed - RNG seed
+   * @returns {Promise<Dataset[]>}
+   */
+  async generate(config) {
+    const tmpConfig = join(tmpdir(), `sdv-config-${randomUUID()}.json`);
+    await this.fsFns.writeFile(
+      tmpConfig,
+      JSON.stringify({
+        metadata: config.metadata,
+        data: config.data,
+        rows: config.rows || 1000,
+        seed: config.seed,
+      }),
+    );
+
+    this.logger.info("sdv", `Running SDV: rows=${config.rows || 1000}`);
+    const { stdout } = await this.execFileFn("python3", [
+      this.scriptPath,
+      tmpConfig,
+    ]);
+    await this.fsFns.rm(tmpConfig);
+
+    // Parse newline-delimited JSON
+    return stdout
+      .trim()
+      .split("\n")
+      .map((line) => {
+        const obj = JSON.parse(line);
+        return {
+          name: `${config.name}_${obj.name}`,
+          schema: null,
+          records: obj.records,
+          metadata: { tool: "sdv", table: obj.name },
+        };
+      });
+  }
+}
+
+/**
+ * @param {object} deps
+ * @returns {SdvTool}
+ */
+export function createSdvTool(deps) {
+  return new SdvTool(deps);
+}

package/tools/sdv_generate.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+"""Bridge between fit-universe and SDV."""
+import json
+import sys
+import pandas as pd
+from sdv.metadata import Metadata
+from sdv.single_table import GaussianCopulaSynthesizer
+
+
+def main():
+    config = json.load(open(sys.argv[1]))
+    metadata = Metadata.load_from_json(config["metadata"])
+    seed = config.get("seed", 0)
+
+    for table_name in metadata.get_tables():
+        data = pd.read_csv(config["data"][table_name])
+        synth = GaussianCopulaSynthesizer(metadata, table_name=table_name)
+        synth.fit(data)
+        samples = synth.sample(num_rows=config["rows"], seed=seed)
+
+        output = {
+            "name": table_name,
+            "records": json.loads(samples.to_json(orient="records")),
+        }
+        print(json.dumps(output))
+
+
+if __name__ == "__main__":
+    main()

package/tools/synthea.js

@@ -0,0 +1,126 @@
+/**
+ * Synthea tool — generates FHIR R4 patient data via Java subprocess.
+ */
+
+import { join } from "path";
+
+export class SyntheaTool {
+  /**
+   * @param {object} deps
+   * @param {object} deps.logger
+   * @param {string} deps.syntheaJar - Absolute path to synthea-with-dependencies.jar
+   * @param {Function} deps.execFileFn - async (cmd, args) => { stdout }
+   * @param {object} deps.fsFns - { readFile, readdir, mkdtemp, rm }
+   */
+  constructor({ logger, syntheaJar, execFileFn, fsFns }) {
+    if (!logger) throw new Error("SyntheaTool requires logger");
+    if (!syntheaJar) throw new Error("SyntheaTool requires syntheaJar");
+    if (!execFileFn) throw new Error("SyntheaTool requires execFileFn");
+    if (!fsFns) throw new Error("SyntheaTool requires fsFns");
+    this.logger = logger;
+    this.syntheaJar = syntheaJar;
+    this.execFileFn = execFileFn;
+    this.fsFns = fsFns;
+  }
+
+  /**
+   * Check that Java and the Synthea jar are available.
+   * @returns {Promise<boolean>}
+   */
+  async checkAvailability() {
+    try {
+      await this.execFileFn("java", ["-version"]);
+      await this.fsFns.readFile(this.syntheaJar);
+      return true;
+    } catch {
+      throw new Error(
+        `Synthea requires Java and ${this.syntheaJar}. ` +
+          "Install Java (java.com) and download Synthea " +
+          "(github.com/synthetichealth/synthea/releases). " +
+          "Set SYNTHEA_JAR to the jar path.",
+      );
+    }
+  }
+
+  /**
+   * Generate FHIR patient data, returning one dataset per resource type.
+   * @param {object} config
+   * @param {string} config.name - Dataset name from DSL
+   * @param {number} [config.population=100] - Number of patients
+   * @param {string[]} [config.modules] - Synthea modules to enable
+   * @param {number} config.seed - RNG seed
+   * @returns {Promise<Dataset[]>}
+   */
+  async generate(config) {
+    const tmpDir = await this.fsFns.mkdtemp("synthea-");
+    const args = [
+      "-jar",
+      this.syntheaJar,
+      "-p",
+      String(config.population || 100),
+      "-s",
+      String(config.seed),
+      "--exporter.fhir.export",
+      "true",
+      "--exporter.baseDirectory",
+      tmpDir,
+    ];
+    if (config.modules) {
+      for (const mod of config.modules) {
+        args.push("-m", mod);
+      }
+    }
+
+    this.logger.info(
+      "synthea",
+      `Running Synthea: population=${config.population || 100}`,
+    );
+    await this.execFileFn("java", args);
+
+    // Read FHIR bundles from output
+    const fhirDir = join(tmpDir, "fhir");
+    const bundleFiles = (await this.fsFns.readdir(fhirDir)).filter((f) =>
+      f.endsWith(".json"),
+    );
+    const bundles = await Promise.all(
+      bundleFiles.map(async (f) =>
+        JSON.parse(await this.fsFns.readFile(join(fhirDir, f), "utf-8")),
+      ),
+    );
+
+    // Flatten bundles into datasets by resource type
+    const byType = new Map();
+    for (const bundle of bundles) {
+      for (const entry of bundle.entry || []) {
+        const resource = entry.resource;
+        const type = resource.resourceType;
+        if (!byType.has(type)) byType.set(type, []);
+        byType.get(type).push(resource);
+      }
+    }
+
+    // Return one dataset per resource type
+    const datasets = [];
+    for (const [type, records] of byType) {
+      datasets.push({
+        name: `${config.name}_${type.toLowerCase()}`,
+        schema: null,
+        records,
+        metadata: { tool: "synthea", resourceType: type },
+      });
+    }
+
+    // Clean up
+    await this.fsFns.rm(tmpDir, { recursive: true });
+
+    return datasets;
+  }
+}
+
+/**
+ * @param {object} deps
+ * @returns {SyntheaTool}
+ */
+export function createSyntheaTool(deps) {
+  return new SyntheaTool(deps);
+}