Metadata-Version: 2.4
Name: gdg_bu_kg
Version: 0.1.3
Summary: Python SDK for the Babcock University Knowledge Graph API
Project-URL: Homepage, https://babcock-kg.com
Project-URL: Documentation, https://docs.babcock-kg.com
Project-URL: Repository, https://github.com/babcock-kg/kg-client-python
Project-URL: Issues, https://github.com/babcock-kg/kg-client-python/issues
Author: Babcock KG Team
License: MIT
Keywords: babcock,knowledge-graph,llm,neo4j,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Requires-Dist: pydantic>=2.0
Requires-Dist: tenacity>=8.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Description-Content-Type: text/markdown

# gdg_bu_kg: Babcock Knowledge Graph Python SDK 🎓🧠

[![PyPI version](https://img.shields.io/pypi/v/gdg-bu-kg.svg)](https://pypi.org/project/gdg-bu-kg/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Versions](https://img.shields.io/pypi/pyversions/gdg-bu-kg.svg)](https://pypi.org/project/gdg-bu-kg/)

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

```bash
pip install gdg-bu-kg
```

---

## 🔑 Authentication

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

```python
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.

```python
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.

```python
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:

```python
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:

```python
# 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.
