@elizaos/plugin-rolodex 2.0.0-alpha.3

package/dist/utils/graphTraversal.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Graph traversal utilities for the entity relationship graph.
+ *
+ * Operates on an adjacency-list representation built from the
+ * runtime's relationship data. All traversals are bounded to
+ * prevent runaway computation on large graphs.
+ */
+import type { Relationship, UUID } from "@elizaos/core";
+/**
+ * An adjacency-list graph built from relationships.
+ * Maps entityId -> Set of connected entityIds.
+ */
+export type AdjacencyGraph = Map<UUID, Set<UUID>>;
+/**
+ * Build an adjacency graph from a list of relationships.
+ * Relationships are treated as undirected edges.
+ */
+export declare function buildAdjacencyGraph(relationships: Relationship[]): AdjacencyGraph;
+/**
+ * Get the N-hop neighborhood of an entity.
+ *
+ * This is the key operation for small-world entity resolution: instead
+ * of scanning all entities, we only compare against entities within
+ * a few hops. In small-world networks, 2-3 hops covers the relevant
+ * local cluster.
+ *
+ * @param graph  The adjacency graph.
+ * @param start  The starting entity.
+ * @param hops   Maximum number of hops (default 2).
+ * @param maxNodes Maximum nodes to return (safety bound, default 200).
+ * @returns Set of entity IDs within the neighborhood (excluding start).
+ */
+export declare function getNeighborhood(graph: AdjacencyGraph, start: UUID, hops?: number, maxNodes?: number): Set<UUID>;
+/**
+ * Find the shortest path between two entities using BFS.
+ *
+ * @returns Array of entity IDs forming the path, or null if no path exists.
+ *          Includes both start and end.
+ */
+export declare function shortestPath(graph: AdjacencyGraph, start: UUID, end: UUID, maxDepth?: number): UUID[] | null;
+/**
+ * Get shared connections between two entities.
+ *
+ * @returns Set of entity IDs that are directly connected to both A and B.
+ */
+export declare function sharedConnections(graph: AdjacencyGraph, entityA: UUID, entityB: UUID): Set<UUID>;
+/**
+ * Compute degree centrality for all nodes (number of direct connections).
+ * Returns nodes sorted by degree descending.
+ */
+export declare function degreeCentrality(graph: AdjacencyGraph): Array<{
+    entityId: UUID;
+    degree: number;
+}>;
+/**
+ * Detect clusters / communities using a simple label propagation approach.
+ *
+ * Each node starts with its own label. In each iteration, nodes adopt the
+ * most common label among their neighbors. Converges when labels stabilize.
+ *
+ * This is O(V + E) per iteration and typically converges in 3-5 iterations
+ * for small-world graphs.
+ *
+ * @param graph     The adjacency graph.
+ * @param maxIter   Maximum iterations (default 10).
+ * @returns Map of entityId -> clusterId.
+ */
+export declare function detectClusters(graph: AdjacencyGraph, maxIter?: number): Map<UUID, string>;
+/**
+ * Get all entities in the same cluster as the given entity.
+ */
+export declare function getClusterMembers(clusters: Map<UUID, string>, entityId: UUID): UUID[];
+/**
+ * Compute a simple "influence score" for an entity based on:
+ *  - Degree centrality (how many connections)
+ *  - Betweenness approximation (how many shortest paths pass through)
+ *
+ * The betweenness is approximated by sampling rather than computing
+ * all-pairs shortest paths (which is O(V^3)).
+ *
+ * @param graph      The adjacency graph.
+ * @param entityId   The entity to score.
+ * @param sampleSize Number of random pairs to sample for betweenness.
+ * @returns Influence score 0-1.
+ */
+export declare function influenceScore(graph: AdjacencyGraph, entityId: UUID, sampleSize?: number): number;

package/dist/utils/relationshipStrength.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Calculate relationship strength based on interaction patterns
+ *
+ * @param {Object} params - Parameters for calculating relationship strength
+ * @param {number} params.interactionCount - Total number of interactions
+ * @param {string} params.lastInteractionAt - ISO timestamp of last interaction
+ * @param {number} params.messageQuality - Average quality score of messages (0-10)
+ * @param {string} params.relationshipType - Type of relationship
+ * @returns {number} Relationship strength score (0-100)
+ */
+export declare function calculateRelationshipStrength({ interactionCount, lastInteractionAt, messageQuality, relationshipType, }: {
+    interactionCount: number;
+    lastInteractionAt?: string;
+    messageQuality?: number;
+    relationshipType?: string;
+}): number;

