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

> Learn how to track and audit AI decisions with Semantica. This guide details capturing provenance, causal links, and generating regulator-ready audit trails in W3C PROV-O format.

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

---

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

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

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

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