# How to Analyze the Impact of a Decision Using Semantica: 4-Layer Workflow

> Analyze decision impact with Semantica. Discover downstream effects using semantic-structural vectors for rapid precedent retrieval and graph exploration.

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

---

**Semantica analyzes decision impact by modeling every choice as a hybrid semantic-structural vector, enabling rapid precedent retrieval, graph-based context exploration, and aggregate statistics that reveal downstream effects across your knowledge graph.**

To analyze the impact of a decision effectively, you need to trace how individual choices propagate through entities, policies, and historical precedents. The `semantica-agi/semantica` repository provides a **decision vector architecture** that captures choices as rich embeddings, allowing you to quantify alignment with existing trends and surface hidden relationships in your decision corpus.

## The Four Layers of Decision Impact Analysis

Semantica structures decision impact analysis into four logical layers. Each layer corresponds to specific modules in [`semantica/vector_store/decision_vector_methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/decision_vector_methods.py) and [`semantica/vector_store/vector_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/vector_store.py).

| Layer | Purpose | Primary Functions |
|-------|---------|-------------------|
| **1. Ingestion** | Record decisions with automatic embedding generation | `quick_decision`, `store_decision` |
| **2. Retrieval** | Locate precedents and build contextual subgraphs | `find_precedents`, `get_decision_context`, `explain` |
| **3. Analytics** | Compute aggregate statistics and confidence metrics | `get_decision_statistics` |
| **4. Tuning** | Adjust semantic vs. structural similarity weighting | `update_similarity_weights` |

This architecture enables both qualitative narrative generation and quantitative evidence gathering for any decision's ripple effects.

## Ingestion: Recording Decisions as Semantic Vectors

