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

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, 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, which contains GraphBuilder and GraphAnalyzer classes, while chunking utilities live in 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 and 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, while ontology tools reside in 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, and the visualization workbench is accessible through 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 – Entry point for NER, relation, event, and triplet extraction.
• semantica/kg/__init__.py – Contains GraphBuilder, GraphAnalyzer, and graph-analytics utilities.
• semantica/vector_store/__init__.py – Defines the abstract VectorStore class and backend registry.
• semantica/reasoning/__init__.py – Houses forward-chaining, Rete, Datalog, and SPARQL engines.
• semantica/provenance/__init__.py – Implements the W3C PROV-O provenance manager.
• semantica/ontology/__init__.py – Provides OWL generation, SHACL validation, and SKOS utilities.
• semantica/split/__init__.py – Offers entity-aware, relation-aware, and graph-based chunkers for GraphRAG pipelines.
• semantica/export/__init__.py – Exporters for RDF, OWL, Parquet, Cypher, JSON-LD, and other formats.
• 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:

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 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 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 contains the GraphBuilder class that consumes outputs from the extraction pipeline defined in 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, 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.

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