Module

analysis.links.types

Semantic Link Types and Connectivity Scoring for Bengal SSG.

Defines the semantic relationships between pages and provides weighted connectivity scoring for nuanced content analysis. This replaces binary orphan detection with a spectrum of connectivity levels that reveal improvement opportunities.

Link Types (by editorial intent): High Intent (human-authored):

  • EXPLICIT: Markdown links text in content
  • MENU: Navigation menu items

Medium Intent (algorithmic):

  • TAXONOMY: Shared tags/categories
  • RELATED: Computed related posts

Low Intent (structural):

  • TOPICAL: Section hierarchy (parent β†’ children)
  • SEQUENTIAL: Next/prev navigation

Default Weights:

MENU: 10.0, EXPLICIT: 1.0, TAXONOMY: 1.0, RELATED: 0.75, TOPICAL: 0.5, SEQUENTIAL: 0.25

Connectivity Levels:

  • WELL_CONNECTED (🟒): Score >= 2.0 - No action needed
  • ADEQUATELY_LINKED (🟑): Score 1.0-2.0 - Could improve
  • LIGHTLY_LINKED (🟠): Score 0.25-1.0 - Should improve
  • ISOLATED (πŸ”΄): Score < 0.25 - Needs attention

Classes:

LinkType: Enum of semantic link relationships LinkMetrics: Detailed link breakdown for weighted scoring ConnectivityLevel: Classification based on score thresholds ConnectivityReport: Site-wide connectivity analysis

Example:

>>> metrics = LinkMetrics(explicit=2, taxonomy=1, topical=1)
>>> score = metrics.connectivity_score()
>>> level = ConnectivityLevel.from_score(score)
>>> print(f"Score: {score}, Level: {level.label}")

Score: 3.5, Level: Well-Connected

See Also:

  • bengal/analysis/knowledge_graph.py: Uses link types for graph building
4Classes

Classes

LinkType 6 β–Ό
Semantic relationship types between pages. Links carry meaning beyond simple connectivity. The typ…

Semantic relationship types between pages.

Links carry meaning beyond simple connectivity. The type indicates the editorial intent and discoverability value of the relationship.

Attributes

Name Type Description
EXPLICIT β€”

Human-authored markdown links text in content
MENU β€”

Navigation menu item (deliberate prominence)
TAXONOMY β€”

Shared tags/categories (topic clustering)
RELATED β€”

Algorithm-computed related posts (automated)
TOPICAL β€”

Section hierarchy parent β†’ child (topical context)
SEQUENTIAL β€”

Next/prev navigation within section (reading order)
LinkMetrics 12 β–Ό
Detailed link breakdown for a page. Tracks the count of each link type pointing to a page, enablin…

Detailed link breakdown for a page.

Tracks the count of each link type pointing to a page, enabling weighted connectivity scoring.

Attributes

Name Type Description
explicit int

Count of explicit markdown links
menu int

Count of menu item references
taxonomy int

Count of shared taxonomy links
related int

Count of related post links
topical int

Count of section hierarchy links (parent β†’ child)
sequential int

Count of next/prev navigation links

Methods

connectivity_score 1 float β–Ό
Calculate weighted connectivity score.
def connectivity_score(self, weights: dict[LinkType, float] | None = None) -> float
Parameters
Name Type Description
weights β€”

Optional custom weights. Defaults to DEFAULT_WEIGHTS.

Default:None
Returns
float Weighted sum of all link counts. Higher = better connected.
total_links 0 int β–Ό
Total number of incoming links (unweighted).
def total_links(self) -> int
Returns
int
has_human_links 0 bool β–Ό
True if page has any human-authored links (explicit or menu).
def has_human_links(self) -> bool
Returns
bool
has_structural_links 0 bool β–Ό
True if page has structural links (section/nav).
def has_structural_links(self) -> bool
Returns
bool
has_any_links 0 bool β–Ό
True if page has any incoming links.
def has_any_links(self) -> bool
Returns
bool
to_dict 0 dict[str, int] β–Ό
Convert to dictionary for serialization.
def to_dict(self) -> dict[str, int]
Returns
dict[str, int]
ConnectivityLevel 4 β–Ό
Connectivity classification based on weighted score thresholds. Replaces binary orphan/not-orphan …

Connectivity classification based on weighted score thresholds.

Replaces binary orphan/not-orphan with nuanced levels that reveal opportunities for improvement.

Levels (from best to worst):

  • WELL_CONNECTED: Score >= 2.0 (no action needed)
  • ADEQUATELY_LINKED: Score 1.0-2.0 (could improve)
  • LIGHTLY_LINKED: Score 0.25-1.0 (should improve)
  • ISOLATED: Score < 0.25 (needs attention)

Methods

emoji 0 str β–Ό
Get emoji indicator for this level.
property
def emoji(self) -> str
Returns
str
label 0 str β–Ό
Get human-readable label for this level.
property
def label(self) -> str
Returns
str
description 0 str β–Ό
Get description of what action is needed for this level.
property
def description(self) -> str
Returns
str
from_score 2 ConnectivityLevel β–Ό
Classify a page based on its connectivity score.
classmethod
def from_score(cls, score: float, thresholds: dict[str, float] | None = None) -> ConnectivityLevel
Parameters
Name Type Description
score β€”

Weighted connectivity score from LinkMetrics
thresholds β€”

Optional custom thresholds. Defaults to DEFAULT_THRESHOLDS.

Default:None
Returns
ConnectivityLevel ConnectivityLevel classification
ConnectivityReport 9 β–Ό
Complete connectivity report for a site. Groups pages by connectivity level and provides distribut…

Complete connectivity report for a site.

Groups pages by connectivity level and provides distribution statistics.

Attributes

Name Type Description
isolated list

Pages with score < 0.25
lightly_linked list

Pages with score 0.25-1.0
adequately_linked list

Pages with score 1.0-2.0
well_connected list

Pages with score >= 2.0
total_pages int

Total number of pages analyzed
avg_score float

Average connectivity score across all pages

Methods

get_distribution 0 dict[str, int] β–Ό
Get count distribution by level.
def get_distribution(self) -> dict[str, int]
Returns
dict[str, int]
get_percentages 0 dict[str, float] β–Ό
Get percentage distribution by level.
def get_percentages(self) -> dict[str, float]
Returns
dict[str, float]
to_dict 0 dict β–Ό
Convert to dictionary for serialization.
def to_dict(self) -> dict
Returns
dict