Production-ready Streamlit application for generating AI-powered social media captions with sentiment detection and trending hashtags.
Features • Installation • Usage • Architecture • Deployment
Social Mood Matcher is an AI-powered web application built with Python and Streamlit that analyzes uploaded images and generates engaging social media captions with relevant hashtags. Users can customize the caption style and target platform to create content suitable for Instagram, Facebook, and Twitter/X.
- 🎭 Image Sentiment Detection
- ✍️ Smart Caption Generation
- #️⃣ Trending Hashtag Engine
- 📏 Character Limiting
- 🎨 Beautiful UI
- 🚀 Production Ready
graph TD
A[User Uploads Image] --> B[Image Validation]
B --> C[Image Sentiment Detection]
C --> D[BLIP Image Captioning]
D --> E[Sentiment Analysis]
E --> F[Caption Generation]
E --> G[Hashtag Engine]
F --> H[Character Limiter]
G --> H
H --> I[Final Output]
I --> J[Display to User]
social-mood-matcher/
│
├── app.py # Main Streamlit application
├── requirements.txt # Python dependencies
├── README.md # This file
├── .env.example # Environment template
│
├── config/
│ └── settings.py # Centralized configuration
│
├── services/
│ ├── image_sentiment.py # Sentiment detection service
│ ├── caption_generator.py # Caption generation service
│ ├── hashtag_engine.py # Hashtag recommendation engine
│ └── character_limiter.py # Character limiting service
│
├── utils/
│ ├── image_utils.py # Image processing utilities
│ └── text_utils.py # Text processing utilities
│
├── assets/
│ └── sample_images/ # Sample test images
│
└── tests/
└── test_pipeline.py # Test suite
- Python 3.10 or higher
- pip package manager
- 4GB+ RAM (for AI models)
cd "c:\Users\prana\OneDrive\Desktop\Kitchen Vision"python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activatepip install -r requirements.txtNote: First-time installation will download AI models (~2GB). This is a one-time process.
copy .env.example .env
# Edit .env if you want to customize settingsstreamlit run app.pyThe application will open in your default browser at http://localhost:8501
- Upload Image - Click "Browse files" and select an image (JPG, PNG, WEBP)
- Configure Settings - Choose caption style, platform, and number of hashtags in the sidebar
- Generate - Click "🚀 Generate Caption & Hashtags"
- Copy & Share - Copy the generated content and paste it on your social media!
- Casual - Friendly and relaxed tone with moderate emoji usage
- Aesthetic - Artistic and poetic with minimal emojis
- Professional - Polished and informative with no emojis
- Playful - Fun and energetic with high emoji usage
- Twitter/X - 280 character limit
- Instagram - 2,200 character limit
- Facebook - 63,206 character limit
The application uses the following Hugging Face models:
| Component | Model | Purpose |
|---|---|---|
| Image Captioning | Salesforce/blip-image-captioning-base | Understand image content |
| Sentiment Analysis | distilbert-base-uncased-finetuned-sst-2-english | Detect sentiment |
| Caption Templates | Custom template system | Generate engaging captions |
All models run locally - no API keys required!
Run the test suite:
pytest tests/test_pipeline.py -vRun with coverage:
pytest tests/test_pipeline.py --cov=. --cov-report=html- Push your code to GitHub
- Go to share.streamlit.io
- Connect your repository
- Deploy!
Create a Dockerfile:
FROM python:3.10-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8501
CMD ["streamlit", "run", "app.py", "--server.port=8501", "--server.address=0.0.0.0"]Build and run:
docker build -t social-mood-matcher .
docker run -p 8501:8501 social-mood-matcherThe application can be deployed on any cloud platform that supports Python and Streamlit. See Streamlit deployment docs for detailed guides.
Create a .env file from .env.example:
# Debug Settings
DEBUG=False
LOG_LEVEL=INFO
# Model Cache Directory
MODEL_CACHE_DIR=./models_cache
# Optional API Keys (for future features)
# OPENAI_API_KEY=your_key_here
# HUGGINGFACE_API_KEY=your_key_hereEdit config/settings.py to customize:
- Model configurations
- Character limits
- Hashtag counts
- UI settings
- Sentiment categories
- Caption styles
- First Run: ~30-60 seconds (model loading)
- Subsequent Runs: ~3-5 seconds per image
- Model Size: ~2GB (cached locally)
- Memory Usage: ~2-4GB RAM
Optimization Tips:
- Use GPU if available (change
deviceinconfig/settings.py) - Enable caching (enabled by default)
- Reduce image size before upload
- Multiple caption variants with A/B testing
- Download caption as .txt file
- Light/Dark UI mode toggle
- Real-time trending hashtag API integration
- Multi-language support
- Batch processing for multiple images
- Custom hashtag suggestions
- Analytics dashboard
- Social media direct posting
- Video support
This project was developed with significant assistance from AI coding tools for project planning, code generation, debugging, and documentation. The application was customized, tested, integrated, and deployed by me.
AI tools used:
- ChatGPT
- Gemini
- Hugging Face Transformers
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Hugging Face for amazing AI models
- Streamlit for the beautiful framework
- Salesforce for BLIP model
- The open-source community
Jeeva L
🎓 BCA Graduate
📧 Email: jeevalawrance2004@gmail.com
💼 LinkedIn: https://linkedin.com/in/jeeva-l-5bb2a4387