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

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 and 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 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, which orchestrates the DecisionEmbeddingPipeline (defined in semantica/vector_store/decision_embedding_pipeline.py). This pipeline generates hybrid embeddings combining transformer-based semantic vectors with Node2Vec-style structural representations.

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.

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.

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.

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. 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.

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.

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 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. 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.

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