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

> Easily find similar decisions in Semantica using vector-based precedent retrieval. Learn how to use find precedents or similar to functions for semantic and structural similarity.

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

---

**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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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

```python
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

```python

# 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()`

```python

# 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()`

```python

# 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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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.