Knowledge Graph Management

Manage the multi-KG architecture with endpoints for listing, creating, updating, and deleting knowledge graphs. Includes domain detection, federated search across multiple KGs, and registry management. All operations interface with the MainOrchestrator and KGRegistry.

GET

/api/v1/knowledge-graphs

Retrieve a list of all available knowledge graphs with optional statistics and metadata.

Query Parameters

Parameter	Type	Required	Description
`include_inactive`	boolean	No	Include inactive KGs (default: false)
`kg_type`	string	No	Filter by KG type: "universal", "domain", "user"
`domain`	string	No	Filter by domain (e.g., "health", "finance")

Response Fields

Field	Type	Description
`knowledge_graphs`	array	List of knowledge graph objects
`name`	string	Unique KG identifier (used in API calls)
`display_name`	string	Human-readable name
`description`	string	KG purpose and content description
`entities_count`	integer	Total number of entities in the KG
`relations_count`	integer	Total number of relationships
`sources_count`	integer	Number of data sources ingested
`entity_types`	object	Breakdown of entities by type
`relation_types`	object	Breakdown of relationships by type
`domains`	array	Knowledge domains covered by this KG

Knowledge Graph Selection

Understanding which KG to use for different use cases:

KG_Universal

Best for: General queries, cross-domain questions
Content: Mixed domain information from various sources
Use when: You don't know the specific domain or need broad coverage

Domain-Specific KGs

KG_Healthcare: Medical, clinical, and health information
KG_Legal: Legal documents, case law, regulations
KG_Research: Academic papers, research findings
KG_Technology: Technical documentation, software, hardware

Using KGs in Queries

You can specify which KGs to search in your query requests:

# Query specific KGs
response = requests.post(
    "https://your-api.com/api/v1/query",
    headers={"X-API-Key": "your-api-key"},
    json={
        "query": "What are treatments for diabetes?",
        "kg_names": ["KG_Healthcare", "KG_Universal"]
    }
)

# Or let the system auto-detect (recommended)
response = requests.post(
    "https://your-api.com/api/v1/query",
    headers={"X-API-Key": "your-api-key"},
    json={
        "query": "What are treatments for diabetes?"
        # Domain detection automatically selects appropriate KGs
    }
)

KG Statistics for Monitoring

Track KG Growth Over Time

import requests
from datetime import datetime

def get_kg_stats(kg_name):
    """Get current statistics for a knowledge graph."""
    response = requests.get(
        "https://your-api.com/knowledge-graphs",
        headers={"X-API-Key": "your-api-key"}
    )
    
    kgs = response.json()["knowledge_graphs"]
    kg = next((k for k in kgs if k["name"] == kg_name), None)
    
    if kg:
        return {
            "timestamp": datetime.now().isoformat(),
            "entities": kg["entities_count"],
            "relations": kg["relations_count"],
            "sources": kg["sources_count"]
        }
    return None

# Monitor KG growth
stats = get_kg_stats("KG_Universal")
print(f"Current stats: {stats}")

Response Without Statistics

When include_stats=false, you get a minimal response:

curl -X GET "https://your-api.com/knowledge-graphs?include_stats=false" \
  -H "X-API-Key: your-api-key"

Minimal Response

{
  "knowledge_graphs": [
    {
      "name": "KG_Universal",
      "display_name": "Universal Knowledge Graph",
      "description": "General purpose knowledge graph",
      "domains": ["general", "technology", "science"],
      "status": "active"
    }
  ],
  "total_count": 1
}

Error Responses

No Knowledge Graphs Available

{
  "knowledge_graphs": [],
  "total_count": 0,
  "message": "No knowledge graphs available. Please ingest data first."
}

Unauthorized Access

{
  "detail": "Invalid API key",
  "status_code": 401
}

GET

/api/v1/knowledge-graphs/{kg_name}

Get detailed information about a specific knowledge graph.

POST /api/v1/knowledge-graphs/multi-kg/detect-domain - Domain Detection

Detect relevant domains for a query using the DomainDetector component. Routes through MainOrchestrator.retrieval_pipeline.domain_detector.

Request

cURL Example

curl -X POST https://your-api.com/api/v1/knowledge-graphs/multi-kg/detect-domain \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the symptoms of cardiovascular disease?",
    "top_k_domains": 3
  }'

Response

{
  "detected_domains": [
    {
      "domain": "health",
      "confidence": 0.92,
      "keywords": ["cardiovascular", "disease", "symptoms"]
    },
    {
      "domain": "medicine",
      "confidence": 0.85,
      "keywords": ["disease", "symptoms"]
    }
  ],
  "detection_time_ms": 234.5
}

Agent Interaction

API Request → MainOrchestrator.retrieval_pipeline.domain_detector.detect_domains()
    ↓
DomainDetector.detect_domains()
    ↓
LLM-based domain classification
    ↓
Return ranked domains with confidence scores

POST /api/v1/knowledge-graphs/multi-kg/federated-search - Federated Multi-KG Search

Search across multiple knowledge graphs simultaneously with automatic result fusion. Routes through MainOrchestrator.retrieval_pipeline.unified_retrieval().

Request

cURL Example

curl -X POST https://your-api.com/api/v1/knowledge-graphs/multi-kg/federated-search \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What treatments are available for cardiovascular disease?",
    "top_k": 10,
    "user_id": "user_123"
  }'

Agent Interaction

API Request → MainOrchestrator.retrieval_pipeline.unified_retrieval()
    ↓
QueryRouter.route()
    ↓
