# SocialMagic 🪄
A powerful Python library for social media content enhancement with three magical features:
- **Text Sentiment → Emoji** - Automatically add emojis based on text sentiment
- **Fake Image Detection** - Detect similar/manipulated images using perceptual hashing
- **Micro Story Generator** - Generate engaging short stories for any theme
## 🚀 Installation
```bash
pip install socialmagic
```
Or install from source:
```bash
git clone https://github.com/socialmagic/socialmagic.git
cd socialmagic
pip install -r requirements.txt
pip install .
```
## 📖 Usage
### 1. Text Sentiment to Emoji (emojify)
Analyze text sentiment and automatically append appropriate emojis:
```python
from socialmagic import emojify
# Basic usage
result = emojify("I love this product!")
print(result) # "I love this product! 😍"
result = emojify("This is terrible")
print(result) # "This is terrible 😢"
result = emojify("It's okay, nothing special")
print(result) # "It's okay, nothing special 😐"
# Custom emoji mapping
custom_emojis = {
'positive': ['🎉', '🌟', '✨'],
'negative': ['💔', '😞', '🌧️'],
'neutral': ['🤔', '😶', '📝']
}
result = emojify("Amazing work!", emoji_map=custom_emojis)
print(result) # "Amazing work! 🎉"
```
### 2. Fake/Manipulated Image Detection (fakebuster)
Detect similar images using perceptual hashing to identify potential fakes:
```python
from socialmagic import is_similar
# Compare two images with default 90% threshold
is_fake = is_similar("original.jpg", "suspicious.jpg")
print(f"Images are similar: {is_fake}")
# Custom threshold (0-100)
is_fake = is_similar("image1.jpg", "image2.jpg", threshold=85)
print(f"Images are 85%+ similar: {is_fake}")
# Get exact similarity percentage
from socialmagic.fakebuster import get_similarity_percentage
similarity = get_similarity_percentage("img1.jpg", "img2.jpg")
print(f"Similarity: {similarity}%")
```
### 3. Micro Story Generator (storygen)
Generate engaging short stories for any theme and protagonist:
```python
from socialmagic import generate_story
# Generate stories for different themes
thriller = generate_story("thriller", "Alice")
print(f"Thriller: {thriller}")
comedy = generate_story("comedy", "Bob")
print(f"Comedy: {comedy}")
inspiration = generate_story("inspirational", "Maria")
print(f"Inspirational: {inspiration}")
scifi = generate_story("sci-fi", "Captain Nova")
print(f"Sci-Fi: {scifi}")
# Unknown themes use generic templates
mystery = generate_story("mystery", "Detective Holmes")
print(f"Mystery: {mystery}")
# Get available themes
from socialmagic.storygen import get_available_themes
themes = get_available_themes()
print(f"Available themes: {themes}")
# Add custom templates
from socialmagic.storygen import add_custom_template
add_custom_template("horror", "As {protagonist} entered the abandoned house, the door slammed shut behind them...")
horror_story = generate_story("horror", "Sarah")
print(f"Horror: {horror_story}")
```
## 🎯 Features
### Emojify Module
- **Sentiment Analysis**: Uses VADER sentiment analysis for accurate emotion detection
- **Smart Emoji Selection**: Randomly selects from appropriate emoji sets
- **Custom Emoji Maps**: Define your own emoji collections for different sentiments
- **Multiple Languages**: Works with any text that VADER can analyze
### FakeBuster Module
- **Perceptual Hashing**: Uses advanced image hashing for robust comparison
- **Adjustable Threshold**: Configure sensitivity from 0-100%
- **Error Handling**: Graceful handling of missing files and corrupted images
- **Batch Processing**: Compare multiple images efficiently
### StoryGen Module
- **Multiple Themes**: Built-in support for thriller, comedy, inspirational, and sci-fi
- **Flexible Templates**: Easy to add custom story templates
- **Random Selection**: Ensures variety in generated content
- **Generic Fallback**: Handles unknown themes gracefully
## 🧪 Testing
Run the test suite to verify everything works:
```bash
# Run all tests
python -m pytest tests/
# Run specific module tests
python tests/test_emojify.py
python tests/test_fakebuster.py
python tests/test_storygen.py
```
## 📋 Requirements
- Python 3.7+
- vaderSentiment
- emoji
- Pillow
- imagehash
## 🔧 Development
1. Clone the repository
2. Install dependencies: `pip install -r requirements.txt`
3. Run tests: `python -m pytest tests/`
4. Make your changes
5. Run tests again to ensure everything works
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
## 📞 Support
If you encounter any issues or have questions, please file an issue on the GitHub repository.
## 🌟 Examples
### Complete Social Media Enhancement
```python
from socialmagic import emojify, is_similar, generate_story
# Enhance a social media post
post_text = "Just finished my morning workout"
enhanced_post = emojify(post_text)
print(f"Enhanced post: {enhanced_post}")
# Check if an image is potentially fake
if is_similar("user_upload.jpg", "known_fake.jpg", threshold=90):
print("⚠️ Potential fake image detected!")
# Generate engaging content
story = generate_story("inspirational", "fitness enthusiast")
print(f"Motivational story: {story}")
```
### Batch Image Analysis
```python
from socialmagic.fakebuster import is_similar, get_similarity_percentage
import os
def analyze_image_folder(folder_path, reference_image):
results = []
for filename in os.listdir(folder_path):
if filename.lower().endswith(('.jpg', '.jpeg', '.png')):
image_path = os.path.join(folder_path, filename)
similarity = get_similarity_percentage(reference_image, image_path)
results.append((filename, similarity))
return sorted(results, key=lambda x: x[1], reverse=True)
# Find similar images
similar_images = analyze_image_folder("./images", "reference.jpg")
for filename, similarity in similar_images[:5]:
print(f"{filename}: {similarity}% similar")
```
---
Made with ❤️ by the SocialMagic Team
Raw data
{
"_id": null,
"home_page": "https://github.com/socialmagic/social-magic",
"name": "social-magic",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "sentiment analysis, image detection, story generation, social media",
"author": "SocialMagic Team",
"author_email": "SocialMagic Team <contact@socialmagic.dev>",
"download_url": "https://files.pythonhosted.org/packages/49/79/c7139a17292cd15673b5e2fff76d9d843fb38600aa1168ba5ad6f085a8ae/social_magic-0.1.0.tar.gz",
"platform": null,
"description": "# SocialMagic \ud83e\ude84\r\n\r\nA powerful Python library for social media content enhancement with three magical features:\r\n\r\n- **Text Sentiment \u2192 Emoji** - Automatically add emojis based on text sentiment\r\n- **Fake Image Detection** - Detect similar/manipulated images using perceptual hashing \r\n- **Micro Story Generator** - Generate engaging short stories for any theme\r\n\r\n## \ud83d\ude80 Installation\r\n\r\n```bash\r\npip install socialmagic\r\n```\r\n\r\nOr install from source:\r\n\r\n```bash\r\ngit clone https://github.com/socialmagic/socialmagic.git\r\ncd socialmagic\r\npip install -r requirements.txt\r\npip install .\r\n```\r\n\r\n## \ud83d\udcd6 Usage\r\n\r\n### 1. Text Sentiment to Emoji (emojify)\r\n\r\nAnalyze text sentiment and automatically append appropriate emojis:\r\n\r\n```python\r\nfrom socialmagic import emojify\r\n\r\n# Basic usage\r\nresult = emojify(\"I love this product!\")\r\nprint(result) # \"I love this product! \ud83d\ude0d\"\r\n\r\nresult = emojify(\"This is terrible\")\r\nprint(result) # \"This is terrible \ud83d\ude22\"\r\n\r\nresult = emojify(\"It's okay, nothing special\")\r\nprint(result) # \"It's okay, nothing special \ud83d\ude10\"\r\n\r\n# Custom emoji mapping\r\ncustom_emojis = {\r\n 'positive': ['\ud83c\udf89', '\ud83c\udf1f', '\u2728'],\r\n 'negative': ['\ud83d\udc94', '\ud83d\ude1e', '\ud83c\udf27\ufe0f'],\r\n 'neutral': ['\ud83e\udd14', '\ud83d\ude36', '\ud83d\udcdd']\r\n}\r\n\r\nresult = emojify(\"Amazing work!\", emoji_map=custom_emojis)\r\nprint(result) # \"Amazing work! \ud83c\udf89\"\r\n```\r\n\r\n### 2. Fake/Manipulated Image Detection (fakebuster)\r\n\r\nDetect similar images using perceptual hashing to identify potential fakes:\r\n\r\n```python\r\nfrom socialmagic import is_similar\r\n\r\n# Compare two images with default 90% threshold\r\nis_fake = is_similar(\"original.jpg\", \"suspicious.jpg\")\r\nprint(f\"Images are similar: {is_fake}\")\r\n\r\n# Custom threshold (0-100)\r\nis_fake = is_similar(\"image1.jpg\", \"image2.jpg\", threshold=85)\r\nprint(f\"Images are 85%+ similar: {is_fake}\")\r\n\r\n# Get exact similarity percentage\r\nfrom socialmagic.fakebuster import get_similarity_percentage\r\nsimilarity = get_similarity_percentage(\"img1.jpg\", \"img2.jpg\")\r\nprint(f\"Similarity: {similarity}%\")\r\n```\r\n\r\n### 3. Micro Story Generator (storygen)\r\n\r\nGenerate engaging short stories for any theme and protagonist:\r\n\r\n```python\r\nfrom socialmagic import generate_story\r\n\r\n# Generate stories for different themes\r\nthriller = generate_story(\"thriller\", \"Alice\")\r\nprint(f\"Thriller: {thriller}\")\r\n\r\ncomedy = generate_story(\"comedy\", \"Bob\")\r\nprint(f\"Comedy: {comedy}\")\r\n\r\ninspiration = generate_story(\"inspirational\", \"Maria\")\r\nprint(f\"Inspirational: {inspiration}\")\r\n\r\nscifi = generate_story(\"sci-fi\", \"Captain Nova\")\r\nprint(f\"Sci-Fi: {scifi}\")\r\n\r\n# Unknown themes use generic templates\r\nmystery = generate_story(\"mystery\", \"Detective Holmes\")\r\nprint(f\"Mystery: {mystery}\")\r\n\r\n# Get available themes\r\nfrom socialmagic.storygen import get_available_themes\r\nthemes = get_available_themes()\r\nprint(f\"Available themes: {themes}\")\r\n\r\n# Add custom templates\r\nfrom socialmagic.storygen import add_custom_template\r\nadd_custom_template(\"horror\", \"As {protagonist} entered the abandoned house, the door slammed shut behind them...\")\r\n\r\nhorror_story = generate_story(\"horror\", \"Sarah\")\r\nprint(f\"Horror: {horror_story}\")\r\n```\r\n\r\n## \ud83c\udfaf Features\r\n\r\n### Emojify Module\r\n- **Sentiment Analysis**: Uses VADER sentiment analysis for accurate emotion detection\r\n- **Smart Emoji Selection**: Randomly selects from appropriate emoji sets\r\n- **Custom Emoji Maps**: Define your own emoji collections for different sentiments\r\n- **Multiple Languages**: Works with any text that VADER can analyze\r\n\r\n### FakeBuster Module \r\n- **Perceptual Hashing**: Uses advanced image hashing for robust comparison\r\n- **Adjustable Threshold**: Configure sensitivity from 0-100%\r\n- **Error Handling**: Graceful handling of missing files and corrupted images\r\n- **Batch Processing**: Compare multiple images efficiently\r\n\r\n### StoryGen Module\r\n- **Multiple Themes**: Built-in support for thriller, comedy, inspirational, and sci-fi\r\n- **Flexible Templates**: Easy to add custom story templates\r\n- **Random Selection**: Ensures variety in generated content\r\n- **Generic Fallback**: Handles unknown themes gracefully\r\n\r\n## \ud83e\uddea Testing\r\n\r\nRun the test suite to verify everything works:\r\n\r\n```bash\r\n# Run all tests\r\npython -m pytest tests/\r\n\r\n# Run specific module tests\r\npython tests/test_emojify.py\r\npython tests/test_fakebuster.py\r\npython tests/test_storygen.py\r\n```\r\n\r\n## \ud83d\udccb Requirements\r\n\r\n- Python 3.7+\r\n- vaderSentiment\r\n- emoji \r\n- Pillow\r\n- imagehash\r\n\r\n## \ud83d\udd27 Development\r\n\r\n1. Clone the repository\r\n2. Install dependencies: `pip install -r requirements.txt`\r\n3. Run tests: `python -m pytest tests/`\r\n4. Make your changes\r\n5. Run tests again to ensure everything works\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\r\n\r\n## \ud83d\udcde Support\r\n\r\nIf you encounter any issues or have questions, please file an issue on the GitHub repository.\r\n\r\n## \ud83c\udf1f Examples\r\n\r\n### Complete Social Media Enhancement\r\n\r\n```python\r\nfrom socialmagic import emojify, is_similar, generate_story\r\n\r\n# Enhance a social media post\r\npost_text = \"Just finished my morning workout\"\r\nenhanced_post = emojify(post_text)\r\nprint(f\"Enhanced post: {enhanced_post}\")\r\n\r\n# Check if an image is potentially fake\r\nif is_similar(\"user_upload.jpg\", \"known_fake.jpg\", threshold=90):\r\n print(\"\u26a0\ufe0f Potential fake image detected!\")\r\n\r\n# Generate engaging content\r\nstory = generate_story(\"inspirational\", \"fitness enthusiast\")\r\nprint(f\"Motivational story: {story}\")\r\n```\r\n\r\n### Batch Image Analysis\r\n\r\n```python\r\nfrom socialmagic.fakebuster import is_similar, get_similarity_percentage\r\nimport os\r\n\r\ndef analyze_image_folder(folder_path, reference_image):\r\n results = []\r\n for filename in os.listdir(folder_path):\r\n if filename.lower().endswith(('.jpg', '.jpeg', '.png')):\r\n image_path = os.path.join(folder_path, filename)\r\n similarity = get_similarity_percentage(reference_image, image_path)\r\n results.append((filename, similarity))\r\n \r\n return sorted(results, key=lambda x: x[1], reverse=True)\r\n\r\n# Find similar images\r\nsimilar_images = analyze_image_folder(\"./images\", \"reference.jpg\")\r\nfor filename, similarity in similar_images[:5]:\r\n print(f\"{filename}: {similarity}% similar\")\r\n```\r\n\r\n---\r\n\r\nMade with \u2764\ufe0f by the SocialMagic Team\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python library for social media content enhancement",
"version": "0.1.0",
"project_urls": {
"Bug Reports": "https://github.com/socialmagic/social-magic/issues",
"Documentation": "https://github.com/socialmagic/social-magic#readme",
"Homepage": "https://github.com/socialmagic/social-magic",
"Source": "https://github.com/socialmagic/social-magic"
},
"split_keywords": [
"sentiment analysis",
" image detection",
" story generation",
" social media"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d9aa76c389182e426863967f440d3df8b3119de1f0f85e0f9ed81859e22c1060",
"md5": "e807182f98d2f206da682217c5bc782a",
"sha256": "2d12931b8868c47567f6fd8007eaad78cd4b75486adfc8e90cc0e64acb66ee13"
},
"downloads": -1,
"filename": "social_magic-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e807182f98d2f206da682217c5bc782a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 9995,
"upload_time": "2025-08-11T04:27:53",
"upload_time_iso_8601": "2025-08-11T04:27:53.569805Z",
"url": "https://files.pythonhosted.org/packages/d9/aa/76c389182e426863967f440d3df8b3119de1f0f85e0f9ed81859e22c1060/social_magic-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4979c7139a17292cd15673b5e2fff76d9d843fb38600aa1168ba5ad6f085a8ae",
"md5": "dd7124b26989f9acced65e0cfb282739",
"sha256": "2f090af031cc4b03adde1a05780fdc77a54566d043cff3cfa30b231502bd3cdf"
},
"downloads": -1,
"filename": "social_magic-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "dd7124b26989f9acced65e0cfb282739",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 12491,
"upload_time": "2025-08-11T04:27:54",
"upload_time_iso_8601": "2025-08-11T04:27:54.695522Z",
"url": "https://files.pythonhosted.org/packages/49/79/c7139a17292cd15673b5e2fff76d9d843fb38600aa1168ba5ad6f085a8ae/social_magic-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-11 04:27:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "socialmagic",
"github_project": "social-magic",
"github_not_found": true,
"lcname": "social-magic"
}
JSON
