Code walkthrough · All projects
NodeGraph is a small TypeScript semantic graph layer extracted from NodeRoom. It turns room-like artifacts, spreadsheet rows, notebook blocks, evidence payloads, traces, proposals, sessions, and members into an evidence-backed relationship graph.
Not yet on npm. Until the
@homenshum/nodegraph/@homenshum/nodegraph-livepublishes land, vendorsrc/(orrender/src/) or use afile:dependency.
| Layer | Where | What it owns | First win |
|---|---|---|---|
| Model | repo root (src/) |
Artifacts, traces, proposals, sessions into an evidence-backed relationship graph | npm install && npm test |
| View | render/ |
Live typed-edge rendering: evidence / assertion / traversal edges never look alike, bounded ingestion motion, trust-grammar legend (extracted from TrialScope) | cd render && npm ci && npm run demo -> http://127.0.0.1:4173 |
They compose — and examples/compose proves it in ~15
lines: the model turns a research room (one sheet, an agent's sourced cells,
traces, a proposal) into 54 nodes and 102 edges; the renderer draws them
under the trust grammar. Deliberately conservative: the model's relevance
weight is not a measured count and its refs carry no release, so every
relationship renders as traversal — the refusal is the demo.
The view preserves all 54 source identities and groups the 102 semantic edges
into 96 unique undirected traversal pairs; source direction and verbs remain
in the model.
npm ci
npm --prefix render ci
npm run example:compose # builds both layers, then serves the pageOpen http://127.0.0.1:4173/examples/compose/index.html.
Each layer keeps its own package.json, tests, and README; neither imports the other.
Use Node 22 or 24. Install both packages with npm ci and
npm --prefix render ci, then run:
npm run test:all
npm run typecheck
npm --prefix render run typecheck
npm run example:build
npm run verify:packages
npm audit
npm --prefix render auditverify:packages builds tarballs and installs them outside this repository. It
exercises the public model/core exports, NodeNext type declarations and a
browser consumer bundle. For rendered evidence, install Chromium in both
packages (npx playwright install chromium), then run
npm run verify:packages -- --browser and
npm --prefix render run verify:demo -- --compose.
CI runs the package checks on Windows/Linux with
Node 22/24 and the browser checks on Linux. Artifacts record screenshots, DOM,
axe findings and failures under .proofloop/. These checks do not certify a
hosted deployment, search rankings or full product quality grades. This repo
is a library; publishing or deploying a consuming application is a separate step.
It is renderer-friendly rather than renderer-bound: the core graph derivation, filtering, selection, and layout functions are pure TypeScript. A compact React detail panel is included for apps that want the NodeRoom-style selection sidebar.
Cross-repo integration notes live in docs/internal/.
- People and agent jobs
- Companies and related entities
- Artifacts, spreadsheet rows, and notebook blocks
- Sources and evidence facts
- Funding, projects, achievements, and events
- Trace steps, proposals, and open questions
Edges use semantic verbs such as researched, cited, supported_by, authored, updated, proposed, reviewed, and triggered.
import {
buildGraphRelationshipReviewPlan,
buildNeo4jSyncPlan,
buildNeo4jUpsertPlan,
buildSemanticGraph,
createNodeGraphAgentTools,
exportNodeGraphDocument,
InMemoryNodeGraphAdapter,
selectSemanticGraphCluster,
selectSemanticNeighborhood,
summarizeSemanticGraphClusters,
} from "@homenshum/nodegraph";
const graph = buildSemanticGraph({
roomId: "room-1",
artifacts,
members,
traces,
proposals,
sessions,
});
const company = graph.nodes.find((node) => node.kind === "company");
const selection = selectSemanticNeighborhood(graph, company?.id, 2);
const clusters = summarizeSemanticGraphClusters(graph);
const clusterView = selectSemanticGraphCluster(graph, clusters[0]?.id ?? null, { neighborDepth: 1, maxNodes: 80 });
const relationshipReview = buildGraphRelationshipReviewPlan(graph, "room-1:semantic-graph");
const graphTools = createNodeGraphAgentTools({ getGraph: () => graph });
const neo4jPlan = buildNeo4jUpsertPlan(graph, "room-1");
const document = exportNodeGraphDocument(graph, {
graphId: "room-1",
provenance: { source: "noderoom", sourceId: "room-1" },
layout: { positions, pinnedNodeIds },
});
const memory = new InMemoryNodeGraphAdapter();
const receipt = memory.importDocument(document);
const incrementalNeo4jPlan = buildNeo4jSyncPlan(document, previousDocument, { pruneMissing: true });The nodegraph.document v1 contract is the portable boundary shared by the
React showcase, Streamlit exports, NodeRoom, in-memory storage, and Neo4j sync.
Every document carries a deterministic graph revision and source provenance;
optional layout positions and pinned node ids survive reloads and JSON
round-trips. diffNodeGraphDocuments reports exact node, relationship, and
cluster upserts/removals so hosts can inspect an incremental change before
applying it.
buildGraphRelationshipReviewPlan is the public version of NodeRoom's graph
confirmation layer. It classifies graph edges as source-backed confirmations or
relationships that still need reviewer confirmation, and returns deterministic
JSON-friendly receipts for audits, readme demos, Streamlit apps, or agent tools.
summarizeSemanticGraphClusters ranks person, company, evidence, artifact, and
runtime clusters by connected evidence and review relevance. selectSemanticGraphCluster
isolates one cluster and can add zero, one, or two bounded neighbor rings for
responsive React, Neo4j-style, or Streamlit exploration.
Deck storyboards can be passed in buildSemanticGraph({ decks }). Slides,
claims, source artifacts, trace receipts, proposals, cited evidence, and open
evidence gaps become first-class nodes. A selected node also returns ranked
multi-hop paths, so a reviewer can see the strongest person-to-company,
claim-to-source, and agent-to-artifact routes instead of only immediate links.
NodeGraph does not replace NodeRoom's NodeAgent. It exposes a bridge that lets the canonical NodeAgent runtime call graph tools and lets the React graph UI mount a NodeGraphAgentPanel.
See docs/nodeagent-integration.md for the NodeRoom wiring.
New here? Read docs/START_HERE.md first — it walks one
real user action through the code in the order it executes, and
.tours/ is the same walk as clickable CodeTours.
Each layer has its own commands, because each is its own package — and one command covers both:
# both layers (repo root, after installing in both)
npm run test:all # 14 vitest + 13 node:test + the doc-pointer guard
# model layer (repo root)
npm install
npm run typecheck
npm test # vitest, 14 tests — MODEL layer only, no view-layer code
npm run build
# view layer
cd render
npm install
npm run typecheck
npm test # node:test, 13 tests
npm run verify:demo # serves the demo, drives it in headless ChromeRoot npm test covers the model layer alone. It goes green without executing a
line of render/, so use npm run test:all before believing a suite is green.
The local showcase app demonstrates the same graph relationships NodeRoom uses: people researching companies, evidence-backed rows, traces, proposals, sessions, and clustered project or achievement context. Dragged or explicitly pinned nodes persist across reloads. The toolbar exports the canonical JSON document or a parameterized Neo4j sync plan and can import a prior NodeGraph document.
npm run example:devThen open http://127.0.0.1:5174.
npm run example:build
npm run showcase:capturenpm run showcase:capture writes the README GIF to docs/media/nodegraph-showcase.gif and expects ffmpeg to be available on PATH.
The README clips follow the feature-proof-studio proof pattern: storyboard first, scripted browser state capture, readable frame sequencing, and ffmpeg palette output suitable for GitHub READMEs.
This repo keeps the capture scripts local so NodeGraph can regenerate its own proof assets without cloning another repo:
npm run showcase:capture
npm run streamlit:captureThose commands regenerate:
docs/media/nodegraph-showcase.gif- React graph showcase with draggable React Flow nodes, neighborhood focus, evidence filtering, and the NodeGraph agent panel.docs/media/nodegraph-streamlit-showcase.gif- Streamlit graph showcase with Cytoscape-style interaction, NodeAgent chat, and a visible tool trace.
The same clips are also listed from feature-proof-studio as public proof examples.
NodeGraph uses a Neo4j-style property graph shape: stable node ids, typed node kinds, typed edge relationships, properties, statuses, and provenance refs. buildNeo4jUpsertPlan provides a non-destructive full upsert. buildNeo4jSyncPlan consumes versioned documents and emits only changed records, with host-controlled stale pruning. Both produce parameterized, APOC-free Cypher batches that work with a standard Neo4j driver session; NodeGraph remains storage-neutral and does not embed database credentials or own a Neo4j server.
The Streamlit example defaults to st-link-analysis, a Cytoscape.js community component with draggable nodes, pan/zoom controls, fullscreen graph exploration, neighborhood highlighting, and selected-element metadata. PyVis remains available as a fallback renderer from the sidebar.
npm run build
npm run streamlit:agentThen, in a second terminal:
cd examples/streamlit
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
streamlit run app.pyThe Streamlit app calls NODEGRAPH_NODEAGENT_URL when set, defaulting to the bundled local bridge at http://127.0.0.1:8787/agent. It includes a NodeRoom-style chat lane: users can type @nodeagent questions, use the quick prompt buttons, and inspect each reply's tool trace.
Generate the Streamlit README/demo GIF from the repo root:
npm run streamlit:captureSee docs/integrations.md for the Streamlit example and Neo4j-style mapping.
This package was extracted from NodeRoom's semantic entity graph work. See docs/semantic-entity-graph-research.md for renderer research and design constraints.



