graphingest

graph-ingest

Entity and triple ingestion component for the graph subsystem.

Overview

The graph-ingest component is the entry point for all entity data flowing into the graph system. It subscribes to JetStream subjects for incoming entity events and stores them in the ENTITY_STATES KV bucket.

Architecture

                    ┌─────────────────┐
objectstore.stored ─┤                 │
                    │  graph-ingest   ├──► ENTITY_STATES (KV)
sensor.processed   ─┤                 │
                    └─────────────────┘

Features

• Entity CRUD: Create, read, update, delete entity operations
• Triple Mutations: Add and remove triples on entities
• Hierarchy Inference: Automatically creates container entities based on 6-part entity ID structure
• At-Least-Once Delivery: JetStream subscription with proper acknowledgment

Configuration

{
  "type": "processor",
  "name": "graph-ingest",
  "enabled": true,
  "config": {
    "ports": {
      "inputs": [
        {
          "name": "objectstore_in",
          "subject": "objectstore.stored.entity",
          "type": "jetstream",
          "interface": "storage.stored.v1"
        },
        {
          "name": "sensor_in",
          "subject": "sensor.processed.entity",
          "type": "jetstream",
          "interface": "iot.sensor.v1"
        }
      ],
      "outputs": [
        {
          "name": "entity_states",
          "subject": "ENTITY_STATES",
          "type": "kv"
        }
      ]
    },
    "enable_hierarchy": true
  }
}

Configuration Options

Ports

Inputs

Outputs

Hierarchy Inference

When enable_hierarchy is enabled, the component automatically creates container entities based on the 6-part entity ID structure:

org.platform.domain.system.type.instance
 │      │       │      │     │      │
 └──────┴───────┴──────┴─────┴──────┴─► Real entity
        │       │      │     │
        └───────┴──────┴─────┴─► Type container (*.group)
                │      │
                └──────┴─► System container (*.container)
                       │
                       └─► Domain container (*.level)

This creates edges that enable:

• Efficient traversal by type, system, or domain
• Automatic grouping without explicit relationship creation
• Query-time aggregation by hierarchy level

Dependencies

Upstream

• None (entry point component)

Downstream

• graph-index - watches ENTITY_STATES for index updates
• graph-embedding - watches ENTITY_STATES for embedding generation
• graph-clustering - watches ENTITY_STATES for community detection triggers

Metrics

Health

The component reports healthy when:

• JetStream subscription is active
• KV bucket is accessible
• No sustained error rate above threshold