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

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, 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 – Core engine for ontology operations
• semantica/ontology/ontology_generator.py – Schema generation utilities
• 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 – High-level reasoning facade
• semantica/reasoning/spaql_reasoner.py – SPARQL-based inference engine
• semantica/reasoning/rete_engine.py – Rete algorithm implementation
• 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 – Main provenance coordinator
• semantica/provenance/provenance_storage.py – Storage abstraction layer
• 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 – Decision persistence and recording
• semantica/context/causal_chain_analyzer.py – Causal relationship analysis
• 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

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

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

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

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, enabling OWL export and SHACL generation.
• Reasoning drives inference via rule-based, SPARQL, and Rete engines in 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, tracking sources and confidence scores.
• Decisions embeds decision intelligence into the graph through 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. 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 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.

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