How to Build a Knowledge Graph Using Semantica: The Complete 5-Step Workflow

To build a knowledge graph using Semantica, you orchestrate data through a five-stage pipeline: ingest raw entities and relationships with SeedManager, persist the structure via TripletStore, generate vector embeddings for semantic search, run graph algorithms with GraphReasoner, and render interactive visualizations through KGVisualizer.

The semantica-agi/semantica repository provides a Python-first framework that transforms unstructured or tabular data into structured knowledge graphs—collections of entities, relationships, and ontologies designed for advanced reasoning and AI-driven workflows. Unlike static databases, these graphs support dynamic enrichment, blending symbolic logic with vector similarity for hybrid intelligence applications.

Core Architecture Overview

Semantica organizes knowledge graph construction into four modular layers. Each layer maps to a specific path in the codebase, ensuring clean separation between ingestion, storage, reasoning, and presentation.

• Ingestion & Seeding – The semantica.seed.seed_manager.SeedManager class in semantica/seed/seed_manager.py reads source formats (CSV, JSON, Parquet) and produces the initial graph dictionary containing entities and relationships lists.
• Storage & Persistence – The semantica.triplet_store.triplet_store.TripletStore module handles backend-agnostic persistence, supporting SQLite, PostgreSQL/PGVector, Pinecone, and Neo4j via a unified interface.
• Vectorization & Search – Located in semantica/vector_store/decision_embedding_pipeline.py, this layer generates node embeddings and enables hybrid semantic search across the graph structure.
• Reasoning & Visualization – The semantica.reasoning package (including graph_reasoner.py and sparql_reasoner.py) executes algorithms like PageRank and community detection, while semantica/visualization/kg_visualizer.py provides interactive network rendering.

Step-by-Step Implementation

Step 1: Ingest Raw Data with SeedManager

Start by initializing the SeedManager to parse your source files into a graph dictionary. In semantica/seed/seed_manager.py, the from_csv() method accepts paths for entities and relationships, optionally validating the structure against an ontology when validate=True.

from semantica.seed.seed_manager import SeedManager

seed = SeedManager()
kg = seed.from_csv(
    entities_path="data/entities.csv",
    relationships_path="data/relationships.csv",
    validate=True,  # optional ontology validation

)

The resulting kg object contains two top-level keys: entities (a list of node objects) and relationships (a list of edge objects), each capable of carrying arbitrary metadata payloads.

Step 2: Persist to the Triplet Store

Once seeded, the graph must be persisted. The TripletStore class in semantica/triplet_store/triplet_store.py abstracts storage backends. Instantiate it with a backend identifier and connection string, then call save() to commit the graph dictionary.

from semantica.triplet_store.triplet_store import TripletStore

store = TripletStore(backend="sqlite", db_path="kg.db")
store.save(kg)

This makes the graph available to downstream components without reloading raw source files.

Step 3: Enrich with Vector Embeddings

To enable semantic search, generate embeddings for each node. The embed_graph() function in semantica/vector_store/decision_embedding_pipeline.py batches nodes through a specified embedding model and stores vectors alongside the graph.

from semantica.vector_store.decision_embedding_pipeline import embed_graph

embed_graph(
    store=store,
    model="text-embedding-ada-002",
    batch_size=64,
)

This step is optional but recommended for applications requiring similarity-based retrieval or LLM-augmented reasoning.

Step 4: Execute Graph Reasoning

With the graph stored and vectorized, run analytical algorithms. The GraphReasoner class in semantica/reasoning/graph_reasoner.py provides methods like page_rank() for centrality analysis. For RDF-style inference, use sparql_reasoner.py to execute SPARQL queries against the store.

from semantica.reasoning.graph_reasoner import GraphReasoner

reasoner = GraphReasoner(store=store)
centralities = reasoner.page_rank()
print("Top 5 central nodes:", centralities[:5])

The reasoner can also infer new relationships based on existing patterns, continuously enriching the graph.

Step 5: Visualize and Export

Finally, render the graph interactively. The KGVisualizer class in semantica/visualization/kg_visualizer.py pulls data from the store and renders it using Plotly or NetworkX. The visualization registry in semantica/visualization/methods.py supports network views, community coloring, and centrality-scaled node sizing.