Parallel search across multiple KGs:
    ├─→ KG_Universal (entities + chunks)
    ├─→ KG_Health (entities + chunks)
    └─→ KG_Finance (entities + chunks)
    ↓
FusionEngine.fuse_hits()
    ↓
Return fused and ranked results

POST /api/v1/knowledge-graphs/{kg_name}/search - Search Specific KG

Search within a single knowledge graph.

Request

cURL Example

curl -X POST https://your-api.com/api/v1/knowledge-graphs/KG_Universal/search \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is diabetes?",
    "max_results": 10,
    "user_id": "user_123"
  }'

POST

/api/v1/knowledge-graphs

Create a new knowledge graph definition. Registers the KG in the registry and creates Qdrant collections.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Unique KG identifier (alphanumeric, underscores, hyphens only)
`display_name`	string	No	Human-readable display name (defaults to name)
`description`	string	No	Description of the knowledge graph
`kg_type`	string	Yes	Type: "universal", "domain", "user", "archive"
`domains`	array	No	List of associated domains (e.g., ["health", "finance"])
`embedding_method`	string	No	Embedding method: "semantic_gnn", "pykeen", "dgl_ke" (default: "semantic_gnn")
`enable_sql_storage`	boolean	No	Enable SQL database storage (default: true)
`enable_nebula_storage`	boolean	No	Enable NebulaGraph storage (default: false)

PUT

/api/v1/knowledge-graphs/{kg_name}

Update KG configuration (display name, domains, active status).

Request Body

Field	Type	Required	Description
`display_name`	string	No	Human-readable display name
`description`	string	No	Updated description
`domains`	array	No	Updated list of associated domains
`is_active`	boolean	No	Whether the KG is active

DELETE

/api/v1/knowledge-graphs/{kg_name}

Delete KG and optionally its data (Qdrant collections, SQL data).

Query Parameters

Parameter	Type	Required	Description
`force`	boolean	No	Force deletion even if KG has data (default: false)
`delete_collections`	boolean	No	Delete Qdrant collections (default: true)

GET /api/v1/knowledge-graphs/registry/info - Get Registry Info

Get registry metadata and statistics.

Request

cURL Example

curl -X GET "https://your-api.com/api/v1/knowledge-graphs/registry/info" \
  -H "X-API-Key: your-api-key"

POST /api/v1/knowledge-graphs/registry/reload - Reload Registry

Reload KG registry from configuration files and Qdrant collections.

Request

cURL Example

curl -X POST "https://your-api.com/api/v1/knowledge-graphs/registry/reload" \
  -H "X-API-Key: your-api-key"

Agent Interaction

API Request → load_kg_registry()
    ↓
Reload from config/kgs.yaml
    ↓
Discover KGs from Qdrant collections
    ↓
Merge and register all KGs

Entity CRUD Operations

Manage entities within a specific knowledge graph. These endpoints allow you to create, update, and delete entities directly within a KG context.

POST

/api/v1/knowledge-graphs/{kg_name}/entities

Create a new entity in a specific knowledge graph.

Request Body

Field	Type	Required	Description
`label`	string	Yes	Entity label/name
`type`	string	Yes	Entity type (e.g., DISEASE, PERSON, ORGANIZATION)
`properties`	object	No	Custom properties/metadata

PUT

/api/v1/knowledge-graphs/{kg_name}/entities/{entity_id}

Update an existing entity in a knowledge graph.

DELETE

/api/v1/knowledge-graphs/{kg_name}/entities/{entity_id}

Delete an entity from a knowledge graph.

POST

/api/v1/knowledge-graphs/{kg_name}/entities/bulk-delete

Delete multiple entities from a knowledge graph in a single operation.

Request Body

Field	Type	Required	Description
`ids`	array of strings	Yes	List of entity IDs to delete

Best Practices

Cache results: KG metadata changes infrequently, cache for better performance
Use statistics: Enable stats to understand KG content before querying
Monitor growth: Track entity/relation counts to gauge data quality
Domain matching: Use domain information to select appropriate KGs
Auto-detection: Let the system detect domains automatically for better results
Federated search: Use federated search for cross-domain queries
Registry management: Reload registry after creating KGs programmatically

Integration Examples

Dropdown Population

React - Populate KG Selector

import { useEffect, useState } from 'react';

function KGSelector() {
  const [kgs, setKgs] = useState([]);
  
  useEffect(() => {
    fetch('https://your-api.com/knowledge-graphs', {
      headers: { 'X-API-Key': process.env.API_KEY }
    })
      .then(res => res.json())
      .then(data => setKgs(data.knowledge_graphs));
  }, []);
  
  return (
    <select>
      {kgs.map(kg => (
        <option key={kg.name} value={kg.name}>
          {kg.display_name} ({kg.entities_count.toLocaleString()} entities)
        </option>
      ))}
    </select>
  );
}

Analytics Dashboard

Generate KG Overview Report

import requests
from tabulate import tabulate

def generate_kg_report():
    response = requests.get(
        "https://your-api.com/knowledge-graphs",
        headers={"X-API-Key": "your-api-key"}
    )
    
    kgs = response.json()["knowledge_graphs"]
    
    # Prepare table data
    table_data = []
    for kg in kgs:
        table_data.append([
            kg["name"],
            kg["entities_count"],
            kg["relations_count"],
            kg["sources_count"],
            ", ".join(kg["domains"][:3])
        ])
    
    print(tabulate(
        table_data,
        headers=["Name", "Entities", "Relations", "Sources", "Domains"],
        tablefmt="grid"
    ))

generate_kg_report()