# Components of Semantica's Knowledge Graph: Ontology, Reasoning, Provenance, and Decisions

> Explore Semantica's knowledge graph components: Ontology, Reasoning, Provenance, and Decisions. Transform data into an inferential, traceable, and decision-aware semantic platform.

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

---

**Semantica's knowledge graph architecture is built on four pillars—Ontology, Reasoning, Provenance, and Decisions—that transform raw nodes and edges into a schema-rich, inferential, traceable, and decision-aware semantic platform.**

The `semantica-agi/semantica` repository implements a unified knowledge graph platform that layers these four capabilities atop a base graph of nodes, edges, temporal facts, and provenance. According to the architecture documentation in [`ARCHITECTURE.md`](https://github.com/semantica-agi/semantica/blob/main/ARCHITECTURE.md), these pillars enrich raw graph data with formal semantics, automated inference, end-to-end lineage tracking, and decision intelligence.

## The Four Pillars of Semantica's Knowledge Graph

### Ontology: Formal Schema and Domain Modeling

The **Ontology** component provides a formal schema describing classes, properties, and hierarchies that define the domain of the graph. It enables validation against shapes, automatic SHACL generation, OWL export, and version-controlled schema evolution.

Key implementation files include:
- [`semantica/ontology/ontology_engine.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ontology/ontology_engine.py) – Core engine for ontology operations
- [`semantica/ontology/ontology_generator.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ontology/ontology_generator.py) – Schema generation utilities
- [`semantica/ontology/ontology_usage.md`](https://github.com/semantica-agi/semantica/blob/main/semantica/ontology/ontology_usage.md) – Implementation guide

The primary API surface exposes methods like `OntologyEngine().from_data()` for schema generation, `OntologyEngine().validate()` for consistency checking using reasoners such as HermiT, and `OntologyEngine().to_owl()` for exporting to standard OWL formats.

### Reasoning: Inference and Explanation Generation

The **Reasoning** component derives implicit facts from explicit triples using rule-based, SPARQL, or Rete-engine inference. It supports abductive, deductive, and Datalog reasoning modes while generating human-readable explanations for every inference.

Key implementation files include:
- [`semantica/reasoning/reasoner.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning/reasoner.py) – High-level reasoning facade
- [`semantica/reasoning/spaql_reasoner.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning/spaql_reasoner.py) – SPARQL-based inference engine
- [`semantica/reasoning/rete_engine.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning/rete_engine.py) – Rete algorithm implementation
- [`semantica/reasoning/reasoning_usage.md`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning/reasoning_usage.md) – Usage documentation

Typical usage involves chaining methods like `Reasoner().add_fact()`, `.add_rule()`, and `.infer()`, or executing queries via `SPARQLReasoner(triplet_store=kg).execute_query()`.

### Provenance: W3C PROV-O Lineage Tracking

The **Provenance** component tracks end-to-end lineage for every entity, relationship, and chunk using **W3C PROV-O** standards. It stores source documents, locations, confidence scores, and integrity checksums using either in-memory or SQLite backends.

Key implementation files include:
- [`semantica/provenance/provenance_manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/provenance_manager.py) – Main provenance coordinator
- [`semantica/provenance/provenance_storage.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/provenance_storage.py) – Storage abstraction layer
- [`semantica/provenance/provenance_usage.md`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/provenance_usage.md) – Integration guide

The API provides `ProvenanceManager().track_entity()` for recording lineage metadata and `ProvenanceManager().get_lineage()` for retrieving complete audit trails by entity ID.

### Decisions and Context: Decision Intelligence Lifecycle

The **Decisions** pillar (labeled **Context & Decisions** in the architecture) captures the decision-intelligence lifecycle by recording decisions, linking causal relationships, querying similar precedents, and governing with policy checks. Decisions live as a **Context Graph** tightly coupled to the main knowledge graph.

Key implementation files include:
- [`semantica/context/decision_recorder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/decision_recorder.py) – Decision persistence and recording
- [`semantica/context/causal_chain_analyzer.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/causal_chain_analyzer.py) – Causal relationship analysis
- [`semantica/context/context_usage.md`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_usage.md) – High-level usage documentation

The `Context` facade exposes `context.record_decision()` for logging decisions, `context.find_similar_decisions()` for semantic precedent search, and `context.trace_decision_chain()` for causal auditing.

## How the Components Interoperate

The four pillars form a processing pipeline that enriches data incrementally:

1. **Ingestion** creates the base **knowledge graph (KG)** from raw documents through parsing, normalization, and extraction.

2. **Ontology** augments the KG with a formal schema, enabling shape-validation via `validate()` and OWL export via `to_owl()`.

3. **Reasoning** consumes the ontology-enriched KG to produce new inferred triples and human-readable explanations.

4. **Provenance** attaches PROV-O metadata to every KG artifact, including entities, relationships, inferred facts, and text chunks.

5. **Decisions** layers a decision graph atop the KG, linking decisions to their causal provenance and enabling similarity search and policy governance.

## Practical Implementation Examples

### Generating and Validating Ontologies

```python
from semantica.ontology import OntologyEngine

# Generate an ontology from KG data

data = {
    "entities": [
        {"type": "Person", "name": "Alice"},
        {"type": "Organization", "name": "Acme Corp"},
    ],
    "relationships": [
        {"type": "worksFor", "source": "Alice", "target": "Acme Corp"},
    ],
}
engine = OntologyEngine(base_uri="https://example.org/ontology/")
ontology = engine.from_data(data, name="EmployeeOntology")

# Validate with the HermiT reasoner

validation = engine.validate(ontology, reasoner="hermit")
print("Valid:", validation.valid, "Consistent:", validation.consistent)

# Export to Turtle (OWL)

turtle = engine.to_owl(ontology, format="turtle")
with open("employee_ontology.ttl", "w") as f:
    f.write(turtle)

```

### Running Inference with Rules

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

# Create a reasoner bound to the KG

r = Reasoner()
r.add_fact("Person(John)")
r.add_fact("Person(Jane)")
r.add_rule("IF Person(?x) THEN Human(?x)")

# Infer new facts

new_facts = r.infer()
print("Inferred:", [f.conclusion for f in new_facts])

# Generate a human-readable explanation

explainer = ExplanationGenerator()
explanation = explainer.generate_explanation(new_facts[0])
print(explanation.natural_language)

```

### Tracking Data Lineage

```python
from semantica.provenance import ProvenanceManager

prov = ProvenanceManager()  # In-memory backend

prov.track_entity(
    entity_id="entity_1",
    source="DOI:10.1371/journal.pone.0023601",
    source_location="Figure 2",
    source_quote="Total fish biomass increased by 463%",
    confidence=0.92,
)

lineage = prov.get_lineage("entity_1")
print("Source documents:", lineage["source_documents"])

```

### Recording and Querying Decisions

```python
from semantica.context import Context  # high-level façade

ctx = Context()

# Record a decision

decision_id = ctx.record_decision(
    category="CreditApproval",
    scenario="Loan request of $50k",
    reasoning="Applicant has stable income and good credit score",
    outcome="approved",
    confidence=0.95,
)

# Find similar past decisions

similar = ctx.find_similar_decisions(scenario="Loan request of $50k")
print(f"Found {len(similar)} similar decisions")

```

## Summary

- **Ontology** provides formal schema definitions and validation capabilities through [`semantica/ontology/ontology_engine.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ontology/ontology_engine.py), enabling OWL export and SHACL generation.
- **Reasoning** drives inference via rule-based, SPARQL, and Rete engines in [`semantica/reasoning/reasoner.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning/reasoner.py), producing explained derivations from explicit triples.
- **Provenance** ensures complete traceability using W3C PROV-O standards implemented in [`semantica/provenance/provenance_manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/provenance_manager.py), tracking sources and confidence scores.
- **Decisions** embeds decision intelligence into the graph through [`semantica/context/decision_recorder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/decision_recorder.py), supporting causal analysis and precedent search.

## Frequently Asked Questions

### What is the difference between Ontology and Reasoning in Semantica?

**Ontology** defines the schema and validation rules for the knowledge graph, specifying classes, properties, and hierarchies. **Reasoning** applies inference engines to derive new facts from existing triples using those schemas. While Ontology establishes what *can* exist, Reasoning determines what *must* exist based on logical rules.

### How does Semantica track provenance?

Semantica implements W3C PROV-O standards through the `ProvenanceManager` class in [`semantica/provenance/provenance_manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/provenance_manager.py). It captures source documents, exact locations (like figure numbers), direct quotes, confidence scores, and integrity checksums for every entity and relationship, storing this lineage in-memory or in SQLite.

### Can Semantica export decisions to standard formats?

Yes. The decision recording system in [`semantica/context/decision_recorder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/decision_recorder.py) captures decisions with full PROV-O lineage, enabling audit-ready export. Decisions integrate with the provenance layer, allowing complete causal chains to be serialized using standard W3C provenance formats alongside the knowledge graph.

### How do the four components interact during data ingestion?

During ingestion, raw data first populates the base knowledge graph. The **Ontology** layer immediately validates this data against formal schemas. **Reasoning** then processes the validated triples to infer implicit relationships. **Provenance** tags every artifact—from raw chunks to inferred facts—with source metadata. Finally, **Decisions** can reference this enriched, traceable graph to record contextual choices and link them to the underlying evidence chain.