How to Build a Knowledge Graph with Semantica: A Complete Pipeline Guide

Use Semantica’s modular four-stage pipeline—seed ingestion, LLM-driven extraction, vector storage, and visualization—to construct, enrich, and query production-ready knowledge graphs from structured and unstructured data.

Semantica is a modular Python framework developed by semantica-agi/semantica designed specifically to build a knowledge graph with Semantica through composable, interchangeable components. The architecture separates concerns into distinct stages, allowing you to swap vector stores, LLM providers, or visualization backends without rewriting core logic. This guide examines the actual source implementation to demonstrate how to orchestrate SeedDataManager, extraction tools, and the Reasoner class into an end-to-end workflow.

The Four-Stage Knowledge Graph Pipeline

Semantica organizes knowledge graph construction into four discrete stages, each handled by specialized classes in the codebase.

Stage 1: Seed Ingestion and Foundation Graphs

The pipeline begins with SeedDataManager in semantica/seed/seed_manager.py, which registers raw data sources and converts them into a canonical foundation graph. This class supports CSV, JSON, database, and API sources through register_source() and loads them via load_from_* methods. The create_foundation_graph() method validates and assembles the initial entity-relationship structure, enforcing quality checks via validate_quality() before returning the graph object.

Stage 2: LLM-Driven Extraction and Enrichment

Unstructured text feeds into the extraction layer located in semantica/mcp/tools/extraction.py. The extract_entities_and_relations() function invokes language models to parse free-form text into structured graph elements. To merge these extractions with seed data, SeedDataManager provides integrate_with_extracted() (lines 190–225), which supports three merge strategies: seed_first, extracted_first, or merge, configurable via the merge_strategy parameter.

Stage 3: Vector Storage and Semantic Reasoning

The abstract VectorStore class in semantica/vector_store/vector_store.py defines the storage interface, with concrete implementations like FaissStore (semantica/vector_store/faiss_store.py) providing in-memory ANN indexing. After ingestion, persist entities and relationships using upsert_entities() and upsert_relationships(). The Reasoner class in semantica/reasoning/reasoner.py executes queries against this storage, supporting SPARQL reasoning (via semantica/reasoning/sparql_reasoner.py), fact assertion through AssertAction, and custom reasoning actions.

Stage 4: Visualization and Export

The KGVisualizer class in semantica/visualization/kg_visualizer.py coordinates multiple visualization methods including network diagrams, community detection, and centrality-based sizing. For downstream analytics, semantica/visualization/utils/export_formats.py provides utilities to serialize graphs to Parquet, Arrow, or JSON-LD formats using classes like ParquetExporter.

End-to-End Implementation Example

The following runnable example demonstrates the complete workflow from seed data to visualization:

from semantica.seed import SeedDataManager
from semantica.mcp.tools.extraction import extract_entities_and_relations
from semantica.vector_store.faiss_store import FaissStore
from semantica.reasoning.reasoner import Reasoner
from semantica.visualization.kg_visualizer import KGVisualizer

# 1️⃣ Load seed data and create foundation graph

seed_mgr = SeedDataManager()
seed_mgr.register_source(
    name="people",
    format="json",
    location="data/people.json",
    entity_type="Person",
)
foundation = seed_mgr.create_foundation_graph()

# 2️⃣ Enrich with LLM extraction

extracted = extract_entities_and_relations(
    text="Alice works at Acme Corp and lives in Berlin.",
    llm="gpt-4o-mini",
)
graph = seed_mgr.integrate_with_extracted(
    foundation, 
    extracted, 
    merge_strategy="merge"
)

# 3️⃣ Persist in vector store for semantic search

store = FaissStore(dim=768)
store.upsert_entities(graph["entities"])
store.upsert_relationships(graph["relationships"])

# 4️⃣ Execute reasoning queries

