​
Knowledge Graph with Vedaya

This guide explains how to use Vedaya’s Knowledge Graph API to extract entities and relationships from your documents, visualize the knowledge graph, and perform advanced graph operations.

​
Overview

Vedaya’s Knowledge Graph system allows you to:

  • Automatically detect entities and relationships in your documents
  • View and explore the connections between concepts
  • Merge and manage entities
  • Visualize data as graphs, hypergraphs, and concept clusters
  • Connect to external graph databases like Neo4j

​
Entity Detection

After ingesting documents, you can start entity detection:

import requests
import json

url = "https://vedaya-backend.fly.dev/api/knowledge-graph/detect-entities"

payload = json.dumps({
  "document_ids": ["f12345678"], # Optional: specific documents only
  "force_rebuild": False         # Set to True to rebuild from scratch
})

headers = {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload)
print(response.json())

This will start an asynchronous process to detect entities and relationships in your documents. The process runs in the background, and you can check its status:

import requests

url = "https://vedaya-backend.fly.dev/api/knowledge-graph/entity-detection-status"

headers = {
  'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get(url, headers=headers)
print(response.json())

​
Exploring Entities

Once entity detection is complete, you can retrieve and explore the detected entities:

import requests

url = "https://vedaya-backend.fly.dev/api/knowledge-graph/entities"

# Optional query parameters
params = {
  "limit": 100,            # Number of entities to retrieve
  "entity_type": "PERSON", # Filter by entity type
  "min_mentions": 2        # Minimum number of mentions
}

headers = {
  'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

To get details about a specific entity:

import requests

entity_id = "e12345678"  # ID of the entity
url = f"https://vedaya-backend.fly.dev/api/knowledge-graph/entities/{entity_id}"

headers = {
  'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get(url, headers=headers)
print(response.json())

​
Exploring Relationships

You can also retrieve and explore the detected relationships:

import requests

url = "https://vedaya-backend.fly.dev/api/knowledge-graph/relationships"

# Optional query parameters
params = {
  "limit": 100,
  "relationship_type": "WORKS_FOR"  # Filter by relationship type
}

headers = {
  'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

​
Merging Entities

Sometimes the system may detect the same real-world entity as multiple entities. You can merge them:

import requests
import json

url = "https://vedaya-backend.fly.dev/api/knowledge-graph/merge-entities"

payload = json.dumps({
  "source_entities": ["e12345678", "e87654321"],  # Entities to merge
  "target_entity": "e12345678"                   # Entity to merge into
})

headers = {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload)
print(response.json())

​
Visualization

​
Graph Visualization

To get data for visualizing the knowledge graph:

import requests
import json

url = "https://vedaya-backend.fly.dev/api/knowledge-graph/graph-data"

payload = json.dumps({
  "node_label": "AI",      # Starting node label
  "max_depth": 3,          # Maximum graph traversal depth
  "max_nodes": 1000,       # Maximum number of nodes
  "embeddingRank": 128,    # Rank of embeddings to use
  "useGPU": False          # Whether to use GPU
})

headers = {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload)
print(response.json())

​
Hypergraph Visualization

For hypergraph visualization:

import requests

url = "https://vedaya-backend.fly.dev/api/knowledge-graph/hypergraph"

# Query parameters
params = {
  "limit_entities": 100,
  "limit_hyperedges": 20,
  "embedding_rank": 128
}

headers = {
  'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

​
Concept Clusters

To visualize concept clusters:

import requests

url = "https://vedaya-backend.fly.dev/api/knowledge-graph/concept-clusters"

params = {
  "embedding_rank": 128
}

headers = {
  'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

​
Generating Embeddings

To generate embeddings for entities in the knowledge graph:

import requests

url = "https://vedaya-backend.fly.dev/api/knowledge-graph/generate-embeddings"

params = {
  "embedding_rank": 128,
  "use_gpu": False
}

headers = {
  'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(url, headers=headers, params=params)
print(response.json())

​
Neo4j Integration

You can connect Vedaya to a Neo4j database for advanced graph operations:

import requests
import json

url = "https://vedaya-backend.fly.dev/api/knowledge-graph/connect-neo4j"

payload = json.dumps({
  "uri": "bolt://localhost:7687",
  "username": "neo4j",
  "password": "your_password",
  "database": "vedaya"  # Optional: specific Neo4j database
})

headers = {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload)
print(response.json())

​
Best Practices

  1. Document Quality: Higher quality documents yield better entity detection
  2. Processing Order: Always ingest documents before running entity detection
  3. Entity Merging: Regularly review and merge duplicate entities
  4. Graph Exploration: Start with specific entity types to explore the graph more effectively
  5. Neo4j Integration: Use Neo4j for complex graph queries and analytics

For more details on available endpoints and parameters, see the Knowledge Graph API Reference.