@danielsimonjr/memory-mcp 12.5.2 → 12.7.0

package/dist/core/GraphTraversal.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Graph Traversal
+ *
+ * Phase 4 Sprints 6-8: Graph traversal algorithms for knowledge graph analysis.
+ * Includes BFS, DFS, shortest path, all paths, connected components, and centrality.
+ *
+ * @module core/GraphTraversal
+ */
+import type { Relation, TraversalOptions, TraversalResult, PathResult, ConnectedComponentsResult, CentralityResult } from '../types/index.js';
+import type { GraphStorage } from './GraphStorage.js';
+/**
+ * Graph traversal algorithms for knowledge graph analysis.
+ *
+ * Provides BFS, DFS, shortest path finding, connected component detection,
+ * and centrality metrics for analyzing graph structure.
+ */
+export declare class GraphTraversal {
+    private storage;
+    constructor(storage: GraphStorage);
+    /**
+     * Get neighbors of a node based on traversal direction and filters.
+     *
+     * @param entityName - Entity to get neighbors for
+     * @param options - Traversal options
+     * @returns Array of neighbor entity names with their relations
+     */
+    getNeighborsWithRelations(entityName: string, options?: TraversalOptions): Array<{
+        neighbor: string;
+        relation: Relation;
+    }>;
+    /**
+     * Breadth-First Search traversal starting from a given entity.
+     *
+     * @param startEntity - Entity name to start traversal from
+     * @param options - Traversal options
+     * @returns Traversal result with visited nodes, depths, and parent pointers
+     */
+    bfs(startEntity: string, options?: TraversalOptions): TraversalResult;
+    /**
+     * Depth-First Search traversal starting from a given entity.
+     *
+     * @param startEntity - Entity name to start traversal from
+     * @param options - Traversal options
+     * @returns Traversal result with visited nodes, depths, and parent pointers
+     */
+    dfs(startEntity: string, options?: TraversalOptions): TraversalResult;
+    /**
+     * Find the shortest path between two entities using BFS.
+     *
+     * @param source - Source entity name
+     * @param target - Target entity name
+     * @param options - Traversal options
+     * @returns PathResult if path exists, null otherwise
+     */
+    findShortestPath(source: string, target: string, options?: TraversalOptions): Promise<PathResult | null>;
+    /**
+     * Reconstruct path from parent pointers.
+     */
+    private reconstructPath;
+    /**
+     * Find all paths between two entities up to a maximum depth.
+     *
+     * @param source - Source entity name
+     * @param target - Target entity name
+     * @param maxDepth - Maximum path length (default: 5)
+     * @param options - Traversal options
+     * @returns Array of PathResult objects for all found paths
+     */
+    findAllPaths(source: string, target: string, maxDepth?: number, options?: TraversalOptions): Promise<PathResult[]>;
+    /**
+     * Find all connected components in the graph.
+     *
+     * Uses BFS to find all weakly connected components (treating the graph as undirected).
+     *
+     * @returns ConnectedComponentsResult with all components
+     */
+    findConnectedComponents(): Promise<ConnectedComponentsResult>;
+    /**
+     * Calculate degree centrality for all entities.
+     *
+     * Degree centrality is the number of connections an entity has,
+     * normalized by the maximum possible connections.
+     *
+     * @param direction - Direction to count: 'in', 'out', or 'both' (default)
+     * @param topN - Number of top entities to return (default: 10)
+     * @returns CentralityResult with scores and top entities
+     */
+    calculateDegreeCentrality(direction?: 'in' | 'out' | 'both', topN?: number): Promise<CentralityResult>;
+    /**
+     * Calculate betweenness centrality for all entities.
+     *
+     * Betweenness centrality measures how often a node appears on shortest paths
+     * between other nodes. Uses Brandes' algorithm for efficiency.
+     *
+     * @param options - Configuration options
+     * @param options.topN - Number of top entities to return (default: 10)
+     * @param options.chunkSize - Yield control every N vertices (default: 50)
+     * @param options.onProgress - Progress callback (0.0 to 1.0)
+     * @param options.approximate - Use approximation for faster results (default: false)
+     * @param options.sampleRate - Sample rate for approximation (default: 0.2)
+     * @returns CentralityResult with scores and top entities
+     */
+    calculateBetweennessCentrality(options?: {
+        topN?: number;
+        chunkSize?: number;
+        onProgress?: (progress: number) => void;
+        approximate?: boolean;
+        sampleRate?: number;
+    }): Promise<CentralityResult>;
+    /**
+     * Sample entities randomly for approximation algorithms.
+     *
+     * @param entities - Array of entities to sample from
+     * @param sampleSize - Number of entities to sample
+     * @returns Array of sampled entities
+     */
+    private sampleEntities;
+    /**
+     * Calculate PageRank centrality for all entities.
+     *
+     * PageRank measures importance based on incoming connections from
+     * other important nodes. Uses iterative power method.
+     *
+     * @param dampingFactor - Damping factor (default: 0.85)
+     * @param maxIterations - Maximum iterations (default: 100)
+     * @param tolerance - Convergence tolerance (default: 1e-6)
+     * @param topN - Number of top entities to return (default: 10)
+     * @returns CentralityResult with scores and top entities
+     */
+    calculatePageRank(dampingFactor?: number, maxIterations?: number, tolerance?: number, topN?: number): Promise<CentralityResult>;
+    /**
+     * Get top N entities from a scores map.
+     */
+    private getTopEntities;
+}
+//# sourceMappingURL=GraphTraversal.d.ts.map

