Zero-Shot Category Classification API

A production-ready FastAPI application that uses zero-shot classification with the Facebook BART-large-MNLI model to categorize YouTube channel descriptions into predefined categories.

🚀 Quick Start

Docker Deployment (Recommended)

# Build and run with Docker Compose
docker-compose up --build

# Or build and run standalone
docker build -t category-classifier .
docker run -p 5680:5680 category-classifier

Local Development

# Install dependencies
pip install -r requirements.txt

# Run the application
uvicorn classify:app --host 0.0.0.0 --port 5680

📋 Table of Contents

• Overview
• Architecture
• Features
• API Documentation
• Installation
• Usage
• Model Information
• Logging
• Deployment
• Performance
• Contributing
• License

🎯 Overview

This application provides a RESTful API for automatic categorization of YouTube channel descriptions using state-of-the-art zero-shot learning. Instead of training a model on specific categories, it leverages the BART-large-MNLI model's understanding of language to classify text into any set of predefined categories.

Use Cases

• YouTube channel categorization
• Content recommendation systems
• Content moderation
• Market research and analysis
• Content discovery platforms

🏗️ Architecture

graph TB
    A[Client Request] --> B[FastAPI Application]
    B --> C[Request Validation]
    C --> D[Logging Middleware]
    D --> E[Zero-Shot Classifier]
    E --> F[BART-large-MNLI Model]
    F --> G[Category Prediction]
    G --> H[Response Generation]
    H --> I[Logging]
    I --> J[Client Response]
    
    K[Docker Container] --> B
    L[Model Files] --> F
    M[Log Volume] --> I
    
    style A fill:#e1f5fe
    style F fill:#fff3e0
    style K fill:#f3e5f5
    style L fill:#e8f5e8

Loading

Technical Stack

• Web Framework: FastAPI (Python 3.9+)
• ML Framework: Transformers (Hugging Face)
• Model: Facebook BART-large-MNLI
• Containerization: Docker & Docker Compose
• ASGI Server: Uvicorn
• Validation: Pydantic

✨ Features

• Zero-Shot Learning: Classify into any category without retraining
• Production Ready: Docker containerization with proper logging
• RESTful API: Clean, documented endpoints
• Comprehensive Logging: Request/response logging with timestamps
• Error Handling: Graceful error responses
• Auto-Documentation: Swagger UI and ReDoc available
• Volume Persistence: Persistent log storage across container restarts

📚 API Documentation

Base URL

http://localhost:5680

Endpoints

POST /classify/

Classify a channel description into one of the predefined categories.

Request Body:

{
  "description": "string"
}

Response:

{
  "description": "string",
  "predicted_category": "string"
}

Example Request:

curl -X POST "http://localhost:5680/classify/" \
     -H "Content-Type: application/json" \
     -d '{"description": "We share educational videos about programming and technology"}'

Example Response:

{
  "description": "We share educational videos about programming and technology",
  "predicted_category": "Technology"
}

API Documentation

• Swagger UI: http://localhost:5680/docs
• ReDoc: http://localhost:5680/redoc

🏗️ Installation

Prerequisites

• Docker & Docker Compose (recommended)
• Python 3.9+ (for local development)
• 4GB+ RAM (for model loading)

Docker Installation

1. Clone the repository:

   git clone https://github.com/devtitus/Project_zero_shot_classification.git
   cd Project_zero_shot_classification

2. Build and run:

   docker-compose up --build

3. Verify installation:

   curl http://localhost:5680/docs

Local Development Installation

1. Clone and setup:

   git clone https://github.com/devtitus/Project_zero_shot_classification.git
   cd Project_zero_shot_classification
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies:

   pip install -r requirements.txt

3. Run the application:

   uvicorn classify:app --host 0.0.0.0 --port 5680

🤖 Model Information

BART-large-MNLI

• Model Type: Sequence-to-Sequence Transformer
• Architecture: BART (Bidirectional and Auto-Regressive Transformers)
• Pre-training: Masked Language Modeling + Denoising
• Fine-tuning: Multi-Genre Natural Language Inference (MNLI)
• Parameters: ~406M
• Model Size: ~1.6GB

Classification Categories

The model classifies descriptions into 24 predefined categories:

