How to Find Similar Decisions in Semantica: Complete Guide to Vector-Based Precedent Retrieval

Use the find_precedents() or similar_to() convenience functions from the decision vector methods module to query Semantica's vector store and retrieve decisions ranked by semantic and structural similarity.

Semantica stores decisions as vectors in a configurable vector store backend, enabling rapid precedent retrieval through hybrid similarity search. To find similar decisions in Semantica, you interact with the high-level APIs defined in semantica/vector_store/decision_vector_methods.py, which automatically handle vectorization, similarity computation, and metadata filtering.

Understanding the Decision Vector Architecture

Semantica represents each decision as a vector embedding that captures both semantic meaning and structural graph relationships. The system combines cosine similarity on semantic embeddings with graph-based structural similarity (Node2Vec, PathFinder, etc.) to rank results.

The vector store abstraction allows you to use backends like Weaviate, FAISS, or custom implementations. All retrieval operations delegate to the store's underlying search_decisions method, which handles the hybrid scoring logic internally.

Finding Similar Decisions with find_precedents()

The find_precedents() function, implemented at lines 99‑147 in semantica/vector_store/decision_vector_methods.py, searches for decisions that match a textual query string.

Key parameters:

• query – The natural language scenario or question to match against
• semantic_weight – Float between 0 and 1 controlling embedding similarity influence (default varies by implementation)
• structural_weight – Float between 0 and 1 controlling graph structure influence
• limit – Maximum number of results to return
• category – Optional metadata filter to scope results to specific domains

This function automatically retrieves the global vector store instance (set via set_global_vector_store) or accepts an explicit store parameter, then returns a list of dictionaries containing decision metadata and similarity scores.

Finding Similar Decisions with similar_to()

The similar_to() function, located at lines 79‑100 in semantica/vector_store/decision_vector_methods.py, finds decisions most similar to a specific scenario string rather than a general query.

Core functionality:

• Accepts a scenario string describing the specific situation you want to match
• Supports hybrid search when use_hybrid_search=True, combining semantic and structural signals
• Returns ranked decisions with similarity scores for precedent analysis and explainability

Both functions obtain their vector store instance through the global store registry, ensuring consistent backend usage across your application without passing store objects repeatedly.

Step-by-Step Implementation

Follow this workflow to initialize your vector store and retrieve similar decisions:

1. Initialize and Register the Vector Store

from semantica.vector_store.my_store import MyVectorStore
from semantica.vector_store.decision_vector_methods import (
    set_global_vector_store,
    find_precedents,
    similar_to,
)

# Initialize your chosen backend (Weaviate, FAISS, or custom)

store = MyVectorStore()
set_global_vector_store(store)  # Makes store available globally

2. Store Decision Records

# Record historical decisions with metadata

store.store_decision(
    scenario="Approve loan for client A",
    outcome="approved",
    category="finance",
    confidence=0.92,
)

store.store_decision(
    scenario="Reject loan for client B",
    outcome="rejected",
    category="finance",
    confidence=0.88,
)

3. Query Using find_precedents()

# Search for precedents matching a general query

precedents = find_precedents(
    query="loan approval for a new customer",
    limit=5,
    semantic_weight=0.75,    # Prioritize semantic similarity

    structural_weight=0.25,
    category="finance",      # Filter by metadata

)

print("Precedents:", precedents)

4. Query Using similar_to()

# Find decisions similar to a specific scenario

similar = similar_to(
    scenario="Grant credit line increase for existing client",
    limit=3,
    use_hybrid_search=True,  # Combine semantic + structural scores

)

print("Similar decisions:", similar)

Both methods return structured data including the decision's scenario, outcome, category, confidence level, and computed similarity score, enabling integration with downstream analytics or explanation generation pipelines.

Summary

• Decisions are vectors: Semantica stores decisions as embeddings in configurable vector stores (Weaviate, FAISS, or custom backends), enabling semantic search capabilities.

• Two primary APIs: Use find_precedents() (lines 99‑147) for general text queries and similar_to() (lines 79‑100) for specific scenario matching, both defined in semantica/vector_store/decision_vector_methods.py.

• Hybrid scoring: Both functions leverage the store's search_decisions method to combine cosine similarity on embeddings with graph-based structural similarity (Node2Vec, PathFinder).

• Global configuration: Register your vector store once using set_global_vector_store() to enable stateless convenience functions throughout your application.

• Metadata filtering: Apply filters by category, confidence thresholds, or custom metadata fields to narrow precedent searches to relevant decision contexts.

Frequently Asked Questions

What is the difference between find_precedents() and similar_to()?

find_precedents() accepts a general query string and is optimized for searching across decision descriptions using weighted semantic and structural similarity, while similar_to() accepts a specific scenario string and excels at finding decisions that closely match a particular situation, optionally using hybrid search mode. Both functions reside in semantica/vector_store/decision_vector_methods.py but serve different retrieval patterns.

Which vector store backends does Semantica support?

Semantica supports pluggable backends including Weaviate, FAISS, and custom implementations defined in semantica/vector_store/<backend>.py files. Any backend implementing the store_decision() and search_decisions() methods can integrate with the find_precedents() and similar_to() convenience functions.

How does hybrid similarity scoring work in Semantica?

The vector store's search_decisions method calculates cosine similarity between semantic embeddings and combines it with graph-based structural similarity metrics (Node2Vec embeddings or PathFinder scores) using the weights specified in semantic_weight and structural_weight parameters. This dual approach captures both conceptual meaning and relational context from the knowledge graph.

Can I filter similar decision results by confidence or outcome?

Yes, both find_precedents() and similar_to() support metadata filtering through parameters like category, and the underlying vector store implementations typically accept additional filters for confidence thresholds, specific outcomes, or custom metadata fields. These filters reduce the search space before similarity scoring occurs, improving both relevance and performance.

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