kapps-semantic-middleware#

Semantic middleware for industrial data integration. It registers equipment and its capabilities in a knowledge graph, discovers what a machine can do by querying that graph, and executes operations over MQTT and HTTP.

Hello#

This middleware sits between shopfloor resources and higher-level applications. Instead of hardcoding network addresses or data formats, it uses a knowledge graph to describe what each resource is, what it can do, and how to reach it. Peers discover and invoke functionality through the graph rather than through direct configuration.

What is KAPPS#

KAPPS lets you register equipment and its capabilities in a knowledge graph, discover what a machine can do by querying that graph, and execute operations over MQTT and HTTP. Registration, discovery, and execution are three views of the same triples. A resource publishes what it offers; a consumer queries the graph to find it; coordination happens through graph-state, not message queues.

The components#

Several packages work together:

  • kapps-ogm — handles all knowledge graph reads and writes through a validated object-graph mapping layer.

  • kapps-triplestore-interface — provides raw triple-store access where the OGM has no equivalent yet, such as instance discovery.

  • transitional-sync-middleware — the synchronization layer, a transitional fork of aas-middleware carrying four synchronization fixes, incrementally reimplemented locally. It is retired within a few releases; do not build on it directly.

  • GraphDB — the triple store, brought up with docker compose from the docker/ directory that kapps-examples copies out. Reasoning is required.

  • Per-unit in-process broker — each middleware unit runs its own MQTT broker for southbound device communication.

Install the stack#

Install the library:

pip install kapps-semantic-middleware

To run the example scenarios and factory demos:

pip install "kapps-semantic-middleware[examples]"

To also open the notebooks in Jupyter:

pip install "kapps-semantic-middleware[examples,notebooks]"

Copy the example notebooks into your working directory. This is also how you get the compose files that start GraphDB, so it comes first:

kapps-examples ./kapps-examples
cd kapps-examples

Now start GraphDB (Docker is required for the examples, not for using the library itself):

cd docker
docker compose up -d

Important

GraphDB must be reachable before the first registration. Set the GRAPHDB_* environment variables to tell the middleware where it is.

Bootstrap#

The middleware depends on a specific order of operations. Follow this sequence to reach a running middleware:

from kapps_triplestore_interface import GraphDB
from kapps_ogm import OGM
from kapps_semantic_middleware import SemanticMiddleware, Mode
from kapps_semantic_middleware.seeding import load_shared_ontologies

# 1. Construct the GraphDB connection
db = GraphDB.from_env()

# 2. Construct the OGM wrapper
ogm = OGM(db=db)

# 3. Load the shared ontologies (Core + Interfaces)
load_shared_ontologies(db)

# 4. Seed the individuals your scenario assumes
# (e.g. create resources, parameters, capabilities via ogm.create())

# 5. Construct and start the middleware
middleware = SemanticMiddleware(
    mode=Mode.RESOURCE,
    resource_iri=YOUR_RESOURCE_IRI,
    service_class=YOUR_SERVICE_CLASS,
    ogm=ogm,
    host="127.0.0.1",
    port=8993,
)

A reader who follows this sequence reaches a running middleware without leaving the page.

Where next#

Concepts

Why a knowledge graph sits in the middle, what the three modes mean, and why the reasoner is not optional.

Concepts
Guide

Nine pages in construction order: instantiation, registration, parameters, connectors, coordination, views, writes, and the bootstrap that precedes them.

Guide
Scenarios

Three worked examples in increasing size: Hello World, the door and robot, and the six-process TransferUnit factory.

Scenarios
API reference

Fourteen modules, generated from the docstrings in src/.

API reference