How to Configure Polyglot Graph Storage for RDF and LPG Databases in Semantica

To configure polyglot graph storage in Semantica, create a YAML configuration file at ~/.semantica/config.yaml with storage.rdf and storage.lpg sections specifying your backends and connection options, then load it via GraphStoreRegistry.from_config().

Semantica's architecture treats graph storage as a polyglot component—you can plug in any RDF triple store (Oxigraph, Blazegraph, Apache Jena, Eclipse RDF4J) and any Labeled Property Graph database (Neo4j, FalkorDB, Apache AGE, AWS Neptune) without changing your application code. This guide walks through the complete configuration process based on the semantica-agi/semantica source code.

How Polyglot Graph Storage Configuration Works

Semantica decouples storage backends from application logic through three core components: a YAML configuration file, a registry-based lookup system, and a unified GraphStore abstraction.

The config.yaml File Structure

The configuration file contains a top-level storage section with two keys: rdf and lpg. Each declares a backend name and optional options for driver-specific settings.

# ~/.semantica/config.yaml

storage:
  rdf:
    backend: oxigraph
    options:
      path: ./data/oxigraph.db
  lpg:
    backend: neo4j
    options:
      uri: bolt://localhost:7687
      auth:
        username: neo4j
        password: secret

The storage section supports these RDF backends: oxigraph, blazegraph, jena, rdf4j. For LPG backends: neo4j, falkordb, age, neptune.

Source: The README explains this polyglot design in the storage section【/cache/repos/github.com/semantica-agi/semantica/main/README.md#L78-L80】.

The GraphStoreRegistry Lookup Mechanism

GraphStoreRegistry in semantica/graph_store/registry.py maintains a mapping from backend identifiers to concrete store classes (OxigraphStore, BlazegraphStore, Neo4jStore, etc.). When GraphStore.from_config() is called, the registry:

1. Reads the backend value from the YAML
2. Loads the appropriate class
3. Passes the options dict to its constructor

Key file: semantica/graph_store/registry.py implements this lookup logic【/cache/repos/github.com/semantica-agi/semantica/main/semantica/graph_store/registry.py】.

The Unified GraphStore API

The resulting GraphStore object implements a single interface (add_node, add_edge, execute_query, etc.) defined in semantica/graph_store/graph_store.py. Internally, it delegates calls to the RDF or LPG driver, translating between SPARQL and Cypher as needed【/cache/repos/github.com/semantica-agi/semantica/main/semantica/graph_store/graph_store.py】.

Complete Configuration Examples

Minimal Configuration: Oxigraph + Neo4j

This configuration runs an embedded Oxigraph store for RDF data and connects to a local Neo4j instance for property graphs:

# ~/.semantica/config.yaml

storage:
  rdf:
    backend: oxigraph
    options:
      path: ./oxigraph.db
  lpg:
    backend: neo4j
    options:
      uri: bolt://localhost:7687
      auth:
        username: neo4j
        password: ********

Loading the Store in Python

from semantica.context import ContextGraph
from semantica.graph_store.registry import GraphStoreRegistry

# Automatically reads ~/.semantica/config.yaml

graph_store = GraphStoreRegistry.from_config()

# Build a ContextGraph that uses the polyglot store

ctx = ContextGraph(storage=graph_store, advanced_analytics=True)

# Add an RDF triple

ctx.storage.rdf_store.add_triple(
    ("http://example.org/Alice", "http://xmlns.com/foaf/0.1/knows", "http://example.org/Bob")
)

# Add an LPG edge

ctx.storage.lpg_store.add_edge(
    source="Alice", target="Bob", edge_type="knows", since="2024-01-01"
)

Source: Example usage appears in the quick-start snippet of the README【/cache/repos/github.com/semantica-agi/semantica/main/README.md#L9-L13】.

Swapping Backends Without Code Changes

To migrate from embedded Oxigraph to remote Blazegraph, and from Neo4j to AWS Neptune, only update the YAML:

storage:
  rdf:
    backend: blazegraph
    options:
      endpoint: http://blazegraph.example.com/sparql
  lpg:
    backend: neptune
    options:
      endpoint: https://neptune.amazonaws.com:8182
      auth:
        aws_region: us-east-1
        iam_role: arn:aws:iam::123456789012:role/NeptuneAccess

The same Python code (GraphStoreRegistry.from_config()) now instantiates BlazegraphStore and AmazonNeptune classes.

Programmatic Configuration (No Config File)

For dynamic environments, build stores directly and pass them to GraphStore:

from semantica.graph_store.graph_store import GraphStore
from semantica.graph_store.neo4j_store import Neo4jStore
from semantica.graph_store.oxigraph_store import OxigraphStore

# Create individual store instances

rdf = OxigraphStore(path="./myoxigraph")
lpg = Neo4jStore(uri="bolt://localhost:7687", auth=("neo4j", "s3cr3t"))

# Compose into unified GraphStore

store = GraphStore(rdf_store=rdf, lpg_store=lpg)

# Use with ContextGraph

ctx = ContextGraph(storage=store, advanced_analytics=True)

Implementation Files Reference

File	Purpose	Location
config.py	Parses and validates YAML configuration	semantica/graph_store/config.py
registry.py	Maps identifiers to store classes	semantica/graph_store/registry.py
graph_store.py	Unified GraphStore abstraction	semantica/graph_store/graph_store.py
oxigraph_store.py	Embedded Oxigraph RDF implementation	semantica/graph_store/oxigraph_store.py
blazegraph_store.py	Remote Blazegraph SPARQL endpoint	semantica/graph_store/blazegraph_store.py
neo4j_store.py	Neo4j Cypher driver	semantica/graph_store/neo4j_store.py
falkordb_store.py	FalkorDB RedisGraph driver	semantica/graph_store/falkordb_store.py
age_store.py	Apache AGE PostgreSQL driver	semantica/graph_store/age_store.py
amazon_neptune.py	AWS Neptune Gremlin/Cypher driver	semantica/graph_store/amazon_neptune.py

Summary

• Polyglot graph storage configuration in Semantica uses a single YAML file to declare both RDF and LPG backends
• GraphStoreRegistry.from_config() reads ~/.semantica/config.yaml and instantiates the correct drivers
• Backend swaps require zero code changes—only update the backend and options in your configuration
• Unified API through GraphStore abstracts SPARQL/Cypher differences
• Eight supported backends cover local embedded stores to managed cloud services

Frequently Asked Questions

What file format does Semantica use for storage configuration?

Semantica uses YAML for storage configuration. The default location is ~/.semantica/config.yaml, though you can specify alternate paths when calling registry methods directly.

Can I use different RDF and LPG backends in the same application?

Yes. Semantica's polyglot design intentionally supports mixing backends—you can pair any supported RDF store with any supported LPG database. The GraphStore abstraction maintains separate rdf_store and lpg_store attributes that operate independently.

How do I migrate from local development to production storage?

Update only your config.yaml file. Change backend: oxigraph to backend: blazegraph or backend: neptune, then adjust the options section with production endpoints and credentials. Your Python code calling GraphStoreRegistry.from_config() remains unchanged.

Is authentication supported for remote graph databases?

Yes. The options section accepts backend-specific authentication. For Neo4j, use auth: {username: ..., password: ...}. For AWS Neptune, use auth: {aws_region: ..., iam_role: ...}. Each driver implementation in semantica/graph_store/ validates and applies these credentials appropriately.

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