Semantic Graph

Semantic Graph API

Capture and query the Knowledge Graph - a semantic network of relationships and engineering decisions between components, machines, facilities, and other entities. This is Nelo's brain for understanding your organization's asset relationships.

10 EndpointsKnowledge GraphDecision ArchaeologyRelationship Tracing

Overview

Entity Types

• component: Individual parts/devices
• machine: Equipment/controllers
• facility: Physical locations
• unit: Facility subdivisions
• tag: Sensor measurements
• user: Engineers/operators

Relationship Types

• PART_OF: Hierarchy relationships
• MOUNTED_ON: Component placement
• LOCATED_IN: Physical location
• CONNECTED_TO: Signal/data flow
• COMPATIBLE_WITH: Compatibility
• REPLACES: Substitution

Graph Overview

Get statistics and recent activity from the Knowledge Graph.

GET/v1/semantic-graph/overviewAuth Required

Get Graph Overview

Returns graph statistics, entity distribution, relationship types, and recent activity.

Response

Responsejson

{
  "total_relationships": 1250,
  "total_decisions": 340,
  "entity_type_counts": [
    {"entity_type": "component", "count": 456},
    {"entity_type": "machine", "count": 89},
    {"entity_type": "tag", "count": 234},
    {"entity_type": "facility", "count": 12}
  ],
  "relationship_type_counts": [
    {"relationship_type": "MOUNTED_ON", "count": 456},
    {"relationship_type": "CONNECTED_TO", "count": 312},
    {"relationship_type": "PART_OF", "count": 89}
  ],
  "recent_relationships": [
    {
      "id": "rel_123",
      "source_type": "component",
      "source_id": "comp_456",
      "target_type": "machine",
      "target_id": "mach_789",
      "relationship_type": "MOUNTED_ON",
      "semantic_meaning": "Temperature sensor mounted on production line controller",
      "created_at": "2024-08-26T15:30:00Z"
    }
  ]
}

Try it out

cURLbash

curl -X GET "https://sapienstream.com/api/v1/semantic-graph/overview" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET/v1/semantic-graph/knowledge-graphAuth Required

Get Knowledge Graph Data

Returns decision-centric graph data for visualization. Shows engineering decisions as nodes with relationships.

Response

Responsejson

{
  "nodes": [
    {
      "id": "dec_001",
      "type": "decision",
      "category": "component_selection",
      "summary": "Selected Rosemount 3144P for temperature monitoring",
      "reasoning": "Best accuracy and HART support for Zone 1 area",
      "created_at": "2024-08-26T10:00:00Z"
    }
  ],
  "edges": [
    {
      "id": "edge_001",
      "source": "dec_001",
      "target": "dec_002",
      "relationship": "influenced_by",
      "strength": 0.85
    }
  ],
  "stats": {
    "total_decisions": 45,
    "decision_categories": {"component_selection": 20, "configuration_change": 15}
  }
}

Try it out

cURLbash

curl -X GET "https://sapienstream.com/api/v1/semantic-graph/knowledge-graph" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Relationships

Create and manage semantic relationships between entities. Each relationship captures the decision reasoning and engineering context.

POST/v1/semantic-graph/relationshipsAuth Required

Create Relationship

Create a semantic relationship between two entities with decision context.

Request Body

Requestjson

{
  "source_type": "component",
  "source_id": "550e8400-e29b-41d4-a716-446655440000",
  "target_type": "machine",
  "target_id": "660e8400-e29b-41d4-a716-446655440001",
  "relationship_type": "MOUNTED_ON",
  "decision_reasoning": "Selected for its HART protocol support and Zone 1 certification",
  "alternatives_considered": [
    {
      "id": "alt_001",
      "name": "Siemens SITRANS",
      "why_not_chosen": "Higher cost, longer lead time"
    }
  ],
  "selection_criteria": {
    "cost": "medium",
    "performance": "high",
    "availability": "immediate"
  },
  "engineering_context": {
    "installation_date": "2024-08-26",
    "technician": "John Smith"
  }
}

Response

Responsejson

{
  "id": "rel_abc123",
  "source_type": "component",
  "source_id": "550e8400-e29b-41d4-a716-446655440000",
  "target_type": "machine",
  "target_id": "660e8400-e29b-41d4-a716-446655440001",
  "relationship_type": "MOUNTED_ON",
  "semantic_meaning": "Temperature transmitter mounted on production line controller",
  "decision_reasoning": "Selected for its HART protocol support and Zone 1 certification",
  "confidence_score": 0.95,
  "created_by": "user_123",
  "created_at": "2024-08-26T15:30:00Z"
}

Try it out

cURLbash

curl -X POST "https://sapienstream.com/api/v1/semantic-graph/relationships" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET/v1/semantic-graph/relationships/traces/{entity_type}/{entity_id}Auth Required

Trace Relationships

Get all relationships connected to an entity, tracing the knowledge graph.

Parameters

entity_typestringRequired

Entity type (component, machine, etc.)

entity_idstringRequired

Entity UUID

Response

Responsejson

