AI-Powered E-commerce Personalization Platform

Enterprise-grade LLM and agentic AI system for intelligent e-commerce personalization

Documentation • API Reference • Deployment • Architecture • Roadmap

---

Overview

A complete, production-ready platform that combines OpenAI's powerful LLMs with a multi-agent architecture to deliver intelligent product recommendations, dynamic pricing optimization, semantic search, and seamless payment integration.

Perfect for building intelligent e-commerce experiences with AI-powered personalization.

✨ Key Capabilities

• 🤖 Explainable AI Reasoning - Multi-step agent reasoning with confidence tracking for transparent decisions
• 🔍 Hybrid Semantic Search - Keyword + vector search using OpenAI embeddings and FAISS/Pinecone
• 💰 Dynamic Pricing - Market-aware price optimization based on demand, inventory, and competitor pricing
• 💳 Secure Payments - Stripe integration with webhook handling and refund processing
• 🧾 Order Management - Create orders, track status, cancel or update orders
• ☁️ Cloud Native - AWS Lambda, ECS, API Gateway, and S3 support for serverless deployment
• ⚡ High Performance - Async FastAPI with 200-500ms recommendation generation
• 📦 Production Ready - Comprehensive error handling, logging, health checks, and monitoring
• 🧪 Tested & Documented - Full test suite with CI/CD pipelines and 2,500+ lines of documentation

---

📊 Project Statistics

Metric	Count
Python Files	20+
Lines of Code	4,000+
API Endpoints	13
AI Agents	2
Services	5+
Documentation	5 guides (2,500+ lines)
Data Models	15+
Integration Points	4
Test Suite	Ready for CI/CD

---

🎯 Features

Core Capabilities

• AI-Powered Recommendations: Multi-agent system using OpenAI embeddings for intelligent product suggestions
• Semantic Search: Hybrid keyword + vector search using FAISS/Pinecone for context-aware discovery
• Dynamic Pricing Agent: Real-time price optimization based on demand, inventory, competitor pricing, and user segments
• Real-time Search API: FastAPI-based endpoints with ElasticSearch integration
• Payment Integration: Stripe integration for secure payment processing
• Cart API Integration: Seamless cart management and promotion application
• Serverless Deployment: AWS Lambda, API Gateway, and S3 infrastructure

Agent Systems

1. Recommendation Agent: Multi-step reasoning for personalized product suggestions

   • User behavior analysis
   • Product fit evaluation
   • Business rule application
   • Contextual reason generation

2. Pricing Agent: Dynamic pricing based on multiple factors

   • Demand signals
   • Inventory levels
   • Competitor pricing
   • User segment multipliers

Infrastructure

• Containerization: Docker and Docker Compose for local development
• Cloud Deployment: AWS (S3, Lambda, API Gateway, ECS)
• CI/CD Pipeline: GitHub Actions for automated testing and deployment
• Database: PostgreSQL for persistent data
• Caching: Redis for performance optimization
• Search: ElasticSearch for full-text search capabilities

---

🚀 Quick Start (30 seconds)

Prerequisites

• Python 3.11+
• Docker & Docker Compose
• OpenAI API key
• Stripe API keys (for payment testing)

Run with Docker

# Clone repository
git clone <repository-url>
cd LLM-client

# Setup environment
cp .env.example .env
# Edit .env with your API keys

# Start all services
docker-compose up -d

# Access API
open http://localhost:8000/docs

Or Manual Setup

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Create environment file
cp .env.example .env
# Edit .env with your credentials

# Run application
uvicorn app.main:app --reload

Access the API

• API Server: http://localhost:8000
• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• Health Check: http://localhost:8000/health

---

📚 API Documentation

Recommendations API

Get Personalized Recommendations

POST /api/v1/recommendations
Content-Type: application/json

{
  "user_id": "user_123",
  "session_id": "session_456",
  "context": {
    "user_id": "user_123",
    "session_id": "session_456",
    "device_type": "web",
    "previous_purchases": ["prod_001"],
    "cart_items": ["prod_002"],
    "browsing_history": ["electronics"]
  },
  "num_recommendations": 5
}

Search API

Hybrid Product Search

GET /api/v1/search/products?q=laptop&search_type=hybrid&limit=10

Payment API

Create Payment Intent

POST /api/v1/payments/intent
Content-Type: application/json

{
  "user_id": "user_123",
  "amount": 199.99,
  "currency": "USD",
  "items": [...]
}

Orders API

Create Order

POST /api/v1/orders
Content-Type: application/json

{
  "user_id": "user_123",
  "items": [
    {
      "product_id": "prod_001",
      "product_name": "Premium Laptop",
      "quantity": 1,
      "unit_price": 1299.99,
      "total_price": 1299.99
    }
  ],
  "total_amount": 1299.99,
  "shipping_address": "123 Main St"
}

For detailed API documentation, see API_REFERENCE.md

---

📁 Project Structure

