# How Semantica's ExplanationGenerator Provides Explainable Reasoning Paths

> Semantica's ExplanationGenerator creates clear, step-by-step reasoning paths from raw inference. Get machine-processable logic and human-readable explanations.

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

---

**Semantica's ExplanationGenerator constructs explainable reasoning paths by transforming raw inference results into structured, step‑by‑step traces composed of `ReasoningStep` objects, enabling both machine‑processable logic and human‑readable natural‑language justifications.**

The `semantica-agi/semantica` repository implements a neuro‑symbolic AI framework where transparency is paramount. The `ExplanationGenerator` class serves as the central engine for converting opaque reasoning outputs—whether deductive proofs, abductive hypotheses, or simple inferences—into **explainable reasoning paths** that trace exactly how a conclusion was reached.

## Core Data Structures for Reasoning Transparency

The explanation architecture in [`semantica/reasoning/explanation_generator.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning/explanation_generator.py) decouples logical representation from presentation through four primary data classes.

### ReasoningStep

The `ReasoningStep` class (lines 44‑55) captures a single discrete inference operation. It stores a unique step identifier, a human‑readable description, the specific rule applied, input facts, the output fact, confidence scores, and arbitrary metadata. This granularity ensures that every logical operation remains auditable.

### ReasoningPath

A `ReasoningPath` (lines 58‑66) aggregates multiple `ReasoningStep` instances into an ordered sequence. It tracks the initial premises, the final conclusion, and an aggregate confidence calculation across all steps, providing the structural backbone for **explainable reasoning paths**.

### Justification and Explanation

The `Justification` class (lines 69‑78) bundles a conclusion with its supporting `ReasoningPath`, evidence references, and natural‑language text. The top‑level `Explanation` class (lines 82‑92) encapsulates the final output, including optional reasoning paths and justifications, making the trace consumable by both visualizers and end‑users.

## The Explanation Generation Workflow

The `ExplanationGenerator` orchestrates the creation of explanations through a type‑aware dispatch system that handles diverse reasoning modalities.

### Entry Point and Type Dispatch

The `generate_explanation` method acts as the primary entry point (lines 130‑173), accepting any reasoning object—`InferenceResult`, `Proof`, `AbductiveExplanation`, or generic values. It inspects the input type and routes to specialized helper methods, ensuring that each reasoning paradigm receives appropriate processing for building **explainable reasoning paths**.

### Specialized Handlers for Different Reasoning Types

Four distinct handlers convert specific reasoning artifacts into structured traces:

1. **Inference Results**: `_explain_inference_result` (lines 191‑236) constructs a `ReasoningPath` from premises, optionally appends rule application steps, and assembles the final `Explanation` object.
2. **Proof Objects**: `_explain_proof` (lines 238‑274) iterates through proof steps, converting each into a `ReasoningStep` to build a complete deductive trace.
3. **Abductive Explanations**: `_explain_abductive` (lines 276‑315) transforms hypothesis objects into reasoning paths that explain why a particular hypothesis best explains the observed facts.
4. **Fallback Handling**: `_explain_generic` wraps unrecognized objects in a basic `Explanation` container for API consistency.

### Path Retrieval and Justification

The public method `show_reasoning_path` (lines 29‑41) provides direct access to the embedded `ReasoningPath` from any explanation. For formal validation, `justify_conclusion` (lines 43‑98) aggregates input facts across all steps, calculates aggregate confidence, and generates natural‑language justifications via `_generate_justification_text`.

## Natural Language Synthesis

Depending on the `detail_level` configuration and `generate_nl` flag, the generator synthesizes human‑readable descriptions. Helper methods `_generate_natural_language`, `_generate_natural_language_from_proof`, and `_generate_natural_language_from_abductive` (lines 112‑155) produce varying verbosity levels, from concise summaries to detailed step‑by‑step narratives of the **explainable reasoning paths**.

## Practical Code Examples

The following examples demonstrate how to generate and consume explanations using the `ExplanationGenerator`.

First, instantiate the generator and process an inference result:

```python
from semantica.reasoning import ExplanationGenerator, InferenceResult

# Mock inference result (typically produced by a Reasoner)

inference = InferenceResult(
    conclusion="All mammals are warm‑blooded",
    premises=["All dogs are mammals", "All cats are mammals"],
    confidence=0.96,
    rule_used=Rule(name="Transitivity", rule_id="R1")
)

gen = ExplanationGenerator(config={"detail_level": "detailed"})
explanation = gen.generate_explanation(inference)

print("Explanation ID:", explanation.explanation_id)
print("NL text:", explanation.natural_language)
print("Path ID:", explanation.reasoning_path.path_id)
for step in explanation.reasoning_path.steps:
    print(f"- {step.step_id}: {step.description}")

```

To retrieve only the reasoning path and generate a formal justification:

```python
path = gen.show_reasoning_path(inference)
just = gen.justify_conclusion(conclusion=inference.conclusion, reasoning_path=path)

print("\nJustification text:")
print(just.explanation_text)

```

These snippets illustrate how the generator creates full reasoning traces, exposes them via `show_reasoning_path`, and transforms them into natural‑language justifications.

## Summary

- **Semantica's ExplanationGenerator** in [`semantica/reasoning/explanation_generator.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning/explanation_generator.py) converts raw reasoning outputs into structured, auditable traces.
- **Four data classes**—`ReasoningStep`, `ReasoningPath`, `Justification`, and `Explanation`—provide the architectural foundation for transparent reasoning.
- **Type‑aware dispatch** via `generate_explanation` handles inference results, proofs, and abductive explanations through specialized handlers.
- **Dual representation** separates machine‑processable logic from human‑readable natural language, enabling consumption by both visualizers and end‑users.
- **Public methods** `show_reasoning_path` and `justify_conclusion` provide programmatic access to reasoning traces and formal justifications.

## Frequently Asked Questions

### What file contains the ExplanationGenerator implementation?

The `ExplanationGenerator` class and its associated data models reside in [`semantica/reasoning/explanation_generator.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning/explanation_generator.py) within the `semantica-agi/semantica` repository. This module defines the core logic for transforming reasoning results into structured explanations.

### How does Semantica handle different types of reasoning inputs?

The generator uses a dispatch pattern in the `generate_explanation` method to route inputs to specialized handlers: `_explain_inference_result` for deductive inferences, `_explain_proof` for formal proofs, `_explain_abductive` for hypothesis generation, and `_explain_generic` as a fallback for unknown types.

### Can I extract just the reasoning path without natural language?

Yes. The `show_reasoning_path` method returns the `ReasoningPath` object directly, containing the ordered list of `ReasoningStep` instances without requiring natural language generation. This is useful for downstream visualizers or automated analysis tools that need structured data.

### What information does each ReasoningStep capture?

Each `ReasoningStep` stores a unique identifier, textual description, the rule applied during that step, input facts, the resulting output fact, confidence scores, and metadata. This comprehensive capture ensures complete auditability of the reasoning process.