Skip to content
HomenShumPublic

About

TypeScript semantic graph model and live renderer in one repo: evidence, artifacts, traces and proposals become typed relationships. Model in src/, view in render/; NodeRoom-compatible and storage-neutral.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

NodeGraph: Artifacts, traces and proposals into an evidence-backed graph.

Code walkthrough · All projects

NodeGraph

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-live publishes land, vendor src/ (or render/src/) or use a file: dependency.

What the view layer looks like, live

The scenario gallery recorded live: dense constellation, assertion chain, hub burst, drag

One repo, two layers

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 page

Open http://127.0.0.1:4173/examples/compose/index.html.

The model layer's research room drawn by the live renderer

Each layer keeps its own package.json, tests, and README; neither imports the other.

Verify a handoff

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 audit

verify: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/.

NodeGraph product showcase

What It Models

  • 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.

Usage

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.

NodeAgent Bridge

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.

Development

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 Chrome

Root 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.

Example App

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:dev

Then open http://127.0.0.1:5174.

npm run example:build
npm run showcase:capture

npm run showcase:capture writes the README GIF to docs/media/nodegraph-showcase.gif and expects ffmpeg to be available on PATH.

Feature Proof Studio Clips

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:capture

Those 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.

Streamlit And Neo4j-Style Graphs

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.

NodeGraph Streamlit showcase

npm run build
npm run streamlit:agent

Then, in a second terminal:

cd examples/streamlit
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
streamlit run app.py

The 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:capture

See docs/integrations.md for the Streamlit example and Neo4j-style mapping.

Origin

This package was extracted from NodeRoom's semantic entity graph work. See docs/semantic-entity-graph-research.md for renderer research and design constraints.

About

TypeScript semantic graph model and live renderer in one repo: evidence, artifacts, traces and proposals become typed relationships. Model in src/, view in render/; NodeRoom-compatible and storage-neutral.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages