|
Download API_EXAMPLES.md from Ayush-003/ThinkOV2: direct link, hf CLI and curl.
- Browser
- Download file 9.65 kB
-
https://huggingface.co/spaces/Ayush-003/ThinkOV2/resolve/main/API_EXAMPLES.md
- Command line
-
hf download hf://spaces/Ayush-003/ThinkOV2/API_EXAMPLES.md
-
curl -L -o API_EXAMPLES.md https://huggingface.co/spaces/Ayush-003/ThinkOV2/resolve/main/API_EXAMPLES.md
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) | |