How to Use Distance Intelligence for Semantic Neighborhood Analysis in Semantica

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	Stores nodes/edges and computes distance metadata on neighbor queries when include_distance_metadata=True
Path Algorithms	PathFinder in 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	Maps raw hop counts to human-readable distance bands
API Contracts	Distance schemas in 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	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).

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, this triggers on-the-fly computation of hop counts, distance bands, and decay scores.

# 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:

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 provides structural analysis beyond neighborhood queries. It supports multiple algorithms for different analytical needs.

Dijkstra's algorithm for shortest weighted path:

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 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.

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 and routes in 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 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 for Dijkstra, BFS, and k-shortest-paths analysis
• Classify distances with classify_path_distance from 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 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. 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 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 and the user guide at docs/guides/distance-intelligence.md. The OpenAPI schemas in semantica/explorer/schemas.py define the exact request/response shapes for programmatic integration.

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