LLM-client/
├── app/
│   ├── api/                 # 4 route modules (recommendations, search, payments, health)
│   ├── agents/              # 2 AI agents (recommendation, pricing)
│   ├── services/            # Business logic (search, recommendation, promotion)
│   ├── integrations/        # External services (payment, cart, AWS)
│   ├── models/              # 15+ Pydantic data models
│   ├── utils/               # Embeddings and vector database utilities
│   ├── config/              # Settings and configuration management
│   └── main.py              # FastAPI application entry point
├── aws/                     # AWS Lambda handler and CloudFormation
├── tests/                   # API tests and pytest configuration
├── .github/workflows/       # CI/CD pipelines (testing, security, deployment)
├── Dockerfile               # Container image definition
├── docker-compose.yml       # Local environment orchestration
├── requirements.txt         # Python dependencies
├── makefile.py              # Development command helper
├── examples.py              # Complete API usage examples
└── [Documentation Files]    # README, API_REFERENCE, AGENT_ARCHITECTURE, DEPLOYMENT, ROADMAP

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Client Application                       │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                    FastAPI Gateway                           │
│  (CORS, GZIP, Error Handling, Authentication)              │
└─────────────────────┬───────────────────────────────────────┘
                      │
      ┌───────────────┼───────────────┐
      ▼               ▼               ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│Recommendation│ │   Search     │ │   Payments   │
│   Agent      │ │   Service    │ │  Integration │
└──────────────┘ └──────────────┘ └──────────────┘
      │               │               │
      ├───────────────┼───────────────┤
      ▼               ▼               ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Vector DB    │ │ ElasticSearch│ │   Stripe     │
│(FAISS/       │ │              │ │   Payment    │
│Pinecone)     │ │              │ │   Provider   │
└──────────────┘ └──────────────┘ └──────────────┘

---

🔧 Configuration

Environment Variables

Copy .env.example to .env and fill in your values:

# Required
OPENAI_API_KEY=sk-...
STRIPE_API_KEY=pk_...
STRIPE_SECRET_KEY=sk_...

# Optional (AWS for cloud deployment)
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...

# Database
DATABASE_URL=postgresql://user:password@localhost/ecommerce

# Vector Database
VECTOR_DB_TYPE=faiss          # or 'pinecone'

# Redis
REDIS_URL=redis://localhost:6379

See .env.example for all available options.

---

🚀 Deployment

Docker Compose (Development)

docker-compose up -d
docker-compose logs -f api

AWS Lambda

./deploy_lambda.sh

Kubernetes

kubectl apply -f deployment.yaml -n ecommerce

For detailed deployment instructions, see DEPLOYMENT.md

---

🧪 Testing

# Run all tests
pytest tests/ -v

# With coverage
pytest tests/ --cov=app --cov-report=html

# Run specific test
pytest tests/test_api.py::test_health_check -v

---

📖 Documentation

• README.md - This file
• API_REFERENCE.md - Complete API documentation with examples
• AGENT_ARCHITECTURE.md - Detailed agent design and workflows
• DEPLOYMENT.md - Step-by-step deployment guide for all platforms
• ROADMAP.md - Feature roadmap and release timeline
• PROJECT_SUMMARY.md - Comprehensive project summary

---

🛠️ Development Tools

Using makefile.py

# View all commands
python makefile.py help

# Common tasks
python makefile.py setup       # Setup development environment
python makefile.py lint        # Run code linters
python makefile.py format      # Format code
python makefile.py test        # Run tests
python makefile.py server      # Start dev server
python makefile.py docker-run  # Start Docker Compose

Or Manual Commands

python makefile.py help        # See all available commands

---

📚 API Examples

Example 1: Get Recommendations

curl -X POST http://localhost:8000/api/v1/recommendations \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_001",
    "session_id": "session_001",
    "context": {
      "user_id": "user_001",
      "session_id": "session_001",
      "device_type": "mobile",
      "previous_purchases": [],
      "cart_items": [],
      "browsing_history": ["electronics"]
    },
    "num_recommendations": 5
  }'

Example 2: Search Products

curl "http://localhost:8000/api/v1/search/products?q=laptop&limit=10"

Example 3: Check Health

curl http://localhost:8000/health

For more examples, see examples.py

---

🔒 Security Features

• ✅ CORS middleware for cross-origin requests
• ✅ GZIP compression for responses
• ✅ Secure error handling without exposing internals
• ✅ Stripe webhook signature verification
• ✅ AWS credentials management
• ✅ Environment variable protection
• ✅ Comprehensive logging for audit trails

---

📈 Performance

• Recommendation Generation: 200-500ms
• Vector Search: 50-100ms
• API Response Time: < 200ms (p95)
• Throughput: 1000+ requests/second per instance
• Availability: Designed for > 99.9% uptime

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

For architecture details, see AGENT_ARCHITECTURE.md

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

Built with modern Python best practices and designed for enterprise-scale e-commerce personalization.

Tech Stack:

• FastAPI
• OpenAI
• FAISS/Pinecone
• PostgreSQL
• Redis
• ElasticSearch
• Stripe
• AWS
• Docker
• GitHub Actions

---

📞 Support

• Documentation: See the docs/ directory
• API Documentation: Visit http://localhost:8000/docs
• Issues: Create a GitHub issue with details
• Discussions: Use GitHub Discussions for questions

---

Created: January 2024
Version: 1.0.0
Status: Production Ready ✅