# How to Use Distance Intelligence for Semantic Neighborhood Analysis in Semantica

> Unlock precise semantic neighborhood analysis with Distance Intelligence in Semantica. Enhance knowledge graph queries using quantitative neighborhood signals for deeper insights.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-16

---

**Distance Intelligence enriches knowledge graph queries with quantitative neighborhood signals—including hop counts, distance bands, confidence-decay scores, and path metadata—to enable precise semantic neighborhood analysis beyond simple graph traversal.**

**Semantica** (semantica-agi/semantica) implements Distance Intelligence as a core layer in its knowledge graph architecture. The feature computes structural proximity metrics on-the-fly through the `ContextGraph` class and exposes them via Python APIs, FastAPI endpoints, and the Explorer dashboard. This guide covers the architecture, key concepts, and practical implementation patterns based on the actual source code.

---

## Architecture of Distance Intelligence in Semantica

Distance Intelligence spans multiple layers of the Semantica stack. Understanding these components helps you choose the right interface for your use case.

| Layer | Component | Responsibility |
|-------|-----------|--------------|
| **Graph Core** | `ContextGraph` in [`semantica/context/graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/graph.py) | Stores nodes/edges and computes distance metadata on neighbor queries when `include_distance_metadata=True` |
| **Path Algorithms** | `PathFinder` in [`semantica/kg/path_finder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/path_finder.py) | Implements Dijkstra, BFS, Yen's k-shortest paths, and all-shortest-paths analysis |
| **Classification** | `classify_path_distance` in [`semantica/utils/helpers.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/helpers.py) | Maps raw hop counts to human-readable distance bands |
| **API Contracts** | Distance schemas in [`semantica/explorer/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/explorer/schemas.py) | Defines `DistanceMatrixRequest/Response`, `CausalDistanceReport`, `DistanceSnapshot` |
| **Explorer UI** | Distance-Intelligence dashboard | Visualizes N×N matrices, ego-mode heatmaps, and path inspectors |
| **Hybrid Retrieval** | `AgentContext.retrieve()` in [`semantica/context/agent_context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py) | Blends semantic similarity with graph proximity using `proximity_weight` |

Each layer builds upon the `ContextGraph` foundation, ensuring consistent distance metadata across interfaces.

---

## Core Distance Intelligence Concepts

Semantica attaches four quantitative signals to every neighborhood query result:

1. **Hop Count** — The integer number of edges traversed from an anchor node to a target node.

2. **Distance Band** — A categorical label (`direct`, `near`, `mid-range`, `distant`) derived from hop count thresholds.

3. **Confidence Decay** — The product of edge weights along the traversal path; values closer to 1.0 indicate stronger evidentiary chains.

4. **Path Metadata** — The complete node-ID sequence (`path_to_anchor`) and the edge type/weight of the final hop.

These signals are computed lazily during query execution and attached to results when explicitly requested.

---

## Setting Up a ContextGraph with Weighted Edges

Distance Intelligence requires weighted edges representing domain-specific confidence. The `ContextGraph.add_edge()` method accepts a `weight` parameter (0.0 to 1.0).

```python
from semantica.context import ContextGraph

graph = ContextGraph()

# Add threat intelligence nodes

graph.add_node("apt29", "ThreatActor", "APT29 / NOBELIUM")
graph.add_node("hammertoss", "Malware", "HAMMERTOSS C2 tool")
graph.add_node("twitter_c2", "Infrastructure", "APT29 Twitter C2 channel")

# Add weighted relationships (confidence as edge weight)

graph.add_edge("apt29", "hammertoss", "deploys", weight=0.95)
graph.add_edge("hammertoss", "twitter_c2", "uses", weight=0.88)

```

Edge weights directly affect **confidence decay** calculations. Higher weights preserve more signal through multi-hop traversals.

---

## Querying Neighbors with Distance Metadata

The `ContextGraph.get_neighbors()` method returns enriched node data when you pass `include_distance_metadata=True`. According to the implementation in [`semantica/context/graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/graph.py), this triggers on-the-fly computation of hop counts, distance bands, and decay scores.

```python

# Retrieve neighbors with full distance intelligence

neighbors = graph.get_neighbors(
    "apt29",
    hops=3,
    include_distance_metadata=True,
)

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

```

**Sample output:**

```

hammertoss           band=direct     decay=0.950  hop=1
twitter_c2           band=near       decay=0.836  hop=2

```

For exhaustive neighborhood analysis, use `get_neighbor_distances()` with confidence filtering:

```python
all_neighbors = graph.get_neighbor_distances(
    "apt29",
    hops=4,
    min_confidence=0.60,  # Filter paths with decay below threshold

)

for n in all_neighbors:
    print(f"[{n['distance_band']}] {n['id']}  decay={n['confidence_decay']:.3f}")

```

---

## Path-Finding with PathFinder

The `PathFinder` class in [`semantica/kg/path_finder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/path_finder.py) provides structural analysis beyond neighborhood queries. It supports multiple algorithms for different analytical needs.

**Dijkstra's algorithm for shortest weighted path:**

```python
from semantica.kg import PathFinder

pf = PathFinder()
path = pf.dijkstra_shortest_path(graph, "apt29", "twitter_c2")
length = pf.path_length(graph, path)

print(f"Shortest path: {' → '.join(path)} (length={length:.3f})")

```

**Additional `PathFinder` methods:**
- `bfs_shortest_path()` — Unweighted breadth-first search
- `yen_k_shortest_paths()` — K-shortest loopless paths
- `all_shortest_paths()` — All minimum-length paths between nodes

These algorithms operate directly on the `ContextGraph` structure and respect edge weights where applicable.

---

## Distance Band Classification

The `classify_path_distance` helper in [`semantica/utils/helpers.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/helpers.py) standardizes hop counts into interpretable categories. You can use this standalone or rely on automatic classification in enriched queries.

