@bufinance/gtm-graph

BUFI's GTM account map: a force-directed graph view (people of interest, bridges, warm paths) plus the pure path/bridge algorithms that power it. Shared between the BUFI desk admin cockpit (workspace dep) and open-agents (published npm dep).

Entry points

| Import | Contents | Safe on server? | | ------------------------------- | ---------------------------------------------------------------------------------------------- | --------------- | | @bufinance/gtm-graph | Data contracts (GtmGraphData, GtmGraphPayload) + everything from /algorithms | Yes | | @bufinance/gtm-graph/algorithms | fewestHops, strongestPath, bridgeScores, neighborhood, edgeWeight, computePoiIds, computeBridgeIds, capGraph | Yes | | @bufinance/gtm-graph/view | GtmGraphView React component (ships "use client") | Client only |

Usage

import { GtmGraphView } from '@bufinance/gtm-graph/view';

<GtmGraphView
  data={{ entities, relationships }}
  decorations={{ poiIds, bridgeScores }} // optional — computed client-side when absent
  now={generatedAt}
  onEntitySelect={id => openDetail(id)}
/>;

import { strongestPath, neighborhood } from '@bufinance/gtm-graph/algorithms';

const warm = strongestPath(graph, repId, targetId, { now: Date.now() });
const context = neighborhood(graph, entityId, 2);

Data shape

GtmGraphData is structurally compatible with the desk repo's KnowledgeGraphData (get_knowledge_graph RPC payload). Edge lastSeenAt/metadata are optional because that RPC omits them — hosts that read entity_relationships directly should include both so recency fading and traversal weights are exact. Missing lastSeenAt is treated as fresh.

Weight formula

w = strength * ln(1 + evidenceCount) * 0.5^(daysStale / 90)

strongestPath runs Dijkstra on 1/w; it can legitimately return MORE hops than fewestHops when a chain of strong fresh edges beats a weak stale direct edge — that divergence is the warm-path payoff.

Versioning discipline

Consumers outside the desk workspace (open-agents) track published versions. Any change to this package needs a version bump + npm publish before those consumers can use it — a workspace-side edit alone is invisible to them. Until the first publish, open-agents consumes the packed tarball via a file: dependency; switch it to ^0.1.0 after publishing.

Development

bun install
bun run build      # tsup → dist (esm + cjs + dts); required before dependents typecheck
bun run test       # bun test (algorithms + view-model + static render)
bun run typecheck
npm pack           # tarball for file: consumers
npm publish --dry-run

Provenance

• Algorithms moved here from the desk repo's packages/intelligence/src/knowledge/graph-paths.ts (plan 099) — that path is now a re-export shim of @bufinance/gtm-graph/algorithms.
• Physics copied (not imported) from packages/intelligence-ui/src/bubble-memory/bubble-physics.ts so the package publishes standalone; the bubble-memory original is unchanged.
• li_connection edge styling is pre-wired for the HeyReach LinkedIn network edges (099 follow-up) — the UI needs zero changes when they land.