# How to Trace the Ancestry of a Decision in Semantica: Complete API Guide

> Trace decision ancestry in Semantica using the context function. Build lineage graphs of related entities, policies, and past decisions with our complete API guide.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: api-reference
- Published: 2026-09-13

---

**You can trace the ancestry of a decision in Semantica using the `context` function (alias for `get_decision_context`) in [`decision_vector_methods.py`](https://github.com/semantica-agi/semantica/blob/main/decision_vector_methods.py), which reconstructs the decision's lineage by building a graph of related entities, policies, and similar prior decisions via the vector-store backend.**

Semantica stores every decision as a vector with rich metadata, enabling full lineage tracking through its decision-context API. When you need to understand what informed a specific decision or explore its historical precedents, the framework provides dedicated methods to reconstruct the surrounding knowledge graph.

## The Decision Context API Architecture

The primary mechanism for ancestry tracing relies on two interconnected components in the Semantica vector store layer.

### Core Entry Point: get_decision_context

The `get_decision_context` function, exposed as the convenience alias `context` in [`semantica/vector_store/decision_vector_methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/decision_vector_methods.py) (lines 90-98), serves as the main interface. This method delegates to `VectorStore.build_decision_context` in [`semantica/vector_store/vector_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/vector_store.py) (lines 29-57), which constructs a graph-like dictionary containing:

- The original decision's metadata
- Associated entities and policies
- A list of **related decisions** obtained via similarity search
- A complete **context graph** with nodes and edges

If the backend cannot retrieve the raw vector (e.g., when using a FAISS index without a direct map), the method returns a warning flag and an empty `related_decisions` list rather than failing silently.

### Method Signature and Parameters

The `context` function accepts several parameters to control the ancestry reconstruction:

```python
ancestry = context(
    decision_id,           # UUID string returned when the decision was recorded

    depth=3,              # Controls how many similar decisions are fetched

    include_entities=True, # Toggle inclusion of attached entities

    include_policies=True, # Toggle inclusion of policy references

    max_hops=4            # Limits graph traversal for multi-hop relationships

)

```

The `depth` parameter retrieves `depth * 5` candidates via the underlying `search_vectors` routine, keeping only the top-scoring matches. The `max_hops` parameter governs how far the graph traversal expands when exploring indirect relationships.

## Anatomy of the Returned Ancestry Structure

The function returns a structured dictionary that fully represents the decision's lineage:

```json
{
  "decision_id": "<id>",
  "decision_metadata": { 
    "category": "...", 
    "outcome": "...", 
    "confidence": 0.9 
  },
  "entities": ["Customer", "Account"],
  "policies": ["CreditPolicyV2"],
  "related_decisions": [
    {
      "id": "<other_id>",
      "similarity": 0.87,
      "metadata": { 
        "category": "...", 
        "outcome": "..." 
      }
    }
  ],
  "context_graph": {
    "nodes": [...],
    "edges": [...]
  }
}

```

The `related_decisions` array represents the actual ancestry—each entry is a prior decision that the similarity engine judged relevant based on vector proximity. The `context_graph` provides the underlying network structure suitable for visualization or further graph analysis.

## Alternative Ancestry Exploration Methods

Beyond the primary context API, Semantica offers specialized methods for different ancestry tracing scenarios.

### Finding Precedents with find_precedents

The `find_precedents` function (aliased as `precedents` in [`decision_vector_methods.py`](https://github.com/semantica-agi/semantica/blob/main/decision_vector_methods.py), lines 98-106) enables free-text querying against the decision history. This is useful when you want to find similar decisions without knowing the specific decision ID:

```python
from semantica.vector_store.decision_vector_methods import precedents

similar = precedents(
    query="Credit limit increase request",
    limit=5,
    category="finance",
    confidence_min=0.8
)

```

This method searches across the vector store using semantic similarity while filtering by metadata fields like category and confidence thresholds.

### Hybrid Similarity Search

For richer lineage analysis, the `similar_to` method (aliased as `similar` in [`decision_vector_methods.py`](https://github.com/semantica-agi/semantica/blob/main/decision_vector_methods.py), lines 78-86) supports hybrid search modes:

```python
from semantica.vector_store.decision_vector_methods import similar

related = similar(
    decision_id=decision_id,
    use_hybrid_search=True  # Blends semantic and structural embeddings

)

```

Setting `use_hybrid_search=True` combines vector similarity with structural embeddings, capturing both semantic meaning and relational topology in the ancestry results.

## Practical Implementation Examples

### Basic Ancestry Lookup

Retrieve the immediate lineage of a specific decision:

```python
from semantica.vector_store.decision_vector_methods import context

decision_id = "d3f9a1b2-4c5e-11ee-b2d6-0242ac130003"
ancestry = context(decision_id, depth=2)
print("Ancestry:", ancestry["related_decisions"])

```

### Filtering Precedents by Domain

Search for historically similar decisions with specific constraints:

```python
from semantica.vector_store.decision_vector_methods import precedents

similar = precedents(
    query="Credit limit increase request",
    limit=5,
    category="finance",
    confidence_min=0.8
)
for d in similar:
    print(d["id"], d["metadata"]["outcome"], d["score"])

```

### Visualizing the Context Graph

Export the ancestry graph for visualization tools:

```python
from semantica.vector_store.decision_vector_methods import context
import plotly.graph_objects as go

decision_id = "d3f9a1b2-4c5e-11ee-b2d6-0242ac130003"
graph = context(decision_id, depth=3)["context_graph"]

fig = go.Figure()
for node in graph["nodes"]:
    fig.add_trace(go.Scatter(
        x=[node["x"]], 
        y=[node["y"]],
        mode='markers+text',
        text=node["label"], 
        hoverinfo='text'
    ))
for edge in graph["edges"]:
    fig.add_trace(go.Scatter(x=edge["x"], y=edge["y"], mode='lines'))
fig.show()

```

## Key Source Files

Understanding the implementation details requires familiarity with these specific modules:

- **[`semantica/vector_store/decision_vector_methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/decision_vector_methods.py)** – Convenience wrappers including `context`, `precedents`, and `similar`
- **[`semantica/vector_store/vector_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/vector_store.py)** – Backend implementation containing `build_decision_context` and search logic
- **[`semantica/mcp/tools/decisions.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/tools/decisions.py)** – Higher-level MCP command-line integration for decision tracking workflows
- **[`tests/vector_store/test_end_to_end_decision_tracking.py`](https://github.com/semantica-agi/semantica/blob/main/tests/vector_store/test_end_to_end_decision_tracking.py)** – Test suite demonstrating end-to-end ancestry tracing usage

## Summary

- The **`context`** function in [`decision_vector_methods.py`](https://github.com/semantica-agi/semantica/blob/main/decision_vector_methods.py) is the primary entry point for tracing decision ancestry in Semantica, aliasing `get_decision_context`.
- The method returns a structured graph containing `related_decisions`, `entities`, `policies`, and a traversable `context_graph`.
- Use **`depth`** to control similarity search breadth and **`max_hops`** to limit graph traversal depth.
- **`find_precedents`** (aliased as `precedents`) enables free-text ancestry searches without requiring a decision ID.
- The backend gracefully handles missing vector mappings (e.g., FAISS without direct maps) by returning warning flags rather than raising exceptions.

## Frequently Asked Questions

### What is the difference between `context` and `precedents` in Semantica?

The **`context`** function requires a specific `decision_id` and reconstructs the ancestry for that exact decision using vector similarity. The **`precedents`** function accepts a free-text query string and searches the entire decision history for similar cases, optionally filtering by category or confidence thresholds. Use `context` when analyzing a known decision's lineage; use `precedents` when exploring historical precedents for a hypothetical scenario.

### How does Semantica handle missing vectors when tracing ancestry?

If the vector-store backend cannot retrieve the raw vector—such as when using a FAISS index without a direct ID-to-vector mapping—the `build_decision_context` method returns a response containing a warning flag and an empty `related_decisions` list. This allows your application to detect data availability issues without crashing, enabling fallback logic or user notifications.

### Can I control how many related decisions appear in the ancestry graph?

Yes, the `depth` parameter in the `context` function controls the ancestry breadth. The implementation retrieves `depth * 5` candidate decisions via `search_vectors`, then filters to the top-scoring matches. For example, `depth=3` fetches 15 candidates and keeps the best matches. Additional parameters like `include_entities` and `include_policies` toggle whether non-decision nodes appear in the returned graph structure.

### What does the `use_hybrid_search` parameter do in the `similar` function?

Setting `use_hybrid_search=True` in the `similar_to` method (aliased as `similar`) enables a combined search strategy that merges **semantic embeddings** (meaning-based similarity) with **structural embeddings** (relationship-based topology). This produces richer ancestry results that capture not just what the decision was about, but how it was connected to other decisions in the knowledge graph, providing a more complete lineage analysis.