gdg-bu-kg 0.1.3

Python SDK for the Babcock University Knowledge Graph API

gdg_bu_kg: Babcock Knowledge Graph Python SDK 🎓🧠

The official Python SDK for the Babcock University Knowledge Graph. This library provides a seamless interface for querying the university's structured data using both natural language (AI-powered) and raw Cypher queries.

---

🚀 Features

• Hybrid Auth (High Speed): Uses permanent keys for one-time exchange into short-lived Session JWTs. This reduces query latency by ~500ms by validating tokens statelessly in memory.
• AI assistant (client.query): Ask questions in plain English. Now supports custom system_prompt, temperature, and model overrides per request.
• Raw Graph Access (client.graph_query): Execute custom Cypher queries with automated result sanitization (no more raw Neo4j objects).
• Privacy First: Internal attributes and backend URLs are mangled/hidden in the client to prevent accidental exposure.
• Strongly Typed: Built on Pydantic v2.
• Async Support: Full asyncio compatibility.

---

🛠 Installation

pip install gdg-bu-kg

---

🔑 Authentication

The SDK requires an API Key issued by the Babcock Knowledge Graph platform.

from gdg_bu_kg import KnowledgeGraphClient

client = KnowledgeGraphClient(api_key="bu_kg_your_secret_key")

---

📖 Usage Guide

1. Natural Language AI Queries

Use client.query() to get conversational answers backed by the knowledge graph.

response = client.query(
    "Who are the lecturers in the Computer Science department?",
    system_prompt="You are a helpful Babcock University academic assistant.",
    temperature=0.2,
    max_tokens=500
)

print(response.data.text_response)
# Output: "Based on the records, the lecturers in Computer Science include Dr. Agbaje..."

2. Raw Graph Queries

Use client.graph_query() when you need the underlying nodes and edges for visualization or data processing.

graph_resp = client.graph_query("MATCH (s:School) RETURN s.Name AS Name LIMIT 5")

for node in graph_resp.data.graph.nodes:
    print(f"Found School: {node.properties['Name']}")

3. Asynchronous Usage

For web frameworks like FastAPI or high-concurrency scripts:

from gdg_bu_kg import AsyncKnowledgeGraphClient

async def get_info():
    async with AsyncKnowledgeGraphClient(api_key="...") as client:
        resp = await client.query("Where is the University Library?")
        return resp.data.text_response

---

⚙️ Configuration

Argument / Env Var	Default	Description
api_key	Required	Your unique bu_kg_... key.
base_url	https://bu-kg.vercel.app/v1	The backend API endpoint.
BU_KG_BASE_URL	(None)	Env Var to override the backend globally.
timeout	30	Request timeout in seconds.
max_retries	3	Number of retries on connection failure.

---

📊 Data Models

QueryResponse (from .query())

Attribute	Type	Description
status	str	"success" or "error".
data.text_response	str	The AI-generated conversational answer.
data.graph	GraphModel	The supporting nodes and edges used by the AI.

GraphResponse (from .graph_query())

Attribute	Type	Description
data.graph.nodes	List[NodeModel]	List of nodes (id, label, properties).
data.graph.edges	List[EdgeModel]	List of relationships (from, to, label).
data.context	str	Metadata or execution summary from the server.

---

🧪 Advanced Example: Complex Reasoning

The AI assistant can perform complex joins across the graph:

# Query across Schools -> Departments -> Staff
query = "Which schools have departments managed by staff who also teach Computer Science?"
response = client.query(query)

print(response.data.text_response)

---

🛡 License

Distributed under the MIT License. See LICENSE for more information.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request to our GitHub repository.