package/dist/utils/similarity.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Similarity and matching utilities for entity resolution.
+ *
+ * These are intentionally lightweight – no external NLP dependencies.
+ * The heavy lifting is done by the LLM; these provide fast pre-filters
+ * for candidate generation in the small-world neighborhood scan.
+ */
+/**
+ * Normalized Levenshtein distance between two strings.
+ *
+ * @returns A similarity score 0-1 where 1 means identical.
+ */
+export declare function nameSimilarity(a: string, b: string): number;
+/**
+ * Check whether two handles correlate across platforms.
+ *
+ * Strips common prefixes (@), normalizes case, and compares the
+ * underlying username. Also checks for common patterns like
+ * "dave_codes" matching "davecodes" matching "dave-codes".
+ *
+ * @returns Similarity score 0-1.
+ */
+export declare function handleCorrelation(handleA: string, handleB: string): number;
+/**
+ * Normalize a handle by stripping @, removing separators, lowering case.
+ */
+export declare function normalizeHandle(handle: string): string;
+/**
+ * Jaccard similarity between two sets.
+ *
+ * Used for comparing shared connections, shared rooms, shared topics.
+ *
+ * @returns Score 0-1 where 1 means identical sets.
+ */
+export declare function jaccardSimilarity<T>(setA: Set<T>, setB: Set<T>): number;
+/**
+ * Check if two names could be nicknames / variations of each other.
+ *
+ * Handles common patterns:
+ *  - "Dave" / "David"
+ *  - "TechGuru" / "Tech Guru"
+ *  - First name matching when one side has full name
+ *
+ * @returns Similarity score 0-1.
+ */
+export declare function nameVariationMatch(nameA: string, nameB: string): number;
+/**
+ * Extract the "base" username from a handle, stripping common suffixes
+ * like platform markers (_dev, _eth, _nft) and numbers.
+ */
+export declare function extractBaseUsername(handle: string): string;
+/**
+ * Quick check: could these two strings plausibly refer to the same
+ * entity? Used as a fast pre-filter before more expensive analysis.
+ *
+ * @returns true if there's enough signal to warrant deeper comparison.
+ */
+export declare function couldBeSameEntity(nameA: string, nameB: string): boolean;

package/dist/utils/timeWeighting.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Time-weighted confidence decay.
+ *
+ * Based on the Ebbinghaus forgetting curve, adapted for information
+ * reliability: confidence decays with a configurable half-life, and
+ * corroborations increase stability (each corroboration doubles the
+ * effective half-life).
+ *
+ * Formula: confidence(t) = baseConfidence * 0.5^(elapsed / effectiveHalfLife)
+ *
+ * References:
+ *  - Ebbinghaus, H. (1885). Memory: A Contribution to Experimental Psychology.
+ *  - Leitner spaced-repetition stability model.
+ */
+import type { InformationClaim } from "../types/index";
+/**
+ * Compute the current confidence of a claim, accounting for time decay
+ * and corroboration stability.
+ *
+ * @param claim The information claim to evaluate.
+ * @param now   Current timestamp (ms). Defaults to Date.now().
+ * @returns     The decayed confidence, clamped to [0, 1].
+ */
+export declare function computeDecayedConfidence(claim: InformationClaim, now?: number): number;
+/**
+ * Each corroboration doubles the half-life, making information stickier
+ * the more people confirm it.  Disputes halve it.
+ *
+ * effectiveHalfLife = halfLifeMs * 2^(corroborations - unresolvedDisputes)
+ *
+ * Clamped so it never drops below 1 day or exceeds 365 days (unless
+ * the base half-life is already Infinity for ground truth).
+ */
+export declare function getEffectiveHalfLife(claim: InformationClaim): number;
+/**
+ * Compute decayed relationship strength.
+ *
+ * Uses the same half-life model: strength decays from its base value
+ * since the last interaction.
+ *
+ * @param baseStrength   The strength at last interaction (0-100).
+ * @param lastInteractionAt ISO timestamp of last interaction.
+ * @param halfLifeMs     Decay half-life in ms.
+ * @param now            Current timestamp.
+ * @returns              Decayed strength (0-100).
+ */
+export declare function computeRelationshipDecay(baseStrength: number, lastInteractionAt: string | undefined, halfLifeMs: number, now?: number): number;
+/**
+ * Compute a new base confidence after a corroboration event.
+ *
+ * Each corroboration nudges the base confidence upward using a
+ * diminishing-returns formula:
+ *   newBase = oldBase + (1 - oldBase) * boostFactor
+ *
+ * where boostFactor decreases with each successive corroboration.
+ */
+export declare function boostConfidenceFromCorroboration(currentBase: number, corroborationCount: number): number;
+/**
+ * Reduce confidence when a dispute is filed.
+ *
+ * Drops base confidence by a penalty that scales with how many unresolved
+ * disputes exist vs corroborations.
+ */
+export declare function penalizeConfidenceFromDispute(currentBase: number, unresolvedDisputeCount: number, corroborationCount: number): number;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@elizaos/plugin-rolodex",
+  "version": "2.0.0-alpha.3",
+  "description": "A plugin for ElizaOS that allows you to manage entites, relationships and associations",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun run build.ts",
+    "dev": "bun run build.ts --watch",
+    "test": "elizaos test",
+    "clean": "rm -rf dist .turbo node_modules",
+    "lint": "bunx @biomejs/biome check --write --unsafe .",
+    "lint:check": "bunx @biomejs/biome check .",
+    "format": "bunx @biomejs/biome format --write .",
+    "format:check": "bunx @biomejs/biome format .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@elizaos/core": "2.0.0-alpha.3",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^3.4.0"
+  },
+  "peerDependencies": {
+    "whatwg-url": "7.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "tailwindcss": "^4.1.10",
+    "tsup": "8.5.0",
+    "vite": "^6.3.5",
+    "vitest": "3.1.4",
+    "zod": "^3.22.4",
+    "@biomejs/biome": "^2.3.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}