Knowledge Graph

Overview

The Knowledge Graph provides a visual map of your entire research context. It renders research sources, insights, recommendations, documents, and LLM-extracted entities as nodes, and their relationships as edges — letting you see at a glance how raw user voice flows through to product decisions. The graph uses clustering to group related insights and highlights cross-cutting themes.

How It Works

Fetching the Graph

GET /api/graph/{workspace_id}

Returns the complete graph for a workspace with all non-archived entities.

Optional query parameters:

Parameter	Description
source_types	Comma-separated filter (e.g. interview,survey)
node_types	Comma-separated node types to include: research_source, insight, recommendation, document
min_severity	Minimum insight severity: low, medium, high, critical

The response contains four sections:

{
  "nodes": [...],
  "edges": [...],
  "clusters": [...],
  "stats": { ... }
}

Node Types

Each node represents a workspace entity:

Node Type	Source	Key Fields
research_source	Uploaded files	source_type, processing_status
insight	Synthesized findings	insight_type, severity, frequency
recommendation	Generated features	status, impact_score, effort
document	Drafted docs	document_type, status

Edge Types

Edges represent the actual data relationships stored in Praxiom:

Edge	Direction	Meaning
derived_from	Insight → Research Source	Insight was extracted from this source
addresses	Recommendation → Insight	Recommendation addresses this insight
generated_from	Document → Recommendation	Document was drafted from this recommendation
references	Document → Insight	Document cites this insight

Clusters

The graph groups related insights into clusters using a union-find algorithm. Two insights are grouped together when they share at least one research source. Clusters include both the insights and their shared source nodes.

Each cluster has:

• A descriptive label based on the dominant insight type (e.g. "Pain Points (4 insights)")
• A distinct color from an 8-color palette (indigo, violet, amber, cyan, emerald, rose, blue, pink)

Node Detail

Drill into any node with GET /api/graph/{workspace_id}/node/{node_id}.

This returns the full entity details plus a list of connected_nodes — every directly linked node with its type, label, and relationship type. This powers the detail panel in the graph UI.

For example, clicking an insight node reveals:

• The research sources it was derived from
• Any recommendations that address it
• Any documents that reference it

Graph Statistics

The stats object in the graph response provides a quick health check:

Field	Description
total_nodes	Total entities in the graph
total_edges	Total relationships
source_count	Number of research sources
insight_count	Number of insights
recommendation_count	Number of recommendations
document_count	Number of documents

LLM Entity Extraction

Beyond the standard workspace entities (sources, insights, recommendations, documents), Praxiom automatically extracts semantic entities from your research using Claude Haiku.

Extracted Entity Types

Entity Type	Description	Example
person	Named individuals mentioned in research	"Sarah Chen, VP Product"
pain_point	Specific user problems identified	"Cannot export reports to PDF"
feature	Product features or capabilities	"Real-time collaboration"
workflow	User workflows or processes	"Monthly reporting cycle"
theme	Cross-cutting themes	"Data portability concerns"
decision	Product or business decisions	"Migrate to microservices"
competitor	Competing products or companies	"Notion, Confluence"

Relationship Types

Extracted entities are connected with typed relationships:

Relationship	Direction	Meaning
experiences	Person → Pain Point	User experiences this problem
requests	Person → Feature	User requests this capability
has_theme	Insight → Theme	Insight belongs to this theme
contradicts	Entity → Entity	Two entities present conflicting information
enables	Feature → Workflow	Feature enables this workflow
competes_with	Competitor → Feature	Competitor offers this capability
synthesized_from	Entity → Source	Entity was extracted from this source

Extraction Process

1. When insights are synthesized, Praxiom runs an LLM extraction pass using Claude Haiku
2. Entities are extracted with a confidence score and normalized name (for deduplication)
3. If LLM extraction fails, a keyword fallback extracts entities using pattern matching
4. Duplicate entities (by normalized name) are merged, keeping the highest-confidence version

---

Graph Layout and Performance

The graph uses a spatial grid layout for rendering large workspaces efficiently:

• Nodes are positioned using a force-directed algorithm with spatial grid acceleration
• A ZoomContext provides smooth pan/zoom across the entire graph
• Connected nodes are paginated (loaded on demand when drilling into a node)
• Edges use React.memo to prevent unnecessary re-renders
• Backend queries use composite indexes on workspace_id + entity_type for fast filtering
• N+1 query issues are eliminated with eager loading of connected nodes

These optimisations ensure the graph remains responsive even with hundreds of nodes and thousands of edges.

---

Key Concepts

• Filtering lets you focus the graph on specific source types or severity levels, reducing visual noise for large workspaces.
• Clusters reveal hidden patterns — when multiple insights cluster together through shared sources, it often indicates a systemic issue worth prioritizing.
• Traceability is the graph's core value: you can trace any product decision (document) back through the recommendation, insights, and original user research that justified it.
• Entity extraction adds a semantic layer on top of the structural graph — surfacing people, pain points, features, and themes that cut across multiple sources and insights.

What's Next

• Dashboard Quality — monitor workspace health and quality trends
• Skills — extend the agent's capabilities
• Execution Tickets — turn research into engineering work