# How Semantica Makes Inference Paths Auditable in Its Reasoning Layer

> Discover how Semantica makes inference paths auditable. Learn about provenance tracking and immutable logs for transparent AI reasoning. Explore Semantica now.

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

---

**Semantica achieves auditable inference paths by wrapping inference calls with provenance tracking, persisting each inference as a first-class provenance entity, and exposing detailed reasoning steps through an immutable, queryable audit log.**

The `semantica-agi/semantica` repository implements a provenance-enabled reasoning architecture that treats every inference as a traceable activity. By recording timestamps, agent identifiers, and structured reasoning paths, the system creates immutable audit trails for all derived facts. This design ensures complete transparency into exactly how conclusions are reached within the reasoning layer.

## Provenance-Aware Reasoning Engine

The foundation of auditable inference lies in the `ReasoningEngineWithProvenance` class located in [`semantica/reasoning/reasoning_provenance.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning/reasoning_provenance.py). This wrapper extends the core `Reasoner` to capture comprehensive metadata at the moment of inference execution.

### Capturing Inference Metadata

When the `infer` method is invoked, the engine executes the logic and obtains a list of `InferenceResult` objects. It then generates a unique provenance entity with a UUID formatted as `inference_<…>`, recording the start and end timestamps, the source (defaulting to `reasoning_engine`), and the specific agent that performed the inference. The entity also stores metadata including the number of premises processed and the aggregated confidence score.

This provenance entity is dispatched to the unified `ProvenanceManager` defined in [`semantica/provenance/manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/manager.py), which persists the entry to a configurable backend such as in-memory storage or SQLite.

## Structured Reasoning Paths

Auditability requires more than timestamps—it demands granular visibility into the logical derivation steps. The `ExplanationGenerator` class in [`semantica/reasoning/explanation_generator.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning/explanation_generator.py) translates raw `InferenceResult` objects into both human-readable explanations and machine-parseable reasoning paths.

### From Results to Reasoning Steps

Each `InferenceResult` is decomposed into a series of `ReasoningStep` objects that capture the premise, applied rule, input facts, output fact, confidence score, and additional metadata. These steps are aggregated into a `ReasoningPath` object that can be serialized to JSON or markdown and attached to the provenance entity as evidence.

This structured approach ensures that every derived fact carries a complete genealogy of the logical operations that produced it, fulfilling the requirement for auditable inference paths.

## Exportable Audit Logs

The `ProvenanceManager` provides the `audit_log` method (implemented at line 1172 in [`semantica/provenance/manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/manager.py)) to export all provenance entries—including inference entities—into a chronologically sorted, immutable audit trail.

### Querying and Exporting Evidence

Each audit entry contains activity timestamps, agent details, confidence metrics, and a reference to the reasoning path stored as a JSON blob. The system supports export in **JSON**, **CSV**, or **table** formats, enabling direct integration with downstream compliance workflows or forensic analysis tools.

The storage layer implemented in [`semantica/provenance/storage.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/storage.py) ensures that once recorded, provenance entries cannot be altered or deleted, guaranteeing the integrity of the audit trail for regulatory purposes.

## End-to-End Traceability

When clients request provenance via the `/api/provenance` endpoint, the backend assembles the complete lineage chain. It follows `source='audit'` edges that point to the inference entities originally recorded by `ReasoningEngineWithProvenance`, guaranteeing that any derived fact can be traced back to the exact sequence of inference steps that produced it.

This traceability spans from the initial `infer` call through the reasoning layer to the final storage definitions in [`semantica/provenance/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/schemas.py), creating a closed loop of accountability.

## Implementation Examples

The following examples demonstrate how to perform auditable inference and export the resulting trails for verification:

```python

# Perform an inference while capturing provenance

from semantica.reasoning import ReasoningEngineWithProvenance

engine = ReasoningEngineWithProvenance(provenance=True, agent_id="my_app")
conclusions = engine.infer(premises=my_facts, source="my_data_source")

```

```python

# Generate a human-readable reasoning path for verification

from semantica.reasoning import ExplanationGenerator

gen = ExplanationGenerator()
explanation = gen.generate_explanation(engine._engine.last_results[0])
path = gen.generate_reasoning_path(engine._engine.last_results[0])

print(path)  # Structured list of ReasoningStep objects

print(explanation.natural_language)  # Natural language explanation

```

```python

# Export the full audit log for compliance review

from semantica.provenance import ProvenanceManager

prov_mgr = ProvenanceManager()
audit_json = prov_mgr.audit_log(format="json")
print(audit_json)  # Contains all inference entities and reasoning paths

```

## Summary

- **Provenance Wrapping**: The `ReasoningEngineWithProvenance` class in [`semantica/reasoning/reasoning_provenance.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning/reasoning_provenance.py) intercepts inference calls to create timestamped, UUID-identified provenance entities for every operation.
- **Structured Evidence**: The `ExplanationGenerator` decomposes `InferenceResult` objects into `ReasoningPath` sequences containing detailed `ReasoningStep` metadata, enabling complete logical reconstruction.
- **Immutable Storage**: The `ProvenanceManager` persists entries to backends like SQLite via [`semantica/provenance/storage.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/storage.py), ensuring tamper-proof audit trails that satisfy forensic standards.
- **Exportable Compliance**: The `audit_log` method exports chronological records in JSON, CSV, or table formats, facilitating integration with external compliance platforms.
- **Complete Lineage**: The system traces derived facts back to original premises through `source='audit'` relationships stored according to the schemas defined in [`semantica/provenance/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/schemas.py).

## Frequently Asked Questions

### How does Semantica ensure that inference records cannot be altered after creation?

The `ProvenanceManager` writes entries to storage backends defined in [`semantica/provenance/storage.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/storage.py) using an append-only, immutable design. Once an inference entity is recorded with its UUID and timestamp, the storage layer prevents modifications or deletions, creating a tamper-evident audit trail suitable for regulatory compliance and forensic analysis.

### What specific information is captured in a reasoning path?

Each reasoning path consists of `ReasoningStep` objects that document the input premise, the specific logical rule applied, input facts, output facts, confidence scores, and additional metadata. The `ExplanationGenerator` in [`semantica/reasoning/explanation_generator.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning/explanation_generator.py) serializes these paths to JSON and attaches them directly to provenance entities, providing complete transparency into the logical derivation.

### Can audit logs be exported for integration with external compliance systems?

Yes. The `ProvenanceManager.audit_log()` method supports export in **JSON**, **CSV**, or **table** formats as implemented at line 1172 of [`semantica/provenance/manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/manager.py). This enables seamless integration with external SIEM systems, regulatory reporting tools, or compliance platforms while preserving the exact chronological order and integrity of the inference history.

### How does the system handle concurrent inference operations in the audit trail?

Each inference call through `ReasoningEngineWithProvenance` generates a unique UUID-prefixed entity (`inference_<…>`) and records precise start and end timestamps with microsecond precision. The `ProvenanceManager` processes these entries atomically, ensuring that concurrent operations are recorded sequentially without collision and maintaining the exact chronological order of all reasoning activities in the unified audit log.