| Hop Count | Distance Band |
|-----------|---------------|
| 1 | `direct` |
| 2 | `near` |
| 3–4 | `mid-range` |
| 5+ | `distant` |

These thresholds are configurable in the helper implementation.

---

## Hybrid Retrieval: Blending Semantic and Graph Proximity

The `AgentContext` class enables **semantic neighborhood analysis** that combines vector similarity with Distance Intelligence. Set `proximity_weight` between 0.0 and 1.0 to control the blend.

```python
from semantica.context import AgentContext
from semantica.vector_store import VectorStore

# Initialize hybrid context

context = AgentContext(
    vector_store=VectorStore(backend="faiss", dimension=768),
    knowledge_graph=graph,
    hybrid_alpha=0.5,  # Balance between semantic and structural signals

)

# Store documents (vectors generated automatically)

context.store([
    "APT29 exploited CVE-2024-3400 in PAN-OS targeting NATO governments.",
    "HAMMERTOSS is APT29's C2 tool using Twitter as a covert channel.",
])

# Retrieve with 30% graph proximity weighting

results = context.retrieve(
    "nation-state C2 infrastructure",
    use_graph=True,
    anchor_node="apt29",
    max_hops=3,
    proximity_weight=0.30,
    max_results=5,
)

for r in results:
    score = r.get('combined_score', r['score'])
    band = r.get('distance_band', '-')
    hop = r.get('hop_distance', '-')
    decay = r.get('confidence_decay', 0)
    print(f"[{score:.3f}] band={band:10s} hop={hop} decay={decay:.3f}  {r['content'][:70]}")

```

The `combined_score` fuses:
- Semantic similarity from the vector store
- Graph proximity (inverse hop count and confidence decay)
- Weighted according to `proximity_weight` and `hybrid_alpha`

---

## Explorer UI and API Endpoints

For visualization and HTTP access, the Semantica Explorer exposes Distance Intelligence through schemas defined in [`semantica/explorer/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/explorer/schemas.py) and routes in [`semantica/explorer/routes/graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/explorer/routes/graph.py).

**Key endpoints:**
- `POST /distance-matrix` — Returns N×N distance matrices for node sets
- `GET /causal-distance` — Generates `CausalDistanceReport` with path analysis
- `GET /distance-history` — Retrieves `DistanceSnapshot` series over time

The dashboard renders these as interactive heatmaps and path inspectors. See [`docs/guides/distance-intelligence.md`](https://github.com/semantica-agi/semantica/blob/main/docs/guides/distance-intelligence.md) for complete API documentation.

---

## Summary

- **Distance Intelligence** in Semantica attaches hop counts, distance bands, confidence-decay scores, and path metadata to graph queries
- Enable via `include_distance_metadata=True` in `ContextGraph.get_neighbors()` or `proximity_weight` in `AgentContext.retrieve()`
- Configure edge weights (0.0–1.0) to control confidence decay through multi-hop paths
- Use `PathFinder` in [`semantica/kg/path_finder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/path_finder.py) for Dijkstra, BFS, and k-shortest-paths analysis
- Classify distances with `classify_path_distance` from [`semantica/utils/helpers.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/helpers.py)
- Access through Python APIs, FastAPI endpoints, or the Explorer dashboard

---

## Frequently Asked Questions

### What is the difference between hop count and confidence decay in Semantica?

**Hop count** is the integer number of edges between nodes, while **confidence decay** is the multiplicative product of edge weights along that path. A 3-hop path with weights [0.9, 0.9, 0.9] has decay 0.729, whereas the same hop count with weaker edges [0.5, 0.5, 0.5] decays to 0.125. Both signals are computed in [`semantica/context/graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/graph.py) and attached when `include_distance_metadata=True`.

### How does proximity_weight affect hybrid retrieval results?

The `proximity_weight` parameter (0.0 to 1.0) in `AgentContext.retrieve()` controls what fraction of the final ranking comes from graph proximity versus semantic similarity. At 0.0, results are purely vector-based; at 1.0, purely graph-based. Intermediate values blend the scores as implemented in [`semantica/context/agent_context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py). The `hybrid_alpha` parameter provides additional tuning of the combination formula.

### Can I customize the distance band thresholds for my domain?

Yes. The `classify_path_distance` function in [`semantica/utils/helpers.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/helpers.py) contains the mapping logic. You can fork and modify the thresholds or wrap the function with domain-specific rules. The default bands are: 1 hop = `direct`, 2 hops = `near`, 3–4 hops = `mid-range`, 5+ hops = `distant`.

### Where is the Distance Intelligence API documented?

Reference documentation lives in [`docs/reference/distance.md`](https://github.com/semantica-agi/semantica/blob/main/docs/reference/distance.md) and the user guide at [`docs/guides/distance-intelligence.md`](https://github.com/semantica-agi/semantica/blob/main/docs/guides/distance-intelligence.md). The OpenAPI schemas in [`semantica/explorer/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/explorer/schemas.py) define the exact request/response shapes for programmatic integration.