| 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
- Direct Answer - Lead with the key finding
- Supporting Data - Table or list with specifics
- Why This Matters - Explain the significance
- 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:
- Use a bullet list (
- or *)
- Put the query in double quotes (
"query here")
- 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
- Plain Language First - Say "well-connected" not "high degree centrality"
- Always Explain Why - Every insight needs a "why this matters"
- Offer Next Steps - Never leave users without options
- Use Real Data - Never make up entity names or statistics
- Cite Sources - When showing evidence, include source references
- Quote Follow-Ups - ALWAYS put follow-up queries in "double quotes" with descriptions
- 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" |
