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

> Learn how to build a knowledge graph with Semantica using its four stage pipeline: seed ingestion, LLM extraction, vector storage, and visualization. Construct and query graphs from any data.

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

---

**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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/vector_store.py) defines the storage interface, with concrete implementations like `FaissStore` ([`semantica/vector_store/faiss_store.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning/reasoner.py) executes queries against this storage, supporting SPARQL reasoning (via [`semantica/reasoning/sparql_reasoner.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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:

```python
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`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/hybrid_similarity.py). This combines dense vector similarity from the `VectorStore` with keyword filtering to improve recall:

```python
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`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning/sparql_reasoner.py):

```python
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`](https://github.com/semantica-agi/semantica/blob/main/semantica/seed/seed_manager.py)**: Handles source registration, loading, and foundation graph creation
- **[`semantica/mcp/tools/extraction.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/tools/extraction.py)**: Implements LLM-driven text extraction
- **[`semantica/vector_store/faiss_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/faiss_store.py)**: Provides FAISS-based vector indexing
- **[`semantica/reasoning/reasoner.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning/reasoner.py)**: High-level reasoning interface with support for custom actions
- **[`semantica/visualization/kg_visualizer.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/visualization/kg_visualizer.py)**: Orchestrates graph rendering and layout algorithms
- **[`semantica/visualization/utils/export_formats.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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.