sea-semantic-search

name	sea-semantic-search
description	Search the SEA-Forge Knowledge Graph semantically using SPARQL and DomainForge. Find concepts, relationships, and semantic patterns across specs and code.

SEA Semantic Search

Search the SEA-Forge Knowledge Graph semantically using SPARQL queries and DomainForge integration. Find concepts, relationships, and semantic patterns across specifications and code.

When to Use

Invoke when:

• Finding related concepts in the knowledge graph
• Searching for semantic patterns
• Exploring relationships between specs
• Understanding domain connections
• Finding similar implementations

Usage

User invokes with:

• "Search for concepts related to X"
• "Find relationships between Y and Z"
• "What specs mention 'bounded context'?"
• "Semantic search for user authentication"

Search Process

Step 1: Build SPARQL Query

# Construct SPARQL query based on search terms
SEARCH_TERM="$1"

# Escape term for SPARQL
ESCAPED_TERM=$(echo "$SEARCH_TERM" | sed 's/"/\\"/g')

# Build query
cat > /tmp/sparql-query.rq <<EOF
PREFIX sea: <http://sea-forge.dev/schema/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>

SELECT DISTINCT ?subject ?predicate ?object ?label ?definition
WHERE {
  ?subject ?predicate ?object .
  ?subject rdfs:label ?label .
  OPTIONAL { ?subject sea:definition ?definition }

  FILTER (
    CONTAINS(LCASE(STR(?label)), "$ESCAPED_TERM") ||
    CONTAINS(LCASE(STR(?definition)), "$ESCAPED_TERM") ||
    CONTAINS(LCASE(STR(?object)), "$ESCAPED_TERM")
  )
}
LIMIT 50
EOF

Step 2: Execute Query

# Execute SPARQL query via DomainForge MCP
# or via Oxigraph if available

echo "🔍 Searching knowledge graph for: $SEARCH_TERM"

# Try DomainForge MCP first
if command -v domainforge &> /dev/null; then
  domainforge query --file /tmp/sparql-query.rq > /tmp/search-results.json
else
  # Fallback to Oxigraph
  oxigraph query --file /tmp/sparql-query.rq --location data/knowledge-graph.db > /tmp/search-results.json
fi

Step 3: Parse Results

# Parse JSON results
echo "📊 Found $(jq '.results.bindings | length' /tmp/search-results.json) results"

# Format results for display
jq -r '.results.bindings[] |
  "\(.subject.value)\n  Label: \(.label.value)\n  Definition: \(.definition.value // "N/A")\n"' \
  /tmp/search-results.json

Step 4: Find Related Concepts

# Find concepts related to search results
cat > /tmp/related-query.rq <<EOF
PREFIX sea: <http://sea-forge.dev/schema/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT DISTINCT ?related ?label ?relationship
WHERE {
  {
    ?subject sea:relatedTo ?related .
    ?related rdfs:label ?label .
    BIND("related" as ?relationship)
  } UNION {
    ?subject sea:dependsOn ?related .
    ?related rdfs:label ?label .
    BIND("depends on" as ?relationship)
  } UNION {
    ?subject sea:extends ?related .
    ?related rdfs:label ?label .
    BIND("extends" as ?relationship)
  }

  # Filter to concepts from our search
  VALUES ?subject { $(jq -r '.results.bindings[].subject.value' /tmp/search-results.json | sed 's/^/</;s/$/>/' | tr '\n' ' ') }
}
LIMIT 20
EOF

domainforge query --file /tmp/related-query.rq > /tmp/related-results.json

Step 5: Search Code References

# Find code files that reference the concept
echo "📁 Searching code references..."

for term in "$SEARCH_TERM" $(jq -r '.results.bindings[].label.value' /tmp/search-results.json | head -5); do
  echo "--- References to: $term ---"

  # Search in specs
  grep -r "$term" docs/specs/ --include="*.md" --include="*.yaml" -l 2>/dev/null || true

  # Search in code
  grep -r "$term" src/ --include="*.ts" -l 2>/dev/null || true

  # Search in tests
  grep -r "$term" tests/ --include="*.ts" -l 2>/dev/null || true
done

Step 6: Generate Search Report

cat > tmp/semantic-search-report.md <<EOF
# Semantic Search Report

**Search Term**: $SEARCH_TERM
**Date**: $(date -u +%Y-%m-%dT%H:%M:%SZ)

## Direct Matches
${RESULTS_TABLE}

## Related Concepts
${RELATED_TABLE}

## Code References
${REFERENCES_LIST}

## Visualization
[View in Knowledge Graph](/knowledge-graph?query=$SEARCH_TERM)
EOF

Search Query Templates

Find by Label

PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?subject ?label ?definition
WHERE {
  ?subject rdfs:label ?label .
  FILTER (CONTAINS(LCASE(STR(?label)), "search term"))
}

Find by Definition

PREFIX sea: <http://sea-forge.dev/schema/>

SELECT ?subject ?definition
WHERE {
  ?subject sea:definition ?definition .
  FILTER (CONTAINS(LCASE(STR(?definition)), "search term"))
}

Find Relationships

PREFIX sea: <http://sea-forge.dev/schema/>

SELECT ?subject ?predicate ?object ?predicateLabel
WHERE {
  ?subject ?predicate ?object .
  OPTIONAL { ?predicate rdfs:label ?predicateLabel }
}

Find by Type

PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?subject ?label
WHERE {
  ?subject rdf:type sea:BoundedContext .
  ?subject rdfs:label ?label .
}

Find Dependencies

PREFIX sea: <http://sea-forge.dev/schema/>

SELECT ?subject ?dependency ?dependencyLabel
WHERE {
  ?subject sea:dependsOn ?dependency .
  ?dependency rdfs:label ?dependencyLabel .
}

Integration

• Integrates with knowledge-graph-query skill for SPARQL queries
• Integrates with domainforge-mcp for graph operations
• Integrates with semantic-anchoring for concept validation

Output

After search:

## Semantic Search Results

**Query**: {search_term}
**Results Found**: {count}
**Related Concepts**: {count}

### Direct Matches
| Concept | Definition | Source |
|---------|------------|--------|
| {concept1} | {definition} | {spec/file} |
| {concept2} | {definition} | {spec/file} |

### Related Concepts
| Concept | Relationship |
|---------|-------------|
| {related1} | {relationship} |
| {related2} | {relationship} |

### Code References
- {file1}: {line} - {context}
- {file2}: {line} - {context}

### Knowledge Graph Visualization
[View in Graph Explorer](kg:{concept_id})