Blackwork Mastermind

A web application for managing, organizing, and analyzing image collections. This tool helps maintain a well-organized image library with features like duplicate detection, AI-powered tagging, and detailed analytics.

Features

Core Features

• Image Gallery: Browse your image collection with a modern, responsive interface
• Advanced Search: Search images by filename, path, dimensions, and more
• AI Tagging: Automatically generate descriptive tags for your images using AI
• Duplicate Detection: Find and manage duplicate images in your collection
• Analytics: Get insights about your image collection with detailed statistics
• File Management: Download, delete, and organize images directly from the interface
• Multi-Format Support: Supports JPG, PNG, BMP, TIFF, GIF, WebP, and SVG files

Technical Features

• Preview Generation: Automatically creates and optimizes previews for image display
• Metadata Extraction: Captures image dimensions, format, and other technical details
• Database Management: SQLite database for efficient image metadata storage
• Responsive Design: Modern UI built with Tailwind CSS
• Real-time Processing: Background tasks for scanning and tagging images

Prerequisites

• uv - Fast Python package installer and resolver (manages Python automatically)
• just - Command runner
• cairo (for SVG processing)
• For AI features (optional, choose one):
  • LM Studio - Run AI models locally (free, no API costs)
  • OpenAI API key - Use OpenAI's cloud API (requires paid account)

Installing Prerequisites

macOS:

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install uv (manages Python automatically)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install just and cairo
brew install just cairo

Linux (Ubuntu/Debian):

# Install uv (manages Python automatically)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install just and cairo
sudo apt install just libcairo2-dev

Installing LM Studio (for local AI)

LM Studio allows you to run AI models locally without any API costs.

1. Download LM Studio from lmstudio.ai
2. Install and launch LM Studio
3. Download a vision-capable model (required for image analysis):
   • Go to the "Discover" tab in LM Studio
   • Search for a vision model like gemma-3-12b or any model with vision capabilities
   • Click download and wait for it to complete
4. Start the local server:
   • Go to the "Local Server" tab (left sidebar)
   • Select your downloaded model
   • Click "Start Server"
   • The server will run at http://localhost:1234 by default

5. Verify the server is running:

   curl http://localhost:1234/v1/models
   

   You should see a JSON response listing available models.

Installation

1. Clone the repository:

git clone git@github.com:JCPetrelli/blackwork_mastermind.git
cd blackwork_mastermind

2. Copy the environment template and configure:

cp env.example .env

3. Edit .env and set your configuration:

# Set your Dropbox paths if using Dropbox integration
DROPBOX_BASE_PATH=/path/to/your/dropbox
DROPBOX_PRODUCTS_PATH=/path/to/your/dropbox/products

# For OpenAI API (optional - only if not using LM Studio)
OPENAI_API_KEY=your_openai_api_key_here

# For LM Studio (optional - defaults to localhost:1234)
LM_STUDIO_BASE_URL=http://localhost:1234/v1

4. Install dependencies:

just install

Usage

Running the Application

just run

Or simply:

just

The application will start at http://localhost:5003

Running Tests

just test

Available Commands

Configuration

All configuration is done via environment variables in the .env file. See env.example for all available options:

AI Configuration

The application supports two AI providers for image analysis features (tagging, text extraction, description generation, etc.):

Option 1: LM Studio (Local AI - Recommended)

LM Studio runs AI models locally on your machine. This is free and doesn't require an API key.

Setup: 1. Install LM Studio (see Installing LM Studio above) 2. Download a vision-capable model (e.g., gemma-3-12b, llava, or similar) 3. Start the LM Studio server 4. In the application, go to Settings and select "Local LLM" 5. Set the model path to match your loaded model (e.g., google/gemma-3-12b)

Requirements: - A vision-capable model is required for image analysis features - Recommended: 16GB+ RAM for 12B parameter models, 8GB+ for smaller models - GPU acceleration significantly improves performance (optional but recommended)

Option 2: OpenAI API (Cloud AI)

Use OpenAI's cloud-hosted models. Requires an API key and incurs usage costs.

Setup: 1. Get an API key from platform.openai.com 2. In the application, go to Settings and select "OpenAI API" 3. Enter your API key 4. Select your preferred model (GPT-4o recommended for vision tasks)

Switching Providers

You can switch between providers at any time via the Settings page in the web UI. The application will use whichever provider is currently selected.

AI Features

The following features use the configured AI provider:

Project Structure

blackwork_mastermind/
├── app.py              # Main application file
├── database.py         # Database management
├── scanner.py          # Image scanning functionality
├── tag_images.py       # AI tagging implementation
├── check_duplicates.py # Duplicate detection
├── ai_utils.py         # AI/ML utilities
├── config.py           # Configuration management
├── routes/             # API and web routes
├── templates/          # HTML templates
├── static/             # Static assets
├── utils/              # Utility modules
├── tests/              # Test suite
├── uploads/            # Temporary upload directory
├── previews/           # Original image previews
└── previews_optimized/ # Optimized thumbnails

Database Schema

Images Table

• id: Unique identifier
• filename: Image filename
• full_path: Complete file path
• width: Image width
• height: Image height
• extension: File extension
• file_size: File size
• last_modified: Last modification timestamp
• preview_name: Preview filename
• ai_tags: AI-generated tags
• path_tags: Path-based tags
• created_at: Record creation timestamp

Duplicates Table

• id: Unique identifier
• original_id: Reference to original image
• duplicate_id: Reference to duplicate image
• similarity_score: Similarity percentage
• created_at: Record creation timestamp

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request