package/dist/core/GraphTraversal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphTraversal.d.ts","sourceRoot":"","sources":["../../src/core/GraphTraversal.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAEV,QAAQ,EACR,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,yBAAyB,EACzB,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAYtD;;;;;GAKG;AACH,qBAAa,cAAc;IACb,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY;IAIzC;;;;;;OAMG;IACH,yBAAyB,CACvB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,gBAAqB,GAC7B,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,QAAQ,CAAA;KAAE,CAAC;IA4ClD;;;;;;OAMG;IACH,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,eAAe;IAwCzE;;;;;;OAMG;IACH,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,eAAe;IA8CzE;;;;;;;OAOG;IACG,gBAAgB,CACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IA6C7B;;OAEG;IACH,OAAO,CAAC,eAAe;IA2BvB;;;;;;;;OAQG;IACG,YAAY,CAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,GAAE,MAAU,EACpB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,UAAU,EAAE,CAAC;IAiDxB;;;;;;OAMG;IACG,uBAAuB,IAAI,OAAO,CAAC,yBAAyB,CAAC;IA0CnE;;;;;;;;;OASG;IACG,yBAAyB,CAC7B,SAAS,GAAE,IAAI,GAAG,KAAK,GAAG,MAAe,EACzC,IAAI,GAAE,MAAW,GAChB,OAAO,CAAC,gBAAgB,CAAC;IA+B5B;;;;;;;;;;;;;OAaG;IACG,8BAA8B,CAClC,OAAO,GAAE;QACP,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;QACxC,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;KAChB,GACL,OAAO,CAAC,gBAAgB,CAAC;IAiH5B;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAUtB;;;;;;;;;;;OAWG;IACG,iBAAiB,CACrB,aAAa,GAAE,MAAa,EAC5B,aAAa,GAAE,MAAY,EAC3B,SAAS,GAAE,MAAa,EACxB,IAAI,GAAE,MAAW,GAChB,OAAO,CAAC,gBAAgB,CAAC;IA0E5B;;OAEG;IACH,OAAO,CAAC,cAAc;CASvB"}

package/dist/core/GraphTraversal.js

