Topics

#ai #captions #cli #cloud #gemini #hashtags #instagram #llama #local #media #network #ollama #organize #photos #smart #social #terminal #tool #vision

Language breakdown

No language data available.

▸ Files click to expand

README

📸 AI Instagram Organizer

An AI-powered tool that automatically organizes your photos into Instagram-ready posts with smart captions, optimized hashtags, and multi-platform content generation.

✨ Features

🤖 AI-Powered Analysis

Supports Llama (cloud, default), Ollama (local), and Gemini (cloud) AI providers
Analyzes photos for Instagram worthiness and quality scoring
Generates engaging captions with photo-specific references
Smart hashtag generation and optimization
Advanced computer vision quality analysis (optional)
Instagram engagement prediction modeling

📅 Smart Organization

Chronological post creation based on photo dates
Highlights posts from remaining quality photos
Configurable post sizes (default: 10 photos per post)
Duplicate photo detection and removal
Semantic context analysis for content diversity

🎨 Advanced Features (Optional)

Auto-enhancement (brightness, contrast, saturation)
Multiple format generation (square, story, reel)
HEIC/HEIF to JPEG conversion
Multi-platform content (Instagram, TikTok, Twitter, LinkedIn)
Analytics and insights with visual charts
Smart scheduling recommendations

🏷️ Hashtag Intelligence

Competition-based hashtag categorization
Trending hashtag integration
Location-based hashtag generation
Strategic mixing for optimal reach

🌐 Multi-Platform Content

Instagram feed posts and stories
TikTok/Reels video scripts
Twitter thread generation
LinkedIn professional posts

⏰ Smart Scheduling

Optimal posting time recommendations
Engagement-based scheduling
Customizable posting intervals

🚀 Quick Start

Prerequisites

Install Python dependencies:

pip install pillow imagehash pillow-heif requests

Option 1: Llama API (Default - Recommended)

Get Llama API Key: Sign up at Llama API and get your API key

Quick Setup:

# Run setup script (new users) python utils/setup_llama.py

# Or set environment variable manually export LLAMAAPIKEY="your-api-key-here"

Run with Llama:

# Quick test python aiinstagramorganizer.py --dev-mode --limit 5

# Full run python aiinstagramorganizer.py --source "/path/to/photos"

Option 2: Gemini API (Alternative Cloud Option)

Get Gemini API Key: Go to Google AI Studio

Run with Gemini:

# Quick test python aiinstagramorganizer.py --ai-provider gemini --gemini-key YOURAPIKEY --dev-mode --limit 5

# Full run python aiinstagramorganizer.py --ai-provider gemini --gemini-key YOURAPIKEY --source "/path/to/photos"

Option 3: Ollama (Local AI)

Setup Ollama:

# Install Ollama brew install ollama # macOS # Start service ollama serve

# Pull vision model ollama pull gemma3:4b

Run with Ollama:

python aiinstagramorganizer.py --ai-provider ollama --source "/path/to/photos"

📋 Command Line Options

# Basic usage with Llama (default)
python aiinstagramorganizer.py --source "/path/to/photos"
Basic usage with Gemini
python aiinstagramorganizer.py --ai-provider gemini --gemini-key YOUR_KEY
Development mode (test with fewer photos)
python aiinstagramorganizer.py --dev-mode --limit 10
Simple mode (core features only)
python aiinstagramorganizer.py --simple-mode
Custom settings
python aiinstagramorganizer.py \
  --source "/path/to/photos" \
  --ai-provider llama \
  --llama-key YOUR_KEY \
  --post-size 8 \
  --similarity 5

Available Arguments

| Argument | Description | Default | |----------|-------------|---------| | --source, -s | Source folder path | From config | | --ai-provider | AI provider (llama/ollama/gemini) | llama | | --llama-key | Llama API key | None | | --gemini-key | Gemini API key | None | | --dev-mode, -d | Process fewer photos for testing | False | | --limit, -l | Photo limit in dev mode | 100 | | --post-size, -p | Photos per post | 10 | | --similarity | Similarity threshold (0-10) | 3 | | --simple-mode | Disable advanced features | False | | --config, -c | Config file path | config.json |

