# What Is the Purpose of the `semantica` Directory in the Semantica Repository?

> Discover the purpose of the semantica directory within the semantica-agi/semantica repository. This core Python package provides the graph-native infrastructure for building, reasoning over, and visualizing knowledge graphs.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: internals
- Published: 2026-08-13

---

**The `semantica` directory is the core Python package that houses the complete graph-native infrastructure for building, reasoning over, and visualizing context graphs and knowledge graphs.**

The `semantica` directory serves as the public API and implementation core of the `semantica-agi/semantica` repository. This self-contained Python package bundles deterministic decision intelligence, full audit trails, and enterprise-grade governance into a swappable suite that sits beneath any LLM or agent framework.

## Core Architecture of the `semantica` Package

The directory organizes functionality into specialized sub-packages that handle the entire lifecycle of knowledge graph construction and reasoning.

### Data Ingestion and Semantic Extraction

The **`semantica.ingest`** module pulls data from files, web pages, databases, data-warehouses, and streams. Once ingested, **`semantica.semantic_extract`** performs named entity recognition (NER), relation and event extraction, and triplet generation to structure the raw content. The entry point for these capabilities resides in [`semantica/semantic_extract/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/semantic_extract/__init__.py), which exposes the extraction pipelines.

### Graph Construction and Document Chunking

**`semantica.kg`** builds bi-temporal knowledge graphs and runs graph analytics including centrality calculations, community detection, and link prediction. Complementing this, **`semantica.split`** provides GraphRAG-aware document chunkers that preserve entities and relations across text boundaries. The graph construction logic is accessible through [`semantica/kg/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/__init__.py), which contains `GraphBuilder` and `GraphAnalyzer` classes, while chunking utilities live in [`semantica/split/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/split/__init__.py).

### Reasoning Engines and Vector Storage

**`semantica.reasoning`** offers multiple inference modalities including forward-chaining, Rete algorithm, Datalog, and SPARQL engines with full provenance tracking. For storage and retrieval, **`semantica.vector_store`** abstracts over FAISS, Qdrant, Weaviate, Milvus, Pinecone, PgVector, and SQLite, adding hybrid search and decision-aware retrieval capabilities. These are implemented in [`semantica/reasoning/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning/__init__.py) and [`semantica/vector_store/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/__init__.py) respectively.

### Governance, Provenance, and Ontology Management

Enterprise governance is enforced through **`semantica.provenance`**, which records W3C PROV-O lineage for every fact, decision, and relationship. **`semantica.ontology`** generates OWL ontologies, validates SHACL shapes, and manages SKOS vocabularies. Data quality is maintained by **`semantica.conflicts`** (contradiction detection) and **`semantica.deduplication`** (entity merging). The provenance manager is implemented in [`semantica/provenance/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/__init__.py), while ontology tools reside in [`semantica/ontology/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ontology/__init__.py).

### Pipeline Orchestration and Visualization

**`semantica.pipeline`** provides DSL-driven pipeline construction, while **`semantica.normalize`** handles data cleaning. **`semantica.export`** supports multiple output formats including RDF, OWL, Parquet, Cypher, and JSON-LD. For interactive exploration, **`semantica.visualization`** delivers a graph workbench for visualizing graphs, ontologies, and timelines. Export functionality is centralized in [`semantica/export/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/__init__.py), and the visualization workbench is accessible through [`semantica/visualization/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/visualization/__init__.py).

## Key Source Files in the `semantica` Directory

The public API surface of the `semantica` directory is exposed through these key implementation files:

- **[`semantica/semantic_extract/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/semantic_extract/__init__.py)** – Entry point for NER, relation, event, and triplet extraction.
- **[`semantica/kg/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/__init__.py)** – Contains `GraphBuilder`, `GraphAnalyzer`, and graph-analytics utilities.
- **[`semantica/vector_store/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/__init__.py)** – Defines the abstract `VectorStore` class and backend registry.
- **[`semantica/reasoning/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning/__init__.py)** – Houses forward-chaining, Rete, Datalog, and SPARQL engines.
- **[`semantica/provenance/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/__init__.py)** – Implements the W3C PROV-O provenance manager.
- **[`semantica/ontology/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ontology/__init__.py)** – Provides OWL generation, SHACL validation, and SKOS utilities.
- **[`semantica/split/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/split/__init__.py)** – Offers entity-aware, relation-aware, and graph-based chunkers for GraphRAG pipelines.
- **[`semantica/export/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/__init__.py)** – Exporters for RDF, OWL, Parquet, Cypher, JSON-LD, and other formats.
- **[`semantica/visualization/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/visualization/__init__.py)** – Interactive workbench for visualizing graphs and decision timelines.