The ingestion layer transforms raw decision data into searchable vectors. The `quick_decision` function in [`semantica/vector_store/decision_vector_methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/decision_vector_methods.py) serves as the primary entry point, constructing metadata dictionaries and forwarding them to the storage backend.

Internally, `quick_decision` invokes `store_decision` from [`semantica/vector_store/vector_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/vector_store.py), which orchestrates the **DecisionEmbeddingPipeline** (defined in [`semantica/vector_store/decision_embedding_pipeline.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/decision_embedding_pipeline.py)). This pipeline generates hybrid embeddings combining transformer-based semantic vectors with Node2Vec-style structural representations.

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

decision_id = quick_decision(
    scenario="Approve credit limit increase for client X",
    outcome="approved",
    reasoning="Client has a 5‑year repayment history with no defaults.",
    confidence=0.92,
    entities=["Client X", "Credit Account"],
    category="credit_approval"
)

print(f"Decision stored with ID: {decision_id}")

```

The function returns a persistent vector ID that serves as the anchor for all subsequent impact analysis operations.

## Retrieval: Finding Precedents and Context

Once a decision is stored, the retrieval layer enables three distinct investigative modes: precedent search, graph exploration, and automated explanation.

### Locating Similar Decisions

The `find_precedents` function (aliased as `precedents`) builds filtered search sets and queries the vector store using hybrid similarity scoring. It calls `store.search_decisions`, which mixes semantic cosine similarity with graph-based structural similarity from [`semantica/vector_store/hybrid_similarity.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/hybrid_similarity.py).

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

precedents = find_precedents(
    query="credit limit increase",
    limit=5,
    category="credit_approval",
    confidence_min=0.8
)

for p in precedents:
    print(f"{p['scenario']} → {p['outcome']} (score={p['score']:.2f})")

```

### Exploring the Decision Graph

To understand relational impact, `get_decision_context` expands the neighborhood of a decision node with configurable depth and hop limits. This exposes connections to related entities, governing policies, and prior decisions that might not surface in pure similarity searches.

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

context_graph = get_decision_context(
    decision_id,
    depth=2,
    include_entities=True,
    include_policies=True,
    max_hops=3
)

print("Context nodes:")
for node in context_graph["nodes"]:
    print(f" • {node['id']} ({node['type']})")

```

### Generating Explanations

The `explain` function forwards decision IDs to `store.explain_decision`, returning structured narratives that include reasoning paths, confidence values, and the weighted contributions of semantic versus structural factors.

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

explanation = explain(decision_id, include_paths=True, include_weights=True)

print("Explanation:")
print(explanation["summary"])
print("Weighted contributions:")
for w in explanation["weights"]:
    print(f" - {w['type']}: {w['value']:.3f}")

```

## Analytics: Quantifying Decision Impact

The analytics layer provides aggregate visibility through `get_decision_statistics` in [`semantica/vector_store/decision_vector_methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/decision_vector_methods.py). This function scans the entire decision store to compute:

- **Category distribution** showing decision volume by type
- **Confidence ranges** revealing risk profiles (average, min, max scores)
- **Structural embedding presence** indicating graph-based reasoning availability

These metrics allow you to assess whether a new decision aligns with established policy trends or represents an outlier requiring additional scrutiny.

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

stats = get_decision_statistics()
print("Decision Store Statistics:")
print(f"Total decisions: {stats['total_decisions']}")
print(f"Category distribution: {stats['categories']}")
print(f"Average confidence: {stats['average_confidence']:.2f}")

```

## Tuning: Optimizing Similarity Weights

Impact analysis often requires domain-specific calibration. The `update_similarity_weights` function adjusts the balance between **semantic similarity** (textual meaning) and **structural similarity** (graph topology).

Call this function with values between 0.0 and 1.0 to bias searches toward purely textual matches (higher semantic weight) or relational proximity (higher structural weight). This proves essential when analyzing compliance-heavy domains versus market-driven scenarios.

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

# Favor structural (graph) similarity for policy-heavy analysis

update_similarity_weights(semantic_weight=0.4, structural_weight=0.6)

```

## End-to-End Impact Analysis Workflow

To perform complete **decision impact analysis** in Semantica, chain these operations sequentially:

1. **Record** the decision using `quick_decision` to generate the vector anchor
2. **Retrieve** top-N precedents with `find_precedents` to establish historical context
3. **Explain** the decision using `explain` to surface reasoning and similarity contributions  
4. **Expand** the contextual subgraph via `get_decision_context` to map entity and policy relationships
5. **Summarize** overall decision health using `get_decision_statistics` for quantitative validation

This workflow delivers both qualitative narratives explaining *why* a decision matters and quantitative evidence of *how* it fits within your existing decision corpus.

## Summary

- **Semantica** analyzes decision impact through four layers: ingestion, retrieval, analytics, and tuning
- Use `quick_decision` in [`semantica/vector_store/decision_vector_methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/decision_vector_methods.py) to store decisions with hybrid embeddings
- Retrieve precedents with `find_precedents` and explore relationships via `get_decision_context`
- Generate human-readable impact reports using the `explain` function
- Quantify alignment with existing policies through `get_decision_statistics`
- Adjust search bias between semantic and structural factors using `update_similarity_weights`

## Frequently Asked Questions

### How does Semantica store decision embeddings?

Semantica stores decisions as hybrid vectors through `store_decision` in [`semantica/vector_store/vector_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/vector_store.py). The system invokes the **DecisionEmbeddingPipeline** to generate both semantic embeddings (using transformer models) and structural embeddings (using Node2Vec-style graph vectors), then persists these alongside metadata in the vector store.

### Can I filter precedent searches by confidence thresholds?

Yes. The `find_precedents` function accepts a `confidence_min` parameter that filters results to only include decisions meeting your specified confidence floor. This allows you to exclude low-certainty historical decisions when analyzing high-stakes current choices.

### What is the difference between semantic and structural similarity in Semantica?

Semantic similarity measures textual and conceptual overlap between decision scenarios using cosine similarity on transformer embeddings. Structural similarity measures graph topology proximity—how closely decisions are connected through shared entities, policies, or causal chains. The `update_similarity_weights` function lets you bias searches toward one factor or balance both.