Developer API · AI Integration

AI Traversal Prompts.

KGL ships with ready-to-use system prompt templates that teach an AI assistant how to navigate a .kgl graph. The templates live in the prompts/ directory and are also accessible through the Python API.

Overview

File	Purpose
`prompts/system.md`	Base traversal prompt — teaches link semantics and how to report missing data
`prompts/query-assistant.md`	Query-writing prompt — teaches supported OpenCypher syntax with worked examples
`prompts/graph-summary.md`	Graph summary prompt — instructs the AI to produce a structured graph overview

Each file contains a Purpose section (when to use it), a Prompt section (ready-to-paste system message text), and a Usage example showing expected AI behaviour.

Python API

For programmatic use, kgl.prompts provides PromptTemplates and PromptContext:

python

from kgl.model import Graph
from kgl.prompts import PromptTemplates, PromptContext

graph = Graph.load("./")
ctx = PromptContext(graph=graph)

# Overarching graph context
system_prompt = PromptTemplates.graph_overview(ctx)

# Details for a specific node
node_prompt = PromptTemplates.node_summary(ctx, "/people/alice.kgl#Alice Nguyen")

# Query-writing guide tailored to the loaded graph
query_guide = PromptTemplates.query_guide(ctx)

# Traversal strategy instructions
traversal = PromptTemplates.traversal_strategy(ctx)

# Schema context
schema_ctx = PromptTemplates.schema_description(ctx)

# Context block for a set of nodes
context_block = PromptTemplates.context_extraction(ctx, [
    "/people/alice.kgl#Alice Nguyen",
    "/projects/search-revamp.kgl#Search Revamp",
])

# KGL syntax reference (no graph context needed)
syntax_ref = PromptTemplates.file_format_reference()

`PromptContext`

python

@dataclass
class PromptContext:
    graph: Graph
    node_limit: int = 10    # max nodes to include in overviews
    edge_limit: int = 20    # max edges to include in overviews
    schema: dict | None = None

Usage patterns

Single-node deep dive

Combine the traversal strategy with a specific node summary to give the AI context for answering questions about one node:

python

prompt = PromptTemplates.traversal_strategy(ctx) + "\n\n" + \
         PromptTemplates.node_summary(ctx, node_id)

Graph-aware query assistant

Combine the graph overview with the query guide to let the AI help write queries:

python

prompt = PromptTemplates.graph_overview(ctx) + "\n\n" + \
         PromptTemplates.query_guide(ctx)

Multi-node context extraction

When the AI needs to reason about a cluster of related nodes:

python

relevant_ids = [
    "/people/alice.kgl#Alice Nguyen",
    "/projects/search-revamp.kgl#Search Revamp",
]
prompt = PromptTemplates.context_extraction(ctx, relevant_ids)

Relationship to the file format

The prompts/system.md file is a Markdown document. Its Prompt section contains the ready-to-paste text for use in any AI interface.

The Python PromptTemplates class generates equivalent content dynamically, tailored to the actual graph contents — listing real node types and relationship types from the loaded graph rather than generic examples. This makes the prompt more precise when your graph has a well-defined schema.

The link semantics in KGL (→ for hard links, ~> for soft links) are designed to be directly meaningful to AI models. The base traversal prompt teaches models to treat → as "follow this to fully understand me" and ~> as "background context, fetch only if you need depth".