Edge Weights Convention in Understand Anything: Normalized Values and Validation Rules

Edge weights in Understand Anything follow a strict 0-to-1 normalization scheme, defaulting to 0.5 when omitted and automatically clamped or coerced by the schema validator.

The Understand Anything repository defines a standardized convention for relationship strength across its knowledge graph. Every connection between entities is represented as a GraphEdge with a mandatory weight field that quantifies the intensity of the relationship. This convention ensures consistent behavior across graph visualization, layout algorithms, and aggregation utilities.

GraphEdge Weight Specification

In packages/core/src/types.ts, the GraphEdge interface declares weight as a number constrained to the inclusive range 0–1. This normalized scale allows the graph engine to uniformly interpret relationship strength regardless of the source relationship type.

The TypeScript definition enforces this contract at the type level, though runtime validation in packages/core/src/schema.ts provides additional safeguards. According to the Understand Anything source code, higher values indicate tighter, more influential connections between nodes, while values near zero represent weak or incidental relationships.

Validation and Auto-Correction Logic

The schema validator in packages/core/src/schema.ts (lines 308–342) implements three critical behaviors to maintain data integrity: default value injection, string coercion, and range clamping.

Default Value Assignment

When an edge object omits the weight property entirely, the validator automatically assigns 0.5. This occurs in src/schema.ts at lines 308–311, providing a neutral midpoint that prevents undefined behavior in graph algorithms while indicating an unspecified relationship strength.

String-to-Number Coercion

If a string value is supplied (for example, "0.8"), the parser attempts numeric conversion at lines 319–328. Successfully parsed strings become proper numbers, while unparsable strings fall back to the default 0.5 rather than throwing validation errors.

Range Clamping

Values outside the 0–1 boundary are clamped to valid extremes. Lines 334–342 in src/schema.ts implement this logic: any value below 0.0 is raised to 0, and any value exceeding 1.0 is lowered to 1. This prevents layout algorithms from receiving extreme values that could distort visualizations.

Semantic Meaning and Runtime Usage

In Understand Anything, edge weights serve as the primary mechanism for expressing relationship strength. The GraphEdge.weight value directly influences force-directed layouts and clustering algorithms by modulating attraction forces between connected nodes.

The dashboard package leverages these weights in packages/dashboard/src/utils/edgeAggregation.ts when collapsing multiple edges into single visual links. During graph construction, packages/core/src/analyzer/graph-builder.ts frequently assigns maximum weights (1.0) to structural containment relationships, such as "file contains function" edges, while dynamic dependencies receive variable weights based on call frequency or import centrality.

Practical Implementation Examples

The following TypeScript examples demonstrate how the convention handles various input scenarios:

// Explicit strong relationship
{
  source: "file:src/index.ts",
  target: "file:src/service.ts",
  type: "imports",
  direction: "forward",
  weight: 0.9
}

// Omitted weight triggers default injection (0.5)
{
  source: "file:src/utils.ts",
  target: "function:src/utils.ts:helper",
  type: "contains",
  direction: "forward"
}

// String coercion: "0.8" becomes 0.8
{
  source: "file:src/api.ts",
  target: "file:src/db.ts",
  type: "reads_from",
  direction: "forward",
  weight: "0.8"
}

// Out-of-range clamping: 1.5 becomes 1.0
{
  source: "file:src/old.ts",
  target: "file:src/new.ts",
  type: "calls",
  direction: "forward",
  weight: 1.5
}

Summary

• Edge weights in Understand Anything use a normalized 0–1 scale defined in packages/core/src/types.ts.
• Default value is 0.5 when the field is missing, enforced by src/schema.ts lines 308–311.
• String coercion automatically converts numeric strings to numbers, with invalid strings defaulting to 0.5.
• Range clamping ensures values below 0 become 0 and values above 1 become 1.
• Semantic usage affects graph layout algorithms in graph-builder.ts and aggregation logic in edgeAggregation.ts.

Frequently Asked Questions

What is the valid range for edge weights in Understand Anything?

Edge weights must be numbers between 0 and 1 inclusive. The GraphEdge interface in packages/core/src/types.ts defines this constraint, and the schema validator in packages/core/src/schema.ts enforces it through automatic clamping.

What happens if I omit the weight field when creating a GraphEdge?

The schema validator automatically assigns a default value of 0.5. This logic is implemented in src/schema.ts at lines 308–311, ensuring that graph algorithms always receive a valid numeric weight even when the field is omitted.

Can I pass a string representation of a number for the weight property?

Yes, the validator coerces string values to numbers. As shown in src/schema.ts lines 319–328, strings like "0.8" are parsed to 0.8, while unparsable strings fall back to the default 0.5 rather than causing validation failures.

How do edge weights affect the graph visualization?

Edge weights represent relationship strength and influence force-directed layouts and clustering algorithms. Higher weights create stronger visual and physical connections between nodes. The aggregation utilities in packages/dashboard/src/utils/edgeAggregation.ts use these values when combining multiple edges for display purposes.

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