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.

Reasoning (Inference)

The Knowledge Graph service supports bounded, deterministic reasoning with explicit profile selection.

Reasoning Profiles

Profile Description
none No inference (default)
rdfs RDFS subclass inference
owlrl-lite OWL-RL with axiomatic + datatype axioms disabled
custom_ruleset_v1 Custom SPARQL CONSTRUCT rules

Using Reasoning

Reasoning is off by default - you must explicitly request it per query:

1
2
3
4
5
6
7
8

# Query with RDFS reasoning
curl -X POST http://localhost:8010/kg/sparql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "PREFIX ex: <http://example.org/> PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> SELECT ?s WHERE { ?s a ex:Person }",
    "format": "json",
    "reasoning_profile": "rdfs"
  }'

Response with Inferred Metadata

When reasoning is enabled, the response includes inferred metadata:

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

{
  "head": {"vars": ["s"]},
  "results": {
    "bindings": [
      {"s": {"type": "uri", "value": "http://example.org/Alice"}}
    ]
  },
  "inferred": {
    "enabled": true,
    "profile": "rdfs",
    "snapshot_id": "ifl:snap:efc90c7cbc093814",
    "graph_uri": "urn:sea:inferred:ifl:snap:efc90c7cbc093814",
    "explicit_triples": 12,
    "inferred_triples": 3,
    "rule_set_hash": "5a3e9...",
    "duration_ms": 15.2
  }
}

Inferred Named Graphs

Inferred triples are stored in a named graph: urn:sea:inferred:<snapshot_id>

Each inferred triple is annotated with reification:

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
Reasoning produces no results Verify reasoning_profile is valid and data supports inference