How to Track and Audit AI Decisions Using Semantica: Complete Technical Guide

Semantica treats every AI decision as a first-class node in its Context Graph, automatically capturing full provenance, causal relationships, and regulator-ready audit trails that can be exported to W3C PROV-O format.

Tracking AI decisions for compliance and debugging requires more than simple logging—it demands a structured knowledge representation that preserves context and causality. The open-source semantica-agi/semantica framework implements deterministic decision auditing through a graph-native architecture where every choice becomes a persistent, queryable node. This guide explains how to implement full decision traceability using Semantica's MCP tools and Context Graph API.

The Four-Step Decision Tracking Pipeline

Semantica implements decision auditing through a deterministic pipeline that does not rely on LLM reasoning for provenance, ensuring traceability and compliance. Each step corresponds to specific functions in the mcp/tools/decisions.py module.

Step 1: Record Decisions with Schema Validation

Before persistence, all decision payloads are validated against the RECORD_DECISION JSON‑Schema defined in mcp/schemas.py (lines 39‑78). This schema enforces required fields including category, scenario, reasoning, outcome, and confidence.

The handle_record_decision function in mcp/tools/decisions.py (lines 22‑41) orchestrates the recording process. It creates a graph node via graph.record_decision(...) and persists the mutation to disk at SEMANTICA_KG_PATH. If persistence fails, the function rolls back the in‑memory state to maintain consistency (lines 22‑75).

Step 2: Link Causal Relationships

After recording, you establish provenance links using graph.add_causal_relationship(parent_id, child_id, relationship_type). Supported relationship types include:

• CAUSED – Direct causal dependency
• INFLUENCED – Partial or supporting influence
• PRECEDENT_FOR – Historical basis for subsequent decisions

These edges become part of the graph topology, enabling downstream traversal and impact analysis.

Step 3: Query and Analyze Decision History

Semantica provides MCP tool handlers for retrospective analysis without requiring LLM interpretation:

• handle_query_decisions (lines 85‑104) – Natural‑language semantic search with filtering by category or outcome
• handle_find_precedents (lines 110‑121) – Locate similar historical decisions using hybrid similarity (dense + sparse vectors)
• handle_get_causal_chain (lines 126‑144) – Extract ordered upstream/downstream chains using CausalChainAnalyzer or the backend’s get_causal_chain implementation
• handle_analyze_decision_impact (lines 126‑131) – Generate downstream influence maps via graph.analyze_decision_impact

Step 4: Export W3C PROV‑O Audit Trails

For regulatory review, the RDFExporter class in semantica/export.py converts the decision sub‑graph into standard formats. Calling graph.to_kg_dict() serializes the knowledge graph, which RDFExporter().export() renders as RDF/Turtle, JSON‑LD, or CSV compliant with W3C PROV‑O standards.

Recording and Linking Decisions in Practice

The following example demonstrates the complete lifecycle from recording a credit approval decision to establishing its causal links.

from semantica.context import ContextGraph

# Initialize the graph with advanced analytics enabled

graph = ContextGraph(advanced_analytics=True)

# Record a decision with full context and metadata

decision_id = graph.record_decision(
    category="credit_application",
    scenario="Applicant A: $85k income, 31% DTI, 3‑yr employment",
    reasoning="Income meets threshold; employment stable; no adverse credit events",
    outcome="proceed_to_underwriting",
    confidence=0.88,
    metadata={"applicant_id": "A‑7291"},
)

# Establish causal provenance (e.g., link to a prior risk assessment)

graph.add_causal_relationship(
    source="prior_risk_assessment_id",
    target=decision_id,
    relationship_type="CAUSED",  # Options: CAUSED, INFLUENCED, PRECEDENT_FOR

)

The record_decision method returns a unique decision_id that serves as the anchor for all subsequent auditing operations. By setting SEMANTICA_KG_PATH in your environment, these mutations persist across process restarts.

Querying Causal Chains and Impact Analysis

Once decisions are recorded, you can trace their lineage and downstream effects using the MCP tool handlers.

from semantica.mcp.tools.decisions import (
    handle_query_decisions,
    handle_get_causal_chain,
    handle_analyze_decision_impact,
)

# Natural-language search for precedents

results = handle_query_decisions({
    "query": "personal loan approval with low DTI",
    "limit": 5,
})
print(f"Found {len(results['decisions'])} relevant decisions")

# Trace upstream causal chain for audit

chain = handle_get_causal_chain({
    "decision_id": decision_id,
    "direction": "upstream",
    "max_depth": 10,
})
print("Upstream dependencies:", chain["chain"])

# Analyze downstream impact

impact = handle_analyze_decision_impact({"decision_id": decision_id})
print("Downstream influence map:", impact["impact"])

The handle_get_causal_chain function returns an ordered list of nodes representing the complete decision lineage, while handle_analyze_decision_impact identifies all downstream nodes affected by the target decision.

Exporting Audit Trails for Compliance

To generate regulator-ready artifacts, serialize the graph to PROV‑O format.

from semantica.export import RDFExporter

# Build the knowledge graph dictionary

kg_dict = graph.to_kg_dict()

# Export to W3C PROV-O (Turtle format)

exporter = RDFExporter()
exporter.export(kg_dict, "audit_trail.ttl", format="turtle")

This produces a standards-compliant file containing every decision node, its provenance metadata, and causal relationships—suitable for direct submission to compliance auditors or ingestion into external governance platforms.

Summary

• Treat decisions as first-class nodes in the Context Graph to preserve complete audit context
• Validate payloads against the RECORD_DECISION schema in mcp/schemas.py (lines 39‑78) before persistence
• Link causality using add_causal_relationship with types CAUSED, INFLUENCED, or PRECEDENT_FOR
• Query history via handle_query_decisions (lines 85‑104) using natural language or structured filters
• Trace lineage with handle_get_causal_chain (lines 126‑144) for deterministic audit trails
• Export compliance artifacts using RDFExporter to generate W3C PROV‑O documents for regulatory review

Frequently Asked Questions

What is W3C PROV-O and why is it required for AI auditing?

W3C PROV-O is a standard ontology for representing provenance information on the web. Regulators increasingly require AI systems to produce audit trails in this format because it provides an interoperable, machine-readable representation of how decisions were made, what data influenced them, and what outputs they produced. Semantica’s RDFExporter generates PROV-O compatible RDF/Turtle files directly from the Context Graph.

How does Semantica ensure decision provenance without LLM hallucinations?

All provenance tracking in Semantica is deterministic and graph-based. The handle_record_decision and causal linking functions operate through strict schema validation and explicit graph mutations rather than LLM generation. This ensures that every relationship is explicitly declared by the calling application code and stored immutably in the knowledge graph, eliminating the risk of hallucinated provenance chains.

Can I filter decisions by specific categories or confidence thresholds?

Yes. The handle_query_decisions function (lines 85‑104 in mcp/tools/decisions.py) accepts structured filters alongside natural-language queries. You can filter by category to isolate specific decision types (e.g., "credit_application") or by outcome to analyze approval vs. denial patterns. The underlying graph.find_similar_decisions API also supports metadata-based filtering for custom confidence thresholds.

What happens if the knowledge graph persistence fails during recording?

The handle_record_decision function implements transactional safety. If persistence to SEMANTICA_KG_PATH fails after the in‑memory graph is mutated, the function rolls back the mutation to ensure consistency between the in‑memory state and the on-disk knowledge graph. This prevents silent data loss and guarantees that successful function returns always indicate durable storage.

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