kg-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" |