Module

analysis.link_suggestions

Link Suggestion Engine for Bengal SSG.

Provides smart cross-linking recommendations based on:

  • Topic similarity (shared tags, categories, keywords)
  • PageRank importance (prioritize linking to high-value pages)
  • Navigation patterns (betweenness, closeness)
  • Current link structure (avoid over-linking, find gaps)

Helps improve:

  • Internal linking structure
  • SEO through better site connectivity
  • Content discoverability
  • User navigation
View source
3 Classes 1 Function

Classes

LinkSuggestion dataclass
A suggested link between two pages. Represents a recommendation to add a link from source page to …
1

A suggested link between two pages.

Represents a recommendation to add a link from source page to target page based on topic similarity, importance, and connectivity analysis.

Attributes

Name Type Description
source Page

Page where the link should be added
target Page

Page that should be linked to
score float

Recommendation score (0.0-1.0, higher is better)
reasons list[str]

List of reasons why this link is suggested
Internal Methods 1
__repr__
0 str 
def __repr__(self) -> str
Returns

str

LinkSuggestionResults dataclass
Results from link suggestion analysis. Contains all link suggestions generated for the site, along…
3

Results from link suggestion analysis.

Contains all link suggestions generated for the site, along with statistics and methods for querying suggestions.

Attributes

Name Type Description
suggestions list[LinkSuggestion]

List of all link suggestions, sorted by score
total_suggestions int

Total number of suggestions generated
pages_analyzed int

Methods 3

get_suggestions_for_page
Get link suggestions for a specific page.
2 list[LinkSuggestion] 
def get_suggestions_for_page(self, page: Page, limit: int = 10) -> list[LinkSuggestion]

Get link suggestions for a specific page.

Parameters 2
page Page

Page to get suggestions for
limit int

Maximum number of suggestions
Returns

list[LinkSuggestion] —

List of LinkSuggestion objects sorted by score

get_top_suggestions
Get top N suggestions across all pages.
1 list[LinkSuggestion] 
def get_top_suggestions(self, limit: int = 50) -> list[LinkSuggestion]

Get top N suggestions across all pages.

Parameters 1
limit int
Returns

list[LinkSuggestion]

get_suggestions_by_target
Get all suggestions that point to a specific target page.
1 list[LinkSuggestion] 
def get_suggestions_by_target(self, target: Page) -> list[LinkSuggestion]

Get all suggestions that point to a specific target page.

Parameters 1
target Page
Returns

list[LinkSuggestion]

LinkSuggestionEngine
Generate smart link suggestions to improve site connectivity. Uses multiple signals to recommend l…
6

Generate smart link suggestions to improve site connectivity.

Uses multiple signals to recommend links:

  1. Topic Similarity: Pages with shared tags/categories
  2. PageRank: Prioritize linking to important pages
  3. Navigation Value: Link to bridge pages
  4. Link Gaps: Find underlinked valuable content

Methods 1

generate_suggestions
Generate link suggestions for all pages.
0 LinkSuggestionResults 
def generate_suggestions(self) -> LinkSuggestionResults

Generate link suggestions for all pages.

Returns

LinkSuggestionResults —

LinkSuggestionResults with all suggestions

Internal Methods 5
__init__
Initialize link suggestion engine.
3 None 
def __init__(self, graph: KnowledgeGraph, min_score: float = 0.3, max_suggestions_per_page: int = 10)

Initialize link suggestion engine.

Parameters 3
graph KnowledgeGraph

KnowledgeGraph with page connections
min_score float

Minimum score threshold for suggestions
max_suggestions_per_page int

Maximum suggestions per page
_generate_suggestions_for_page
Generate link suggestions for a single page.
6 list[LinkSuggestion] 
def _generate_suggestions_for_page(self, source: Page, all_pages: list[Page], page_tags: dict[Page, set[str]], page_categories: dict[Page, set[str]], pagerank_scores: dict[Page, float], betweenness_scores: dict[Page, float]) -> list[LinkSuggestion]

Generate link suggestions for a single page.

Parameters 6
source Page
all_pages list[Page]
page_tags dict[Page, set[str]]
page_categories dict[Page, set[str]]
pagerank_scores dict[Page, float]
betweenness_scores dict[Page, float]
Returns

list[LinkSuggestion]

_calculate_link_score
Calculate link score between two pages.
6 tuple[float, list[str]] 
def _calculate_link_score(self, source: Page, target: Page, page_tags: dict[Page, set[str]], page_categories: dict[Page, set[str]], pagerank_scores: dict[Page, float], betweenness_scores: dict[Page, float]) -> tuple[float, list[str]]

Calculate link score between two pages.

Parameters 6
source Page
target Page
page_tags dict[Page, set[str]]
page_categories dict[Page, set[str]]
pagerank_scores dict[Page, float]
betweenness_scores dict[Page, float]
Returns

tuple[float, list[str]] —

Tuple of (score, reasons)

_build_tag_map
Build mapping of page -> set of tags.
1 dict[Page, set[str]] 
def _build_tag_map(self, pages: list[Page]) -> dict[Page, set[str]]

Build mapping of page -> set of tags.

Parameters 1
pages list[Page]
Returns

dict[Page, set[str]]

_build_category_map
Build mapping of page -> set of categories.
1 dict[Page, set[str]] 
def _build_category_map(self, pages: list[Page]) -> dict[Page, set[str]]

Build mapping of page -> set of categories.

Parameters 1
pages list[Page]
Returns

dict[Page, set[str]]

Functions

suggest_links
Convenience function for link suggestions.
3 LinkSuggestionResults 
def suggest_links(graph: KnowledgeGraph, min_score: float = 0.3, max_suggestions_per_page: int = 10) -> LinkSuggestionResults

Convenience function for link suggestions.

Parameters 3

Name Type Default Description
graph KnowledgeGraph —

KnowledgeGraph with page connections
min_score float 0.3

Minimum score threshold
max_suggestions_per_page int 10

Max suggestions per page

Returns

LinkSuggestionResults —

LinkSuggestionResults with all suggestions