@bufinance/gtm-graph 0.1.0

package/dist/algorithms/index.d.cts

@@ -0,0 +1,205 @@
+/**
+ * Graph path / bridge engine (plan 099; re-homed here as the published SSOT
+ * in plan 100 — `packages/intelligence/src/knowledge/graph-paths.ts` is now a
+ * re-export shim of this module).
+ *
+ * PURE module: no I/O, no clocks, no randomness — every time- or
+ * order-sensitive function takes explicit `now` / `seed` / `pairs` inputs so
+ * results are deterministic and testable, and so the UI can run the same
+ * code client-side over a fetched graph payload.
+ *
+ * Operates on a camelCase graph shape structurally compatible with the
+ * `get_knowledge_graph` RPC payload (`KnowledgeGraphData` in the BUFI desk
+ * repo). NOTE: that RPC's relationship objects omit `lastSeenAt`; the weight
+ * formula treats a missing `lastSeenAt` as "fresh" (factor 1).
+ *
+ * Weight formula (documented constants below):
+ *   w = strength * ln(1 + evidenceCount) * recencyFactor(lastSeenAt, now)
+ *   recencyFactor = 0.5 ^ (daysStale / 90)   — halves per 90 stale days
+ *
+ * Scale ceiling: everything here is in-memory over the fetched graph —
+ * fine for the BUFI-internal GTM graph (thousands of edges). Past ~50k
+ * edges, graduate to pgRouting / an RPC (see the 2026-07-16 gtm-graph spec).
+ */
+interface GraphEntityLike {
+    id: string;
+}
+interface GraphEdgeLike {
+    id: string;
+    sourceEntityId: string;
+    targetEntityId: string;
+    relationshipType: string;
+    strength?: number | null;
+    evidenceCount?: number | null;
+    lastSeenAt?: string | null;
+}
+interface GraphDataLike {
+    entities: GraphEntityLike[];
+    relationships: GraphEdgeLike[];
+}
+interface AdjacentEdge {
+    edgeId: string;
+    otherId: string;
+    relationshipType: string;
+    weight: number;
+}
+/** node id → undirected incident edges (both directions materialized). */
+type Adjacency = Map<string, AdjacentEdge[]>;
+interface GraphPath {
+    /** Node ids from source to target (inclusive). */
+    nodeIds: string[];
+    /** Edge ids traversed, in order (`nodeIds.length - 1` entries). */
+    edgeIds: string[];
+    /** Hop count (= edgeIds.length). */
+    hops: number;
+    /** Sum of Dijkstra costs (1/w) — lower = stronger; 0 for the trivial path. */
+    cost: number;
+}
+/** Staleness half-life: an edge unseen for this many days weighs half. */
+declare const RECENCY_HALF_LIFE_DAYS = 90;
+/** Default strength when the payload omits it (DB default is 1.0). */
+declare const DEFAULT_STRENGTH = 1;
+/** Default evidence count when the payload omits it (DB default is 1). */
+declare const DEFAULT_EVIDENCE_COUNT = 1;
+/** Floor so degenerate edges never divide by zero in 1/w costs. */
+declare const MIN_EDGE_WEIGHT = 0.000001;
+/** 0.5^(daysStale/90); missing/unparseable lastSeenAt → 1 (fresh). */
+declare function recencyFactor(lastSeenAt: string | null | undefined, now: number): number;
+/** w = strength * ln(1 + evidenceCount) * recencyFactor — floored at MIN_EDGE_WEIGHT. */
+declare function edgeWeight(edge: GraphEdgeLike, now: number): number;
+/**
+ * Undirected adjacency view with per-edge weights.
+ * `now` (epoch ms) drives the recency factor — pass a fixed value in tests.
+ */
+declare function buildAdjacency(data: GraphDataLike, options: {
+    now: number;
+}): Adjacency;
+interface FewestHopsOptions {
+    now?: number;
+    /** Give up beyond this many hops (default: unbounded). */
+    maxHops?: number;
+    /** Reuse a prebuilt adjacency (must match `data`). */
+    adjacency?: Adjacency;
+}
+/** BFS shortest path by hop count. Null when unreachable (or beyond maxHops). */
+declare function fewestHops(data: GraphDataLike, fromId: string, toId: string, options?: FewestHopsOptions): GraphPath | null;
+interface StrongestPathOptions {
+    /** Epoch ms for the recency factor. REQUIRED for determinism. */
+    now: number;
+    adjacency?: Adjacency;
+}
+/**
+ * Dijkstra minimizing sum(1/w): prefers few, strong, recent edges.
+ * Can legitimately return MORE hops than `fewestHops` when a longer chain of
+ * strong edges beats a weak direct edge. Null when unreachable.
+ */
+declare function strongestPath(data: GraphDataLike, fromId: string, toId: string, options: StrongestPathOptions): GraphPath | null;
+interface BridgeScoreOptions {
+    now?: number;
+    /** Max sampled node pairs (default 200). */
+    sampleSize?: number;
+    /** PRNG seed — same seed + same graph → identical scores. */
+    seed?: number;
+    /** Explicit pair list overrides sampling entirely (fully deterministic). */
+    pairs?: Array<[string, string]>;
+}
+declare const DEFAULT_BRIDGE_SAMPLE_SIZE = 200;
+declare const DEFAULT_BRIDGE_SEED = 99;
+/**
+ * Approximate betweenness: run `fewestHops` over sampled node pairs and count
+ * how often each node sits STRICTLY INSIDE the path. Normalized to [0, 1]
+ * by the max count. Deterministic given (`seed` | `pairs`) + the graph.
+ */
+declare function bridgeScores(data: GraphDataLike, options?: BridgeScoreOptions): Map<string, number>;
+/**
+ * The sub-graph within `hops` of `centerId` (entities + every edge whose two
+ * endpoints are both inside). Empty graph when the center is unknown.
+ */
+declare function neighborhood(data: GraphDataLike, centerId: string, hops: number): GraphDataLike;
+
+/**
+ * GTM decorations — pure classification helpers on top of the path engine
+ * (plan 100). Implements the POI + bridge definitions from the 2026-07-16
+ * gtm-graph spec so every consumer (desk admin route, open-agents endpoint,
+ * Shiva MCP routes) classifies nodes identically.
+ *
+ * - POI (person of interest): persons with `champion_of` /
+ *   `decision_maker_for` edges into OPEN deals, OR a decision-maker title
+ *   match on their metadata.
+ * - Bridge: top-N nodes by sampled betweenness (`bridgeScores`) — the
+ *   people/orgs the most shortest paths flow through.
+ */
+interface GtmEntityLike {
+    id: string;
+    entityType: string;
+    entityName?: string;
+    metadata?: Record<string, unknown> | null;
+}
+interface GtmEdgeLike {
+    id: string;
+    sourceEntityId: string;
+    targetEntityId: string;
+    relationshipType: string;
+    strength?: number | null;
+    evidenceCount?: number | null;
+    lastSeenAt?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+interface GtmGraphLike {
+    entities: GtmEntityLike[];
+    relationships: GtmEdgeLike[];
+}
+type GtmNodeClass = 'poi' | 'bridge' | 'other';
+/** Edge types that mark a person as tied to a deal's buying decision. */
+declare const POI_EDGE_TYPES: readonly ["champion_of", "decision_maker_for"];
+/**
+ * Canonical CLOSED pipeline stages (lowercased): deals in these stages no
+ * longer make their champions POIs. Mirrors `@bu/types/sales-pipeline`
+ * (`Activo` = won, `Nurture/Perdido` = lost) — duplicated here because this
+ * package is published standalone and cannot import `@bu/*`.
+ */
+declare const DEFAULT_CLOSED_STAGES: readonly ["activo", "nurture/perdido", "won", "lost"];
+/**
+ * Decision-maker title fragments (lowercased substring match) for the
+ * title-based POI rule. Derived from the current LATAM-agencies ICP
+ * (tasks/notes/2026-07-15-icp-enriched-r1.md in the desk repo). Hosts can
+ * override via `PoiOptions.titlePatterns`.
+ */
+declare const DEFAULT_POI_TITLE_PATTERNS: readonly ["founder", "co-founder", "cofounder", "ceo", "coo", "cfo", "owner", "partner", "managing director", "director general", "general manager", "head of finance", "head of operations", "finance manager", "operations manager"];
+interface PoiOptions {
+    /** Lowercased stage names counting as CLOSED (default: DEFAULT_CLOSED_STAGES). */
+    closedStages?: readonly string[];
+    /** Lowercased title fragments that qualify a person as POI (default: DEFAULT_POI_TITLE_PATTERNS). */
+    titlePatterns?: readonly string[];
+}
+/** True when the deal entity's `metadata.stage` is NOT in the closed set (unknown stage → open). */
+declare function isOpenDeal(deal: GtmEntityLike, closedStages?: readonly string[]): boolean;
+/**
+ * POI ids per the spec: persons with champion_of/decision_maker_for edges
+ * into OPEN deals, OR a decision-maker title match.
+ */
+declare function computePoiIds(data: GtmGraphLike, options?: PoiOptions): Set<string>;
+interface BridgeOptions {
+    /** How many top-scored nodes count as bridges (default 5). */
+    topN?: number;
+    /** Epoch ms for recency weighting (default 0 = ignore recency). */
+    now?: number;
+    /** Deterministic sampling seed forwarded to bridgeScores. */
+    seed?: number;
+    /** Explicit pair list forwarded to bridgeScores (fully deterministic). */
+    pairs?: Array<[string, string]>;
+}
+/**
+ * Top-N bridge node ids by sampled betweenness. Nodes with score 0 are never
+ * bridges, so small/star graphs can return fewer than `topN`.
+ */
+declare function computeBridgeIds(data: GtmGraphLike, options?: BridgeOptions): Set<string>;
+/** Node class from precomputed POI/bridge sets — POI wins over bridge. */
+declare function classifyNode(id: string, poiIds: ReadonlySet<string>, bridgeIds: ReadonlySet<string>): GtmNodeClass;
+/**
+ * Cap a graph at `maxNodes` keeping the highest-degree nodes (POIs/bridges
+ * always survive), plus every edge whose two endpoints survive.
+ */
+declare function capGraph(data: GtmGraphLike, maxNodes: number, pinned?: ReadonlySet<string>): GtmGraphLike;
+
+export { type Adjacency, type AdjacentEdge, type BridgeOptions, type BridgeScoreOptions, DEFAULT_BRIDGE_SAMPLE_SIZE, DEFAULT_BRIDGE_SEED, DEFAULT_CLOSED_STAGES, DEFAULT_EVIDENCE_COUNT, DEFAULT_POI_TITLE_PATTERNS, DEFAULT_STRENGTH, type FewestHopsOptions, type GraphDataLike, type GraphEdgeLike, type GraphEntityLike, type GraphPath, type GtmEdgeLike, type GtmEntityLike, type GtmGraphLike, type GtmNodeClass, MIN_EDGE_WEIGHT, POI_EDGE_TYPES, type PoiOptions, RECENCY_HALF_LIFE_DAYS, type StrongestPathOptions, bridgeScores, buildAdjacency, capGraph, classifyNode, computeBridgeIds, computePoiIds, edgeWeight, fewestHops, isOpenDeal, neighborhood, recencyFactor, strongestPath };

package/dist/algorithms/index.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Graph path / bridge engine (plan 099; re-homed here as the published SSOT
+ * in plan 100 — `packages/intelligence/src/knowledge/graph-paths.ts` is now a
+ * re-export shim of this module).
+ *
+ * PURE module: no I/O, no clocks, no randomness — every time- or
+ * order-sensitive function takes explicit `now` / `seed` / `pairs` inputs so
+ * results are deterministic and testable, and so the UI can run the same
+ * code client-side over a fetched graph payload.
+ *
+ * Operates on a camelCase graph shape structurally compatible with the
+ * `get_knowledge_graph` RPC payload (`KnowledgeGraphData` in the BUFI desk
+ * repo). NOTE: that RPC's relationship objects omit `lastSeenAt`; the weight
+ * formula treats a missing `lastSeenAt` as "fresh" (factor 1).
+ *
+ * Weight formula (documented constants below):
+ *   w = strength * ln(1 + evidenceCount) * recencyFactor(lastSeenAt, now)
+ *   recencyFactor = 0.5 ^ (daysStale / 90)   — halves per 90 stale days
+ *
+ * Scale ceiling: everything here is in-memory over the fetched graph —
+ * fine for the BUFI-internal GTM graph (thousands of edges). Past ~50k
+ * edges, graduate to pgRouting / an RPC (see the 2026-07-16 gtm-graph spec).
+ */
+interface GraphEntityLike {
+    id: string;
+}
+interface GraphEdgeLike {
+    id: string;
+    sourceEntityId: string;
+    targetEntityId: string;
+    relationshipType: string;
+    strength?: number | null;
+    evidenceCount?: number | null;
+    lastSeenAt?: string | null;
+}
+interface GraphDataLike {
+    entities: GraphEntityLike[];
+    relationships: GraphEdgeLike[];
+}
+interface AdjacentEdge {
+    edgeId: string;
+    otherId: string;
+    relationshipType: string;
+    weight: number;
+}
+/** node id → undirected incident edges (both directions materialized). */
+type Adjacency = Map<string, AdjacentEdge[]>;
+interface GraphPath {
+    /** Node ids from source to target (inclusive). */
+    nodeIds: string[];
+    /** Edge ids traversed, in order (`nodeIds.length - 1` entries). */
+    edgeIds: string[];
+    /** Hop count (= edgeIds.length). */
+    hops: number;
+    /** Sum of Dijkstra costs (1/w) — lower = stronger; 0 for the trivial path. */
+    cost: number;
+}
+/** Staleness half-life: an edge unseen for this many days weighs half. */
+declare const RECENCY_HALF_LIFE_DAYS = 90;
+/** Default strength when the payload omits it (DB default is 1.0). */
+declare const DEFAULT_STRENGTH = 1;
+/** Default evidence count when the payload omits it (DB default is 1). */
+declare const DEFAULT_EVIDENCE_COUNT = 1;
+/** Floor so degenerate edges never divide by zero in 1/w costs. */
+declare const MIN_EDGE_WEIGHT = 0.000001;
+/** 0.5^(daysStale/90); missing/unparseable lastSeenAt → 1 (fresh). */
+declare function recencyFactor(lastSeenAt: string | null | undefined, now: number): number;
+/** w = strength * ln(1 + evidenceCount) * recencyFactor — floored at MIN_EDGE_WEIGHT. */
+declare function edgeWeight(edge: GraphEdgeLike, now: number): number;
+/**
+ * Undirected adjacency view with per-edge weights.
+ * `now` (epoch ms) drives the recency factor — pass a fixed value in tests.
+ */
+declare function buildAdjacency(data: GraphDataLike, options: {
+    now: number;
+}): Adjacency;
+interface FewestHopsOptions {
+    now?: number;
+    /** Give up beyond this many hops (default: unbounded). */
+    maxHops?: number;
+    /** Reuse a prebuilt adjacency (must match `data`). */
+    adjacency?: Adjacency;
+}
+/** BFS shortest path by hop count. Null when unreachable (or beyond maxHops). */
+declare function fewestHops(data: GraphDataLike, fromId: string, toId: string, options?: FewestHopsOptions): GraphPath | null;
+interface StrongestPathOptions {
+    /** Epoch ms for the recency factor. REQUIRED for determinism. */
+    now: number;
+    adjacency?: Adjacency;
+}
+/**
+ * Dijkstra minimizing sum(1/w): prefers few, strong, recent edges.
+ * Can legitimately return MORE hops than `fewestHops` when a longer chain of
+ * strong edges beats a weak direct edge. Null when unreachable.
+ */
+declare function strongestPath(data: GraphDataLike, fromId: string, toId: string, options: StrongestPathOptions): GraphPath | null;
+interface BridgeScoreOptions {
+    now?: number;
+    /** Max sampled node pairs (default 200). */
+    sampleSize?: number;
+    /** PRNG seed — same seed + same graph → identical scores. */
+    seed?: number;
+    /** Explicit pair list overrides sampling entirely (fully deterministic). */
+    pairs?: Array<[string, string]>;
+}
+declare const DEFAULT_BRIDGE_SAMPLE_SIZE = 200;
+declare const DEFAULT_BRIDGE_SEED = 99;
+/**
+ * Approximate betweenness: run `fewestHops` over sampled node pairs and count
+ * how often each node sits STRICTLY INSIDE the path. Normalized to [0, 1]
+ * by the max count. Deterministic given (`seed` | `pairs`) + the graph.
+ */
+declare function bridgeScores(data: GraphDataLike, options?: BridgeScoreOptions): Map<string, number>;
+/**
+ * The sub-graph within `hops` of `centerId` (entities + every edge whose two
+ * endpoints are both inside). Empty graph when the center is unknown.
+ */
+declare function neighborhood(data: GraphDataLike, centerId: string, hops: number): GraphDataLike;
+
+/**
+ * GTM decorations — pure classification helpers on top of the path engine
+ * (plan 100). Implements the POI + bridge definitions from the 2026-07-16
+ * gtm-graph spec so every consumer (desk admin route, open-agents endpoint,
+ * Shiva MCP routes) classifies nodes identically.
+ *
+ * - POI (person of interest): persons with `champion_of` /
+ *   `decision_maker_for` edges into OPEN deals, OR a decision-maker title
+ *   match on their metadata.
+ * - Bridge: top-N nodes by sampled betweenness (`bridgeScores`) — the
+ *   people/orgs the most shortest paths flow through.
+ */
+interface GtmEntityLike {
+    id: string;
+    entityType: string;
+    entityName?: string;
+    metadata?: Record<string, unknown> | null;
+}
+interface GtmEdgeLike {
+    id: string;
+    sourceEntityId: string;
+    targetEntityId: string;
+    relationshipType: string;
+    strength?: number | null;
+    evidenceCount?: number | null;
+    lastSeenAt?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+interface GtmGraphLike {
+    entities: GtmEntityLike[];
+    relationships: GtmEdgeLike[];
+}
+type GtmNodeClass = 'poi' | 'bridge' | 'other';
+/** Edge types that mark a person as tied to a deal's buying decision. */
+declare const POI_EDGE_TYPES: readonly ["champion_of", "decision_maker_for"];
+/**
+ * Canonical CLOSED pipeline stages (lowercased): deals in these stages no
+ * longer make their champions POIs. Mirrors `@bu/types/sales-pipeline`
+ * (`Activo` = won, `Nurture/Perdido` = lost) — duplicated here because this
+ * package is published standalone and cannot import `@bu/*`.
+ */
+declare const DEFAULT_CLOSED_STAGES: readonly ["activo", "nurture/perdido", "won", "lost"];
+/**
+ * Decision-maker title fragments (lowercased substring match) for the
+ * title-based POI rule. Derived from the current LATAM-agencies ICP
+ * (tasks/notes/2026-07-15-icp-enriched-r1.md in the desk repo). Hosts can
+ * override via `PoiOptions.titlePatterns`.
+ */
+declare const DEFAULT_POI_TITLE_PATTERNS: readonly ["founder", "co-founder", "cofounder", "ceo", "coo", "cfo", "owner", "partner", "managing director", "director general", "general manager", "head of finance", "head of operations", "finance manager", "operations manager"];
+interface PoiOptions {
+    /** Lowercased stage names counting as CLOSED (default: DEFAULT_CLOSED_STAGES). */
+    closedStages?: readonly string[];
+    /** Lowercased title fragments that qualify a person as POI (default: DEFAULT_POI_TITLE_PATTERNS). */
+    titlePatterns?: readonly string[];
+}
+/** True when the deal entity's `metadata.stage` is NOT in the closed set (unknown stage → open). */
+declare function isOpenDeal(deal: GtmEntityLike, closedStages?: readonly string[]): boolean;
+/**
+ * POI ids per the spec: persons with champion_of/decision_maker_for edges
+ * into OPEN deals, OR a decision-maker title match.
+ */
+declare function computePoiIds(data: GtmGraphLike, options?: PoiOptions): Set<string>;
+interface BridgeOptions {
+    /** How many top-scored nodes count as bridges (default 5). */
+    topN?: number;
+    /** Epoch ms for recency weighting (default 0 = ignore recency). */
+    now?: number;
+    /** Deterministic sampling seed forwarded to bridgeScores. */
+    seed?: number;
+    /** Explicit pair list forwarded to bridgeScores (fully deterministic). */
+    pairs?: Array<[string, string]>;
+}
+/**
+ * Top-N bridge node ids by sampled betweenness. Nodes with score 0 are never
+ * bridges, so small/star graphs can return fewer than `topN`.
+ */
+declare function computeBridgeIds(data: GtmGraphLike, options?: BridgeOptions): Set<string>;
+/** Node class from precomputed POI/bridge sets — POI wins over bridge. */
+declare function classifyNode(id: string, poiIds: ReadonlySet<string>, bridgeIds: ReadonlySet<string>): GtmNodeClass;
+/**
+ * Cap a graph at `maxNodes` keeping the highest-degree nodes (POIs/bridges
+ * always survive), plus every edge whose two endpoints survive.
+ */
+declare function capGraph(data: GtmGraphLike, maxNodes: number, pinned?: ReadonlySet<string>): GtmGraphLike;
+
+export { type Adjacency, type AdjacentEdge, type BridgeOptions, type BridgeScoreOptions, DEFAULT_BRIDGE_SAMPLE_SIZE, DEFAULT_BRIDGE_SEED, DEFAULT_CLOSED_STAGES, DEFAULT_EVIDENCE_COUNT, DEFAULT_POI_TITLE_PATTERNS, DEFAULT_STRENGTH, type FewestHopsOptions, type GraphDataLike, type GraphEdgeLike, type GraphEntityLike, type GraphPath, type GtmEdgeLike, type GtmEntityLike, type GtmGraphLike, type GtmNodeClass, MIN_EDGE_WEIGHT, POI_EDGE_TYPES, type PoiOptions, RECENCY_HALF_LIFE_DAYS, type StrongestPathOptions, bridgeScores, buildAdjacency, capGraph, classifyNode, computeBridgeIds, computePoiIds, edgeWeight, fewestHops, isOpenDeal, neighborhood, recencyFactor, strongestPath };

package/dist/algorithms/index.js

@@ -0,0 +1,3 @@
+export { DEFAULT_BRIDGE_SAMPLE_SIZE, DEFAULT_BRIDGE_SEED, DEFAULT_CLOSED_STAGES, DEFAULT_EVIDENCE_COUNT, DEFAULT_POI_TITLE_PATTERNS, DEFAULT_STRENGTH, MIN_EDGE_WEIGHT, POI_EDGE_TYPES, RECENCY_HALF_LIFE_DAYS, bridgeScores, buildAdjacency, capGraph, classifyNode, computeBridgeIds, computePoiIds, edgeWeight, fewestHops, isOpenDeal, neighborhood, recencyFactor, strongestPath } from '../chunk-MW4VOWB5.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/algorithms/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}