reasoner = Reasoner(vector_store=store, knowledge_graph=graph)
results = reasoner.query("Which persons are located in Berlin?")
print(results)  # → [{'entity': 'Alice', ...}]

# 5️⃣ Visualize the knowledge graph

visualizer = KGVisualizer()
visualizer.visualize_network(graph)  # Opens interactive Plotly view

Advanced Techniques and Configuration

Beyond basic ingestion, Semantica provides sophisticated mechanisms for data integration and querying.

Configuring Merge Strategies for Data Integration

When combining seed and extracted data, the integrate_with_extracted() method resolves conflicts using configurable strategies:

• seed_first: Preserves seed data when entities overlap, discarding extracted duplicates
• extracted_first: Overwrites seed data with extracted information when conflicts occur
• merge: Combines properties from both sources, creating rich composite entities

Hybrid Similarity Search

For retrieval-augmented generation or entity resolution, use the HybridSimilarity class in semantica/vector_store/hybrid_similarity.py. This combines dense vector similarity from the VectorStore with keyword filtering to improve recall:

from semantica.vector_store.hybrid_similarity import HybridSimilarity

hybrid = HybridSimilarity(vector_store=store)
results = hybrid.search('software engineer', top_k=5)

Executing SPARQL Queries

The library includes a native SPARQL reasoner for complex graph traversals. Access this through the Reasoner class or directly via semantica/reasoning/sparql_reasoner.py:

sparql = """
SELECT ?person 
WHERE { 
    ?person a :Person . 
    ?person :livesIn :Berlin . 
}"""
answers = reasoner.sparql_query(sparql)

Core Files and Architecture

Understanding these key files enables effective customization of the pipeline:

• semantica/seed/seed_manager.py: Handles source registration, loading, and foundation graph creation
• semantica/mcp/tools/extraction.py: Implements LLM-driven text extraction
• semantica/vector_store/faiss_store.py: Provides FAISS-based vector indexing
• semantica/reasoning/reasoner.py: High-level reasoning interface with support for custom actions
• semantica/visualization/kg_visualizer.py: Orchestrates graph rendering and layout algorithms
• semantica/visualization/utils/export_formats.py: Serializes graphs to Parquet, Arrow, and JSON-LD

Summary

• Seed ingestion uses SeedDataManager to convert CSV, JSON, or API data into foundation graphs via create_foundation_graph()
• Enrichment combines structured seed data with LLM-extracted entities using integrate_with_extracted() and configurable merge strategies
• Storage persists vectors in backends like FaissStore, enabling fast similarity search through the VectorStore interface
• Reasoning executes SPARQL queries and custom logic via the Reasoner class to infer new facts from the graph
• Visualization generates interactive networks through KGVisualizer and exports to columnar formats for analytics

Frequently Asked Questions

What data formats does Semantica support for seed ingestion?

Semantica’s SeedDataManager supports CSV, JSON, database connections, and API endpoints through dedicated load_from_* methods. The register_source() method accepts a format parameter that determines the parser used when create_foundation_graph() executes.

How does Semantica handle conflicts between seed data and LLM-extracted information?

The integrate_with_extracted() method in semantica/seed/seed_manager.py provides three resolution strategies: seed_first prioritizes original data, extracted_first prefers LLM output, and merge combines properties from both sources. This configuration is passed via the merge_strategy parameter.

Can I replace FAISS with another vector database like Qdrant?

Yes. Semantica abstracts storage behind the VectorStore base class in semantica/vector_store/vector_store.py. Concrete implementations exist for FAISS, Qdrant, and Pinecone. Simply instantiate your preferred backend (e.g., QdrantStore) and pass it to the Reasoner constructor—the interface remains identical.

How do I export a knowledge graph for external analysis?

Use the export utilities in semantica/visualization/utils/export_formats.py. The ParquetExporter class serializes entity and relationship data to columnar Parquet format, while Arrow and JSON-LD exporters handle streaming and semantic web use cases respectively.

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