How to Use the Knowledge Graph Service

This guide explains how to operate the SEA™ Knowledge Graph Service for semantic queries and event projections.

Prerequisites

Quick Start

1
2
3
4
5

# Start services
just dev-up

# Verify health
curl http://localhost:8010/health

SPARQL Queries

Execute SPARQL queries against the semantic graph:

1
2
3
4
5
6
7

# Query all debt items
curl -X POST http://localhost:8010/kg/sparql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "PREFIX sea-debt: <http://sea-forge.com/schema/debt#> SELECT ?debt ?status WHERE { ?debt a sea-debt:SemanticDebtItem ; sea-debt:status ?status }",
    "format": "json"
  }'

Common Query Patterns

Query Pattern Description
Blockers by Context Find blocking debt items in a specific bounded context
Policy Hotspots Concepts with the highest debt count
Cascade Detection Debt items affecting dependent concepts
Expired Accepted Debt Accepted debt past expiration

See SDS-003 Query Cookbook for complete SPARQL examples.

Event Projection

Project semantic events to RDF triples:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Project a SemanticDebtCreated event
curl -X POST http://localhost:8010/kg/projection \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "SemanticDebtCreated",
    "event_id": "uuid-here",
    "payload": {
      "debtId": "debt-001",
      "failureClass": "Incomplete_Model",
      "severity": "Medium",
      "status": "open",
      "boundedContext": "orders",
      "conceptIds": ["Order", "LineItem"],
      "policyNames": ["SchemaCheck"]
    }
  }'

Supported Event Types

Event Type Description Triples Added
SemanticDebtCreated New debt item ~9 per event
SemanticDebtUpdated Update status ~1 per event
SemanticDebtSuperseded Supersede debt ~2 per event
SemanticIncidentCreated New incident ~5 per event

Snapshots

Each projection creates an immutable snapshot:

1
2
3
4
5
6
7
8
9

# Get current stats
curl http://localhost:8010/kg/stats

# Response:
# {
#   "triple_count": 164,
#   "snapshot_count": 1,
#   "current_snapshot": "ifl:snap:561b776b9c604e94"
# }

API Documentation

Interactive API docs available at: http://localhost:8010/docs

Troubleshooting

Issue Solution
Connection refused Run just dev-up and wait for services
Empty query results Verify namespace prefix matches sea-debt:
Projection fails Check event_type is supported