ThinkOV2 / API_EXAMPLES.md
Ayush-003's picture
Upload 28 files
9be2851 verified
|
Raw History Blame Contribute Delete
9.65 kB
# Grocify Chat Agent - API Test Examples
This file contains example API requests for testing the Grocify Chat Agent.
## Base URL
- Local: `http://localhost:8000`
- Production: `https://your-space-url.hf.space`
---
## 1. Health Check
### GET /
```bash
curl -X GET "http://localhost:8000/"
```
**Expected Response:**
```json
{
"service": "Grocify Chat Agent",
"version": "2.0.0",
"status": "healthy",
"features": {
"rag": true,
"tool_calling": true,
"voice": true,
"multilingual": true,
"sentiment_analysis": true
}
}
```
---
## 2. Simple Chat
### POST /chat
```bash
curl -X POST "http://localhost:8000/chat" \
-H "Content-Type: application/json" \
-d '{
"user_message": "Hello! I need help with my order",
"locale": "en-IN"
}'
```
**Expected Response:**
```json
{
"session_id": "generated-uuid",
"response": {
"reply_text": "Hello! I'd be happy to help you with your order...",
"confidence": 0.85,
"sources": [],
"actions": [],
"structured_response": null,
"escalation": null
},
"timestamp": "2025-10-15T10:30:00Z"
}
```
---
## 3. Product Search
### POST /chat
```bash
curl -X POST "http://localhost:8000/chat" \
-H "Content-Type: application/json" \
-d '{
"user_message": "Find Diwali gifts under 3000 for someone who likes skincare",
"locale": "en-IN"
}'
```
**Expected Response:**
```json
{
"session_id": "uuid",
"response": {
"reply_text": "I found 3 great Diwali gift options for skincare lovers under ₹3000...",
"confidence": 0.92,
"sources": [
{
"id": "doc_1",
"title": "Product Catalog",
"location": "vector_db"
}
],
"actions": [
{
"tool_name": "product_search",
"tool_input": {
"query": "skincare",
"max_price": 3000,
"tags": ["gifting", "diwali"]
}
}
],
"structured_response": {
"type": "product_carousel",
"items": [
{
"id": "SKIN002",
"title": "Organic Skincare Gift Set",
"price": 1899,
"currency": "INR",
"image": "https://example.com/skincare.jpg",
"cta": "View details",
"url": "https://grocify.com/products/SKIN002"
}
]
}
}
}
```
---
## 4. Order Tracking
### POST /chat
```bash
curl -X POST "http://localhost:8000/chat" \
-H "Content-Type: application/json" \
-d '{
"user_message": "Where is my order #12345?",
"session_id": "existing-session-id",
"locale": "en-IN"
}'
```
**Expected Response:**
```json
{
"session_id": "existing-session-id",
"response": {
"reply_text": "Your order #12345 is currently Out for Delivery...",
"confidence": 0.95,
"structured_response": {
"type": "order_card",
"order_id": "12345",
"status": "Out for Delivery",
"eta": "Oct 18, 2025, 2:00 PM IST",
"tracking_url": "https://carrier/track/DLV123"
}
}
}
```
---
## 5. Coupon Validation
### POST /chat
```bash
curl -X POST "http://localhost:8000/chat" \
-H "Content-Type: application/json" \
-d '{
"user_message": "Is coupon DIWALI25 valid?",
"locale": "en-IN"
}'
```
**Expected Response:**
```json
{
"response": {
"reply_text": "Yes! Coupon DIWALI25 is valid and gives you 25% off on all products. It expires on October 30, 2025.",
"confidence": 0.98,
"structured_response": {
"type": "promotion_card",
"coupon": "DIWALI25",
"discount": "25% off",
"description": "Valid on all products",
"expires": "2025-10-30",
"cta": "Apply Coupon"
}
}
}
```
---
## 6. Escalation Trigger
### POST /chat
```bash
curl -X POST "http://localhost:8000/chat" \
-H "Content-Type: application/json" \
-d '{
"user_message": "I want to speak to a human agent",
"locale": "en-IN"
}'
```
**Expected Response:**
```json
{
"response": {
"reply_text": "I understand you'd like to speak with someone. Let me connect you with one of our team members...",
"confidence": 0.9,
"escalation": {
"escalate": true,
"queue": "support",
"priority": "normal",
"agent_brief": {
"summary": "Escalation triggered: explicit_request...",
"user_identifiers": {
"session_id": "uuid",
"locale": "en-IN"
},
"suggested_actions": [
"Review conversation history",
"Verify user identity"
]
}
}
}
}
```
---
## 7. Multilingual (Hindi)
### POST /chat
```bash
curl -X POST "http://localhost:8000/chat" \
-H "Content-Type: application/json" \
-d '{
"user_message": "मुझे अपने ऑर्डर की जानकारी चाहिए",
"locale": "hi-IN"
}'
```
---
## 8. Get Session Details
### GET /session/{session_id}
```bash
curl -X GET "http://localhost:8000/session/abc123"
```
**Expected Response:**
```json
{
"session_id": "abc123",
"user_id": null,
"created_at": "2025-10-15T10:00:00Z",
"updated_at": "2025-10-15T10:30:00Z",
"conversation": [
{
"role": "user",
"content": "Hello",
"timestamp": "2025-10-15T10:00:00Z"
},
{
"role": "assistant",
"content": "Hello! How can I help you?",
"timestamp": "2025-10-15T10:00:05Z"
}
],
"escalation_count": 0,
"failed_attempts": 0
}
```
---
## 9. Delete Session
### DELETE /session/{session_id}
```bash
curl -X DELETE "http://localhost:8000/session/abc123"
```
**Expected Response:**
```json
{
"message": "Session deleted successfully",
"session_id": "abc123"
}
```
---
## 10. List Available Tools
### GET /tools
```bash
curl -X GET "http://localhost:8000/tools"
```
**Expected Response:**
```json
{
"tools": [
{
"name": "product_search",
"description": "Search product catalog with filters like categories, tags, price range"
},
{
"name": "order_lookup",
"description": "Retrieve order status, tracking info, and ETA"
},
{
"name": "promotions_check",
"description": "Validate coupon codes and check promotion eligibility"
},
{
"name": "sentiment_analysis",
"description": "Analyze sentiment and emotion in user messages"
},
{
"name": "crm_query",
"description": "Retrieve user profile and history from CRM"
}
]
}
```
---
## 11. Get Configuration
### GET /config
```bash
curl -X GET "http://localhost:8000/config"
```
**Expected Response:**
```json
{
"llm_model": "gemini-2.0-flash",
"supported_locales": ["en-IN", "hi-IN", "ta-IN", "te-IN", "mr-IN"],
"default_locale": "en-IN",
"features": {
"voice": true,
"sentiment_analysis": true,
"tool_calling": true,
"auto_translation": true
}
}
```
---
## 12. Add Documents to Knowledge Base
### POST /documents/add
```bash
curl -X POST "http://localhost:8000/documents/add" \
-F "file=@new_faq.txt"
```
**Expected Response:**
```json
{
"message": "Documents added successfully",
"filename": "new_faq.txt",
"chunks_added": 15
}
```
---
## Testing Tips
1. **Save Session ID**: Reuse the `session_id` from responses to maintain conversation context
2. **Test Edge Cases**:
- Invalid order IDs
- Expired coupons
- Out of stock products
- Empty messages
3. **Test Multilingual**:
- Send messages in different languages
- Verify language detection
- Check response translations
4. **Monitor Confidence**:
- Low confidence (<0.5) may trigger escalation
- High confidence (>0.8) indicates good understanding
5. **Test Structured Responses**:
- Product searches should return carousels
- Order queries should return order cards
- Escalations should include agent brief
---
## Python Testing Script
```python
import requests
import json
BASE_URL = "http://localhost:8000"
def test_chat(message, session_id=None):
payload = {
"user_message": message,
"locale": "en-IN"
}
if session_id:
payload["session_id"] = session_id
response = requests.post(f"{BASE_URL}/chat", json=payload)
return response.json()
# Test simple chat
result = test_chat("Hello!")
print(json.dumps(result, indent=2))
# Test with session
session_id = result["session_id"]
result2 = test_chat("Find gifts under 2000", session_id)
print(json.dumps(result2, indent=2))
```
---
## JavaScript/Node.js Testing Script
```javascript
const axios = require('axios');
const BASE_URL = 'http://localhost:8000';
async function testChat(message, sessionId) {
const payload = {
user_message: message,
locale: 'en-IN'
};
if (sessionId) {
payload.session_id = sessionId;
}
const response = await axios.post(`${BASE_URL}/chat`, payload);
return response.data;
}
// Test
(async () => {
const result = await testChat('Hello!');
console.log(JSON.stringify(result, null, 2));
const sessionId = result.session_id;
const result2 = await testChat('Find gifts under 2000', sessionId);
console.log(JSON.stringify(result2, null, 2));
})();
```
---
For more examples and integration patterns, see [INTEGRATION_GUIDE.md](./INTEGRATION_GUIDE.md)