@@ -0,0 +1,556 @@
+/**
+ * Graph Traversal
+ *
+ * Phase 4 Sprints 6-8: Graph traversal algorithms for knowledge graph analysis.
+ * Includes BFS, DFS, shortest path, all paths, connected components, and centrality.
+ *
+ * @module core/GraphTraversal
+ */
+/**
+ * Phase 4 Sprint 6: Default traversal options.
+ */
+const DEFAULT_OPTIONS = {
+    direction: 'both',
+    maxDepth: Infinity,
+    relationTypes: [],
+    entityTypes: [],
+};
+/**
+ * Graph traversal algorithms for knowledge graph analysis.
+ *
+ * Provides BFS, DFS, shortest path finding, connected component detection,
+ * and centrality metrics for analyzing graph structure.
+ */
+export class GraphTraversal {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    // ==================== Sprint 6: BFS and DFS Traversal ====================
+    /**
+     * Get neighbors of a node based on traversal direction and filters.
+     *
+     * @param entityName - Entity to get neighbors for
+     * @param options - Traversal options
+     * @returns Array of neighbor entity names with their relations
+     */
+    getNeighborsWithRelations(entityName, options = {}) {
+        // Filter out undefined values before merging with defaults
+        const definedOptions = Object.fromEntries(Object.entries(options).filter(([, v]) => v !== undefined));
+        const opts = { ...DEFAULT_OPTIONS, ...definedOptions };
+        const neighbors = [];
+        // Get relations based on direction
+        let relations = [];
+        if (opts.direction === 'outgoing' || opts.direction === 'both') {
+            relations = relations.concat(this.storage.getRelationsFrom(entityName));
+        }
+        if (opts.direction === 'incoming' || opts.direction === 'both') {
+            relations = relations.concat(this.storage.getRelationsTo(entityName));
+        }
+        // Filter by relation types if specified
+        if (opts.relationTypes && opts.relationTypes.length > 0) {
+            const typeSet = new Set(opts.relationTypes.map(t => t.toLowerCase()));
+            relations = relations.filter(r => typeSet.has(r.relationType.toLowerCase()));
+        }
+        // Process relations to get neighbors
+        for (const relation of relations) {
+            const neighbor = relation.from === entityName ? relation.to : relation.from;
+            // Skip self-loops
+            if (neighbor === entityName)
+                continue;
+            // Filter by entity types if specified
+            if (opts.entityTypes && opts.entityTypes.length > 0) {
+                const entity = this.storage.getEntityByName(neighbor);
+                if (!entity)
+                    continue;
+                const typeSet = new Set(opts.entityTypes.map(t => t.toLowerCase()));
+                if (!typeSet.has(entity.entityType.toLowerCase()))
+                    continue;
+            }
+            neighbors.push({ neighbor, relation });
+        }
+        return neighbors;
+    }
+    /**
+     * Breadth-First Search traversal starting from a given entity.
+     *
+     * @param startEntity - Entity name to start traversal from
+     * @param options - Traversal options
+     * @returns Traversal result with visited nodes, depths, and parent pointers
+     */
+    bfs(startEntity, options = {}) {
+        const opts = { ...DEFAULT_OPTIONS, ...options };
+        // Validate start entity exists
+        if (!this.storage.hasEntity(startEntity)) {
+            return { nodes: [], depths: new Map(), parents: new Map() };
+        }
+        const visited = new Set();
+        const queue = [{ node: startEntity, depth: 0 }];
+        const nodes = [];
+        const depths = new Map();
+        const parents = new Map();
+        visited.add(startEntity);
+        parents.set(startEntity, null);
+        while (queue.length > 0) {
+            const { node, depth } = queue.shift();
+            // Respect maxDepth limit
+            if (depth > opts.maxDepth)
+                continue;
+            nodes.push(node);
+            depths.set(node, depth);
+            // Get neighbors and add unvisited ones to queue
+            const neighbors = this.getNeighborsWithRelations(node, opts);
+            for (const { neighbor } of neighbors) {
+                if (!visited.has(neighbor)) {
+                    visited.add(neighbor);
+                    queue.push({ node: neighbor, depth: depth + 1 });
+                    parents.set(neighbor, node);
+                }
+            }
+        }
+        return { nodes, depths, parents };
+    }
+    /**
+     * Depth-First Search traversal starting from a given entity.
+     *
+     * @param startEntity - Entity name to start traversal from
+     * @param options - Traversal options
+     * @returns Traversal result with visited nodes, depths, and parent pointers
+     */
+    dfs(startEntity, options = {}) {
+        const opts = { ...DEFAULT_OPTIONS, ...options };
+        // Validate start entity exists
+        if (!this.storage.hasEntity(startEntity)) {
+            return { nodes: [], depths: new Map(), parents: new Map() };
+        }
+        const visited = new Set();
+        const stack = [{ node: startEntity, depth: 0 }];
+        const nodes = [];
+        const depths = new Map();
+        const parents = new Map();
+        parents.set(startEntity, null);
+        while (stack.length > 0) {
+            const { node, depth } = stack.pop();
+            // Skip if already visited
+            if (visited.has(node))
+                continue;
+            // Respect maxDepth limit
+            if (depth > opts.maxDepth)
+                continue;
+            visited.add(node);
+            nodes.push(node);
+            depths.set(node, depth);
+            // Get neighbors and add unvisited ones to stack
+            const neighbors = this.getNeighborsWithRelations(node, opts);
+            for (const { neighbor } of neighbors) {
+                if (!visited.has(neighbor)) {
+                    stack.push({ node: neighbor, depth: depth + 1 });
+                    if (!parents.has(neighbor)) {
+                        parents.set(neighbor, node);
+                    }
+                }
+            }
+        }
+        return { nodes, depths, parents };
+    }
+    // ==================== Sprint 7: Path Finding Algorithms ====================
+    /**
+     * Find the shortest path between two entities using BFS.
+     *
+     * @param source - Source entity name
+     * @param target - Target entity name
+     * @param options - Traversal options
+     * @returns PathResult if path exists, null otherwise
+     */
+    async findShortestPath(source, target, options = {}) {
+        // Ensure graph is loaded to populate indexes
+        await this.storage.loadGraph();
+        // Validate entities exist
+        if (!this.storage.hasEntity(source) || !this.storage.hasEntity(target)) {
+            return null;
+        }
+        // Same source and target
+        if (source === target) {
+            return { path: [source], length: 0, relations: [] };
+        }
+        const opts = { ...DEFAULT_OPTIONS, ...options };
+        const visited = new Set();
+        const queue = [source];
+        const parents = new Map();
+        visited.add(source);
+        parents.set(source, null);
+        while (queue.length > 0) {
+            const current = queue.shift();
+            // Found target, reconstruct path
+            if (current === target) {
+                return this.reconstructPath(source, target, parents);
+            }
+            // Get neighbors
+            const neighbors = this.getNeighborsWithRelations(current, opts);
+            for (const { neighbor, relation } of neighbors) {
+                if (!visited.has(neighbor)) {
+                    visited.add(neighbor);
+                    queue.push(neighbor);
+                    parents.set(neighbor, { parent: current, relation });
+                }
+            }
+        }
+        // No path found
+        return null;
+    }
+    /**
+     * Reconstruct path from parent pointers.
+     */
+    reconstructPath(_source, target, parents) {
+        const path = [];
+        const relations = [];
+        let current = target;
+        while (current !== null) {
+            path.unshift(current);
+            const parentInfo = parents.get(current);
+            if (parentInfo) {
+                relations.unshift(parentInfo.relation);
+                current = parentInfo.parent;
+            }
+            else {
+                current = null;
+            }
+        }
+        return {
+            path,
+            length: path.length - 1,
+            relations,
+        };
+    }
+    /**
+     * Find all paths between two entities up to a maximum depth.
+     *
+     * @param source - Source entity name
+     * @param target - Target entity name
+     * @param maxDepth - Maximum path length (default: 5)
+     * @param options - Traversal options
+     * @returns Array of PathResult objects for all found paths
+     */
+    async findAllPaths(source, target, maxDepth = 5, options = {}) {
+        // Ensure graph is loaded to populate indexes
+        await this.storage.loadGraph();
+        // Validate entities exist
+        if (!this.storage.hasEntity(source) || !this.storage.hasEntity(target)) {
+            return [];
+        }
+        const opts = { ...DEFAULT_OPTIONS, ...options };
+        const allPaths = [];
+        const currentPath = [source];
+        const currentRelations = [];
+        const visited = new Set([source]);
+        const dfsAllPaths = (current, depth) => {
+            if (depth > maxDepth)
+                return;
+            if (current === target && depth > 0) {
+                allPaths.push({
+                    path: [...currentPath],
+                    length: currentPath.length - 1,
+                    relations: [...currentRelations],
+                });
+                return;
+            }
+            const neighbors = this.getNeighborsWithRelations(current, opts);
+            for (const { neighbor, relation } of neighbors) {
+                if (!visited.has(neighbor)) {
+                    visited.add(neighbor);
+                    currentPath.push(neighbor);
+                    currentRelations.push(relation);
+                    dfsAllPaths(neighbor, depth + 1);
+                    currentPath.pop();
+                    currentRelations.pop();
+                    visited.delete(neighbor);
+                }
+            }
+        };
+        dfsAllPaths(source, 0);
+        return allPaths;
+    }
+    // ==================== Sprint 8: Connected Components ====================
+    /**
+     * Find all connected components in the graph.
+     *
+     * Uses BFS to find all weakly connected components (treating the graph as undirected).
+     *
+     * @returns ConnectedComponentsResult with all components
+     */
+    async findConnectedComponents() {
+        const graph = await this.storage.loadGraph();
+        const visited = new Set();
+        const components = [];
+        for (const entity of graph.entities) {
+            if (!visited.has(entity.name)) {
+                // BFS to find all nodes in this component
+                const component = [];
+                const queue = [entity.name];
+                visited.add(entity.name);
+                while (queue.length > 0) {
+                    const current = queue.shift();
+                    component.push(current);
+                    // Get all neighbors (both directions for weakly connected)
+                    const neighbors = this.getNeighborsWithRelations(current, { direction: 'both' });
+                    for (const { neighbor } of neighbors) {
+                        if (!visited.has(neighbor)) {
+                            visited.add(neighbor);
+                            queue.push(neighbor);
+                        }
+                    }
+                }
+                components.push(component);
+            }
+        }
+        // Sort components by size (largest first)
+        components.sort((a, b) => b.length - a.length);
+        return {
+            components,
+            count: components.length,
+            largestComponentSize: components.length > 0 ? components[0].length : 0,
+        };
+    }
+    // ==================== Sprint 8: Centrality Algorithms ====================
+    /**
+     * Calculate degree centrality for all entities.
+     *
+     * Degree centrality is the number of connections an entity has,
+     * normalized by the maximum possible connections.
+     *
+     * @param direction - Direction to count: 'in', 'out', or 'both' (default)
+     * @param topN - Number of top entities to return (default: 10)
+     * @returns CentralityResult with scores and top entities
+     */
+    async calculateDegreeCentrality(direction = 'both', topN = 10) {
+        const graph = await this.storage.loadGraph();
+        const scores = new Map();
+        const n = graph.entities.length;
+        // Calculate degree for each entity
+        for (const entity of graph.entities) {
+            let degree = 0;
+            if (direction === 'in' || direction === 'both') {
+                degree += this.storage.getRelationsTo(entity.name).length;
+            }
+            if (direction === 'out' || direction === 'both') {
+                degree += this.storage.getRelationsFrom(entity.name).length;
+            }
+            // Normalize by maximum possible degree
+            const normalizedDegree = n > 1 ? degree / (n - 1) : 0;
+            scores.set(entity.name, normalizedDegree);
+        }
+        // Get top N entities
+        const topEntities = this.getTopEntities(scores, topN);
+        return {
+            scores,
+            topEntities,
+            algorithm: 'degree',
+        };
+    }
+    /**
+     * Calculate betweenness centrality for all entities.
+     *
+     * Betweenness centrality measures how often a node appears on shortest paths
+     * between other nodes. Uses Brandes' algorithm for efficiency.
+     *
+     * @param options - Configuration options
+     * @param options.topN - Number of top entities to return (default: 10)
+     * @param options.chunkSize - Yield control every N vertices (default: 50)
+     * @param options.onProgress - Progress callback (0.0 to 1.0)
+     * @param options.approximate - Use approximation for faster results (default: false)
+     * @param options.sampleRate - Sample rate for approximation (default: 0.2)
+     * @returns CentralityResult with scores and top entities
+     */
+    async calculateBetweennessCentrality(options = {}) {
+        const { topN = 10, chunkSize = 50, onProgress, approximate = false, sampleRate = 0.2 } = options;
+        const graph = await this.storage.loadGraph();
+        const scores = new Map();
+        // Initialize scores
+        for (const entity of graph.entities) {
+            scores.set(entity.name, 0);
+        }
+        // Determine which sources to process (full or sampled)
+        let sourcesToProcess = graph.entities;
+        if (approximate && graph.entities.length > 100) {
+            const sampleSize = Math.max(10, Math.floor(graph.entities.length * sampleRate));
+            sourcesToProcess = this.sampleEntities(graph.entities, sampleSize);
+        }
+        // Brandes' algorithm with chunked processing
+        let processed = 0;
+        for (const source of sourcesToProcess) {
+            const stack = [];
+            const predecessors = new Map();
+            const sigma = new Map(); // Number of shortest paths
+            const distance = new Map(); // Distance from source
+            const delta = new Map(); // Dependency
+            // Initialize
+            for (const entity of graph.entities) {
+                predecessors.set(entity.name, []);
+                sigma.set(entity.name, 0);
+                distance.set(entity.name, -1);
+                delta.set(entity.name, 0);
+            }
+            sigma.set(source.name, 1);
+            distance.set(source.name, 0);
+            // BFS
+            const queue = [source.name];
+            while (queue.length > 0) {
+                const v = queue.shift();
+                stack.push(v);
+                const neighbors = this.getNeighborsWithRelations(v, { direction: 'both' });
+                for (const { neighbor: w } of neighbors) {
+                    // First time w is discovered
+                    if (distance.get(w) === -1) {
+                        distance.set(w, distance.get(v) + 1);
+                        queue.push(w);
+                    }
+                    // w is on a shortest path from source via v
+                    if (distance.get(w) === distance.get(v) + 1) {
+                        sigma.set(w, sigma.get(w) + sigma.get(v));
+                        predecessors.get(w).push(v);
+                    }
+                }
+            }
+            // Accumulation
+            while (stack.length > 0) {
+                const w = stack.pop();
+                for (const v of predecessors.get(w)) {
+                    const contribution = (sigma.get(v) / sigma.get(w)) * (1 + delta.get(w));
+                    delta.set(v, delta.get(v) + contribution);
+                }
+                if (w !== source.name) {
+                    scores.set(w, scores.get(w) + delta.get(w));
+                }
+            }
+            // Yield control periodically to prevent blocking event loop
+            processed++;
+            if (processed % chunkSize === 0) {
+                // Yield control to allow event loop to process other events
+                await new Promise(resolve => setImmediate(resolve));
+                // Report progress
+                if (onProgress) {
+                    onProgress(processed / sourcesToProcess.length);
+                }
+            }
+        }
+        // Final progress update
+        if (onProgress) {
+            onProgress(1);
+        }
+        // Scale scores if using approximation
+        if (approximate && sampleRate < 1.0) {
+            const scaleFactor = 1 / sampleRate;
+            for (const [entity, score] of scores) {
+                scores.set(entity, score * scaleFactor);
+            }
+        }
+        // Normalize scores
+        const n = graph.entities.length;
+        const normalization = n > 2 ? 2 / ((n - 1) * (n - 2)) : 1;
+        for (const [name, score] of scores) {
+            scores.set(name, score * normalization);
+        }
+        const topEntities = this.getTopEntities(scores, topN);
+        return {
+            scores,
+            topEntities,
+            algorithm: 'betweenness',
+        };
+    }
+    /**
+     * Sample entities randomly for approximation algorithms.
+     *
+     * @param entities - Array of entities to sample from
+     * @param sampleSize - Number of entities to sample
+     * @returns Array of sampled entities
+     */
+    sampleEntities(entities, sampleSize) {
+        const shuffled = [...entities];
+        // Fisher-Yates shuffle
+        for (let i = shuffled.length - 1; i > 0; i--) {
+            const j = Math.floor(Math.random() * (i + 1));
+            [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+        }
+        return shuffled.slice(0, sampleSize);
+    }
+    /**
+     * Calculate PageRank centrality for all entities.
+     *
+     * PageRank measures importance based on incoming connections from
+     * other important nodes. Uses iterative power method.
+     *
+     * @param dampingFactor - Damping factor (default: 0.85)
+     * @param maxIterations - Maximum iterations (default: 100)
+     * @param tolerance - Convergence tolerance (default: 1e-6)
+     * @param topN - Number of top entities to return (default: 10)
+     * @returns CentralityResult with scores and top entities
+     */
+    async calculatePageRank(dampingFactor = 0.85, maxIterations = 100, tolerance = 1e-6, topN = 10) {
+        const graph = await this.storage.loadGraph();
+        const n = graph.entities.length;
+        if (n === 0) {
+            return { scores: new Map(), topEntities: [], algorithm: 'pagerank' };
+        }
+        // Initialize PageRank scores
+        const scores = new Map();
+        const initialScore = 1 / n;
+        for (const entity of graph.entities) {
+            scores.set(entity.name, initialScore);
+        }
+        // Build outgoing links map
+        const outLinks = new Map();
+        for (const entity of graph.entities) {
+            const outgoing = this.storage.getRelationsFrom(entity.name);
+            outLinks.set(entity.name, outgoing.map(r => r.to));
+        }
+        // Power iteration
+        for (let iteration = 0; iteration < maxIterations; iteration++) {
+            const newScores = new Map();
+            let totalDiff = 0;
+            // Calculate dangling node contribution (nodes with no outgoing links)
+            let danglingSum = 0;
+            for (const entity of graph.entities) {
+                if (outLinks.get(entity.name).length === 0) {
+                    danglingSum += scores.get(entity.name);
+                }
+            }
+            const danglingContribution = (dampingFactor * danglingSum) / n;
+            // Calculate new scores
+            for (const entity of graph.entities) {
+                let incomingScore = 0;
+                const incoming = this.storage.getRelationsTo(entity.name);
+                for (const relation of incoming) {
+                    const source = relation.from;
+                    const sourceOutCount = outLinks.get(source)?.length || 1;
+                    incomingScore += scores.get(source) / sourceOutCount;
+                }
+                const newScore = (1 - dampingFactor) / n + dampingFactor * incomingScore + danglingContribution;
+                newScores.set(entity.name, newScore);
+                totalDiff += Math.abs(newScore - scores.get(entity.name));
+            }
+            // Update scores
+            for (const [name, score] of newScores) {
+                scores.set(name, score);
+            }
+            // Check convergence
+            if (totalDiff < tolerance) {
+                break;
+            }
+        }
+        const topEntities = this.getTopEntities(scores, topN);
+        return {
+            scores,
+            topEntities,
+            algorithm: 'pagerank',
+        };
+    }
+    /**
+     * Get top N entities from a scores map.
+     */
+    getTopEntities(scores, topN) {
+        return Array.from(scores.entries())
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, topN)
+            .map(([name, score]) => ({ name, score }));
+    }
+}