from semantica.visualization.kg_visualizer import KGVisualizer

viz = KGVisualizer(store=store)
viz.visualize_network(
    node_color="centrality",
    node_size="centrality",
    community=True,
)

For downstream consumption, export the graph using utilities in semantica/mcp/tools/export.py, which support Parquet, Arrow, JSON-LD, and GraphQL formats.

End-to-End Code Example

The following runnable script combines all five stages into a single pipeline. Execute this after installing the semantica package to generate a fully enriched, visualized knowledge graph from CSV inputs.

# 1️⃣  Initialise a SeedManager and load raw data

from semantica.seed.seed_manager import SeedManager

seed = SeedManager()
kg = seed.from_csv(
    entities_path="data/entities.csv",
    relationships_path="data/relationships.csv",
    validate=True,
)

# 2️⃣  Persist the graph (SQLite used here)

from semantica.triplet_store.triplet_store import TripletStore

store = TripletStore(backend="sqlite", db_path="kg.db")
store.save(kg)

# 3️⃣  Enrich with node embeddings (OpenAI ada-002 as an example)

from semantica.vector_store.decision_embedding_pipeline import embed_graph

embed_graph(
    store=store,
    model="text-embedding-ada-002",
    batch_size=64,
)

# 4️⃣  Run a reasoning query – e.g., PageRank centrality

from semantica.reasoning.graph_reasoner import GraphReasoner

reasoner = GraphReasoner(store=store)
centralities = reasoner.page_rank()
print("Top 5 central nodes:", centralities[:5])

# 5️⃣  Visualise the graph interactively

from semantica.visualization.kg_visualizer import KGVisualizer

viz = KGVisualizer(store=store)
viz.visualize_network(
    node_color="centrality",
    node_size="centrality",
    community=True,
)

Running this pipeline creates a knowledge graph from CSV files, stores it locally, produces embeddings, computes PageRank centralities, and launches an interactive visualization.

Summary

• Semantica provides a modular Python framework for building knowledge graphs through five distinct stages: ingestion, persistence, vectorization, reasoning, and visualization.
• The SeedManager class in semantica/seed/seed_manager.py handles initial data ingestion and optional ontology validation.
• TripletStore in semantica/triplet_store/triplet_store.py abstracts storage backends including SQLite, PostgreSQL, Pinecone, and Neo4j.
• Vector embeddings are generated via embed_graph() in semantica/vector_store/decision_embedding_pipeline.py, enabling hybrid semantic search.
• Graph analytics such as PageRank and community detection are executed by GraphReasoner in semantica/reasoning/graph_reasoner.py.
• Interactive visualizations and multi-format exports are managed by KGVisualizer and the export utilities in semantica/mcp/tools/export.py.

Frequently Asked Questions

What storage backends does Semantica support for knowledge graphs?

According to the source code in semantica/triplet_store/triplet_store.py, the TripletStore class supports multiple backends including SQLite, PostgreSQL with PGVector, Pinecone, and Neo4j. You specify the backend via the backend parameter during instantiation, allowing you to switch from local development to production vector databases without changing application logic.

How does Semantica validate ontologies during data ingestion?

The SeedManager class in semantica/seed/seed_manager.py accepts a validate boolean parameter in methods like from_csv(). When set to True, the manager validates incoming entities and relationships against a predefined ontology schema, ensuring only semantically consistent data enters the graph. This prevents malformed edges or missing required properties from polluting the knowledge base.

Can I use a custom embedding model instead of OpenAI’s Ada?

Yes. The embed_graph() function in semantica/vector_store/decision_embedding_pipeline.py exposes a model parameter that accepts arbitrary model identifiers. While examples reference OpenAI’s text-embedding-ada-002, you can pass any compatible model string handled by the underlying embedding provider, allowing integration with open-source models or custom fine-tuned transformers.

What export formats are available for serialized knowledge graphs?

The export utilities located in semantica/mcp/tools/export.py support several industry-standard formats. You can serialize graphs to Parquet, Arrow, JSON-LD, or GraphQL representations. These formats enable downstream consumption by analytics pipelines, LLM-augmented agents, or external knowledge-base services that require structured graph data.

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