ComputerAssignments/CA10_knowledge_graphs/docs/API_REFERENCE.md

API Reference

Overview

The CA10 Knowledge Graphs API provides RESTful endpoints for interacting with knowledge graphs, performing reasoning, and generating visualizations.

Base URL

http://localhost:8000

Authentication

Currently, the API does not require authentication. For production use, implement proper authentication mechanisms.

Endpoints

Health Check

GET /health

Check if the API server is running.

Response

{
  "status": "healthy",
  "version": "2.0.0",
  "timestamp": "2025-01-08T12:00:00Z"
}

---

Knowledge Graph Operations

POST /query

Query the knowledge graph.

Request Body

{
  "query": "What did Einstein discover?",
  "max_results": 5,
  "include_reasoning": true
}

Response

{
  "query": "What did Einstein discover?",
  "results": [
    {
      "subject": "Einstein",
      "predicate": "discovered",
      "object": "relativity"
    }
  ],
  "reasoning": {
    "steps": ["..."],
    "confidence": 0.95
  }
}

GET /entities

List all entities in the knowledge graph.

Query Parameters

• limit (optional): Maximum number of entities to return (default: 100)
• offset (optional): Pagination offset (default: 0)
• type (optional): Filter by entity type

Response

{
  "entities": [
    {
      "id": "einstein",
      "name": "Albert Einstein",
      "type": "person",
      "properties": {
        "born": 1879,
        "died": 1955
      }
    }
  ],
  "total": 150,
  "limit": 100,
  "offset": 0
}

GET /relations

List all relations in the knowledge graph.

Response

{
  "relations": [
    {
      "subject": "Einstein",
      "predicate": "discovered",
      "object": "relativity"
    }
  ],
  "total": 500
}

---

Reasoning Operations

POST /reasoning/query

Perform multi-agent reasoning on a query.

Request Body

{
  "query": "What are the connections between Einstein and quantum mechanics?",
  "max_depth": 5,
  "use_multi_agent": true,
  "temperature": 0.1
}

Response

{
  "query": "What are the connections between Einstein and quantum mechanics?",
  "final_answer": "Einstein made significant contributions...",
  "reasoning_steps": [
    {
      "step": 1,
      "agent": "entity_agent",
      "action": "identify_entities",
      "result": ["Einstein", "quantum mechanics"]
    }
  ],
  "confidence": 0.92,
  "execution_time": 2.5
}

POST /rag/query

Query using Retrieval-Augmented Generation.

Request Body

{
  "query": "Who are the most influential scientists?",
  "max_results": 10,
  "include_sources": true
}

Response

{
  "query": "Who are the most influential scientists?",
  "answer": "The most influential scientists include...",
  "retrieved_documents": [
    {
      "content": "Einstein was a physicist...",
      "score": 0.95,
      "source": "scientific_kg"
    }
  ],
  "confidence": 0.88
}

---

Embedding Operations

POST /embeddings/train

Train an embedding model.

Request Body

{
  "model_type": "TransE",
  "embedding_dim": 100,
  "num_epochs": 100,
  "learning_rate": 0.001,
  "batch_size": 32
}

Response

{
  "model_id": "transe_20250108_120000",
  "status": "training",
  "estimated_time": 300
}

GET /embeddings/similar/{entity_id}

Find similar entities based on embeddings.

Path Parameters

• entity_id: ID of the entity

Query Parameters

• k (optional): Number of similar entities to return (default: 5)

Response

{
  "entity_id": "einstein",
  "similar_entities": [
    {
      "id": "newton",
      "name": "Isaac Newton",
      "similarity": 0.92
    },
    {
      "id": "bohr",
      "name": "Niels Bohr",
      "similarity": 0.89
    }
  ]
}

---

Visualization Operations

POST /visualize

Generate a knowledge graph visualization.

Request Body

{
  "max_entities": 30,
  "layout": "spring",
  "include_labels": true,
  "format": "png"
}

Response

{
  "visualization_url": "/data/visualizations/kg_20250108_120000.png",
  "format": "png",
  "dimensions": {
    "width": 1200,
    "height": 800
  }
}

GET /visualize/embeddings

Visualize entity embeddings.

Query Parameters

• method (optional): Visualization method (pca, tsne, umap) (default: pca)
• max_entities (optional): Maximum entities to visualize (default: 100)

Response

{
  "visualization_url": "/data/visualizations/embeddings_pca_20250108.png",
  "method": "pca",
  "num_entities": 100
}

---

Statistics Operations

GET /stats

Get knowledge graph statistics.

Response

{
  "num_entities": 150,
  "num_relations": 500,
  "num_triples": 1200,
  "entity_types": {
    "person": 50,
    "concept": 70,
    "location": 30
  },
  "relation_types": {
    "discovered": 45,
    "influenced": 120,
    "worked_with": 80
  },
  "network_metrics": {
    "density": 0.023,
    "avg_degree": 8.0,
    "clustering_coefficient": 0.45
  }
}

GET /stats/influence

Get influence scores for entities.

Query Parameters

• top_k (optional): Number of top entities to return (default: 10)

Response

{
  "top_influential": [
    {
      "entity_id": "einstein",
      "name": "Albert Einstein",
      "influence_score": 0.95
    },
    {
      "entity_id": "newton",
      "name": "Isaac Newton",
      "influence_score": 0.93
    }
  ]
}

---

Error Responses

All endpoints may return the following error responses:

400 Bad Request

{
  "error": "Bad Request",
  "message": "Invalid query parameter",
  "details": "max_results must be a positive integer"
}

404 Not Found

{
  "error": "Not Found",
  "message": "Entity not found",
  "entity_id": "unknown_entity"
}

500 Internal Server Error

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred",
  "trace_id": "abc123"
}

---

Rate Limiting

Currently, no rate limiting is implemented. For production use, consider implementing rate limiting to prevent abuse.

---

WebSocket Support (Coming Soon)

Real-time updates and streaming responses will be available via WebSocket connections.

---

Examples

Python Example

import requests

# Base URL
BASE_URL = "http://localhost:8000"

# Query the knowledge graph
response = requests.post(f"{BASE_URL}/query", json={
    "query": "What did Einstein discover?",
    "max_results": 5
})

print(response.json())

# Get entity statistics
response = requests.get(f"{BASE_URL}/stats")
print(response.json())

# Find similar entities
response = requests.get(f"{BASE_URL}/embeddings/similar/einstein?k=5")
print(response.json())

cURL Example

# Health check
curl http://localhost:8000/health

# Query
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "What did Einstein discover?", "max_results": 5}'

# Get statistics
curl http://localhost:8000/stats

# Find similar entities
curl http://localhost:8000/embeddings/similar/einstein?k=5

JavaScript Example

// Query the knowledge graph
fetch("http://localhost:8000/query", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "What did Einstein discover?",
    max_results: 5,
  }),
})
  .then((response) => response.json())
  .then((data) => console.log(data));

---

API Versioning

The current API version is v1. Future versions will be available at /v2/, /v3/, etc.

---

Support

For API support and questions:

• Check the documentation
• Report issues on the repository
• Join the community discussions

---

Last Updated: January 2025
API Version: 1.0.0