# How to Build a Knowledge Graph with Semantica's GraphBuilder: A Complete Guide

> Learn how to build a knowledge graph with Semantica's GraphBuilder. Easily add entities, relationships, and vector embeddings, then export your graph in various formats.

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

---

**Semantica's GraphBuilder lets you construct knowledge graphs by adding entities as nodes, connecting them with relationship edges, optionally enriching them with vector embeddings, and exporting to multiple formats.**

Building a **knowledge graph (KG)** with Semantica starts with the `GraphBuilder` class in [`semantica/kg/graph_builder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_builder.py). This component orchestrates the pipeline from raw data to a queryable graph structure, integrating with vector stores for semantic search and MCP tools for automated reasoning.

---

## Core Architecture of Semantica's GraphBuilder

The `GraphBuilder` follows a modular design that separates data collection, storage, reasoning, and export.

### Pipeline Overview

```

[Data Extraction] → [GraphBuilder] → [VectorStore (optional)] → [MCP Reasoning] → [Export/Visualization]

```

Each stage connects through well-defined interfaces:

- **GraphBuilder** ([`semantica/kg/graph_builder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_builder.py)) — collects entities and relationships
- **Graph data structures** ([`semantica/kg/graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph.py)) — lightweight node/edge containers
- **Vector store adapters** (`semantica/vector_store/`) — pluggable embedding backends (Qdrant, Weaviate, Pinecone)
- **MCP integration** ([`semantica/mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/tools/graph.py)) — rule-based inference and provenance tracking

---

## Building a Knowledge Graph: Step-by-Step

### Step 1: Initialize the GraphBuilder

Create a builder instance. For basic usage, no configuration is required.

```python
from semantica.kg.graph_builder import GraphBuilder

builder = GraphBuilder()

```

### Step 2: Add Entities as Nodes

Use `add_entity()` to create nodes. Each entity requires a **type label** and a **properties dictionary**.

```python
builder.add_entity(
    entity_type="Person",
    properties={"name": "Alice", "age": 30}
)
builder.add_entity(
    entity_type="Person",
    properties={"name": "Bob", "age": 25}
)

```

### Step 3: Add Relationships as Edges

Use `add_relationship()` to connect entities. The method matches source and target by their properties, then attaches edge properties.

```python
builder.add_relationship(
    relationship_type="knows",
    source={"name": "Alice"},
    target={"name": "Bob"},
    properties={"since": 2020}
)

```

### Step 4: Build and Export

Call `build()` to finalize the graph, then save to JSON-LD, RDF, CSV, or other formats.

```python
kg = builder.build()
kg.save("my_knowledge_graph.json")

```

---

## Enriching Knowledge Graphs with Vector Embeddings

The **GraphBuilder** accepts an optional `vector_store` parameter to automatically compute and persist embeddings. This enables similarity-based queries across the knowledge graph.

```python
from semantica.kg.graph_builder import GraphBuilder
from semantica.vector_store.qdrant_store import QdrantVectorStore

# Initialize Qdrant backend (credentials from environment)

vec_store = QdrantVectorStore(collection_name="my_kg_vectors")

builder = GraphBuilder(vector_store=vec_store)

# Embeddings are computed and stored automatically

builder.add_entity(
    entity_type="Document",
    properties={"title": "Semantica Overview", "text": "Semantica is a ..."}
)

kg = builder.build()
kg.save("kg_with_embeddings.json")

```

According to the semantica-agi/semantica source code, the `vector_store` interface is implemented in [`semantica/vector_store/qdrant_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/qdrant_store.py) with additional backends available in the same package.

---

## Running Automated Reasoning with MCP Tools

Built knowledge graphs integrate with Semantica's **MCP (Multimodal Coordination Protocol)** for remote reasoning. The [`semantica/mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/tools/graph.py) module provides tools for inference and provenance tracking.

```python
from semantica.mcp.session import Session
from semantica.kg.graph_builder import GraphBuilder

session = Session()
builder = GraphBuilder()

# ... populate entities and relationships ...

kg = builder.build()
session.upload_graph(kg)           # Transmit to MCP server

session.run_tool("graph.reason")   # Execute reasoning

result = session.download_graph()
result.save("kg_reasoned.json")

```

The `Session` class in [`semantica/mcp/session.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/session.py) handles communication with the MCP server, enabling distributed graph operations.

---

## Visualizing Your Knowledge Graph

For interactive exploration, output to HTML using the built-in visualizer:

```python
from semantica.kg.graph_builder import GraphBuilder
from semantica.visualization.kg_visualizer import KGVisualizer

builder = GraphBuilder()

# ... add entities and relationships ...

kg = builder.build()
visualizer = KGVisualizer()
visualizer.render(kg, output_path="kg.html")

```

The `KGVisualizer` in [`semantica/visualization/kg_visualizer.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/visualization/kg_visualizer.py) produces self-contained HTML files suitable for browser-based exploration.

---

## Key Source Files Reference

| File | Purpose |
|------|---------|
| [`semantica/kg/graph_builder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_builder.py) | Core `GraphBuilder` class with `add_entity()`, `add_relationship()`, and `build()` methods |
| [`semantica/kg/graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph.py) | Node/edge data structures and traversal utilities |
| [`semantica/mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/tools/graph.py) | MCP tool implementation for graph reasoning |
| [`semantica/vector_store/qdrant_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/qdrant_store.py) | Qdrant vector store backend for embeddings |
| [`semantica/visualization/kg_visualizer.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/visualization/kg_visualizer.py) | HTML rendering for knowledge graphs |
| [`semantica/mcp/session.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/session.py) | MCP server session management |

---

## Summary

- **GraphBuilder** ([`semantica/kg/graph_builder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_builder.py)) is the central class for knowledge graph construction with methods `add_entity()`, `add_relationship()`, and `build()`.
- Entities require a type label and properties dictionary; relationships connect entities via source/target property matching.
- Optional **vector store integration** enables automatic embedding generation for semantic similarity queries.
- **MCP tools** ([`semantica/mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/tools/graph.py)) provide remote reasoning capabilities through the `Session` interface.
- Export formats include JSON-LD, RDF, and CSV; visualization outputs to interactive HTML.

---

## Frequently Asked Questions

### What is the minimum code needed to create a knowledge graph with Semantica?

Three essential calls: instantiate `GraphBuilder`, add entities with `add_entity()`, then call `build()`. Relationships are optional for a valid graph. The minimal example requires only [`semantica/kg/graph_builder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_builder.py).

### How does Semantica handle entity disambiguation when adding relationships?

The `add_relationship()` method matches source and target entities by their **property dictionaries**. Ensure unique identifying properties (like `"name"` or `"id"`) to avoid ambiguous matches. For complex disambiguation, pre-process entities before graph construction.

### Can I use multiple vector stores with the same GraphBuilder?

No — the `GraphBuilder` accepts a single `vector_store` parameter. To use multiple embedding backends, create separate builder instances or implement a custom vector store that multiplexes to several backends.

### What MCP reasoning tools are available for built knowledge graphs?

The `graph.reason` tool in [`semantica/mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/tools/graph.py) performs rule-based inference. Additional tools for provenance tracking and subgraph extraction are exposed through the same module; list available tools with `session.list_tools()` after uploading a graph.