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

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. 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) — collects entities and relationships
• Graph data structures (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) — 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.

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.

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.

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.

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.

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 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 module provides tools for inference and provenance tracking.

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 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:

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 produces self-contained HTML files suitable for browser-based exploration.

---

Key Source Files Reference

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

---

Summary

• GraphBuilder (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) 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.

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 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.

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