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

You can trace the ancestry of a decision in Semantica using the context function (alias for get_decision_context) in 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 (lines 90-98), serves as the main interface. This method delegates to VectorStore.build_decision_context in 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:

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:

{
  "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, 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:

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, lines 78-86) supports hybrid search modes:

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:

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:

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:

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 – Convenience wrappers including context, precedents, and similar
• semantica/vector_store/vector_store.py – Backend implementation containing build_decision_context and search logic
• 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 – Test suite demonstrating end-to-end ancestry tracing usage

Summary

• The context function in 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.

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