kg-insights

name	kg-insights
description	Helps users discover patterns and insights in their Knowledge Graphs. Use when users ask about important entities, connections, patterns, or want to understand what they can do with their graph. Triggers proactively after extraction to show what's possible.

Knowledge Graph Insights

Help users explore their Knowledge Graph with natural questions. Transform graph analysis into actionable insights with clear explanations of why each finding matters.

What Users Can Ask

Question	Sub-Resource	When to Use
"Who are the key players?"	questions/key-players.md	User wants to find important entities
"How is X connected to Y?"	questions/connections.md	User wants to understand relationship paths
"What groups or clusters exist?"	questions/groups.md	User wants to see topic organization
"Where is X mentioned?"	questions/evidence.md	User wants source citations for claims
"What can I do with this graph?"	POWER-QUERY.md	User is unsure what's possible

Proactive Triggers

Invoke this skill automatically in these situations:

After Extraction Completes

When extract_to_kg finishes successfully:

Great! I've added [N] entities and [M] relationships to your graph.

Your Knowledge Graph now has [total] entities. Would you like me to:
1. Show who the key players are
2. Find interesting connections
3. See how topics cluster together

Just ask, or type a number!

After Milestone Reached

When graph reaches 50+ entities:

Your Knowledge Graph is growing! With [N] entities, there's a lot to explore.

Some questions you might find interesting:
- "Who appears most often across my sources?"
- "How is [popular entity] connected to [another]?"
- "What are the main topic clusters?"

When User Seems Unsure

If user asks vague questions like "what now?" or "what's next?":

• Read POWER-QUERY.md for smart suggestions
• Present personalized options based on their graph's content

Tool Mapping

Map natural questions to KG tools:

User Intent	Tool	Parameters
Key players	get_kg_stats	project_id
Connections	Graph path query	source/target labels
Evidence	Source lookup	entity/relationship ID
Statistics	get_kg_stats	project_id

Response Format

Always Include

1. Direct Answer - Lead with the key finding
2. Supporting Data - Table or list with specifics
3. Why This Matters - Explain the significance
4. Explore Further - 2-3 follow-up suggestions

Example Response Structure

## Key Players in Your Graph

Based on connection analysis, here are the most influential entities:

| Entity | Type | Connections | Appears In |
|--------|------|-------------|------------|
| [Name] | Person | 12 | 4 sources |
| [Name] | Organization | 8 | 3 sources |

### Why This Matters

These entities are central to your research because:
- **[Name]** appears across multiple sources, suggesting they're a recurring theme
- **[Name]** connects to many other entities, making them a good entry point

### Explore Further

- "How is [Name A] connected to [Name B]?" — Trace the relationship path
- "Show me [Name]'s connections" — See their full network
- "What sources mention [Name]?" — Find evidence and citations

Follow-Up Format (CRITICAL - MUST READ)

The frontend parses your "Explore Further" section and creates clickable suggestion cards.

For this to work, you MUST use this exact format:

### Explore Further

- "Query in quotes" — Brief description
- "Another query" — Brief description

Required Elements:

1. Use a bullet list (- or *)
2. Put the query in double quotes ("query here")
3. Add a description after em-dash (—) or colon (:)

Correct:

- "Show me Fear's connections" — See the full network
- "How is Hope connected to Fear?" — Trace the path

Wrong (cards won't appear):

- Show me Fear's connections
- How is Hope connected to Fear?

Replace placeholders like [Name] with actual entity names from the user's graph.

Graph Analysis Methods

Use these approaches when answering questions:

Finding Key Players (Degree Centrality)

Count connections for each entity. More connections = more central.

• Use get_kg_stats for type breakdown
• Cross-reference with source counts

Finding Paths (Shortest Path)

Use NetworkX path finding to show how entities connect.

• Show step-by-step: A -> B -> C
• Include relationship types at each step

Finding Clusters (Community Detection)

Group entities that are densely connected.

• Use entity types as initial groupings
• Look for entities bridging groups

Finding Evidence (Provenance)

Trace entities and relationships back to sources.

• Include confidence scores
• Quote relevant text when available

Critical Rules

1. Plain Language First - Say "well-connected" not "high degree centrality"
2. Always Explain Why - Every insight needs a "why this matters"
3. Offer Next Steps - Never leave users without options
4. Use Real Data - Never make up entity names or statistics
5. Cite Sources - When showing evidence, include source references
6. Quote Follow-Ups - ALWAYS put follow-up queries in "double quotes" with descriptions
7. Use Entity Names - Replace [placeholders] with actual names from the user's graph

Error Handling

Issue	Response
No project selected	"Please select a Knowledge Graph project first, or create one with kg-bootstrap"
Empty graph	"Your graph doesn't have any entities yet. Add a transcript with extract_to_kg"
Entity not found	"I couldn't find '[name]' in your graph. Try a different spelling or check available entities"
No path exists	"These entities aren't connected in your graph. They may appear in separate contexts"