Add instrument method compatibility graph

Author: evilfps

README.md

@@ -1,2 +1,4 @@
 # deepevents.ai
 deepevents.ai main codebase
+
+- `instrument-method-compatibility-graph/` adds instrument, method, and dataset compatibility checks for scientific knowledge graphs.

instrument-method-compatibility-graph/README.md

@@ -0,0 +1,39 @@
+# Instrument Method Compatibility Graph
+
+This module adds a focused knowledge graph slice for instrument, method, and dataset compatibility.
+
+It covers:
+
+- typed instrument, method, dataset, and experiment nodes
+- compatibility edges across instruments, methods, and datasets
+- modality, file format, resolution, calibration, and evidence checks
+- entity pages for instrument, method, and dataset navigation
+- candidate edge recommendations for graph discovery
+- curator actions, audit events, and deterministic digests
+
+The implementation is dependency-free and uses synthetic sample data only.
+
+## Run
+
+```bash
+npm run check
+npm test
+npm run demo
+```
+
+## Demo Assets
+
+- short demo video: `docs/demo.webm`
+- `docs/demo.svg`
+
+## API
+
+```js
+import {
+  evaluateInstrumentMethodCompatibility,
+  renderInstrumentMethodCompatibilityReport
+} from "./src/instrument-method-compatibility-graph.js";
+
+const result = evaluateInstrumentMethodCompatibility(input);
+console.log(renderInstrumentMethodCompatibilityReport(result));
+```

instrument-method-compatibility-graph/data/sample-graph-input.json

@@ -0,0 +1,89 @@
+{
+  "generatedAt": "2026-05-16T17:10:00Z",
+  "project": {
+    "id": "kg-neuroimmune-221",
+    "title": "Neuroimmune Knowledge Map",
+    "domain": "neuroscience"
+  },
+  "instruments": [
+    {
+      "id": "inst-confocal-7",
+      "name": "Confocal Microscope 7",
+      "modalities": ["imaging"],
+      "supportedMethodIds": ["method-cell-segmentation", "method-colocalization"],
+      "calibrationDate": "2026-04-22T00:00:00Z"
+    },
+    {
+      "id": "inst-flow-alpha",
+      "name": "Flow Cytometer Alpha",
+      "modalities": ["single-cell"],
+      "supportedMethodIds": ["method-cell-count"],
+      "calibrationDate": "2025-11-15T00:00:00Z"
+    }
+  ],
+  "methods": [
+    {
+      "id": "method-cell-segmentation",
+      "name": "Cell Segmentation",
+      "status": "active",
+      "requiredModalities": ["imaging"],
+      "acceptedOutputs": ["ome-tiff", "tiff"],
+      "maxResolutionMicrons": 0.8,
+      "maxCalibrationAgeDays": 60
+    },
+    {
+      "id": "method-legacy-clustering",
+      "name": "Legacy Clustering",
+      "status": "deprecated",
+      "requiredModalities": ["single-cell"],
+      "acceptedOutputs": ["fcs"],
+      "maxCalibrationAgeDays": 120
+    }
+  ],
+  "datasets": [
+    {
+      "id": "data-glia-images",
+      "name": "Glia marker image stack",
+      "modality": "imaging",
+      "format": "ome-tiff",
+      "resolutionMicrons": 0.5
+    },
+    {
+      "id": "data-cytokine-fcs",
+      "name": "Cytokine panel FCS",
+      "modality": "single-cell",
+      "format": "fcs",
+      "resolutionMicrons": 1.2
+    }
+  ],
+  "experiments": [
+    {
+      "id": "exp-segmentation-01",
+      "instrumentId": "inst-confocal-7",
+      "methodId": "method-cell-segmentation",
+      "datasetId": "data-glia-images",
+      "evidence": [
+        {
+          "id": "ev-segmentation-validation",
+          "type": "validation",
+          "status": "ready",
+          "quality": 0.91
+        }
+      ]
+    },
+    {
+      "id": "exp-legacy-flow-02",
+      "instrumentId": "inst-flow-alpha",
+      "methodId": "method-legacy-clustering",
+      "datasetId": "data-cytokine-fcs",
+      "evidence": [
+        {
+          "id": "ev-flow-draft",
+          "type": "notebook",
+          "status": "draft",
+          "quality": 0.44
+        }
+      ]
+    }
+  ]
+}

instrument-method-compatibility-graph/docs/demo.svg

@@ -0,0 +1,11 @@
+# Requirement Map
+
+This slice targets issue #17's graph navigation and recommendation requirements.
+
+| Requirement | Coverage |
+| --- | --- |
+| Entity extraction / linked data | Models typed instrument, method, dataset, and experiment nodes with stable ids. |
+| Knowledge navigation | Builds entity pages and graph query labels for instrument-to-method-to-dataset traversal. |
+| Relationship quality | Scores compatibility edges and flags modality, format, resolution, calibration, evidence, and deprecated-method issues. |
+| Recommendations | Emits candidate graph edges when instrument, method, and dataset metadata are compatible. |
+| Tests | `npm test` covers ready edges, missing nodes, mismatch blockers, stale calibration, weak evidence, recommendations, digests, and reports. |

instrument-method-compatibility-graph/docs/demo.webm

@@ -0,0 +1,15 @@
+{
+  "name": "instrument-method-compatibility-graph",
+  "version": "1.0.0",
+  "description": "Deterministic instrument and method compatibility graph checks for research projects.",
+  "type": "module",
+  "scripts": {
+    "check": "node --check src/instrument-method-compatibility-graph.js && node --check scripts/demo.js && node --check test/instrument-method-compatibility-graph.test.js",
+    "demo": "node scripts/demo.js",
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

instrument-method-compatibility-graph/docs/requirement-map.md

@@ -0,0 +1,14 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  evaluateInstrumentMethodCompatibility,
+  renderInstrumentMethodCompatibilityReport
+} from "../src/instrument-method-compatibility-graph.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const inputPath = path.join(__dirname, "..", "data", "sample-graph-input.json");
+const input = JSON.parse(fs.readFileSync(inputPath, "utf8"));
+
+const result = evaluateInstrumentMethodCompatibility(input);
+console.log(renderInstrumentMethodCompatibilityReport(result));