Skip to content

README.md

Latest commit

 

History

History
354 lines (267 loc) · 10.2 KB

README.md

File metadata and controls

354 lines (267 loc) · 10.2 KB
Raw

Customer Insights GenAI API

Overview

This API processes customer feedback text to extract marketing insights. It performs sentiment analysis, identifies unmet needs, and detects safety concerns using AWS Bedrock Claude-3-Haiku.

Primary Use Case: Marketing Intelligence

Objective: Process customer feedback for marketing insights

Core Capabilities

  1. Sentiment Analysis - Classify customer sentiment and satisfaction
  2. Insight Mining - Extract unmet needs and pain points
  3. Multi-language Support - English, Spanish, and French
  4. Safety Detection - Identify potential product safety concerns

Value-Added Features

  • Adverse Event Detection - Local safety concern detection
  • Recommendations - Generate suggested actions
  • Response Time - 1.6-2.7s via AWS Bedrock

API Endpoint

POST /insights

Input Format

{
  "text": "The product works well but the setup process was confusing and took hours",
  "source": "customer_review",
  "category": "product_feedback"
}

Output Format

{
  "sentiment_score": -0.8,
  "sentiment_label": "negative",
  "language_detected": "english",
  "insights": {
    "unmet_needs": ["product safety", "device reliability"],
    "pain_points": ["device overheating", "burn injury"],
    "positive_aspects": []
  },
  "recommendations": [
    "prioritize product safety testing",
    "improve device cooling mechanisms",
    "add clear safety warnings"
  ],
  "adverse_events": ["burn"],
  "safety_concerns": [
    {
      "event": "burn",
      "severity": "mild",
      "confidence": 0.8,
      "safety_category": "Thermal Injury",
      "detected_phrase": "The device got very hot and burned my hand..."
    }
  ],
  "processing_time_ms": 1520,
  "confidence": 0.95,
  "model": "claude-3-haiku",
  "status": "success"
}

Marketing Applications

1. Product Development

  • Feature Prioritization: Identify most requested features
  • Pain Point Resolution: Address common customer frustrations
  • User Experience: Improve product usability based on feedback

2. Customer Segmentation

  • Satisfaction Levels: Group customers by sentiment patterns
  • Need Categories: Segment by unmet needs and requirements
  • Engagement Strategies: Tailor messaging to customer sentiment

3. Competitive Intelligence

  • Market Gaps: Discover underserved customer needs
  • Positioning: Understand customer perception vs competitors
  • Opportunity Mapping: Identify new market opportunities

4. Campaign Optimization

  • Message Testing: Analyze response sentiment to marketing copy
  • Channel Effectiveness: Compare sentiment across communication channels
  • Content Strategy: Develop content addressing identified needs

Technical Architecture

AWS Bedrock Integration

  • Model: Claude-3-Haiku for fast, cost-effective analysis
  • Capabilities: Natural language understanding, multilingual processing
  • Performance: ~1-2 second inference time

SageMaker Auto-Scaling

  • Instance Range: 1-4 instances (configurable via CloudFormation parameters)
  • Scaling Metric: Target 100 invocations per instance per minute
  • Scale-Out: 60 second cooldown for rapid response to traffic spikes
  • Scale-In: 300 second cooldown for cost optimization
  • Instance Type: ml.m5.large (configurable)
  • Cost Optimization: Automatic scaling down during low traffic periods

Input Processing Pipeline

  1. Validation: Content filtering and quality checks
  2. Language Detection: Automatic language identification
  3. Translation: Convert non-English text to English for analysis
  4. Analysis: Sentiment, insights, and recommendations generation

Security & Privacy

  • PII Sanitization: Automatic removal of personal information
  • Content Filtering: Block inappropriate or harmful content
  • Data Encryption: All data encrypted in transit and at rest
  • Audit Logging: Complete request/response tracking

Package Structure

src/
├── __init__.py          # Package version and metadata
└── genai/
    ├── __init__.py      # Module exports and API surface
    ├── genai_insights.py     # Main GenAI Lambda handler
    ├── sagemaker_proxy.py    # SageMaker endpoint proxy Lambda
    ├── prompts.py           # Marketing-focused prompt templates
    ├── adverse_events.py    # Safety concern detection
    ├── utils.py            # Input validation and utilities
    └── requirements.txt     # Python dependencies

Python Package Installation

# Install as editable package (for development)
pip install -e .

# Import modules after installation
from genai import genai_handler, sagemaker_handler
from genai.utils import validate_input
from genai.adverse_events import detect_adverse_events

Usage Examples

Customer Review Analysis

curl -X POST https://api-url/insights \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Love the product but wish it had mobile app integration",
    "source": "app_store_review",
    "category": "feature_request"
  }'

Social Media Monitoring

