How the Louvain Community Detection Algorithm Works in LLM Wiki: Graph-Based Knowledge Clustering

LLM Wiki applies the Louvain method to its internal link graph to automatically discover densely-connected communities of related pages and calculate cohesion scores that measure group interconnectedness.

The Louvain community detection algorithm serves as the backbone of topic clustering in LLM Wiki, transforming the unstructured web of internal links into organized, navigable knowledge groups. By treating each wiki page as a node and each hyperlink as an edge, the system identifies natural content communities without manual tagging. This analysis examines the production implementation found in src/lib/wiki-graph-analysis.ts and the supporting type definitions in src/lib/wiki-graph.ts.

Graph Construction and Representation

The pipeline begins by constructing an undirected graph using the Graphology library. The detectCommunities function initializes a new graph instance and populates it with the wiki's structural data.

Nodes are added using graph.addNode(node.id) for every page in the knowledge base. For edges, the implementation calls graph.addEdgeWithKey to create weighted connections between linked pages while explicitly preventing duplicate edges. This deduplication ensures that multiple references between the same pair of pages do not skew community detection results.

The resulting structure represents the complete wiki topology as an undirected, weighted graph where edge weights reflect link strength between related content.

Running the Louvain Algorithm

Once the graph is constructed, the system invokes the specialized graphology-communities-louvain package to perform the actual partition optimization. The function signature used is:

const communityMap: Record<string, number> = louvain(graph, { resolution: 1 })

This returns a mapping from node ID to community ID, effectively assigning each wiki page to a specific cluster. The resolution parameter directly controls granularity: values less than 1 produce coarser communities (fewer, larger groups), while values greater than 1 yield finer-grained partitions (more, smaller groups). The default resolution of 1 provides a balanced clustering suitable for general topic organization.

Community Analysis and Metrics Calculation

After obtaining the initial assignments, the implementation performs several analytical passes to compute meaningful community statistics.

Node Grouping and Edge Counting

The code transforms the flat communityMap into a Map<number, string[]> structure that groups node IDs by their assigned community. It then iterates through the original edge list to tally intra-community edges—connections where both endpoints share the same community ID. This count is stored in intraEdgesByCommunity for subsequent calculations.

Cohesion and Top Node Detection

For each discovered community, the system calculates four key metrics:

1. Node Count: The total number of pages belonging to the community.
2. Possible Edges: The theoretical maximum calculated as nodeCount * (nodeCount - 1) / 2, representing a fully-connected subgraph.
3. Cohesion Score: The ratio of intraEdges / possibleEdges, where a value of 1.0 indicates a completely interconnected community (clique) and lower values indicate sparser connectivity.
4. Top Nodes: The five pages with the highest linkCount (most outgoing connections) within the community, sorted in descending order to identify central hub pages.

ID Remapping and Sorting

To ensure consistent UI presentation, communities are sorted by descending node count. The system then remaps community IDs to a consecutive range (0 through N-1), eliminating gaps that may exist in the raw Louvain output. This normalization simplifies frontend consumption and ensures predictable ordering.

Web Worker Integration for Performance

To maintain UI responsiveness during computation, LLM Wiki offloads the detection process to a dedicated Web Worker implemented in src/lib/wiki-graph-analysis.worker.ts. This architecture prevents graph analysis from blocking the main thread, allowing users to continue interacting with the wiki while the algorithm processes potentially thousands of nodes and edges in the background.

Practical Implementation Example

The following TypeScript example demonstrates how to invoke the community detection pipeline using the actual LLM Wiki API:

import { detectCommunities } from "./lib/wiki-graph-analysis"

// Define wiki pages with metadata
const nodes = [
  { id: "pageA", label: "Machine Learning Basics", linkCount: 12 },
  { id: "pageB", label: "Neural Networks", linkCount: 8 },
  { id: "pageC", label: "Deep Learning", linkCount: 15 },
  { id: "pageD", label: "Ancient History", linkCount: 3 },
]

// Define internal links between pages
const edges = [
  { source: "pageA", target: "pageB", weight: 1 },
  { source: "pageA", target: "pageC", weight: 1 },
  { source: "pageB", target: "pageC", weight: 1 },
  { source: "pageD", target: "pageA", weight: 0.5 }, // Weak cross-topic link
]

// Execute detection
const { assignments, communities } = detectCommunities(nodes, edges)

// View individual page assignments
for (const [nodeId, communityId] of assignments) {
  console.log(`${nodeId} → community ${communityId}`)
}

// Analyze community structure
communities.forEach(c => {
  console.log(`Community ${c.id}: ${c.nodeCount} pages, cohesion ${c.cohesion.toFixed(2)}`)
  console.log(`Central pages: ${c.topNodes.join(", ")}`)
})

This example illustrates how the algorithm separates the machine learning topics (pages A, B, C) from unrelated content (page D) based purely on connectivity patterns.

Summary

• Graph Representation: LLM Wiki builds an undirected Graphology graph from page nodes and link edges in src/lib/wiki-graph-analysis.ts.
• Louvain Execution: The graphology-communities-louvain package partitions the graph using a configurable resolution parameter to control community granularity.
• Cohesion Metrics: Communities are evaluated using the ratio of actual internal edges to possible edges, identifying tightly-knit knowledge clusters.
• Performance Optimization: Heavy computation runs inside src/lib/wiki-graph-analysis.worker.ts to prevent UI blocking.
• Hub Identification: Each community surfaces its top five most-connected pages to highlight central reference materials.

Frequently Asked Questions

What is the Louvain algorithm used for in LLM Wiki?

The Louvain algorithm automatically organizes the wiki's knowledge base by detecting communities of densely interconnected pages. According to the nashsu/llm_wiki source code, this eliminates the need for manual categorization while ensuring that related topics are grouped together based on actual link patterns rather than superficial tags.

How is community cohesion calculated?

Cohesion measures how tightly-knit a community is by dividing the count of actual intra-community edges by the number of possible edges in a complete graph of that size. In src/lib/wiki-graph-analysis.ts, this is computed as intraEdges / (nodeCount * (nodeCount - 1) / 2), producing a score between 0 and 1 where higher values indicate stronger internal connectivity.

What does the resolution parameter control?

The resolution parameter passed to graphology-communities-louvain adjusts the granularity of detected communities. Values below 1 merge smaller communities into larger clusters, while values above 1 subdivide broad communities into more specific subgroups, allowing administrators to tune the knowledge organization scale.

Where are the type definitions for community data structures?

The CommunityInfo interface and related type definitions reside in src/lib/wiki-graph.ts. This file specifies the structure for community metadata including id, nodeCount, cohesion, and topNodes, ensuring type safety across the detection pipeline and its consumers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}