Visualizations

Access interactive dashboards, network graphs, and analytical visualizations for your knowledge graphs. Visualizations are generated by the EnhancedKGVisualizer agent component and can be embedded in your applications. All visualization endpoints interface with the MainOrchestrator's visualization service.

GET

/api/visualizations/

Get an overview of all knowledge graphs with available visualizations.

Get Visualization Metadata

Get detailed metadata about available visualizations for a specific KG.

GET /api/visualizations/{kg_name}/metadata

curl -X GET "https://your-api.com/api/visualizations/KG_Universal/metadata" \
  -H "X-API-Key: your-api-key"

Response

{
  "kg_name": "KG_Universal",
  "available_visualizations": [
    {
      "name": "dashboard",
      "title": "KG Universal Dashboard",
      "type": "interactive_html",
      "description": "Comprehensive overview with entity/relation statistics",
      "url": "/api/visualizations/KG_Universal/dashboard.html",
      "last_updated": "2024-01-15T10:30:00Z",
      "file_size_kb": 245
    },
    {
      "name": "network",
      "title": "Network Visualization",
      "type": "interactive_graph",
      "description": "Interactive force-directed graph visualization",
      "url": "/api/visualizations/KG_Universal/network_visualization.html",
      "last_updated": "2024-01-15T10:30:00Z",
      "file_size_kb": 512
    },
    {
      "name": "entity_distribution",
      "title": "Entity Distribution",
      "type": "chart",
      "description": "Bar chart showing entity type distribution",
      "url": "/api/visualizations/KG_Universal/entity_distribution.html",
      "last_updated": "2024-01-15T10:30:00Z",
      "file_size_kb": 128
    }
  ],
  "index_url": "/api/visualizations/KG_Universal/",
  "total_visualizations": 3
}

Access Dashboard HTML

Get the interactive dashboard HTML for embedding in your application.

GET /api/visualizations/{kg_name}/dashboard.html

curl -X GET "https://your-api.com/api/visualizations/KG_Universal/dashboard.html" \
  -H "X-API-Key: your-api-key" \
  -H "Accept: text/html"

Response

Returns HTML content ready for iframe embedding or direct display.

<!DOCTYPE html>
<html>
<head>
  <title>KG Universal Dashboard</title>
  <script src="https://cdn.plot.ly/plotly-latest.min.js"></script>
</head>
<body>
  <div id="dashboard">
    <!-- Interactive Plotly charts -->
    <div id="entity-chart"></div>
    <div id="relation-chart"></div>
    <div id="stats-panel"></div>
  </div>
  <script>
    // Visualization JavaScript
  </script>
</body>
</html>

Access Network Visualization

Get the interactive network graph visualization.

GET /api/visualizations/{kg_name}/network_visualization.html

curl -X GET "https://your-api.com/api/visualizations/KG_Universal/network_visualization.html" \
  -H "X-API-Key: your-api-key" \
  -H "Accept: text/html"

Response

Returns interactive network graph HTML with entity relationships.

POST /api/visualizations/{kg_name}/regenerate - Regenerate Visualizations

Regenerate visualizations for a knowledge graph. Routes through EnhancedKGVisualizer.generate_visualizations().

Request

cURL Example

curl -X POST "https://your-api.com/api/visualizations/KG_Universal/regenerate?job_id=job_abc123" \
  -H "X-API-Key: your-api-key"

Query Parameters

Parameter	Type	Description
`job_id`	string	Optional ingestion job ID to regenerate after

Agent Interaction

API Request → EnhancedKGVisualizer.generate_visualizations()
    ↓
┌─────────────────────────────────────┐
│ Visualization Generation            │
│ • Load KG from SQL                  │
│ • Generate network graph            │
│ • Create dashboard charts           │
│ • Export HTML files                 │
└─────────────────────────────────────┘

GET /api/visualizations/{kg_name}/ - Get Visualization Index

