# Distance Intelligence in Semantica: Semantic Neighbourhood Enrichment for Knowledge Graphs

> Discover Distance Intelligence in Semantica's knowledge graph module. Learn how semantic neighbourhood enrichment uses embedding distances for smarter retrieval and causal analysis.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: deep-dive
- Published: 2026-08-21

---

**Distance Intelligence is a Semantica framework feature that enriches knowledge graph nodes with semantic neighbourhood metadata—calculating graph-embedding distances rather than just topological connectivity—to enable proximity-aware retrieval and causal analysis.**

The **Distance Intelligence** system in the semantica-agi/semantica repository transforms raw graph topology into semantically meaningful proximity data. By computing embedding-based distances and caching distance matrices, the KG module enables queries that understand how "close" concepts are in semantic space, powering features from ego-mode visualizations to confidence-weighted retrieval.

## What is Distance Intelligence?

**Distance Intelligence** moves beyond simple hop-counting to measure semantic proximity using graph embeddings. Every node in the knowledge graph receives a *semantic neighbourhood* description that quantifies its relationship to other nodes based on vector-space distances rather than just edge connectivity.

This capability enables sophisticated queries such as *"how semantically close is A to B?"* while returning rich path metadata including distance bands, confidence decay metrics, and full traversal paths. The implementation spans three tightly-coupled architectural layers within the KG core.

## How Distance Intelligence Works in the KG Module

The implementation resides primarily in [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py) and consists of three integrated layers that handle computation, API exposure, and consumption.

### Embedding and Distance Caching Layer

At the foundation, the **Embedding & Distance Cache** computes graph embeddings and maintains per-session distance matrices. This layer ensures thread-safe reuse and automatic cache invalidation through the embedding cache referenced in [`semantica/vector_store/embedding_cache.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/embedding_cache.py) and distance-metadata flags defined in the context graph module.

### API and Metadata Enrichment Layer

The middle layer exposes methods that attach distance intelligence to neighbor queries. When calling `ContextGraph.get_neighbors()` with `include_distance_metadata=True`, the system decorates each result with three critical fields:

- **`distance_band`** – Human-readable proximity classification ("direct", "near", "mid-range", or "distant")
- **`confidence_decay`** – Product of edge weights along the traversed path
- **`path_to_anchor`** – Complete node sequence from source to neighbor

This implementation at line 58 of [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py) enables downstream components to reason about relationship strength without manually calculating graph distances.

### Visualization and Retrieval Integration

The top layer consumes distance metadata for UI rendering and search ranking. The Explorer interface renders ego-mode heat-maps through [`explorer/src/workspaces/GraphWorkspace/GraphInspectorPanel.tsx`](https://github.com/semantica-agi/semantica/blob/main/explorer/src/workspaces/GraphWorkspace/GraphInspectorPanel.tsx), while the retrieval API reads metadata when `proximity_weight > 0` to blend similarity scores with graph proximity.

## The Distance Band Classification System

Distance Intelligence categorizes semantic proximity using a deterministic hop-count classifier defined in [`semantica/utils/helpers.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/helpers.py). The `classify_path_distance()` function implements the following taxonomy:

```python
def classify_path_distance(hop_count: int) -> str:
    """Map hop count → distance band."""
    if hop_count <= 1:
        return "direct"
    if hop_count <= 3:
        return "near"
    if hop_count <= 6:
        return "mid-range"
    return "distant"

```

This classification appears in the `distance_band` field of every neighbor result when metadata enrichment is enabled. The **confidence decay** value complements this by representing the multiplied edge weights along the path, providing a continuous measure of relationship strength that contrasts with the discrete band classification.

## Practical Implementation: Code Examples

### Retrieving Neighbors with Distance Metadata

To fetch enriched neighbor data including distance bands and paths, use the `include_distance_metadata` flag in `ContextGraph.get_neighbors()`:

```python
from semantica.context import ContextGraph

# Assume g is a populated ContextGraph instance

neighbors = g.get_neighbors(
    "A",
    hops=3,
    include_distance_metadata=True,
)

for n in neighbors:
    print(
        f"{n['id']} – hop:{n['hop']} – band:{n['distance_band']} "
        f"– decay:{n['confidence_decay']:.3f}"
    )

```

Each dictionary in the returned list contains the node's identifier, hop count, distance band classification, confidence decay value, and the full path to anchor.

### Filtering by Confidence and Distance