{
  "entity_type": "component",
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "incoming": [
    {
      "id": "rel_001",
      "source_type": "tag",
      "source_id": "tag_123",
      "relationship_type": "MEASURES",
      "semantic_meaning": "Tag TE01_PV measures this sensor output"
    }
  ],
  "outgoing": [
    {
      "id": "rel_002",
      "target_type": "machine",
      "target_id": "mach_456",
      "relationship_type": "MOUNTED_ON",
      "semantic_meaning": "Sensor mounted on production controller"
    }
  ],
  "total_connections": 5
}

Try it out

cURLbash

curl -X GET "https://sapienstream.com/api/v1/semantic-graph/relationships/traces/{entity_type}/{entity_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET/v1/semantic-graph/relationships/{relationship_id}Auth Required

Get Relationship

Get details of a specific relationship including full decision context.

Parameters

relationship_idstringRequired

Relationship UUID

Response

Responsejson

{
  "id": "rel_abc123",
  "source_type": "component",
  "source_id": "550e8400-e29b-41d4-a716-446655440000",
  "target_type": "machine",
  "target_id": "660e8400-e29b-41d4-a716-446655440001",
  "relationship_type": "MOUNTED_ON",
  "semantic_meaning": "Temperature transmitter mounted on production line controller",
  "decision_reasoning": "Selected for its HART protocol support",
  "alternatives_considered": [...],
  "selection_criteria": {...},
  "engineering_context": {...},
  "confidence_score": 0.95,
  "created_by": "user_123",
  "created_at": "2024-08-26T15:30:00Z"
}

Try it out

cURLbash

curl -X GET "https://sapienstream.com/api/v1/semantic-graph/relationships/{relationship_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

DELETE/v1/semantic-graph/relationships/{relationship_id}Auth Required

Delete Relationship

Soft-delete a relationship from the knowledge graph.

Parameters

relationship_idstringRequired

Relationship UUID

Response

Responsejson

204 No Content

Try it out

cURLbash

curl -X DELETE "https://sapienstream.com/api/v1/semantic-graph/relationships/{relationship_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Engineering Decisions

Record and query engineering decisions - the "why" behind your asset configurations.

POST/v1/semantic-graph/decisionsAuth Required

Create Decision

Record an engineering decision with full context and reasoning.

Request Body

Requestjson

{
  "entity_type": "component",
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "decision_type": "component_selection",
  "summary": "Selected Rosemount 3144P for temperature monitoring",
  "reasoning": "Required HART protocol for diagnostics, Zone 1 certification for hazardous area",
  "alternatives_considered": [
    {"name": "Siemens SITRANS", "reason_not_chosen": "Higher cost"}
  ],
  "context": {
    "project": "Line 2 Upgrade",
    "budget_constraint": "$5000 per sensor"
  }
}

Response

Responsejson

{
  "id": "dec_abc123",
  "entity_type": "component",
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "decision_type": "component_selection",
  "summary": "Selected Rosemount 3144P for temperature monitoring",
  "reasoning": "Required HART protocol for diagnostics...",
  "created_by": "user_123",
  "created_at": "2024-08-26T15:30:00Z"
}

Try it out

cURLbash

curl -X POST "https://sapienstream.com/api/v1/semantic-graph/decisions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET/v1/semantic-graph/decisions/{entity_type}/{entity_id}Auth Required

Get Entity Decisions

Get all engineering decisions related to an entity.

Parameters

entity_typestringRequired

Entity type

entity_idstringRequired

Entity UUID

Response

Responsejson

[
  {
    "id": "dec_001",
    "decision_type": "component_selection",
    "summary": "Selected Rosemount 3144P",
    "reasoning": "Best fit for hazardous area requirements",
    "created_at": "2024-08-26T10:00:00Z"
  },
  {
    "id": "dec_002",
    "decision_type": "configuration_change",
    "summary": "Changed sensor range to 0-200°C",
    "reasoning": "Process temperature exceeded original 150°C limit",
    "created_at": "2024-08-27T14:30:00Z"
  }
]

Try it out

cURLbash

curl -X GET "https://sapienstream.com/api/v1/semantic-graph/decisions/{entity_type}/{entity_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Orphan Management

Identify and clean up relationships that reference non-existent entities.

GET/v1/semantic-graph/orphansAuth Required

List Orphaned Relationships

Find relationships where source or target entity no longer exists.

Response

Responsejson

{
  "orphaned_relationships": [
    {
      "id": "rel_old001",
      "source_type": "component",
      "source_id": "deleted_comp_123",
      "target_type": "machine",
      "target_id": "mach_456",
      "issue": "source_missing"
    }
  ],
  "total_orphans": 3
}

Try it out

cURLbash

curl -X GET "https://sapienstream.com/api/v1/semantic-graph/orphans" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

DELETE/v1/semantic-graph/orphansAuth Required

Cleanup Orphaned Relationships

Remove all orphaned relationships from the graph. Admin only.

Response

Responsejson

{
  "deleted_count": 3,
  "message": "Successfully cleaned up 3 orphaned relationships"
}

Try it out

cURLbash

curl -X DELETE "https://sapienstream.com/api/v1/semantic-graph/orphans" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Use Cases

Decision Archaeology

Trace back why specific components were chosen months or years later. Invaluable for troubleshooting and future similar projects.

Impact Analysis

Before replacing a component, understand all relationships and dependencies to avoid unintended consequences.

Knowledge Transfer

New engineers can understand the reasoning behind existing configurations without hunting down the original decision makers.