curl -X POST https://api-url/insights \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Frustrated with customer service wait times #needhelp",
    "source": "twitter",
    "category": "service_feedback"
  }'

Safety Issue Detection

curl -X POST https://api-url/insights \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The device got very hot and burned my hand during use. This is dangerous!",
    "source": "customer_complaint",
    "category": "safety_issue"
  }'

Key Metrics

  • Response Time: < 3 seconds (95th percentile)
  • Accuracy: 85%+ sentiment classification accuracy
  • Language Support: English, Spanish, French
  • Throughput: 100+ requests/minute (auto-scales to 400+ with 4 instances)
  • Cost: < $0.01 per analysis
  • Auto-Scaling: Responds to traffic within 60 seconds

Business Value

Use Cases

  • Product Development: Feature prioritization based on feedback
  • Marketing: Sentiment-based customer segmentation
  • Support: Proactive issue identification
  • Analysis: Automated feedback processing

Metrics

  • Sentiment Trends: Track customer satisfaction over time
  • Feature Requests: Identify most requested capabilities
  • Issue Detection: Monitor safety concerns and problems
  • Response Analysis: Process feedback at scale

Deployment Commands

Infrastructure Management

make deploy          # Deploy complete infrastructure with auto-scaling (1-4 instances)
make deploy-dev      # Deploy with minimal scaling (1-2 instances)
make deploy-prod     # Deploy with production scaling (2-8 instances)
make deploy-custom   # Deploy with custom scaling parameters (interactive)
make update-lambda   # Update Lambda function code only
make destroy         # Tear down all resources
make status          # Check deployment status

Auto-Scaling Monitoring

make get-endpoints   # List SageMaker endpoints with scaling info
make get-scaling     # Show detailed auto-scaling configuration and metrics

Auto-Scaling Configuration Examples

# Development environment (cost-optimized)
make deploy-dev

# Production environment (high availability)
make deploy-prod

# Custom configuration (interactive prompts)
make deploy-custom

# Manual CloudFormation deployment with custom parameters
aws cloudformation deploy \
  --template-file infrastructure/cloudformation-complete.yaml \
  --stack-name ml-pipeline-stack \
  --parameter-overrides \
    EndpointMinCapacity=2 \
    EndpointMaxCapacity=8 \
    EndpointTargetInvocations=150 \
  --capabilities CAPABILITY_NAMED_IAM

API Testing

make test-api        # Test Customer Insights API
make get-api-url     # Get API endpoint URL

Development

make start-notebook  # Start SageMaker notebook instance
make stop-notebook   # Stop SageMaker notebook instance

Performance Metrics

Current Performance (Production)

  • Average Response Time: 1.7s (1613ms - 1940ms observed)
  • 95th Percentile: < 2.5s ✅ (Target: < 3s)
  • Consistency: ±300ms variance
  • Model: Claude-3-Haiku via AWS Bedrock
  • Confidence Score: 0.9 (90% accuracy)

Performance Breakdown

  • AWS Bedrock Inference: ~1.5s
  • Lambda Processing: ~200ms
  • API Gateway Overhead: ~100ms
  • Safety Analysis: ~50ms

Optimization Results

  • Cold Start: < 3s (optimized from 10s+)
  • Memory Usage: 1024MB (optimal for Bedrock calls)
  • Cost per Request: < $0.005
  • Throughput: 100+ concurrent requests (400+ with auto-scaling)

Auto-Scaling Performance

  • Scale-Out Time: 60 seconds to add instances
  • Scale-In Time: 300 seconds to remove instances (cost optimization)
  • Target Metric: 100 invocations per instance per minute
  • Instance Range: 1-4 instances (default), configurable up to 8+
  • Cost Efficiency: Automatic scale-down during low traffic periods

Value-Added Features Performance

  • Adverse Event Detection: 0ms (local processing)
  • Multi-language Support: +200ms for translation
  • Safety Concerns: Real-time detection
  • Recommendation Engine: Integrated in main inference

Development

Package Installation

# Install package in development mode
pip install -e .

# Verify installation
python -c "import genai; print('Package installed successfully')"

Module Usage

# Import Lambda handlers
from genai import genai_handler, sagemaker_handler

# Import utilities
from genai.utils import validate_input
from genai.adverse_events import detect_adverse_events
from genai.prompts import SENTIMENT_PROMPT

# Use in SageMaker notebooks or local development
result = genai_handler(event, context)

Getting Started

  1. Deploy Infrastructure: make deploy
  2. Install Package: pip install -e .
  3. Test API: make test-api
  4. Get Endpoint: make get-api-url
  5. Integrate Systems: Connect to CRM, support tools, and analytics platforms
  6. Monitor Performance: Track metrics and optimize based on usage patterns

This API processes customer feedback to provide sentiment analysis, unmet needs identification, and safety concern detection for marketing and product teams.