## Practical Example: Using the `semantica` Package

The following minimal example demonstrates how the `semantica` directory's top-level functionality works in practice:

```python
from semantica.context import ContextGraph

# Create a context graph with advanced analytics enabled

graph = ContextGraph(advanced_analytics=True)

# Record a decision – becomes a first-class node in the graph

decision_id = graph.record_decision(
    category="vendor_selection",
    scenario="Choose cloud provider for HIPAA workload",
    reasoning="AWS offers BAA, mature HIPAA tooling, and existing team expertise",
    outcome="selected_aws",
    confidence=0.93,
)

# Trace the causal chain of that decision

chain = graph.trace_decision_chain(decision_id)

print(f"Causal chain for decision {decision_id}:")
for step in chain:
    print(step)

```

This snippet works because all underlying operations—including ingest, extraction, KG building, provenance recording, and reasoning—are implemented within the `semantica` package.

## Summary

- The **`semantica` directory** is the core Python package implementing the entire Semantica platform.
- It provides **end-to-end capabilities** from data ingestion through knowledge graph construction to visualization.
- Key modules include **`semantica.kg`** for graph construction and **`semantica.reasoning`** for deterministic inference.
- The package implements **W3C PROV-O provenance tracking** through [`semantica/provenance/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/__init__.py) for full auditability.
- It abstracts multiple vector stores including FAISS, Qdrant, and Weaviate via the `semantica.vector_store` module.
- All functionality is exposed through a unified public API in the respective [`__init__.py`](https://github.com/semantica-agi/semantica/blob/main/__init__.py) files.

## Frequently Asked Questions

### What is the difference between `semantica.kg` and `semantica.semantic_extract`?

`semantica.semantic_extract` handles the extraction of entities, relations, and events from raw data through NER and triplet generation. `semantica.kg` takes these extracted elements to construct the actual bi-temporal knowledge graph, running analytics like centrality and community detection. According to the source code, [`semantica/kg/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/__init__.py) contains the `GraphBuilder` class that consumes outputs from the extraction pipeline defined in [`semantica/semantic_extract/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/semantic_extract/__init__.py).

### How does the `semantica` directory integrate with vector databases?

The `semantica.vector_store` module provides a unified abstraction layer that wraps backends including FAISS, Qdrant, Weaviate, Milvus, Pinecone, PgVector, and SQLite. As implemented in [`semantica/vector_store/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/__init__.py), this module adds hybrid search capabilities and decision-aware retrieval on top of these stores, allowing seamless swapping of backends without changing application logic.

### What governance features are built into the `semantica` package?

The package implements enterprise-grade governance through `semantica.provenance`, which records W3C PROV-O lineage for every fact and decision. Additionally, `semantica.conflicts` identifies contradictory facts while `semantica.deduplication` merges duplicate entities before they propagate through the system. These modules ensure full audit trails and data quality enforcement.

### Can the `semantica` package operate independently of external LLM frameworks?

Yes, the `semantica` directory constitutes a self-contained, swappable suite that adds deterministic decision intelligence beneath any LLM, agent framework, or vector store. While it integrates with LLMs, its core graph-native infrastructure—including the reasoning engine, provenance tracking, and knowledge graph construction—functions independently as the implementation core of the Semantica platform.