Knowledge Graph & Relations Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Knowledge Graph & Relations Engine is a core architectural component of HEX-YT-INTEL designed to transform linear content (transcripts and summaries) into a multi-dimensional, structured intelligence product. It operates by deconstructing content into discrete semantic entities and mapping the relationships between them to enable deep-dive analysis, semantic search, and Retrieval-Augmented Generation (RAG) ingestion.
The system serves as the foundational layer for "Knowledge System Foundation," allowing the platform to project future trends, identify information gaps, and reveal "unfair advantages" derived from the source material. It utilizes a deterministic, closed-universe parser to ensure all nodes and edges are extracted exclusively from the provided transcript without external hallucination.
Sources: web/lib/prompts/ucis-v5.1.ts:16-24, web/lib/intelligence/knowledge-graph.ts:1-12
System Architecture
The engine follows a Hexagonal (Ports & Adapters) architecture pattern, where the graph synthesis logic is a pure service that can be utilized in both browser and worker environments. It processes the 11 dimensions of the Ultimate Content Intelligence System (UCIS) to generate a weighted directed graph.
Core Components
- KnowledgeGraphSynthesizer: The primary class responsible for building the graph. It uses a similarity engine to compute relationships between content dimensions.
- SimilarityEngine: A pluggable component (defaulting to
TfIdfSimilarityEngine) that calculates cosine similarity matrices and extracts key terms. - Sentiment Analyzer: A heuristic-based engine that evaluates the polarity of content to identify "contrarian" relationships.
Data Flow Diagram
The following diagram illustrates the transformation of raw transcript data into a structured knowledge graph.
Graph Synthesis Logic
The synthesis pipeline involves four distinct stages to ensure the resulting graph is both sparse enough for human readability and dense enough for technical analysis.
1. Similarity Computation
The engine computes an $N \times N$ cosine similarity matrix where $N$ represents the 11 UCIS dimensions. It also identifies the most significant terms for each node.
Sources: web/lib/intelligence/knowledge-graph.ts:7-8
2. Adaptive Edge Selection
To avoid a "hairball" visualization, the engine applies a distribution-aware floor. It calculates the mean ($m$) and standard deviation ($s$) of similarities across the graph. Edges are selected based on the top-k neighbors for each node, provided they exceed the calculated threshold.
| Threshold Band | Definition | Relation Kind |
|---|---|---|
| $\ge m + 1.0s$ | Near-duplicate framing or extremely high overlap | similar |
| $\ge m + 0.25s$ | Strong topical or logical connection | related |
| $\ge Floor$ | Distant or secondary connection | tangent |
| Polarity Offset $\ge 0.6$ | Topically linked but opposite stance | contrarian |
Sources: web/lib/intelligence/knowledge-graph.ts:94-118
3. Sentiment & Polarity Analysis
The engine uses a pre-defined lexicon of positive and negative markers to assign a polarity score to each dimension. This score is used to identify "Contrarian Perspectives" (Dimension 9.5), which are critical for providing a balanced intelligence product.
const POSITIVE = new Set(['success', 'effective', 'powerful', 'robust', 'innovative']);
const NEGATIVE = new Set(['risk', 'threat', 'failure', 'flawed', 'bias']);
function polarityOf(text: string): number {
// Calculates (pos - neg) / (pos + neg)
}
Sources: web/lib/intelligence/knowledge-graph.ts:27-46, web/lib/prompts/ucis-v5.1.ts:212-214
Data Structures
The Knowledge Graph is represented by nodes (entities) and edges (relations). In Dimension 8 of the UCIS framework, these are explicitly structured for downstream ingestion.
Node Definitions
Nodes represent domain-specific semantic entities such as People, Concepts, Frameworks, Tools, Organizations, and Metrics.
| Field | Type | Description |
|---|---|---|
label | string | The entity name (e.g., "Systems Thinking") |
type | enum | person | concept | framework | tool | organization | study | trend | metric |
weight | number | Importance (1-10) based on weighted-degree centrality |
polarity | number | Sentiment score ranging from -1 to 1 |
Sources: web/lib/prompts/ucis-v5.1.ts:192-198, web/lib/intelligence/knowledge-graph.ts:139-148
Relationship Definitions
Edges define the nature of connections between nodes extracted from the transcript.
| Field | Type | Description |
|---|---|---|
source | string | Origin entity label |
target | string | Destination entity label |
relation | string | Nature of connection (e.g., "uses", "impacts", "is_part_of") |
strength | number | Connection strength based on semantic similarity (1-10) |
Sources: web/lib/prompts/ucis-v5.1.ts:200-205, web/lib/intelligence/knowledge-graph.ts:121-123
Dimension Mapping & Persona Weighting
The engine doesn't just link data; it weights the importance of nodes based on the active Primary Persona. For instance, Dimension 11 (Monetization) is heavily weighted for "Content Creators" and "Indie Makers," while Dimension 3 (Architecture) is prioritized for "Consultants."
Persona-Dimension Relationship
Implementation Constraints
To maintain technical accuracy and "closed-universe" integrity, the Relations Engine follows strict enforcement rules:
- Transcript Absolutism: No nodes or relations can be inferred if they do not exist in the literal text of the transcript.
- Insufficient Data Protocol: If a dimension lacks depth for relationship mapping, it is marked as
[Insufficient data in source transcript to fulfill this dimension]. - Structural Integrity: Structural document headers (e.g., "Apex Intelligence") are forbidden from being extracted as nodes to ensure the graph contains only domain-specific intelligence.
Sources: web/lib/prompts/ucis-v5.1.ts:31-48, web/lib/prompts/ucis-v5.1.ts:192-194, web/lib/tests/ucis-v5-validator.test.ts:117-125
Conclusion
The Knowledge Graph & Relations Engine transforms raw video data into a high-density "technical instrument register." By utilizing normalized weighted-degree centrality and adaptive similarity thresholds, it identifies a "Foundational Root" (the most central node in the discourse) and builds a semantic map that allows users to navigate complex 2-hour masterclasses as structured, actionable databases.
Sources: web/lib/intelligence/knowledge-graph.ts:133-155, design-system/HEX-YT-INTEL Design System (1)/README.md:1-10