# Relationship Between GraphBuilder, GraphAnalyzer, and GraphStore in Semantica

> Understand the relationship between Semantica's GraphBuilder, GraphAnalyzer, and GraphStore. Learn how these components enable flexible knowledge graph operations with Neo4j, Stardog, or Jena.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: internals
- Published: 2026-09-11

---

**Semantica splits knowledge-graph operations into three decoupled components—GraphBuilder for constructing KnowledgeGraphs, GraphAnalyzer for read-only statistical analysis, and GraphStore for backend persistence—enabling flexible data pipelines that work with Neo4j, Stardog, or Jena without architectural changes.**

The Semantica repository (`semantica-agi/semantica`) implements a modular architecture for knowledge-graph management. Understanding the relationship between **GraphBuilder**, **GraphAnalyzer**, and **GraphStore** allows developers to ingest raw data, perform in-memory analytics, and optionally persist results to graph databases using a clear separation of concerns.

## GraphBuilder: Constructing KnowledgeGraphs

Located in [`semantica/kg/graph_builder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_builder.py), the **GraphBuilder** class constructs a `KnowledgeGraph` data structure from raw entities, relationships, and temporal information. It normalizes payloads, assigns unique identifiers, and attaches provenance metadata, remaining agnostic to subsequent analysis or storage layers.

The primary entry point is `build_from_documents()`, which returns a fully instantiated KnowledgeGraph:

```python
from semantica.kg import GraphBuilder

builder = GraphBuilder()
kg = builder.build_from_documents(my_docs)

```

## GraphAnalyzer: Computing Statistics and Insights

The **GraphAnalyzer** performs read-only analytics on existing KnowledgeGraph instances. As referenced in [`tests/visualization/reproduce_notebooks.py`](https://github.com/semantica-agi/semantica/blob/main/tests/visualization/reproduce_notebooks.py), this component calculates node and edge statistics, centrality measures, community detection, and temporal versioning without modifying graph structure.

Use `compute_statistics()` to derive metrics:

```python
from semantica.kg import GraphAnalyzer

analyzer = GraphAnalyzer()
stats = analyzer.compute_statistics(kg)

```

## GraphStore: Persisting to Graph Databases

Found in [`semantica/graph_store/graph_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/graph_store/graph_store.py), **GraphStore** abstracts persistence across Neo4j, Stardog, and Jena backends. It provides CRUD operations through a unified API, accepting configuration parameters such as `backend` and `uri` during instantiation.

Persist graphs using the `save()` method:

```python
from semantica.graph_store import GraphStore

store = GraphStore(backend="neo4j", uri="bolt://localhost:7687")
store.save(kg)

```

## Integration Workflow: Build, Analyze, Store

The three components interact through a linear pipeline that maintains strict separation of concerns:

1. **Build** – `GraphBuilder` ingests raw documents and produces an in-memory `KnowledgeGraph`.
2. **Analyze** – `GraphAnalyzer` processes the graph without side effects via `compute_statistics()`.
3. **Store** – `GraphStore` optionally persists the graph to the configured backend using `save()`.

This decoupling allows multiple analytical passes on the same graph before storage, or swapping storage technologies without modifying construction or analysis logic.

```python
from semantica.kg import GraphBuilder, GraphAnalyzer
from semantica.graph_store import GraphStore

# Construct

builder = GraphBuilder()
kg = builder.build_from_documents(documents)

# Analyze

analyzer = GraphAnalyzer()
metrics = analyzer.compute_statistics(kg)

# Persist (optional)

store = GraphStore(backend="neo4j", uri="bolt://localhost:7687")
store.save(kg)

```

## Summary

- **GraphBuilder** ([`semantica/kg/graph_builder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_builder.py)) creates `KnowledgeGraph` instances via `build_from_documents()`, handling entity normalization and ID assignment.
- **GraphAnalyzer** (imported in [`tests/visualization/reproduce_notebooks.py`](https://github.com/semantica-agi/semantica/blob/main/tests/visualization/reproduce_notebooks.py)) executes read-only analytics through `compute_statistics()`, supporting centrality and community detection without graph mutation.
- **GraphStore** ([`semantica/graph_store/graph_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/graph_store/graph_store.py)) provides backend-agnostic persistence to Neo4j, Stardog, or Jena using the `save()` method.
- Components operate sequentially—construction, then analysis, then optional storage—enabling flexible, decoupled knowledge-graph pipelines.

## Frequently Asked Questions

### What is the primary responsibility of GraphBuilder in Semantica?

**GraphBuilder**, located in [`semantica/kg/graph_builder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_builder.py), is responsible for constructing `KnowledgeGraph` data structures from raw inputs. It normalizes entity payloads, assigns unique identifiers, attaches provenance metadata, and handles temporal information through methods like `build_from_documents()`.

### Does GraphAnalyzer modify the KnowledgeGraph during analysis?

No, **GraphAnalyzer** performs strictly read-only operations according to the source code structure. It computes statistics, centrality measures, and community detection without mutating the underlying graph, allowing safe repeated analysis of the same in-memory instance.

### Which graph databases are supported by GraphStore?

**GraphStore** supports multiple backends including **Neo4j**, **Stardog**, and **Jena**, as implemented in [`semantica/graph_store/graph_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/graph_store/graph_store.py). The constructor accepts a `backend` parameter and connection URI, enabling seamless switching between storage technologies without code changes to other components.

### Can I use GraphBuilder and GraphAnalyzer without GraphStore?

Yes, **GraphBuilder** and **GraphAnalyzer** function independently of **GraphStore**. You can construct a KnowledgeGraph and run analytical workflows entirely in-memory without ever invoking `save()`, making persistence optional for lightweight analytics or prototyping scenarios.