1. Technology - Programming, software, hardware, AI/ML
2. Education - Learning, tutorials, courses, academic content
3. Gaming - Video games, game reviews, gameplay
4. Lifestyle - Daily life, routines, personal development
5. Comedy - Humor, jokes, entertainment
6. Music - Songs, music videos, covers
7. Finance - Investing, personal finance, business
8. News - Current events, journalism, reporting
9. Health & Fitness - Exercise, wellness, medical content
10. Travel - Destinations, travel tips, vlogs
11. Sports - Athletic events, sports analysis
12. Food & Cooking - Recipes, cooking tutorials
13. Beauty & Fashion - Makeup, style, fashion tips
14. Entertainment - Movies, TV shows, pop culture
15. DIY & Crafts - Handmade projects, tutorials
16. Science - Scientific content, research, explanations
17. Automotive - Cars, vehicles, automotive content
18. Pets & Animals - Animal care, pet videos
19. Vlogging - Personal vlogs, daily content
20. Reaction & Commentary - Reactions, reviews, commentary
21. ASMR & Relaxation - ASMR, relaxation content
22. Business & Entrepreneurship - Business advice, startups
23. True Crime - Crime stories, investigations
24. Spirituality & Religion - Religious content, spiritual guidance

📝 Logging

The application provides comprehensive logging for monitoring and debugging:

Log Levels

• INFO: Request/response logging, classification results
• ERROR: System errors and exceptions

Log Storage

• Console: Real-time logging to stdout
• Files: Daily log files in /app/logs/ directory
• Format: api_YYYY-MM-DD.log

Log Volume

Docker Compose creates a persistent volume category_logs that survives container restarts.

Viewing Logs

# Docker Compose
docker-compose logs -f

# Docker (standalone)
docker logs <container_id>

# Direct file access
docker exec -it category-classifier cat /app/logs/api_2024-01-01.log

🚀 Deployment

Production Deployment

1. Build production image:

   docker build -t category-classifier:production .

2. Deploy with Docker Compose:

   docker-compose -f docker-compose.yml up -d

3. Monitor deployment:

   docker-compose logs -f

Scaling Considerations

• Model Loading: Model is loaded once at startup
• Memory Requirements: ~2GB RAM for model + application
• Concurrency: FastAPI handles multiple requests concurrently
• Load Balancing: Use reverse proxy (nginx) for multiple instances

Environment Variables

Currently, the application uses default configurations. For production:

• PORT: Change default port (5680)
• LOG_LEVEL: Adjust logging verbosity
• MODEL_PATH: Custom model location

⚡ Performance

Model Loading

• Cold Start: ~30-60 seconds for model loading
• Memory Usage: ~1.6GB for model weights
• CPU/GPU: Works on CPU, GPU acceleration available

Inference Performance

• Latency: ~1-3 seconds per classification
• Throughput: ~10-20 requests/second (CPU)
• Batching: Single request processing

Optimization Tips

1. GPU Acceleration: Use CUDA-enabled containers
2. Model Quantization: Reduce model size for faster inference
3. Caching: Cache frequent classifications
4. Load Balancing: Distribute load across multiple instances

🧪 Testing

Manual Testing

# Test classification endpoint
curl -X POST "http://localhost:5680/classify/" \
     -H "Content-Type: application/json" \
     -d '{"description": "Learn Python programming with our comprehensive tutorials"}'

# Test API documentation
curl http://localhost:5680/docs

Expected Responses

Success Response:

{
  "description": "Learn Python programming with our comprehensive tutorials",
  "predicted_category": "Education"
}

Error Response:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "description"],
      "msg": "Field required",
      "input": {}
    }
  ]
}

🔧 Configuration

Docker Configuration

The docker-compose.yml file configures:

• Service Name: category-classifier
• Port Mapping: 5680:5680
• Volume Mapping: Local directory + persistent logs
• Restart Policy: Unless stopped

Application Configuration

The classify.py file contains:

• Categories: 24 predefined classification categories
• Model: BART-large-MNLI from Hugging Face
• Logging: File and console logging setup
• Middleware: Request/response logging

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make changes and test locally
4. Commit changes: git commit -m 'Add feature'
5. Push to branch: git push origin feature-name
6. Create Pull Request

Development Guidelines

• Follow PEP 8 Python style guidelines
• Add tests for new features
• Update documentation for changes
• Use meaningful commit messages

📄 License

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

🆘 Troubleshooting

Common Issues

Model Loading Errors:

• Ensure sufficient memory (4GB+ recommended)
• Check model files in models/bart-large-mnli/ directory

Docker Issues:

• Verify Docker is running
• Check port 5680 is available
• Ensure proper file permissions

API Errors:

• Verify JSON format in request body
• Check description field is present
• Review logs for detailed error messages

Getting Help

• Issues: Report bugs and feature requests on GitHub
• Documentation: Check this README and inline code comments
• Logs: Review application logs for error details

📞 Contact

For questions and support, please contact the project maintainer or create an issue on GitHub.

---

Note: This is a production-ready application for zero-shot text classification. Ensure proper resource allocation and monitoring in production environments.