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 /

curl -X GET "http://localhost:8000/"

Expected Response:

{
  "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

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:

{
  "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

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:

{
  "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

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:

{
  "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

curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "user_message": "Is coupon DIWALI25 valid?",
    "locale": "en-IN"
  }'

Expected Response:

{
  "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

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:

{
  "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

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}

curl -X GET "http://localhost:8000/session/abc123"

Expected Response:

{
  "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}

curl -X DELETE "http://localhost:8000/session/abc123"

Expected Response:

{
  "message": "Session deleted successfully",
  "session_id": "abc123"
}

10. List Available Tools

GET /tools

curl -X GET "http://localhost:8000/tools"

Expected Response:

{
  "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

curl -X GET "http://localhost:8000/config"

Expected Response:

{
  "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

curl -X POST "http://localhost:8000/documents/add" \
  -F "file=@new_faq.txt"

Expected Response:

{
  "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

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

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