Serve index page with links to all visualizations for a KG.

Request

cURL Example

curl -X GET "https://your-api.com/api/visualizations/KG_Universal/" \
  -H "X-API-Key: your-api-key" \
  -H "Accept: text/html"

Response

Returns HTML index page with navigation links to all available visualizations.

DELETE /api/visualizations/{kg_name} - Delete Visualizations

Delete all visualizations for a knowledge graph.

Request

cURL Example

curl -X DELETE "https://your-api.com/api/visualizations/KG_Universal" \
  -H "X-API-Key: your-api-key"

Response

{
  "success": true,
  "message": "Visualizations deleted for KG_Universal",
  "deleted_files": [
    "dashboard.html",
    "network_visualization.html",
    "entity_distribution.html"
  ],
  "timestamp": "2024-01-15T14:30:00Z"
}

Check Visualization Service Health

Verify the visualization service is operational.

GET /api/visualizations/health

curl -X GET "https://your-api.com/api/visualizations/health"

Response

{
  "status": "healthy",
  "service": "kg_visualization",
  "directory_writable": true,
  "available_kgs": 2,
  "total_visualizations": 8,
  "last_generation": "2024-01-15T10:30:00Z",
  "timestamp": "2024-01-15T14:30:00Z"
}

Embedding Visualizations

Visualizations can be embedded in your applications using iframes or by downloading the HTML files directly. Use the visualization URLs returned by the API to embed interactive dashboards in your web applications.

Visualization Types

Dashboard

Purpose: Comprehensive overview of KG statistics
Contains: Entity distribution, relation types, source breakdown
Technology: Plotly interactive charts
Best for: Executive summaries, monitoring

Network Visualization

Purpose: Explore entity relationships visually
Contains: Force-directed graph, entity nodes, relationship edges
Technology: D3.js or Cytoscape
Best for: Relationship discovery, pattern identification

Entity Distribution

Purpose: Show entity type breakdown
Contains: Bar/pie charts of entity counts by type
Technology: Plotly/Chart.js
Best for: Data quality assessment

Relation Types

Purpose: Analyze relationship patterns
Contains: Charts showing relationship type distribution
Technology: Plotly
Best for: Schema understanding

Error Responses

No Visualizations Available

{
  "detail": "No visualizations found for knowledge graph 'KG_Test'",
  "status_code": 404,
  "message": "Visualizations are generated during data ingestion. Please ingest data first."
}

Visualization Generation Failed

{
  "detail": "Visualization service unavailable",
  "status_code": 503,
  "message": "Visualization generation is currently disabled or failed"
}

Customization

While visualizations are auto-generated, you can customize their appearance using URL parameters:

# Custom theme
/api/visualizations/KG_Universal/dashboard.html?theme=dark

# Limit entities shown
/api/visualizations/KG_Universal/network_visualization.html?max_nodes=100

# Filter by entity type
/api/visualizations/KG_Universal/network_visualization.html?entity_type=Person

Best Practices

Check availability: Verify visualizations exist before embedding
Use iframes: Embed visualizations in iframes for security
Cache metadata: Cache visualization metadata to reduce API calls
Responsive design: Ensure iframe containers are responsive
Loading states: Show loading indicators while visualizations load
Error handling: Handle 404s gracefully for KGs without data
Performance: Large KGs may have heavy visualizations, show warnings

Performance Considerations

KG Size	Visualization Load Time	Recommendations
Small (<1K entities)	<1 second	All visualizations work well
Medium (1K-10K entities)	1-3 seconds	Network visualization may be slower
Large (10K+ entities)	3-10 seconds	Use filtered views, limit network nodes

Security

API Key Required: All visualization endpoints require authentication
Iframe Sandbox: Use sandbox attribute when embedding untrusted visualizations
CORS: Configure CORS headers if embedding from different domains
CSP: Ensure Content Security Policy allows embedded visualizations