Automated painting metadata generation system for managing artwork Photo and metadata files. This program is set up to process new paintings on the users computer, then it will upload them to the artist website and to social media. Eventually it will do all the basic art management functions for an artist, including sending out letters to galleries, interior designers etc. It is being coded by Claude AI with guidance from myself. I am trying to do ALL the coding with the AI and make architectural and UX decisions only, as an experiment in using this technology. When finished it will be an AI agent for general use by artists everywhere, and my stepping stone to a new career. Enjoy!
From here on this was all generated by Claude, given careful prompting and decision making:
Theo Van Gogh is an art management automation system built for working artists. It handles the repetitive tasks of cataloging, organizing, and preparing artwork for online publication. The system uses Claude's vision API to analyze paintings and generate professional gallery-quality titles and descriptions, then organizes everything into a structured metadata system ready for upload to websites and social media platforms.
- AI-Powered Analysis — Claude vision API analyzes paintings and generates 10 diverse title options per work (traditional + quantum/mysterious/esoteric themes)
- Gallery Descriptions — Automatically writes collector-focused descriptions covering visual analysis, emotional impact, and technical notes
- Smart File Management — Pairs high-resolution and social media versions, renames files to sanitized titles
- Metadata System — Generates structured JSON and human-readable text files for each painting
- Collection Organization — Moves processed paintings into collection-based folder hierarchies
- Upload Tracking — JSON-based tracker monitors which paintings have been uploaded to which platforms
- Skeleton Metadata Generator — Batch-creates stub metadata files from existing folder structure
- Interactive Metadata Editor — Browse and fill in missing metadata fields with list-based selections
- Instagram Folder Sync — Reorganizes social media photo folders to match the primary collection structure
- Admin Mode — 10 interactive configuration options for managing the entire system
- FASO Website Automation — Playwright-based upload to Fine Art Studio Online with Cloudflare handling
We are going to build interfaces to other platforms for artists to display work
- Mastadon works
Other sites are coming once I have developer accounts
- Instagram, Bluesky, Facebook, Threads, Linked In, Tiktok, Pixelfed, Cara automation
These features are going to be a seperate AI agent.
- Email campaigns to galleries and interior designers
- Full AI agent for general artist use
| Component | Technology |
|---|---|
| Language | Python 3.12 |
| CLI Framework | Click |
| Terminal UI | Rich |
| AI | Anthropic Claude API (vision + text) |
| Browser Automation | Playwright |
| Image Processing | Pillow |
| Environment Config | python-dotenv |
| Testing | pytest with coverage |
| CI/CD | GitHub Actions |
git clone https://github.com/your-username/theo-van-gogh.git
cd theo-van-goghpython3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activatepip install -r requirements.txt
pip install -r requirements-dev.txt # For development/testingcp .env.example .envEdit .env with your settings:
ANTHROPIC_API_KEY=your_api_key_here
PAINTINGS_BIG_PATH=/home/username/ai-workzone/my-paintings-big
PAINTINGS_INSTAGRAM_PATH=/home/username/ai-workzone/my-paintings-instagram
METADATA_OUTPUT_PATH=/home/username/ai-workzone/processed-metadatapython main.py verify-configThe system expects this layout on disk:
~/ai-workzone/
├── my-paintings-big/ # High-resolution originals
│ ├── oil-paintings/
│ ├── landscapes-and-cityscapes-real-places/
│ ├── sea-beasties-from-titan/
│ └── ... # One folder per collection
├── my-paintings-instagram/ # Social media versions (<1MB)
│ ├── oil-paintings/ # Mirrors big folder structure
│ ├── landscapes-and-cityscapes-real-places/
│ └── ...
└── processed-metadata/ # Generated metadata output
├── oil-paintings/
│ ├── dutch_bridge.json
│ └── dutch_bridge.txt
└── ...
python main.py process # Process new paintings with AI metadata generation
python main.py admin # Open interactive admin mode
python main.py verify-config # Check configuration and paths
python main.py list-categories # Show all painting categories with file counts
python main.py test-faso-login # Test FASO website login (Phase 2)When you run python main.py process, the system walks you through each painting:
- Displays file information (big + instagram versions)
- Generates 10 AI title options and displays them
- User selects an AI title or enters custom title
- User optionally enters notes about the painting (multi-line)
- Prompts for substrate, medium, subject, style, collection
- Prompts for dimensions, price, and creation date
- Generates a professional gallery description via Claude (incorporating user notes)
- Renames files to the sanitized title
- Saves metadata as JSON and human-readable text
- Moves files into the correct collection folder
- Updates the upload tracker
Run python main.py admin to access 10 management options:
| Option | Description |
|---|---|
| 1 | Edit Anthropic API Key |
| 2 | Edit File Paths |
| 3 | Edit Dimension Unit (cm/in) |
| 4 | Add to Lists (Substrates, Mediums, Subjects, Styles, Collections) |
| 5 | Manage Social Media Platforms |
| 6 | Sync Collection Folders |
| 7 | View Current Settings |
| 8 | Generate Skeleton Metadata |
| 9 | Edit Metadata |
| 10 | Sync Instagram Folders |
Option 8 — Generate Skeleton Metadata: Scans each subfolder in my-paintings-big and creates stub metadata JSON files using the filename as the title. Photos with the same base name but different trailing numbers (e.g., Mountain-View-1.jpg, Mountain-View-2.jpg) are grouped into a single metadata file.
Option 9 — Edit Metadata: Browse processed-metadata subfolders, select individual files or edit all sequentially. Each field shows its current value — press Enter to keep or type a new value. List fields (substrate, medium, etc.) show numbered options from settings.
Option 10 — Sync Instagram Folders: Flattens all instagram photos to the root directory, then reorganizes them to match the big folder structure by matching filenames. Reports unmatched files on both sides.
Each painting produces a JSON file:
{
"filename_base": "dutch_bridge",
"category": "landscapes-and-cityscapes-real-places",
"files": {
"big": "/path/to/my-paintings-big/landscapes/dutch_bridge.jpg",
"instagram": "/path/to/my-paintings-instagram/landscapes/dutch_bridge.jpg"
},
"title": {
"selected": "Dutch Bridge",
"all_options": [
"Morning Light on the Amstel",
"Dutch Bridge",
"Canal Crossing at Dawn",
"Urban Reflections",
"Amsterdam in Watercolor"
]
},
"description": "A luminous watercolor capturing the interplay of light...",
"dimensions": {
"width": 50.0,
"height": 70.0,
"depth": 1.0,
"unit": "cm",
"formatted": "50.0cm x 70.0cm x 1.0cm"
},
"substrate": "Canvas",
"medium": "Acrylic",
"subject": "Cityscape",
"style": "Impressionism",
"collection": "Landscapes and Cityscapes, Real Places",
"price_eur": 150.0,
"creation_date": "2025-07-20",
"processed_date": "2026-02-10T15:42:29.997257",
"analyzed_from": "instagram"
}theo-van-gogh/
├── main.py # CLI entry point (Click commands)
├── config/
│ ├── settings.py # All paths, lists, and constants
│ └── prompts.py # AI prompt templates
├── src/
│ ├── image_analyzer.py # Claude vision API integration
│ ├── file_manager.py # File pairing, renaming, EXIF
│ ├── metadata_manager.py # JSON/text metadata creation
│ ├── cli_interface.py # Rich terminal UI prompts
│ ├── file_organizer.py # Move files to collection folders
│ ├── upload_tracker.py # Multi-platform upload tracking
│ ├── admin_mode.py # Interactive admin menu (10 options)
│ ├── collection_folder_manager.py # Collection folder sync
│ ├── skeleton_metadata_generator.py # Batch stub metadata creation
│ ├── metadata_editor.py # Interactive metadata editor
│ ├── instagram_folder_sync.py # Instagram folder reorganization
│ └── faso_client.py # FASO website automation (Phase 2)
├── tests/
│ ├── conftest.py # Shared fixtures
│ ├── test_file_manager.py
│ ├── test_file_organizer.py
│ ├── test_upload_tracker.py
│ ├── test_cli_interface.py
│ ├── test_skeleton_metadata_generator.py
│ ├── test_metadata_editor.py
│ └── test_instagram_folder_sync.py
├── requirements.txt # Runtime dependencies
├── requirements-dev.txt # Development dependencies
├── pytest.ini # Test configuration
├── .env.example # Environment template
└── .github/workflows/ci.yml # CI pipeline
# Run all tests
python -m pytest
# Run a specific test file
python -m pytest tests/test_skeleton_metadata_generator.py -v
# Run tests without coverage
python -m pytest --no-covCurrent status: 85 tests, 45% coverage, all passing.
Use admin mode option 4 to add new collections, substrates, mediums, subjects, or styles. Then run option 6 to create the matching folders.
Edit config/prompts.py to adjust title generation style, description format, tone, and perspective.
Use admin mode option 5 to register new platforms (Instagram, Mastodon, etc.) in the upload tracker.
| Problem | Solution |
|---|---|
| "Anthropic API key: NOT configured" | Create .env from .env.example and add your API key |
| "No categories found" | Check paths in .env, run python main.py verify-config |
| "Module not found" errors | Activate venv: source venv/bin/activate, reinstall deps |
| Coverage threshold failure | Current threshold is 40%, run pytest to check |
Private project for Christopher Rehm's art management workflow. You may use this software for personal use, modify it for personal use,share with others, but you may not sell the code in this project. https://creativecommons.org/licenses/by-nc-sa/4.0/
- Anthropic API: https://docs.anthropic.com/
- Rich library: https://rich.readthedocs.io/
- Click CLI: https://click.palletsprojects.com/
- Playwright: https://playwright.dev/python/