For sorted, filtered neighbor lists, the `get_neighbor_distances()` method builds upon the base neighbor query and applies confidence thresholds:

```python

# Return only neighbors with confidence decay exceeding 0.4

filtered = g.get_neighbor_distances(
    node_id="A",
    hops=4,
    min_confidence=0.4,
)

for item in filtered:
    print(item["id"], item["distance_band"], item["confidence_decay"])

```

This helper method calls `get_neighbors(..., include_distance_metadata=True)` internally, then filters and sorts results by hop count and confidence decay according to the implementation in lines 34-59 of [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py).

### Proximity-Blended Retrieval

Applications can weight search results by semantic proximity using the `proximity_weight` parameter in the `retrieve()` method:

```python
results = g.retrieve(
    query="machine learning",
    top_k=10,
    proximity_weight=0.3,          # 30% weight from distance decay

    include_distance_metadata=True,
)

```

The retrieval engine calculates the final ranking score by multiplying the base semantic similarity by the factor `(1 - proximity_weight) + proximity_weight * confidence_decay`. This produces results that balance textural relevance with graph-topological proximity.

## Advanced Applications

Distance Intelligence propagates through higher-level APIs to support complex reasoning workflows:

- **Causal chain analysis** – The `trace_decision_causality()` function annotates each reasoning step with distance bands, allowing downstream logic to distinguish between "near" and "distant" causal influences.

- **Hybrid precedent search** – The `find_precedents_hybrid()` method accepts `distance_band` filters to surface only closely related historical precedents, ignoring semantically distant matches regardless of their lexical similarity.

- **Confidence decay propagation** – Required paths accumulate edge weights to calculate multiplicative confidence values, enabling probabilistic reasoning across the graph.

## Summary

- **Distance Intelligence** enriches knowledge graph nodes with semantic proximity metadata beyond simple hop counts.
- The system classifies distances into **four bands** ("direct", "near", "mid-range", "distant") using the `classify_path_distance()` helper in [`semantica/utils/helpers.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/helpers.py).
- Enable metadata enrichment by setting `include_distance_metadata=True` when calling `ContextGraph.get_neighbors()` in [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py).
- Each enriched result contains **`distance_band`**, **`confidence_decay`**, and **`path_to_anchor`** fields.
- Use **`proximity_weight`** in retrieval queries to blend semantic similarity scores with graph-based confidence decay.
- The Explorer UI visualizes this data through [`GraphInspectorPanel.tsx`](https://github.com/semantica-agi/semantica/blob/main/GraphInspectorPanel.tsx), rendering proximity heat-maps and path inspections.

## Frequently Asked Questions

### What is Distance Intelligence in Semantica?

Distance Intelligence is a framework feature that calculates semantic distances between knowledge graph nodes using graph embeddings rather than just topological edges. It enriches query results with proximity metadata including distance bands, confidence decay values, and full traversal paths to enable context-aware retrieval and reasoning.

### How does the distance band classification work?

The system uses the `classify_path_distance()` function in [`semantica/utils/helpers.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/helpers.py) to map hop counts to human-readable categories: "direct" for 1 hop or less, "near" for 2-3 hops, "mid-range" for 4-6 hops, and "distant" for anything beyond 6 hops. This classification appears in the `distance_band` field when `include_distance_metadata=True` is specified.

### What files contain the Distance Intelligence implementation?

The core implementation resides in [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py) (API methods), [`semantica/utils/helpers.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/helpers.py) (distance classification), and [`semantica/vector_store/embedding_cache.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/embedding_cache.py) (matrix caching). User-facing documentation lives in [`docs/guides/distance-intelligence.md`](https://github.com/semantica-agi/semantica/blob/main/docs/guides/distance-intelligence.md), while the Explorer UI consumes this data through [`explorer/src/workspaces/GraphWorkspace/GraphInspectorPanel.tsx`](https://github.com/semantica-agi/semantica/blob/main/explorer/src/workspaces/GraphWorkspace/GraphInspectorPanel.tsx).

### How can I use proximity weighting in retrieval queries?

Pass the `proximity_weight` parameter (float between 0.0 and 1.0) to the `retrieve()` method on your `ContextGraph` instance. The engine blends the base similarity score with the result's `confidence_decay` value using the formula `(1 - proximity_weight) + proximity_weight * confidence_decay`, prioritizing nodes that are both textually relevant and graph-proximate to the query context.