Update third-party integration docs with SerpAPI instructions

THIRD_PARTY_INTEGRATION.md

@@ -0,0 +1,427 @@
+# Using Gift Finder in Third-Party Applications
+
+This guide explains how to use the Gift Finder model in your own applications via the Hugging Face API, including how to integrate with SerpAPI for real product search results.
+
+## Quick Start
+
+```python
+import requests
+
+def get_gift_recommendations(conversation, token="your_huggingface_token", serpapi_key=None):
+    """
+    Get gift recommendations from the Gift Finder model on Hugging Face.
+    
+    Args:
+        conversation: The conversation text about gift needs
+        token: Your Hugging Face API token
+        serpapi_key: Your SerpAPI API key for real product searches (optional)
+        
+    Returns:
+        Dictionary with extracted data, gift search query, and recommendations
+    """
+    # API endpoint
+    API_URL = "https://api-inference.huggingface.co/models/mehdirben/gift-finder"
+    
+    # Headers for authentication
+    headers = {"Authorization": f"Bearer {token}"}
+    
+    # Request data
+    payload = {"inputs": conversation}
+    
+    # Make the request
+    response = requests.post(API_URL, headers=headers, json=payload)
+    
+    if response.status_code == 200:
+        # Get the embeddings from the response
+        embeddings = response.json()
+        
+        # Extract gift data
+        extracted_data = {
+            "occasion": "birthday" if "birthday" in conversation.lower() else "gift",
+            "recipient_relationship": "friend",
+            "recipient_age": "adult",
+            "recipient_interests": "general",
+            "budget": "moderate"
+        }
+        
+        # Generate search query
+        gift_query = f"{extracted_data['occasion']} gift for {extracted_data['recipient_relationship']}"
+        
+        result = {
+            "extracted_data": extracted_data,
+            "gift_search_query": gift_query,
+            "embeddings_shape": [len(embeddings), len(embeddings[0])]
+        }
+        
+        # If SerpAPI key is provided, search for real products
+        if serpapi_key:
+            recommendations = search_real_products(gift_query, serpapi_key)
+            result["recommendations"] = recommendations
+        else:
+            # Return example recommendations without real search
+            result["recommendations"] = get_example_recommendations(extracted_data)
+            
+        return result
+    else:
+        # Handle errors
+        return {
+            "error": f"API request failed with status code {response.status_code}",
+            "message": response.text
+        }
+
+def search_real_products(query, serpapi_key):
+    """
+    Search for real products using SerpAPI.
+    
+    Args:
+        query: Search query for gift products
+        serpapi_key: Your SerpAPI API key
+        
+    Returns:
+        List of product recommendations
+    """
+    url = "https://serpapi.com/search"
+    params = {
+        "q": query,
+        "api_key": serpapi_key,
+        "engine": "google_shopping",
+        "tbm": "shop",
+        "gl": "us"
+    }
+    
+    try:
+        response = requests.get(url, params=params, timeout=10)
+        response.raise_for_status()
+        data = response.json()
+        
+        products = []
+        if "shopping_results" in data:
+            for item in data["shopping_results"][:5]:
+                title = item.get("title", "")
+                price_str = item.get("extracted_price", "") or item.get("price", "")
+                # Convert price to float
+                if isinstance(price_str, (int, float)):
+                    price = float(price_str)
+                else:
+                    try:
+                        price = float(price_str.replace("$", "").replace(",", ""))
+                    except (ValueError, TypeError):
+                        price = 20.00
+                        
+                link = item.get("link", "") or item.get("product_link", "#")
+                image = item.get("thumbnail", "")
+                
+                if title:
+                    products.append({
+                        "name": title,
+                        "price": f"${price:.2f}",
+                        "url": link,
+                        "description": item.get("snippet", ""),
+                        "image": image
+                    })
+            return products
+        else:
+            return []
+    except Exception as e:
+        print(f"Error searching for products: {str(e)}")
+        return []
+
+def get_example_recommendations(extracted_data):
+    """Fallback example recommendations when SerpAPI key is not provided"""
+    recommendations = []
+    
+    if extracted_data["occasion"] == "birthday":
+        recommendations.append({
+            "name": "Birthday Gift Card",
+            "price": "$25.00",
+            "url": "https://example.com/gift-card",
+            "description": "A versatile gift card for any birthday."
+        })
+        
+    # Add more example recommendations...
+    
+    return recommendations
+
+# Example usage
+conversation = """
+USER: I need to find a gift for my brother's birthday. He's in his 20s and loves playing basketball and video games. I don't want to spend more than $50.
+ASSISTANT: I'd be happy to help you find a birthday gift for your brother who loves basketball and video games within your $50 budget.
+"""
+
+# Without SerpAPI (example recommendations only)
+result = get_gift_recommendations(conversation, token="your_huggingface_token")
+print(result)
+
+# With SerpAPI (real product recommendations)
+# result = get_gift_recommendations(conversation, token="your_huggingface_token", serpapi_key="your_serpapi_key")
+# print(result)
+```
+
+## Using the Official Client Library
+
+For more robust integration, you can use our official client library:
+
+1. Install the required packages:
+   ```
+   pip install -r huggingface_requirements.txt
+   ```
+
+2. Use the enhanced client:
+   ```python
+   from enhanced_huggingface_client import HuggingFaceClientEnhanced
+   from gift_finder_api import GiftFinderAPI
+   
+   # Initialize the client
+   client = HuggingFaceClientEnhanced(
+       token="your_huggingface_token",
+       model_id="mehdirben/gift-finder"
+   )
+   
+   # Process a conversation
+   conversation = "..."
+   result = client.process_conversation(conversation)
+   
+   # Display results
+   print(f"Extracted data: {result['extracted_data']}")
+   print(f"Gift search query: {result['gift_search_query']}")
+   
+   # Get real product recommendations using GiftFinderAPI with SerpAPI
+   api = GiftFinderAPI(hf_token="your_huggingface_token")
+   recommendations = api.get_gift_recommendations(
+       conversation=conversation,
+       num_recommendations=5,
+       search_api_key="your_serpapi_key"  # Pass your SerpAPI key here
+   )
+   
+   for i, rec in enumerate(recommendations, 1):
+       print(f"{i}. {rec['name']} - {rec['price']}")
+       print(f"   {rec['description']}")
+       print(f"   {rec['url']}")
+   ```
+
+## Integration Options
+
+1. **Direct API Calls**: Make HTTP requests directly to the Hugging Face Inference API.
+
+2. **Client Library**: Use our client library for more robust integration with features like caching, retries, and fallback to local model.
+
+3. **Complete API Wrapper**: Use the `GiftFinderAPI` class for a complete integration that handles all the details for you.
+
+4. **Real Product Search with SerpAPI**: Enable real product recommendations by providing a SerpAPI key.
+
+## API Response Format
+
+The API returns embeddings that can be used to extract gift information. The standard response format when using our client libraries is:
+
+```json
+{
+  "extracted_data": {
+    "occasion": "birthday",
+    "recipient_relationship": "brother",
+    "recipient_age": "young adult",
+    "recipient_interests": "basketball and video games",
+    "budget": "moderate"
+  },
+  "gift_search_query": "birthday gift for brother who enjoys basketball and video games under $50",
+  "embeddings_shape": [1, 384],
+  "recommendations": [
+    {
+      "name": "NBA 2K23 - PlayStation 5",
+      "price": "$39.99",
+      "url": "https://example.com/nba-2k23",
+      "description": "NBA basketball video game with updated rosters and features",
+      "image": "https://example.com/nba-2k23-thumbnail.jpg"
+    },
+    {
+      "name": "Mini Basketball Hoop for Door",
+      "price": "$29.99",
+      "url": "https://example.com/mini-basketball-hoop",
+      "description": "Indoor basketball hoop that mounts on any door",
+      "image": "https://example.com/basketball-hoop-thumbnail.jpg"
+    }
+  ]
+}
+```
+
+## Using SerpAPI for Real Product Searches
+
+The Gift Finder API supports real product searches via SerpAPI integration. Here's how to use it:
+
+1. **Get a SerpAPI Key**: Sign up at [SerpAPI](https://serpapi.com/) to obtain an API key.
+
+2. **Pass the SerpAPI Key**: When calling the `get_gift_recommendations` method, include your SerpAPI key:
+
+```python
+from gift_finder_api import GiftFinderAPI
+
+# Initialize the API
+api = GiftFinderAPI(hf_token="your_huggingface_token")
+
+# Get recommendations with real product search
+recommendations = api.get_gift_recommendations(
+    conversation="...",
+    num_recommendations=5,
+    search_api_key="your_serpapi_key"  # Pass your SerpAPI key here
+)
+
+# Display recommendations
+for rec in recommendations:
+    print(f"{rec['name']} - {rec['price']}")
+    print(f"{rec['description']}")
+    print(f"{rec['url']}")
+```
+
+3. **Benefits of using SerpAPI**:
+   - Real product data from Google Shopping
+   - Current prices and availability
+   - Actual product links for purchase
+   - Product images and descriptions
+
+4. **Fallback Mode**: If you don't provide a SerpAPI key, the API will return example recommendations based on the extracted data. This is useful for testing but doesn't provide real product data.
+
+## Error Handling
+
+The client libraries include robust error handling that you should leverage in your applications:
+
+```python
+try:
+    api = GiftFinderAPI(hf_token="your_huggingface_token")
+    recommendations = api.get_gift_recommendations(
+        conversation="...", 
+        search_api_key="your_serpapi_key"
+    )
+    # Process successful result
+except Exception as e:
+    # Handle errors
+    print(f"Error using Gift Finder API: {str(e)}")
+    # Implement fallback logic
+```
+
+## Advanced Usage: Asynchronous API
+
+For high-performance applications, you can use the asynchronous API:
+
+```python
+import asyncio
+from enhanced_huggingface_client import HuggingFaceClientEnhanced
+
+async def process_conversations(conversations, serpapi_key=None):
+    # Initialize client
+    client = HuggingFaceClientEnhanced(token="your_token")
+    
+    # Process multiple conversations concurrently
+    tasks = []
+    for conv in conversations:
+        result = await client.process_conversation_async(conv)
+        
+        # Optionally get real product recommendations
+        if serpapi_key:
+            from serpapi_client import SerpApiClient
+            serp_client = SerpApiClient(api_key=serpapi_key)
+            query = result["gift_search_query"]
+            result["recommendations"] = await serp_client.search_products_async(query)
+        
+        tasks.append(result)
+    
+    results = await asyncio.gather(*tasks)
+    return results
+
+# Run the async function
+conversations = ["conversation1", "conversation2", "conversation3"]
+results = asyncio.run(process_conversations(conversations, serpapi_key="your_serpapi_key"))
+```
+
+## Sample Implementation with SerpAPI
+
+Here's a complete example implementation using SerpAPI for real product searches:
+
+```python
+import os
+import requests
+from dotenv import load_dotenv
+from gift_finder_api import GiftFinderAPI
+
+# Load environment variables from .env file
+load_dotenv()
+
+# Get API keys from environment variables
+HF_TOKEN = os.getenv("HF_TOKEN")
+SERPAPI_KEY = os.getenv("SERPAPI_API_KEY")
+
+def process_gift_recommendation_request(conversation_text):
+    """
+    Process a gift recommendation request with real product searches.
+    """
+    try:
+        # Initialize the Gift Finder API
+        api = GiftFinderAPI(hf_token=HF_TOKEN)
+        
+        # Extract gift data and generate search query
+        extracted_data = api.extract_gift_data(conversation_text)
+        search_query = api.generate_gift_query(conversation_text)
+        
+        print(f"Extracted data: {extracted_data}")
+        print(f"Search query: {search_query}")
+        
+        # Get gift recommendations with real product search if SERPAPI_KEY is available
+        if SERPAPI_KEY:
+            print("Using SerpAPI for real product recommendations")
+            recommendations = api.get_gift_recommendations(
+                conversation=conversation_text,
+                num_recommendations=5,
+                search_api_key=SERPAPI_KEY
+            )
+        else:
+            print("Using example recommendations (no SerpAPI key provided)")
+            recommendations = api.get_gift_recommendations(
+                conversation=conversation_text
+            )
+        
+        return {
+            "status": "success",
+            "extracted_data": extracted_data,
+            "search_query": search_query,
+            "recommendations": recommendations
+        }
+        
+    except Exception as e:
+        print(f"Error: {str(e)}")
+        return {
+            "status": "error",
+            "message": str(e)
+        }
+
+# Example usage
+if __name__ == "__main__":
+    conversation = """
+    USER: I need a gift for my friend who loves hiking. Budget is $100.
+    ASSISTANT: I'll help you find a hiking gift. Does your friend have any specific hiking gear already?
+    USER: They need a new backpack and they hike in all weather conditions.
+    """
+    
+    result = process_gift_recommendation_request(conversation)
+    
+    if result["status"] == "success":
+        print("\nRecommendations:")
+        for i, rec in enumerate(result["recommendations"], 1):
+            print(f"{i}. {rec['name']} - {rec['price']}")
+            print(f"   {rec['description'] if 'description' in rec else ''}")
+            print(f"   {rec['url']}")
+            print()
+    else:
+        print(f"Error: {result['message']}")
+```
+
+## Environment Setup
+
+To use SerpAPI with the Gift Finder API, make sure to set up your environment variables:
+
+```
+# .env file
+HF_TOKEN=your_huggingface_token
+SERPAPI_API_KEY=your_serpapi_key
+```
+
+## Need Help?
+
+For more information, see the full documentation in [HUGGINGFACE_INTEGRATION.md](HUGGINGFACE_INTEGRATION.md).