⚙️ Configuration

Config File (config.json)

{
  "source_folder": "/path/to/your/photos",
  "ai_provider": "llama",
  "processing": {
    "post_size": 10,
    "process_all": false,
    "devmodelimit": 20,
    "similarity_threshold": 3
  },
  "llama": {
    "apikey": "YOURLLAMAAPIKEY_HERE",
    "model": "Llama-4-Maverick-17B-128E-Instruct-FP8",
    "api_url": "https://api.llama.com/v1/chat/completions"
  },
  "gemini": {
    "apikey": "YOURGEMINIAPIKEY_HERE"
  },
  "ollama": {
    "api_url": "http://localhost:11434/api/generate",
    "model": "gemma3:4b"
  },
  "features": {
    "enable_enhancement": true,
    "enable_analytics": true,
    "enable_scheduling": true,
    "enablemultiplatform": true,
    "enablehashtagoptimization": true
  }
}

📁 Output Structure

Simple Mode

instagramposts[timestamp]/
└── Chronological_Posts/
    ├── 2024-01-15Post1/
    │   ├── 01_photo1.jpg
    │   ├── 02_photo2.jpg
    │   └── captions.txt
    └── 2024-01-16Post2/

Advanced Mode (with optional features)

instagramposts[timestamp]/
├── Chronological_Posts/
├── Highlights_Posts/
├── analytics/
│   ├── report.txt
│   └── charts.png
└── posting_schedule.json

🛠️ Helper Scripts

Setup and Migration

setup_llama.py - Interactive setup for new Llama API users
migratetollama.py - Migrate existing Gemini/Ollama setup to Llama
testllamaapi.py - Test Llama API integration with sample image

Usage Examples

# First-time setup
python utils/setup_llama.py
Migrate from Gemini/Ollama
python utils/migratetollama.py
Test API connection
python tests/testllamaapi.py

🎯 Use Cases

First Time Testing

python aiinstagramorganizer.py --ai-provider gemini --gemini-key YOUR_KEY --dev-mode --limit 5

Travel Photos

python aiinstagramorganizer.py --source "~/Photos/Trip" --post-size 12

Quick Processing

python aiinstagramorganizer.py --simple-mode --dev-mode --limit 50

🔧 Advanced Setup

For Full Features (Optional)

# Install additional dependencies for advanced features
pip install matplotlib seaborn opencv-python
Run with all features enabled
python aiinstagramorganizer.py --config config.json

Custom AI Models

Edit config.json:

{
  "ollama": {
    "model": "llava:13b"
  },
  "gemini": {
    "model": "gemini-1.5-pro"
  }
}

🐛 Troubleshooting

Gemini Issues

"API key required": Add --gemini-key YOUR_KEY
"Invalid API key": Check your key at Google AI Studio

Ollama Issues

"Connection refused": Run ollama serve first
"Model not found": Run ollama pull gemma3:4b

General Issues

"No Instagram-worthy photos": The AI is being selective - this is normal
"Source folder not found": Check your path is correct
Memory issues: Use --dev-mode --limit 10

💡 Tips

Start with Gemini: Easier setup, faster results
Test small first: Always use --dev-mode --limit 5 initially
Use simple mode: Add --simple-mode if you don't need advanced features
Check your photos: Make sure they're actual photos, not screenshots

📦 Dependencies

Required

pip install pillow imagehash pillow-heif requests

Optional (for advanced features)

pip install matplotlib seaborn opencv-python

🔄 Switching Between AI Providers

# Use Gemini (cloud-based, fast)
python aiinstagramorganizer.py --ai-provider gemini --gemini-key YOUR_KEY
Use Ollama (local, private)
python aiinstagramorganizer.py --ai-provider ollama