@mindflight/mindbrain-personal-studio 0.6.1 → 0.6.3

package/examples/immeuble/scripts/build-immeuble-model.mjs

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+/**
+ * Idempotent Immeuble model builder (MVP_Serenity_2 style).
+ *
+ * Reads bundle/immeuble.bundle.json, emits:
+ * - model/immeuble_model.json
+ * - fake_data/*.csv (one per entity_type)
+ * - import_ready/mfo_facets_import.csv + graph_edges_import.csv
+ * - contracts/mapping_external_to_canonical.json
+ * - reports/*.json / *.jsonl
+ */
+
+import {
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+  rmSync
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const WS = "immeuble";
+const ONT = "immeuble::core";
+const SCHEMA_PREFIX = "immeuble:core:";
+
+const PATHS = {
+  bundle: join(ROOT, "bundle", "immeuble.bundle.json"),
+  model: join(ROOT, "model", "immeuble_model.json"),
+  mapping: join(ROOT, "contracts", "mapping_external_to_canonical.json"),
+  fakeData: join(ROOT, "fake_data"),
+  importReady: join(ROOT, "import_ready"),
+  reports: join(ROOT, "reports"),
+  successCriteria: join(ROOT, "success-criteria.yaml")
+};
+
+const CLOSED_EDGE_LABELS = [
+  "contains", "owns", "occupies", "household_member", "primary_residence_of",
+  "leases", "rented_to", "assigned_cellar", "assigned_garage", "uses_exclusive",
+  "uses_common", "matched_to", "allocated_to", "requires_review", "documents",
+  "member_of", "has_member", "bills_to", "linked_to", "manages", "represents",
+  "records", "triggered", "decided_by", "manages_project", "designs_for",
+  "has_work_package", "executes_work_package", "has_milestone", "authorized_by",
+  "based_on_quote", "has_budget_line", "invoiced_by", "affects_asset",
+  "reported_by", "has_reserve", "evidenced_by", "covers_asset", "provided_by",
+  "concerns_asset", "has_intervention", "covered_by", "certifies_asset",
+  "measures_asset", "records_reading", "has_agenda_item", "flags_entity"
+];
+
+function schemaId(entityType) {
+  return `${SCHEMA_PREFIX}${entityType}`;
+}
+
+function recordId(entityType, entityId) {
+  return `${entityType}:${entityId}`;
+}
+
+function sourceRef(entityType, entityId) {
+  return `${entityType}:${entityType}:${entityId}`;
+}
+
+function csvEscape(value) {
+  const text = value == null ? "" : String(value);
+  if (/[",\n\r]/.test(text)) {
+    return `"${text.replaceAll('"', '""')}"`;
+  }
+  return text;
+}
+
+function writeCsv(path, headers, rows) {
+  const lines = [headers.join(",")];
+  for (const row of rows) {
+    lines.push(headers.map((h) => csvEscape(row[h])).join(","));
+  }
+  writeFileSync(path, lines.join("\n") + "\n", "utf8");
+}
+
+function parseMeta(raw) {
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+function transformBundleIds(bundle) {
+  const text = JSON.stringify(bundle)
+    .replaceAll("immeuble-demo-llm", WS)
+    .replaceAll("immeuble-demo::docs", `${WS}::docs`)
+    .replaceAll("immeuble-demo::core", ONT)
+    .replaceAll("immeuble-demo", WS)
+    .replaceAll("immeuble_demo", "immeuble")
+    .replaceAll("agent:immeuble-demo", `agent:${WS}`);
+  return JSON.parse(text);
+}
+
+function buildModel(entityTypes) {
+  return {
+    workspace_id: WS,
+    ontology_id: ONT,
+    label: "Immeuble syndic reference model",
+    version: "2026-06-14",
+    closed_edge_labels: CLOSED_EDGE_LABELS.map((l) => l.toUpperCase()),
+    entity_types: entityTypes.map((name) => ({
+      name,
+      label: name,
+      schema_id: schemaId(name),
+      ontology: "core",
+      node_type: name,
+      record_id_pattern: `${name}:<stable-key>`
+    })),
+    contract_relations: []
+  };
+}
+
+function entityToRow(entity) {
+  const meta = parseMeta(entity.metadata_json);
+  return {
+    record_id: recordId(entity.entity_type, entity.entity_id),
+    name: entity.name ?? "",
+    entity_type: entity.entity_type,
+    entity_id: String(entity.entity_id),
+    confidence: entity.confidence ?? 1,
+    ...meta
+  };
+}
+
+function facetContent(entity, row) {
+  const facets = { ...row, source: "fake_data", ontology: "core" };
+  delete facets.record_id;
+  return facets;
+}
+
+function main() {
+  mkdirSync(PATHS.fakeData, { recursive: true });
+  mkdirSync(PATHS.importReady, { recursive: true });
+  mkdirSync(PATHS.reports, { recursive: true });
+
+  let bundle = JSON.parse(readFileSync(PATHS.bundle, "utf8"));
+  bundle = transformBundleIds(bundle);
+  writeFileSync(PATHS.bundle, JSON.stringify(bundle, null, 2) + "\n", "utf8");
+
+  const entities = bundle.entities_raw ?? [];
+  const relations = bundle.relations_raw ?? [];
+  const byType = new Map();
+  const idToEntity = new Map();
+
+  for (const entity of entities) {
+    idToEntity.set(entity.entity_id, entity);
+    const list = byType.get(entity.entity_type) ?? [];
+    list.push(entity);
+    byType.set(entity.entity_type, list);
+  }
+
+  const entityTypes = [...byType.keys()].sort();
+  const model = buildModel(entityTypes);
+  writeFileSync(PATHS.model, JSON.stringify(model, null, 2) + "\n", "utf8");
+
+  for (const old of readdirSync(PATHS.fakeData).filter((f) => f.endsWith(".csv"))) {
+    rmSync(join(PATHS.fakeData, old));
+  }
+
+  const facetRows = [];
+  for (const [entityType, list] of byType.entries()) {
+    const rows = list.map(entityToRow);
+    const headers = [...new Set(rows.flatMap((r) => Object.keys(r)))];
+    const ordered = ["record_id", "name", "entity_type", "entity_id", ...headers.filter((h) => !["record_id", "name", "entity_type", "entity_id"].includes(h))];
+    writeCsv(join(PATHS.fakeData, `${entityType}.csv`), ordered, rows);
+
+    for (const entity of list) {
+      const row = entityToRow(entity);
+      const facets = facetContent(entity, row);
+      facetRows.push({
+        content: entity.name ?? row.record_id,
+        facets: JSON.stringify(facets),
+        schema_id: schemaId(entityType),
+        source_ref: sourceRef(entityType, entity.entity_id),
+        workspace_id: WS
+      });
+    }
+  }
+
+  writeCsv(
+    join(PATHS.importReady, "mfo_facets_import.csv"),
+    ["content", "facets", "schema_id", "source_ref", "workspace_id"],
+    facetRows
+  );
+
+  const edgeRows = relations.map((rel) => {
+    const source = idToEntity.get(rel.source_entity_id);
+    const target = idToEntity.get(rel.target_entity_id);
+    const label = (rel.edge_type ?? "linked_to").toUpperCase();
+    return {
+      confidence: rel.confidence ?? 0.85,
+      label,
+      metadata_json: JSON.stringify({
+        source: "fake_data",
+        relation_contract: {
+          edge_label: label,
+          source_entity_id: rel.source_entity_id,
+          target_entity_id: rel.target_entity_id
+        }
+      }),
+      source: source ? sourceRef(source.entity_type, source.entity_id) : String(rel.source_entity_id),
+      target: target ? sourceRef(target.entity_type, target.entity_id) : String(rel.target_entity_id),
+      workspace_id: WS
+    };
+  });
+
+  writeCsv(
+    join(PATHS.importReady, "graph_edges_import.csv"),
+    ["confidence", "label", "metadata_json", "source", "target", "workspace_id"],
+    edgeRows
+  );
+
+  const mappingEntities = {};
+  for (const entityType of entityTypes) {
+    mappingEntities[entityType] = {
+      csv: `fake_data/${entityType}.csv`,
+      schema_id: schemaId(entityType),
+      record_id_column: "record_id",
+      content_columns: ["name"]
+    };
+  }
+
+  const mapping = {
+    workspace_id: WS,
+    ontology_id: ONT,
+    source_tag: "structured_import",
+    data_plane: "import_ready",
+    import_ready: {
+      facets_csv: "import_ready/mfo_facets_import.csv",
+      edges_csv: "import_ready/graph_edges_import.csv"
+    },
+    entities: mappingEntities,
+    contract_relations: [],
+    edges_mode: "import_ready",
+    notes: "Generated by build-immeuble-model.mjs from bundle/immeuble.bundle.json"
+  };
+  writeFileSync(PATHS.mapping, JSON.stringify(mapping, null, 2) + "\n", "utf8");
+
+  const counts = Object.fromEntries([...byType.entries()].map(([k, v]) => [k, v.length]));
+  const nodeLines = entities.map((e) =>
+    JSON.stringify({
+      record_id: recordId(e.entity_type, e.entity_id),
+      entity_type: e.entity_type,
+      name: e.name,
+      schema_id: schemaId(e.entity_type)
+    })
+  );
+  writeFileSync(join(PATHS.reports, "graph_nodes.jsonl"), nodeLines.join("\n") + "\n", "utf8");
+
+  const edgeLines = edgeRows.map((e) => JSON.stringify(e));
+  writeFileSync(join(PATHS.reports, "graph_edges.jsonl"), edgeLines.join("\n") + "\n", "utf8");
+
+  const prefixViolations = facetRows.filter((r) => !r.schema_id.startsWith("immeuble:"));
+  const modelValidation = {
+    ok: prefixViolations.length === 0,
+    workspace_id: WS,
+    ontology_id: ONT,
+    entity_type_count: entityTypes.length,
+    entity_types: entityTypes,
+    schema_id_prefix: "immeuble:",
+    prefix_violations: prefixViolations.length,
+    generated_at: new Date().toISOString()
+  };
+  writeFileSync(join(PATHS.reports, "01-model.validation.json"), JSON.stringify(modelValidation, null, 2) + "\n", "utf8");
+
+  const mappingValidation = {
+    ok: true,
+    workspace_id: WS,
+    mapped_entity_types: entityTypes.length,
+    facet_rows: facetRows.length,
+    edge_rows: edgeRows.length,
+    all_schema_ids_prefixed: prefixViolations.length === 0,
+    generated_at: new Date().toISOString()
+  };
+  writeFileSync(join(PATHS.reports, "02-mapping.validation.json"), JSON.stringify(mappingValidation, null, 2) + "\n", "utf8");
+
+  const pipelineAudit = {
+    ok: modelValidation.ok && mappingValidation.ok,
+    gates: {
+      model: modelValidation.ok,
+      mapping: mappingValidation.ok,
+      facets: facetRows.length > 0,
+      edges: edgeRows.length > 0
+    },
+    counts,
+    facet_rows: facetRows.length,
+    edge_rows: edgeRows.length,
+    generated_at: new Date().toISOString()
+  };
+  writeFileSync(join(PATHS.reports, "pipeline_audit.json"), JSON.stringify(pipelineAudit, null, 2) + "\n", "utf8");
+
+  console.log(JSON.stringify({
+    ok: pipelineAudit.ok,
+    workspace_id: WS,
+    entity_types: entityTypes.length,
+    facet_rows: facetRows.length,
+    edge_rows: edgeRows.length,
+    fake_data_csv: entityTypes.length,
+    reports: readdirSync(PATHS.reports).length
+  }, null, 2));
+}
+
+main();

package/examples/immeuble/scripts/compare-immeuble-snapshots.sh

@@ -0,0 +1,227 @@
+#!/usr/bin/env bash
+set -eu
+
+FROM_DB=""
+TO_DB=""
+WORKSPACE_ID="immeuble"
+FROM_LABEL=""
+TO_LABEL=""
+CUSTOM_TABLES=""
+JSON_OUTPUT=0
+OUTPUT_FILE=""
+
+usage() {
+  cat <<EOF
+Usage: examples/immeuble/scripts/compare-immeuble-snapshots.sh [options]
+
+Compare two SQLite snapshots from Immeuble and show row-count deltas.
+
+Options:
+  --from <path>            Snapshot A path (required)
+  --to <path>              Snapshot B path (required)
+  --label-a <text>         Optional label for snapshot A
+  --label-b <text>         Optional label for snapshot B
+  --workspace <id>         Workspace filter for workspace-scoped tables (default: immeuble)
+  --tables <t1,t2,...>     Override the default table set
+  --json                   Emit JSON output
+  --out <path>             Write output to a file (human or JSON)
+  -h, --help               Show this help
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --from)
+      FROM_DB="${2:?--from requires a value}"
+      shift 2
+      ;;
+    --to)
+      TO_DB="${2:?--to requires a value}"
+      shift 2
+      ;;
+    --label-a)
+      FROM_LABEL="${2:?--label-a requires a value}"
+      shift 2
+      ;;
+    --label-b)
+      TO_LABEL="${2:?--label-b requires a value}"
+      shift 2
+      ;;
+    --workspace)
+      WORKSPACE_ID="${2:?--workspace requires a value}"
+      shift 2
+      ;;
+    --tables)
+      CUSTOM_TABLES="${2:?--tables requires a value}"
+      shift 2
+      ;;
+    --json)
+      JSON_OUTPUT=1
+      shift
+      ;;
+    --out)
+      OUTPUT_FILE="${2:?--out requires a value}"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "[immeuble-compare] Unknown argument: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$FROM_DB" || -z "$TO_DB" ]]; then
+  echo "[immeuble-compare] --from and --to are required" >&2
+  usage
+  exit 1
+fi
+
+if [[ ! -f "$FROM_DB" ]]; then
+  echo "[immeuble-compare] snapshot does not exist: $FROM_DB" >&2
+  exit 1
+fi
+
+if [[ ! -f "$TO_DB" ]]; then
+  echo "[immeuble-compare] snapshot does not exist: $TO_DB" >&2
+  exit 1
+fi
+
+if ! command -v sqlite3 >/dev/null 2>&1; then
+  echo "[immeuble-compare] sqlite3 is required in PATH" >&2
+  exit 1
+fi
+
+if [[ -z "$FROM_LABEL" ]]; then
+  FROM_LABEL="$(basename "$FROM_DB")"
+fi
+if [[ -z "$TO_LABEL" ]]; then
+  TO_LABEL="$(basename "$TO_DB")"
+fi
+
+DEFAULT_TABLES="agent_facts graph_entity graph_relation entities_raw relations_raw documents_raw facet_assignments_raw facet_assignments_lookup_raw"
+if [[ -n "$CUSTOM_TABLES" ]]; then
+  IFS=',' read -r -a TABLES <<< "$CUSTOM_TABLES"
+else
+  read -r -a TABLES <<< "$DEFAULT_TABLES"
+fi
+
+workspacesql_escape() {
+  printf "%s" "$1" | sed "s/'/''/g"
+}
+WORKSPACE_SQL_SAFE="$(workspacesql_escape "$WORKSPACE_ID")"
+
+table_exists() {
+  local db="$1"
+  local table="$2"
+  sqlite3 "$db" "SELECT COUNT(1) FROM sqlite_master WHERE type='table' AND name='$table';" | tr -d '[:space:]'
+}
+
+has_workspace_column() {
+  local db="$1"
+  local table="$2"
+  sqlite3 "$db" "PRAGMA table_info('$table');" | awk -F'|' 'BEGIN{RS="\n"}{print $2}' | grep -qx "workspace_id" && echo yes
+}
+
+count_rows() {
+  local db="$1"
+  local table="$2"
+  local sql="SELECT COUNT(1) FROM \"$table\";"
+  if [[ "$WORKSPACE_ID" != "all" ]] && [[ "$(has_workspace_column "$db" "$table")" == "yes" ]]; then
+    sql="SELECT COUNT(1) FROM \"$table\" WHERE workspace_id='$WORKSPACE_SQL_SAFE';"
+  fi
+  sqlite3 "$db" "$sql"
+}
+
+collect_line() {
+  local db="$1"
+  local table="$2"
+  if [[ "$(table_exists "$db" "$table")" != "1" ]]; then
+    echo "missing"
+    return
+  fi
+  local cnt
+  cnt="$(count_rows "$db" "$table" | tr -d '[:space:]')"
+  if [[ -z "$cnt" ]]; then
+    echo "0"
+    return
+  fi
+  echo "$cnt"
+}
+
+json_escape() {
+  printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'
+}
+
+declare -a DIFF_LINES=()
+declare -a JSON_TABLES=()
+
+for table in "${TABLES[@]}"; do
+  table="${table#"${table%%[![:space:]]*}"}"
+  table="${table%"${table##*[![:space:]]}"}"
+  if [[ -z "$table" ]]; then
+    continue
+  fi
+  c1="$(collect_line "$FROM_DB" "$table")"
+  c2="$(collect_line "$TO_DB" "$table")"
+  if [[ "$c1" == "missing" || "$c2" == "missing" ]]; then
+    if [[ "$c1" == "missing" && "$c2" == "missing" ]]; then
+      delta="-"
+    else
+      delta="new_table"
+    fi
+  else
+    delta="$((c2 - c1))"
+  fi
+  from_json="$(json_escape "$c1")"
+  to_json="$(json_escape "$c2")"
+  delta_json="$(json_escape "$delta")"
+  DIFF_LINES+=("$table|$c1|$c2|$delta")
+  JSON_TABLES+=("{\"table\":\"$table\",\"from\":\"$from_json\",\"to\":\"$to_json\",\"delta\":\"$delta_json\"}")
+done
+
+rows_changed=0
+for line in "${DIFF_LINES[@]}"; do
+  IFS='|' read -r table from to delta <<< "$line"
+  if [[ "$delta" != "-" && "$delta" != "0" && "$delta" != "new_table" ]]; then
+    rows_changed=1
+  fi
+  if [[ "$delta" == "new_table" ]]; then
+    rows_changed=1
+  fi
+done
+
+if (( JSON_OUTPUT == 1 )); then
+  if [[ ${#JSON_TABLES[@]} -eq 0 ]]; then
+    json="[{\"table\":\"(none)\",\"from\":\"missing\",\"to\":\"missing\",\"delta\":\"-\"}]"
+  else
+    json="$(printf '%s\n' "${JSON_TABLES[@]}" | awk 'BEGIN{printf "["} {printf "%s%s", sep, $0; sep=","} END{printf "]"}')"
+  fi
+
+  payload="{\"from\":\"$FROM_LABEL\",\"to\":\"$TO_LABEL\",\"from_db\":\"$FROM_DB\",\"to_db\":\"$TO_DB\",\"workspace\":\"$WORKSPACE_ID\",\"rows_changed\":$rows_changed,\"tables\":$json}"
+else
+  payload="$(printf 'Comparing snapshots\\nFrom: %s (%s)\\nTo:   %s (%s)\\nWorkspace filter: %s\\n\\n' "$FROM_DB" "$FROM_LABEL" "$TO_DB" "$TO_LABEL" "$WORKSPACE_ID")"
+  payload="$payload$(printf '%-26s %-14s %-14s %-14s\\n' 'table' "from:$FROM_LABEL" "to:$TO_LABEL" "delta")"
+  payload="$payload$(printf '%-26s %-14s %-14s %-14s\\n' '-----' '-------------' '-----------' '-----')"
+  for line in "${DIFF_LINES[@]}"; do
+    IFS='|' read -r table from to delta <<< "$line"
+    payload="$payload$(printf '%-26s %-14s %-14s %-14s\\n' "$table" "$from" "$to" "$delta")"
+  done
+  payload="$payload\\n"
+  if [[ "$rows_changed" -eq 0 ]]; then
+    payload="${payload}No row-change on the selected tables."
+  else
+    payload="${payload}Diff detected on at least one table."
+  fi
+fi
+
+if [[ -n "$OUTPUT_FILE" ]]; then
+  printf '%b' "$payload" > "$OUTPUT_FILE"
+  echo "[immeuble-compare] wrote: $OUTPUT_FILE"
+else
+  printf '%b' "$payload"
+fi