Upload folder using huggingface_hub

.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+.venv/
+
+# Environment variables
+.env
+
+# Google Drive authentication files
+token.pickle
+google_token_base64.txt
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Output files
+!business_card_exports/.gitkeep
+*.xlsx
+*.xls
+
+# Business card images (keep folder structure but ignore images)
+business_cards/*.jpg
+business_cards/*.jpeg
+business_cards/*.png
+business_cards/*.gif
+business_cards/*.bmp
+business_cards/*.webp
+# Keep the .gitkeep file
+!business_cards/.gitkeep
+
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+business_card_extractor.log 
+
+convert_token_to_base64.py

QUICK_START.md

@@ -0,0 +1,53 @@
+# Quick Start Guide
+
+## 1. Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+## 2. Run the Application
+
+```bash
+python app.py
+```
+
+## 3. Use the Web Interface
+
+1. Open your browser to http://localhost:7860
+2. Click "Upload Business Cards" and select one or more business card images
+3. Choose your AI model: Flash (faster) or Pro (more accurate)  
+4. Choose whether to save images (enabled by default)
+5. Click "Process Business Cards"
+6. Download both generated Excel files:
+   - 📁 **Current Run**: Just the cards you processed
+   - 📊 **Total Database**: All cards ever processed
+
+## What Gets Extracted?
+
+- **Names**: Full name, first name, last name
+- **Contact Info**: Multiple emails and phone numbers
+- **Professional Info**: Job title, company, department
+- **Location**: Full address, street, city, state, zip, country
+- **Online**: Website, LinkedIn profile
+- **Other**: Any additional information on the card
+
+## Output Format
+
+- Each business card = 1 row in Excel
+- Two files: Current run + Cumulative database
+- Multiple emails/phones are combined with commas
+- Phone types (mobile/landline) are combined into one column
+- Street and address are combined into one field
+- Filename, processing date, and image path included for reference
+- Images optionally saved to business_cards folder with timestamps
+- Excel files are auto-formatted with proper column widths
+
+## Tips
+
+- Upload multiple cards at once (processed in batches of 5 for efficiency)
+- Supported formats: JPG, PNG, JPEG
+- Higher quality images = better extraction
+- Batch processing reduces API calls and costs
+- Enable image saving to keep a visual record of processed cards
+- Check the preview table before downloading 

README.md

@@ -0,0 +1,112 @@
+---
+title: Business Card Data Extractor
+emoji: 💼
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: "4.44.1"
+app_file: app.py
+pinned: false
+---
+
+# Business Card Data Extractor 💼
+
+An AI-powered tool that extracts structured data from business card images using Google's Gemini AI. Upload business card images and get organized data exported to Excel files with automatic Google Drive storage.
+
+## Features
+
+- **Batch Processing**: Process multiple business cards at once (up to 5 per batch)
+- **AI Model Selection**: Choose between Gemini 2.5 Flash (fast) or Gemini 2.5 Pro (accuracy)
+- **Google Drive Storage**: Automatic upload to organized Drive folders
+- **Excel Export**: Get data in two formats:
+  - Current session results
+  - Cumulative database (appends across sessions)
+- **Smart Data Extraction**: Extracts name, company, title, emails, phones, address, website
+- **Direct Links**: Access files directly through Google Drive URLs
+
+## How to Use
+
+1. **Setup**: Complete the setup process below (one-time)
+2. **Upload Images**: Select up to 5 business card images
+3. **Choose Model**: Select Gemini model (Flash for speed, Pro for accuracy)
+4. **Process**: Click "Extract Business Card Data"
+5. **Access Files**: Download temporary copies or access permanent files via Google Drive links
+
+## Supported Data Fields
+
+- **Name**: Full name from business card
+- **Company**: Company/organization name
+- **Title**: Job title/position
+- **Emails**: Email addresses (comma-separated if multiple)
+- **Phones**: Phone numbers (comma-separated if multiple)
+- **Address**: Full address information
+- **Website**: Company website URL
+- **Processing Info**: Timestamp, model used, filename
+
+## Setup Instructions
+
+### 1. Google Gemini API
+- Get your API key from: https://aistudio.google.com/
+- Set as environment variable: `Gemini_API`
+
+### 2. Google Drive API Setup
+1. **Create Google Cloud Project**:
+   - Go to https://console.cloud.google.com/
+   - Create a new project or select an existing one
+
+2. **Enable Google Drive API**:
+   - In the Google Cloud Console, go to "APIs & Services" > "Library"
+   - Search for "Google Drive API" and enable it
+
+3. **Create OAuth 2.0 Credentials**:
+   - Go to "APIs & Services" > "Credentials"
+   - Click "+ CREATE CREDENTIALS" > "OAuth client ID"
+   - Select "Desktop application"
+   - Download the JSON file
+   - Extract `client_id` and `client_secret` from the JSON
+
+4. **Set Environment Variables**:
+   ```bash
+   GOOGLE_CLIENT_ID=your_client_id_here
+   GOOGLE_CLIENT_SECRET=your_client_secret_here
+   ```
+
+### 3. Local Development Setup
+1. **Install Dependencies**:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+2. **Run Locally First**:
+   ```bash
+   python app.py
+   ```
+   - Complete the OAuth flow in your browser
+   - This creates `token.pickle` file
+
+### 4. Deployment Setup (Hugging Face Spaces, etc.)
+1. **Generate Token for Deployment**:
+   ```bash
+   python convert_token_to_base64.py
+   ```
+   - This converts `token.pickle` to a base64 string
+
+2. **Set Environment Variables** in your deployment platform:
+   ```bash
+   Gemini_API=your_gemini_api_key
+   GOOGLE_CLIENT_ID=your_google_client_id
+   GOOGLE_CLIENT_SECRET=your_google_client_secret
+   GOOGLE_TOKEN_BASE64=your_base64_encoded_token
+   ```
+
+## Google Drive Folders
+- **📁 Exports**: https://drive.google.com/drive/folders/1k5iP4egzLrGJwnHkMhxt9bAkaCiieojO
+- **🖼️ Images**: https://drive.google.com/drive/folders/1gd280IqcAzpAFTPeYsZjoBUOU9S7Zx3c
+
+## Technical Details
+
+- **Image Formats**: JPG, JPEG, PNG, WEBP, BMP
+- **Maximum File Size**: 10MB per image
+- **Batch Processing**: Up to 5 cards per API call
+- **Storage**: Automatic upload to Google Drive
+- **Models**: Gemini 2.5 Flash (fast) / Pro (accurate) 

app.py

@@ -0,0 +1,675 @@
+import gradio as gr
+import google.generativeai as genai
+import json
+import pandas as pd
+from datetime import datetime
+import os
+from pathlib import Path
+from PIL import Image
+import io
+import base64
+import logging
+import sys
+import tempfile
+
+# Import Google Drive functionality
+from google_funcs import get_drive_service, upload_excel_to_exports_folder, upload_image_to_images_folder, list_files_in_folder
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(levelname)s - %(funcName)s:%(lineno)d - %(message)s',
+    handlers=[
+        logging.StreamHandler(sys.stdout)
+    ]
+)
+logger = logging.getLogger(__name__)
+
+# Configure Gemini API
+logger.info("Configuring Gemini API")
+gemini_api_key = os.getenv("Gemini_API")
+if not gemini_api_key:
+    logger.error("Gemini_API environment variable not found!")
+    logger.error("Please set the Gemini_API environment variable with your Google Gemini API key")
+    raise ValueError("❌ Gemini_API environment variable is required. Please set it in your environment.")
+
+genai.configure(api_key=gemini_api_key)
+logger.info("Gemini API configured successfully")
+
+# Initialize Google Drive service
+logger.info("Initializing Google Drive service")
+try:
+    drive_service = get_drive_service()
+    logger.info("Google Drive service initialized successfully")
+except Exception as e:
+    logger.error(f"Failed to initialize Google Drive service: {e}")
+    logger.error("Please ensure GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET environment variables are set")
+    raise ValueError("❌ Google Drive credentials are required. Please set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET environment variables.")
+
+# Log startup
+logger.info("Business Card Data Extractor starting up with Google Drive storage")
+
+def upload_to_google_drive(file_path, is_excel=False, filename=None):
+    """Upload a file to Google Drive"""
+    try:
+        if is_excel:
+            logger.info(f"Uploading Excel file to Google Drive: {filename or file_path}")
+            result = upload_excel_to_exports_folder(drive_service, file_path=file_path, filename=filename)
+        else:
+            logger.info(f"Uploading image file to Google Drive: {filename or file_path}")
+            result = upload_image_to_images_folder(drive_service, file_path=file_path, filename=filename)
+        
+        if result:
+            logger.info(f"Successfully uploaded to Google Drive: {result['webViewLink']}")
+            return result
+        else:
+            logger.error("Failed to upload to Google Drive")
+            return None
+    except Exception as e:
+        logger.error(f"Failed to upload to Google Drive: {e}")
+        return None
+
+def upload_bytes_to_google_drive(file_data, filename, is_excel=False):
+    """Upload file data (bytes) to Google Drive"""
+    try:
+        if is_excel:
+            logger.info(f"Uploading Excel data to Google Drive: {filename}")
+            result = upload_excel_to_exports_folder(drive_service, file_data=file_data, filename=filename)
+        else:
+            logger.info(f"Uploading image data to Google Drive: {filename}")
+            result = upload_image_to_images_folder(drive_service, file_data=file_data, filename=filename)
+        
+        if result:
+            logger.info(f"Successfully uploaded to Google Drive: {result['webViewLink']}")
+            return result
+        else:
+            logger.error("Failed to upload to Google Drive")
+            return None
+    except Exception as e:
+        logger.error(f"Failed to upload to Google Drive: {e}")
+        return None
+
+def extract_business_card_data_batch(images, filenames, model_name="gemini-2.5-flash"):
+    """Extract data from multiple business card images in a single API call"""
+    
+    logger.info(f"Starting batch extraction for {len(images)} images using model: {model_name}")
+    logger.debug(f"Filenames in batch: {filenames}")
+    
+    # Load prompts
+    logger.debug("Loading prompt templates")
+    try:
+        with open("prompts/prompt.txt", "r", encoding="utf-8") as f:
+            prompt_template = f.read()
+        logger.debug(f"Loaded prompt template ({len(prompt_template)} characters)")
+        
+        with open("prompts/system_prompt.txt", "r", encoding="utf-8") as f:
+            system_prompt = f.read()
+        logger.debug(f"Loaded system prompt ({len(system_prompt)} characters)")
+    except FileNotFoundError as e:
+        logger.error(f"Failed to load prompt files: {e}")
+        raise
+    
+    # Configure model
+    logger.debug(f"Configuring Gemini model: {model_name}")
+    generation_config = {
+        "temperature": 0.1,
+        "response_mime_type": "application/json"
+    }
+    
+    try:
+        model = genai.GenerativeModel(
+            model_name=model_name,
+            generation_config=generation_config,
+            system_instruction=system_prompt
+        )
+        logger.debug("Gemini model configured successfully")
+    except Exception as e:
+        logger.error(f"Failed to configure Gemini model: {e}")
+        raise
+    
+    # Prepare multiple images for the model
+    logger.debug("Preparing content parts for API request")
+    content_parts = []
+    
+    # Add the prompt first
+    batch_prompt = f"""
+{prompt_template}
+
+I'm sending you {len(images)} business card images. Please extract the data from each card and return a JSON array with {len(images)} objects. Each object should contain the extracted data for one business card in the same order as the images.
+
+Return format: [card1_data, card2_data, card3_data, ...]
+    """
+    content_parts.append(batch_prompt)
+    logger.debug(f"Added batch prompt ({len(batch_prompt)} characters)")
+    
+    # Add each image
+    logger.debug("Converting and adding images to request")
+    for i, image in enumerate(images):
+        try:
+            buffered = io.BytesIO()
+            image.save(buffered, format="PNG")
+            img_base64 = base64.b64encode(buffered.getvalue()).decode()
+            
+            image_part = {
+                "mime_type": "image/png",
+                "data": img_base64
+            }
+            content_parts.append(f"Business Card {i+1}:")
+            content_parts.append(image_part)
+            logger.debug(f"Added image {i+1} ({len(img_base64)} base64 characters)")
+        except Exception as e:
+            logger.error(f"Failed to process image {i+1} ({filenames[i] if i < len(filenames) else 'unknown'}): {e}")
+            raise
+    
+    # Generate content
+    logger.info(f"Making API call to {model_name} with {len(content_parts)} content parts")
+    try:
+        response = model.generate_content(content_parts)
+        logger.info(f"API call successful. Response length: {len(response.text) if response.text else 0} characters")
+        logger.debug(f"Raw response: {response.text[:500]}..." if len(response.text) > 500 else f"Raw response: {response.text}")
+    except Exception as e:
+        logger.error(f"API call failed: {e}")
+        raise
+    
+    # Parse response
+    logger.debug("Parsing JSON response")
+    try:
+        # Parse JSON response
+        response_data = json.loads(response.text)
+        logger.info(f"Successfully parsed JSON response")
+        
+        # Ensure we got an array
+        if not isinstance(response_data, list):
+            logger.debug("Response is not an array, converting to array")
+            response_data = [response_data]
+        
+        logger.info(f"Response contains {len(response_data)} extracted card data objects")
+        
+        # Add metadata to each card's data
+        logger.debug("Adding metadata to extracted data")
+        for i, data in enumerate(response_data):
+            data['method'] = model_name
+            if i < len(filenames):
+                data['filename'] = filenames[i]
+                logger.debug(f"Added metadata to card {i+1}: {filenames[i]}")
+        
+        logger.info(f"Batch extraction completed successfully for {len(response_data)} cards")
+        return response_data
+        
+    except json.JSONDecodeError as e:
+        logger.warning(f"Initial JSON parsing failed: {e}. Attempting to clean response.")
+        # Try to clean the response
+        text = response.text.strip()
+        if text.startswith("```json"):
+            text = text[7:]
+            logger.debug("Removed ```json prefix")
+        if text.endswith("```"):
+            text = text[:-3]
+            logger.debug("Removed ``` suffix")
+        
+        try:
+            response_data = json.loads(text.strip())
+            logger.info("Successfully parsed cleaned JSON response")
+            
+            # Ensure we got an array
+            if not isinstance(response_data, list):
+                logger.debug("Cleaned response is not an array, converting to array")
+                response_data = [response_data]
+            
+            logger.info(f"Cleaned response contains {len(response_data)} extracted card data objects")
+            
+            # Add metadata to each card's data
+            logger.debug("Adding metadata to cleaned extracted data")
+            for i, data in enumerate(response_data):
+                data['method'] = model_name
+                if i < len(filenames):
+                    data['filename'] = filenames[i]
+                    logger.debug(f"Added metadata to cleaned card {i+1}: {filenames[i]}")
+            
+            logger.info(f"Batch extraction completed successfully after cleaning for {len(response_data)} cards")
+            return response_data
+        except json.JSONDecodeError as e2:
+            logger.error(f"Failed to parse even cleaned JSON response: {e2}")
+            logger.error(f"Cleaned text: {text[:1000]}...")
+            raise
+
+def extract_business_card_data(image, model_name="gemini-2.5-flash"):
+    """Extract data from single business card image - legacy function"""
+    logger.debug(f"Single card extraction called with model: {model_name}")
+    result = extract_business_card_data_batch([image], ["single_card"], model_name)
+    if result:
+        logger.debug("Single card extraction successful")
+        return result[0]
+    else:
+        logger.warning("Single card extraction returned no results")
+        return None
+
+def process_business_cards(images, model_name="gemini-2.5-flash", save_images=True):
+    """Process multiple business card images and create both current run and cumulative Excel files"""
+    
+    logger.info(f"Starting business card processing session")
+    logger.info(f"Number of images received: {len(images) if images else 0}")
+    logger.info(f"Model selected: {model_name}")
+    logger.info(f"Save images option: {save_images}")
+    
+    if not images:
+        logger.warning("No images provided for processing")
+        return None, None, "Please upload at least one business card image.", None
+    
+    all_data = []
+    errors = []
+    
+    # Prepare images for batch processing
+    logger.info("Preparing images for batch processing")
+    image_batches = []
+    filename_batches = []
+    batch_size = 5
+    logger.debug(f"Using batch size: {batch_size}")
+    
+    # Load and group images into batches of 5
+    loaded_images = []
+    filenames = []
+    uploaded_image_links = []
+    
+    logger.info(f"Loading {len(images)} images")
+    for idx, image_path in enumerate(images):
+        try:
+            # Load image
+            if isinstance(image_path, str):
+                logger.debug(f"Loading image {idx+1}: {image_path}")
+                image = Image.open(image_path)
+                filename = os.path.basename(image_path)
+            else:
+                logger.debug(f"Using direct image object {idx+1}")
+                image = image_path
+                filename = f"image_{idx+1}.png"
+            
+            loaded_images.append(image)
+            filenames.append(filename)
+            logger.debug(f"Successfully loaded image {idx+1}: {filename} (size: {image.size})")
+            
+        except Exception as e:
+            error_msg = f"Error loading {image_path}: {str(e)}"
+            logger.error(error_msg)
+            errors.append(error_msg)
+    
+    logger.info(f"Successfully loaded {len(loaded_images)} out of {len(images)} images")
+    
+    # Save images to Google Drive if requested
+    if save_images and loaded_images:
+        logger.info(f"Saving {len(loaded_images)} images to Google Drive")
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        
+        for i, (image, filename) in enumerate(zip(loaded_images, filenames)):
+            try:
+                # Create unique filename with timestamp
+                name, ext = os.path.splitext(filename)
+                if not ext:
+                    ext = '.png'
+                unique_filename = f"{timestamp}_{i+1:03d}_{name}{ext}"
+                
+                # Convert image to bytes
+                img_buffer = io.BytesIO()
+                image.save(img_buffer, format='PNG')
+                img_bytes = img_buffer.getvalue()
+                
+                # Upload to Google Drive
+                result = upload_bytes_to_google_drive(img_bytes, unique_filename, is_excel=False)
+                
+                if result:
+                    uploaded_image_links.append(result['webViewLink'])
+                    logger.debug(f"Saved image {i+1}: {unique_filename}")
+                else:
+                    uploaded_image_links.append(None)
+                    logger.error(f"Failed to upload image {unique_filename}")
+                
+            except Exception as e:
+                logger.error(f"Failed to save image {filename}: {e}")
+                uploaded_image_links.append(None)
+        
+        logger.info(f"Successfully uploaded {sum(1 for link in uploaded_image_links if link)} images to Google Drive")
+    
+    # Group into batches
+    logger.info(f"Grouping {len(loaded_images)} images into batches of {batch_size}")
+    for i in range(0, len(loaded_images), batch_size):
+        batch_images = loaded_images[i:i + batch_size]
+        batch_filenames = filenames[i:i + batch_size]
+        image_batches.append(batch_images)
+        filename_batches.append(batch_filenames)
+        logger.debug(f"Created batch {len(image_batches)} with {len(batch_images)} images: {batch_filenames}")
+    
+    logger.info(f"Created {len(image_batches)} batches for processing")
+    
+    # Process each batch
+    logger.info(f"Starting processing of {len(image_batches)} batches")
+    for batch_idx, (batch_images, batch_filenames) in enumerate(zip(image_batches, filename_batches)):
+        try:
+            logger.info(f"Processing batch {batch_idx + 1}/{len(image_batches)} ({len(batch_images)} cards)")
+            print(f"Processing batch {batch_idx + 1}/{len(image_batches)} ({len(batch_images)} cards)")
+            
+            # Extract data for the entire batch
+            logger.debug(f"Calling batch extraction for batch {batch_idx + 1}")
+            batch_data = extract_business_card_data_batch(batch_images, batch_filenames, model_name)
+            logger.info(f"Batch {batch_idx + 1} extraction completed, got {len(batch_data)} results")
+            
+            # Process each card's data in the batch
+            logger.debug(f"Processing individual card data for batch {batch_idx + 1}")
+            for i, data in enumerate(batch_data):
+                card_filename = batch_filenames[i] if i < len(batch_filenames) else f"card_{i+1}"
+                logger.debug(f"Processing card data for: {card_filename}")
+                
+                # Add timestamp to data
+                timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+                data['processed_date'] = timestamp
+                logger.debug(f"Added timestamp {timestamp} to {card_filename}")
+                
+                # Add Google Drive image link if images were saved
+                global_index = batch_idx * batch_size + i
+                if save_images and global_index < len(uploaded_image_links) and uploaded_image_links[global_index]:
+                    data['google_drive_image_link'] = uploaded_image_links[global_index]
+                    logger.debug(f"Added Google Drive image link for {card_filename}: {uploaded_image_links[global_index]}")
+                else:
+                    data['google_drive_image_link'] = None
+                
+                # Handle multiple values (emails, phones) by joining with commas
+                list_fields_processed = []
+                for key, value in data.items():
+                    if isinstance(value, list):
+                        original_count = len(value)
+                        data[key] = ', '.join(str(v) for v in value)
+                        list_fields_processed.append(f"{key}({original_count})")
+                        logger.debug(f"Combined {original_count} {key} values for {card_filename}")
+                
+                if list_fields_processed:
+                    logger.debug(f"List fields processed for {card_filename}: {list_fields_processed}")
+                
+                # Combine phone fields if they exist separately
+                if 'mobile_phones' in data and data['mobile_phones']:
+                    logger.debug(f"Combining phone fields for {card_filename}")
+                    if data.get('phones'):
+                        # Combine mobile and regular phones
+                        existing_phones = str(data['phones']) if data['phones'] else ""
+                        mobile_phones = str(data['mobile_phones']) if data['mobile_phones'] else ""
+                        combined = [p for p in [existing_phones, mobile_phones] if p and p != 'null']
+                        data['phones'] = ', '.join(combined)
+                        logger.debug(f"Combined phones for {card_filename}: {data['phones']}")
+                    else:
+                        data['phones'] = data['mobile_phones']
+                        logger.debug(f"Used mobile phones as phones for {card_filename}: {data['phones']}")
+                    del data['mobile_phones']  # Remove separate mobile field
+                
+                # Combine address fields if they exist separately  
+                if 'street' in data and data['street']:
+                    logger.debug(f"Combining address fields for {card_filename}")
+                    if data.get('address'):
+                        # If both exist, combine them
+                        if str(data['street']) != str(data['address']) and data['street'] != 'null':
+                            original_address = data['address']
+                            data['address'] = f"{data['street']}, {data['address']}"
+                            logger.debug(f"Combined address for {card_filename}: '{data['street']}' + '{original_address}' = '{data['address']}'")
+                    else:
+                        data['address'] = data['street']
+                        logger.debug(f"Used street as address for {card_filename}: {data['address']}")
+                    del data['street']  # Remove separate street field
+                
+                all_data.append(data)
+                logger.debug(f"Added processed data for {card_filename} to results (total: {len(all_data)})")
+            
+            logger.info(f"Completed processing batch {batch_idx + 1}, total cards processed so far: {len(all_data)}")
+            
+        except Exception as e:
+            batch_filenames_str = ', '.join(batch_filenames)
+            error_msg = f"Error processing batch {batch_idx + 1} ({batch_filenames_str}): {str(e)}"
+            logger.error(error_msg)
+            errors.append(error_msg)
+    
+    if not all_data:
+        logger.warning("No data could be extracted from any images")
+        error_summary = "No data could be extracted from the images.\n" + "\n".join(errors)
+        return None, None, error_summary, None
+    
+    logger.info(f"Successfully extracted data from {len(all_data)} business cards")
+    
+    # Create DataFrame for current run
+    logger.info("Creating DataFrame for current run")
+    current_df = pd.DataFrame(all_data)
+    logger.debug(f"Current run DataFrame created with {len(current_df)} rows and {len(current_df.columns)} columns")
+    logger.debug(f"Columns: {list(current_df.columns)}")
+    
+    # Generate timestamp
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    logger.debug(f"Generated timestamp: {timestamp}")
+    
+    # Create temporary files for Excel generation
+    with tempfile.NamedTemporaryFile(suffix='.xlsx', delete=False) as current_temp:
+        current_temp_path = current_temp.name
+    with tempfile.NamedTemporaryFile(suffix='.xlsx', delete=False) as cumulative_temp:
+        cumulative_temp_path = cumulative_temp.name
+    
+    current_filename = f"current_run_{timestamp}.xlsx"
+    cumulative_filename = "all_business_cards_total.xlsx"
+    
+    # Try to download existing cumulative data from Google Drive
+    logger.info("Checking for existing cumulative file in Google Drive")
+    try:
+        # List files in exports folder to find existing cumulative file
+        exports_files = list_files_in_folder(drive_service, "1k5iP4egzLrGJwnHkMhxt9bAkaCiieojO")
+        cumulative_file = None
+        for file in exports_files:
+            if file['name'] == 'all_business_cards_total.xlsx':
+                cumulative_file = file
+                break
+        
+        if cumulative_file:
+            logger.info("Existing cumulative file found in Google Drive")
+            # For now, we'll just use current data since downloading and merging is complex
+            # In production, you'd want to implement Google Drive file download
+            cumulative_df = current_df
+            logger.info("Using current data only (Google Drive download not implemented yet)")
+        else:
+            logger.info("No existing cumulative file found, using current data only")
+            cumulative_df = current_df
+    except Exception as e:
+        logger.warning(f"Could not check for existing data in Google Drive: {e}")
+        cumulative_df = current_df
+    
+    # Write current run Excel file
+    logger.info(f"Creating current run Excel file: {current_filename}")
+    try:
+        with pd.ExcelWriter(current_temp_path, engine='openpyxl') as writer:
+            current_df.to_excel(writer, index=False, sheet_name='Current Run')
+            logger.debug(f"Written {len(current_df)} rows to 'Current Run' sheet")
+            
+            # Auto-adjust column widths
+            logger.debug("Auto-adjusting column widths for current run file")
+            worksheet = writer.sheets['Current Run']
+            for column in current_df:
+                column_length = max(current_df[column].astype(str).map(len).max(), len(column))
+                col_idx = current_df.columns.get_loc(column)
+                final_width = min(column_length + 2, 50)
+                worksheet.column_dimensions[chr(65 + col_idx)].width = final_width
+        
+        logger.info(f"Current run Excel file created locally")
+        
+        # Upload current run file to Google Drive
+        current_result = upload_to_google_drive(current_temp_path, is_excel=True, filename=current_filename)
+        if current_result:
+            logger.info(f"Current run file uploaded to Google Drive: {current_result['webViewLink']}")
+        
+    except Exception as e:
+        logger.error(f"Failed to create current run Excel file: {e}")
+        raise
+    
+    # Write cumulative Excel file
+    logger.info(f"Creating cumulative Excel file: {cumulative_filename}")
+    try:
+        with pd.ExcelWriter(cumulative_temp_path, engine='openpyxl') as writer:
+            cumulative_df.to_excel(writer, index=False, sheet_name='All Business Cards')
+            logger.debug(f"Written {len(cumulative_df)} rows to 'All Business Cards' sheet")
+            
+            # Auto-adjust column widths
+            logger.debug("Auto-adjusting column widths for cumulative file")
+            worksheet = writer.sheets['All Business Cards']
+            for column in cumulative_df:
+                column_length = max(cumulative_df[column].astype(str).map(len).max(), len(column))
+                col_idx = cumulative_df.columns.get_loc(column)
+                final_width = min(column_length + 2, 50)
+                worksheet.column_dimensions[chr(65 + col_idx)].width = final_width
+        
+        logger.info(f"Cumulative Excel file created locally")
+        
+        # Upload cumulative file to Google Drive
+        cumulative_result = upload_to_google_drive(cumulative_temp_path, is_excel=True, filename=cumulative_filename)
+        if cumulative_result:
+            logger.info(f"Cumulative file uploaded to Google Drive: {cumulative_result['webViewLink']}")
+        
+    except Exception as e:
+        logger.error(f"Failed to create cumulative Excel file: {e}")
+        raise
+    
+    # Note: Don't delete temp files here - Gradio needs them for download
+    # Gradio will handle cleanup automatically
+    
+    # Create summary message
+    logger.info("Creating summary message")
+    num_batches = len(image_batches) if 'image_batches' in locals() else 1
+    summary = f"Successfully processed {len(all_data)} business card(s) in {num_batches} batch(es) of up to 5 cards.\n"
+    summary += f"🤖 AI Model used: {model_name}\n"
+    summary += f"⚡ API calls made: {num_batches} (instead of {len(all_data)})\n"
+    
+    if save_images:
+        num_uploaded = sum(1 for link in uploaded_image_links if link) if 'uploaded_image_links' in locals() else 0
+        summary += f"💾 Images uploaded to Google Drive: {num_uploaded} cards\n\n"
+    else:
+        summary += f"💾 Images uploaded to Google Drive: No (save option was disabled)\n\n"
+    
+    summary += f"📁 Current run file: {current_filename} (uploaded to Google Drive)\n"
+    summary += f"📊 Total cumulative file: {cumulative_filename} (uploaded to Google Drive)\n"
+    summary += f"📊 Total cards in database: {len(cumulative_df)}\n\n"
+    
+    # Add Google Drive links
+    summary += "🔗 Google Drive Links:\n"
+    if 'current_result' in locals() and current_result:
+        summary += f"   📄 Current Run: {current_result['webViewLink']}\n"
+    if 'cumulative_result' in locals() and cumulative_result:
+        summary += f"   📊 Total Database: {cumulative_result['webViewLink']}\n"
+    summary += f"   📁 Exports Folder: https://drive.google.com/drive/folders/1k5iP4egzLrGJwnHkMhxt9bAkaCiieojO\n"
+    summary += f"   🖼️ Images Folder: https://drive.google.com/drive/folders/1gd280IqcAzpAFTPeYsZjoBUOU9S7Zx3c\n\n"
+    
+    if errors:
+        logger.warning(f"Encountered {len(errors)} errors during processing")
+        summary += "Errors encountered:\n" + "\n".join(errors)
+        for error in errors:
+            logger.warning(f"Processing error: {error}")
+    else:
+        logger.info("No errors encountered during processing")
+    
+    # Display preview of current run
+    logger.debug("Creating preview DataFrame")
+    preview_df = current_df.head(10)
+    logger.debug(f"Preview contains {len(preview_df)} rows")
+    
+    logger.info("Business card processing session completed successfully")
+    logger.info(f"Session summary - Cards: {len(all_data)}, Batches: {num_batches}, API calls: {num_batches}, Total DB size: {len(cumulative_df)}")
+    
+    # Return the temporary file paths for download (Gradio will handle the download)
+    return current_temp_path, cumulative_temp_path, summary, preview_df
+
+# Create Gradio interface
+logger.info("Creating Gradio interface")
+with gr.Blocks(title="Business Card Data Extractor") as demo:
+    gr.Markdown(
+        """
+        # Business Card Data Extractor
+        
+        Upload business card images to extract contact information and export to Excel.
+        Cards are processed in batches of 5 for efficiency (fewer API calls, lower cost).
+        
+        **Two files are generated:**
+        - 📁 **Current Run**: Contains only the cards you just processed
+        - 📊 **Total Database**: Contains ALL cards ever processed (cumulative)
+        
+        **☁️ Google Drive Storage:**
+        - 📂 Excel files: Automatically uploaded to Google Drive exports folder
+        - 🖼️ Images: Uploaded to Google Drive images folder (if save option enabled)
+        - 🔗 **Direct Links**: Access files directly through provided Google Drive links
+        - 📁 **Organized Folders**: Separate folders for exports and images
+        
+        **📌 File Access:**
+        - ⬇️ Download directly from interface buttons (temporary copies)
+        - 🔗 Access permanent files via Google Drive links in results
+        - 📁 **Exports Folder**: https://drive.google.com/drive/folders/1k5iP4egzLrGJwnHkMhxt9bAkaCiieojO
+        - 🖼️ **Images Folder**: https://drive.google.com/drive/folders/1gd280IqcAzpAFTPeYsZjoBUOU9S7Zx3c
+        
+        **⚙️ Google Drive Integration:**
+        - Requires `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` environment variables
+        - Files are automatically uploaded and organized in predefined folders
+        """
+    )
+    
+    with gr.Row():
+        with gr.Column():
+            image_input = gr.File(
+                label="Upload Business Cards",
+                file_count="multiple",
+                file_types=[".jpg", ".jpeg", ".png", ".webp", ".bmp"]
+            )
+            
+            model_selector = gr.Dropdown(
+                choices=["gemini-2.5-pro", "gemini-2.5-flash"],
+                value="gemini-2.5-pro",
+                label="AI Model Selection"
+            )
+            
+            save_images_checkbox = gr.Checkbox(
+                value=True,
+                label="Save Business Card Images"
+            )
+            
+            process_btn = gr.Button("Process Business Cards", variant="primary")
+        
+        with gr.Column():
+            current_file = gr.File(label="📁 Download Current Run")
+            total_file = gr.File(label="📊 Download Total Database") 
+            status_output = gr.Textbox(label="Processing Status", lines=5)
+    
+    preview_output = gr.Dataframe(label="Data Preview (Current Run)")
+    
+    # Wrapper function for better error handling and logging
+    def process_with_logging(images, model_name, save_images):
+        """Wrapper function to add error handling and logging to the main process"""
+        try:
+            logger.info(f"Gradio interface initiated processing request")
+            logger.debug(f"Request parameters - Images: {len(images) if images else 0}, Model: {model_name}, Save Images: {save_images}")
+            return process_business_cards(images, model_name, save_images)
+        except Exception as e:
+            logger.error(f"Unexpected error in Gradio processing: {e}")
+            error_msg = f"An unexpected error occurred: {str(e)}\nPlease check the logs for more details."
+            return None, None, error_msg, None
+
+    # Handle processing
+    process_btn.click(
+        fn=process_with_logging,
+        inputs=[image_input, model_selector, save_images_checkbox],
+        outputs=[current_file, total_file, status_output, preview_output]
+    )
+    
+    gr.Markdown(
+        """
+        ## Features:
+        - 🤖 **Model Selection**: Choose between Gemini 2.5 Flash (fast) or Pro (accurate)
+        - ⚡ **Batch Processing**: Processes 5 cards per API call for efficiency
+        - 📄 **Data Extraction**: Names, emails, phone numbers, addresses, and more
+        - 📞 **Smart Combination**: Multiple emails/phones combined with commas
+        - 🏠 **Address Merging**: All phone types and address fields combined
+        - ☁️ **Google Drive Storage**: Automatic upload to organized Drive folders
+        - 🔗 **Direct Links**: Instant access to files via Google Drive URLs
+        - 📊 **Dual Output**: Current run + cumulative database files
+        - 📝 **Full Tracking**: Processing date, filename, Google Drive links, and AI model used
+        - 🎯 **One Row Per Card**: Each business card becomes one spreadsheet row
+        """
+    )
+
+# Launch for Hugging Face Spaces deployment
+logger.info("Starting Gradio demo")
+demo.launch() 

business_card_exports/.gitkeep

@@ -0,0 +1,2 @@
+# This file ensures the business_card_exports directory is created and tracked by git
+# Excel files with extracted business card data will be saved here 

business_cards/.gitkeep

@@ -0,0 +1,2 @@
+# This file ensures the business_cards directory is created and tracked by git
+# Business card images will be saved here when the app runs 

env.example

@@ -0,0 +1,28 @@
+# Environment Variables for Business Card Data Extractor
+# Copy this file to .env and replace with your actual values
+
+# Google Gemini API Key (Required)
+# Get your key from: https://aistudio.google.com/
+# For deployment: Add this as an environment variable named "Gemini_API"
+Gemini_API=your_gemini_api_key_here
+
+# Google Drive API Credentials (Required - for file storage)
+# Get these from Google Cloud Console:
+# 1. Create a project at https://console.cloud.google.com/
+# 2. Enable Google Drive API
+# 3. Create OAuth 2.0 credentials (Desktop application)
+# 4. Download the JSON and extract client_id and client_secret
+GOOGLE_CLIENT_ID=your_google_client_id_here
+GOOGLE_CLIENT_SECRET=your_google_client_secret_here
+
+# Google Drive Token (Required for deployment environments)
+# Generate this by running the app locally first, then use convert_token_to_base64.py
+# For local development: Leave this empty (token.pickle will be created automatically)
+# For deployment: Set this to the base64 encoded token string
+GOOGLE_TOKEN_BASE64=your_base64_encoded_token_here
+
+# Examples:
+# Gemini_API=AIzaSyBxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# GOOGLE_CLIENT_ID=1234567890-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com
+# GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxx
+# GOOGLE_TOKEN_BASE64=gASVxwAAAAAAAAB9cQAoWBYAAABhY2Nlc3NfdG9rZW4... (very long string) 

google_funcs.py

@@ -0,0 +1,195 @@
+import os
+import pickle
+import base64
+from google.auth.transport.requests import Request
+from google_auth_oauthlib.flow import InstalledAppFlow
+from googleapiclient.discovery import build
+from googleapiclient.http import MediaFileUpload, MediaIoBaseUpload
+import io
+from pathlib import Path
+import logging
+
+logger = logging.getLogger(__name__)
+
+# --- CONFIGURATION ---
+# Get credentials from environment variables
+CLIENT_ID = os.getenv("GOOGLE_CLIENT_ID")
+CLIENT_SECRET = os.getenv("GOOGLE_CLIENT_SECRET")
+
+# Google Drive folder IDs
+EXPORTS_FOLDER_ID = "1k5iP4egzLrGJwnHkMhxt9bAkaCiieojO"  # For Excel exports
+IMAGES_FOLDER_ID = "1gd280IqcAzpAFTPeYsZjoBUOU9S7Zx3c"   # For business card images
+
+# Scopes define the level of access you are requesting.
+SCOPES = ['https://www.googleapis.com/auth/drive.file']
+TOKEN_PICKLE_FILE = 'token.pickle'
+
+def get_drive_service():
+    """Authenticates with Google and returns a Drive service object."""
+    creds = None
+    
+    # --- NEW CODE FOR DEPLOYMENT ENVIRONMENTS ---
+    # If token file doesn't exist, try to create it from environment variable
+    if not os.path.exists(TOKEN_PICKLE_FILE):
+        encoded_token = os.environ.get('GOOGLE_TOKEN_BASE64')
+        if encoded_token:
+            logger.info("Found token in environment variable. Recreating token.pickle file.")
+            try:
+                decoded_token = base64.b64decode(encoded_token)
+                with open(TOKEN_PICKLE_FILE, "wb") as token_file:
+                    token_file.write(decoded_token)
+                logger.info("Successfully recreated token.pickle from environment variable")
+            except Exception as e:
+                logger.error(f"Failed to decode token from environment variable: {e}")
+    # --- END OF NEW CODE ---
+    
+    # The file token.pickle stores the user's access and refresh tokens.
+    if os.path.exists(TOKEN_PICKLE_FILE):
+        with open(TOKEN_PICKLE_FILE, 'rb') as token:
+            creds = pickle.load(token)
+            
+    # If there are no (valid) credentials available, let the user log in.
+    if not creds or not creds.valid:
+        if creds and creds.expired and creds.refresh_token:
+            logger.info("Refreshing expired credentials")
+            creds.refresh(Request())
+        else:
+            if not CLIENT_ID or not CLIENT_SECRET:
+                raise ValueError("GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET environment variables are required")
+                
+            logger.info("Starting OAuth flow for new credentials")
+            # Use client_config dictionary instead of a client_secret.json file
+            client_config = {
+                "installed": {
+                    "client_id": CLIENT_ID,
+                    "client_secret": CLIENT_SECRET,
+                    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+                    "token_uri": "https://oauth2.googleapis.com/token",
+                    "redirect_uris": ["http://localhost"]
+                }
+            }
+            flow = InstalledAppFlow.from_client_config(client_config, SCOPES)
+            creds = flow.run_local_server(port=0)
+            
+        # Save the credentials for the next run
+        with open(TOKEN_PICKLE_FILE, 'wb') as token:
+            pickle.dump(creds, token)
+            logger.info("Saved new credentials to token.pickle")
+            
+    return build('drive', 'v3', credentials=creds)
+
+def upload_file_to_drive(service, file_path=None, file_data=None, filename=None, folder_id=None, mimetype='application/octet-stream'):
+    """
+    Uploads a file to a specific folder in Google Drive.
+    
+    Args:
+        service: Google Drive service object
+        file_path: Path to local file (for file uploads)
+        file_data: Bytes data (for in-memory uploads)
+        filename: Name for the file in Drive
+        folder_id: ID of the target folder
+        mimetype: MIME type of the file
+    
+    Returns:
+        dict: File information (id, webViewLink) or None if failed
+    """
+    try:
+        if file_path and os.path.exists(file_path):
+            # Upload from local file
+            if not filename:
+                filename = os.path.basename(file_path)
+            media = MediaFileUpload(file_path, mimetype=mimetype, resumable=True)
+            logger.info(f"Uploading file from path: {file_path}")
+        elif file_data and filename:
+            # Upload from bytes data
+            file_io = io.BytesIO(file_data)
+            media = MediaIoBaseUpload(file_io, mimetype=mimetype, resumable=True)
+            logger.info(f"Uploading file from memory: {filename}")
+        else:
+            logger.error("Either file_path or (file_data + filename) must be provided")
+            return None
+
+        # Define the file's metadata
+        file_metadata = {
+            'name': filename,
+            'parents': [folder_id] if folder_id else []
+        }
+
+        logger.info(f"Uploading '{filename}' to Google Drive folder {folder_id}")
+
+        # Execute the upload request
+        file = service.files().create(
+            body=file_metadata,
+            media_body=media,
+            fields='id, webViewLink, name'
+        ).execute()
+
+        logger.info(f"✅ File uploaded successfully!")
+        logger.info(f"   File ID: {file.get('id')}")
+        logger.info(f"   File Name: {file.get('name')}")
+        logger.info(f"   View Link: {file.get('webViewLink')}")
+
+        return {
+            'id': file.get('id'),
+            'name': file.get('name'),
+            'webViewLink': file.get('webViewLink')
+        }
+
+    except Exception as e:
+        logger.error(f"Failed to upload file to Google Drive: {e}")
+        return None
+
+def upload_excel_to_exports_folder(service, file_path=None, file_data=None, filename=None):
+    """Upload Excel file to the exports folder."""
+    return upload_file_to_drive(
+        service, 
+        file_path=file_path, 
+        file_data=file_data, 
+        filename=filename, 
+        folder_id=EXPORTS_FOLDER_ID,
+        mimetype='application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+    )
+
+def upload_image_to_images_folder(service, file_path=None, file_data=None, filename=None, mimetype='image/png'):
+    """Upload image file to the images folder."""
+    return upload_file_to_drive(
+        service, 
+        file_path=file_path, 
+        file_data=file_data, 
+        filename=filename, 
+        folder_id=IMAGES_FOLDER_ID,
+        mimetype=mimetype
+    )
+
+def list_files_in_folder(service, folder_id, max_results=100):
+    """List files in a specific Google Drive folder."""
+    try:
+        query = f"'{folder_id}' in parents"
+        results = service.files().list(
+            q=query,
+            maxResults=max_results,
+            fields="files(id, name, size, createdTime, webViewLink)"
+        ).execute()
+        
+        files = results.get('files', [])
+        logger.info(f"Found {len(files)} files in folder {folder_id}")
+        return files
+    except Exception as e:
+        logger.error(f"Failed to list files in folder {folder_id}: {e}")
+        return []
+
+if __name__ == '__main__':
+    # Test the Google Drive connection
+    try:
+        drive_service = get_drive_service()
+        logger.info("Google Drive service initialized successfully")
+        
+        # List files in both folders to verify access
+        exports_files = list_files_in_folder(drive_service, EXPORTS_FOLDER_ID)
+        images_files = list_files_in_folder(drive_service, IMAGES_FOLDER_ID)
+        
+        print(f"Exports folder contains {len(exports_files)} files")
+        print(f"Images folder contains {len(images_files)} files")
+        
+    except Exception as e:
+        logger.error(f"Failed to initialize Google Drive: {e}")

prompts/prompt.txt

@@ -0,0 +1,38 @@
+Extract all contact information from the business card image(s).
+
+Output Format:
+- If processing ONE card: Return a single JSON object
+- If processing MULTIPLE cards: Return a JSON array with one object per card
+
+Each JSON object must contain all the extracted information from one business card.
+
+Important Instructions:
+- If a field has multiple values (like multiple email addresses or phone numbers), return them as an array
+- If a field is not found on the card, set its value to null
+- Extract ALL information visible on the card, even if it doesn't fit the standard fields
+- Preserve the exact formatting of phone numbers as shown on the card
+- For names, try to identify first name, last name, and full name separately
+
+Standard Fields to Extract:
+
+{
+  "full_name": "The complete name as displayed",
+  "first_name": "First/given name only",
+  "last_name": "Last/family name only", 
+  "job_title": "Professional title or position",
+  "company": "Company or organization name",
+  "department": "Department or division if specified",
+  "emails": ["Array of all email addresses found"],
+  "phones": ["Array of all phone numbers found (include both mobile and landline)"],
+  "fax": "Fax number if present",
+  "website": "Company or personal website URL",
+  "linkedin": "LinkedIn profile URL if present",
+  "address": "Complete address as displayed (combine street and full address)",
+  "city": "City name",
+  "state": "State or province",
+  "postal_code": "ZIP or postal code",
+  "country": "Country if specified",
+  "additional_info": "Any other relevant information not covered above"
+}
+
+Return ONLY the JSON object, no additional text or formatting.

prompts/system_prompt.txt

@@ -0,0 +1 @@
+You are a highly accurate business card data extraction AI. Your task is to analyze business card images and extract all contact information, formatting the output as structured JSON. When processing multiple cards, return a JSON array with one object per card in the same order as the images. You must identify and extract every piece of information visible on each card, including names, titles, contact details, addresses, and any additional information. Be thorough and precise in your extraction.

requirements.txt

@@ -0,0 +1,9 @@
+gradio==4.44.1
+pydantic==2.10.6
+google-generativeai==0.8.0
+pandas==2.1.4
+openpyxl==3.1.2
+Pillow==10.2.0
+google-auth==2.23.4
+google-auth-oauthlib==1.1.0
+google-api-python-client==2.108.0

setup_hf_space.md

@@ -0,0 +1,60 @@
+# Hugging Face Spaces Setup Guide
+
+## Quick Deployment to Hugging Face Spaces
+
+### 1. Create a New Space
+1. Go to [Hugging Face Spaces](https://huggingface.co/spaces)
+2. Click "Create new Space"
+3. Choose:
+   - **Space name**: `business-card-extractor`
+   - **License**: `mit`
+   - **Space SDK**: `gradio`
+   - **Visibility**: `public` or `private`
+
+### 2. Upload Files
+Upload these files to your space:
+```
+app.py
+requirements.txt
+prompts/prompt.txt
+prompts/system_prompt.txt
+README.md
+business_cards/.gitkeep
+```
+
+**Note**: The `business_cards/` and `business_card_exports/` directories will be created automatically.
+
+### 3. Set Environment Variables
+1. Go to your Space **Settings**
+2. Scroll to **Repository secrets**
+3. Click **Add a new secret**
+4. Set:
+   - **Name**: `Gemini_API`
+   - **Value**: Your Google Gemini API key
+
+### 4. Get Your Gemini API Key
+1. Go to [Google AI Studio](https://aistudio.google.com/)
+2. Click "Get API key"
+3. Create a new API key
+4. Copy the key for use in step 3
+
+### 5. Your Space is Ready!
+- The space will automatically build and deploy
+- It will be available at: `https://huggingface.co/spaces/YOUR_USERNAME/business-card-extractor`
+- All business card images and Excel files will be saved in the space
+
+## Features Available in Hugging Face Spaces
+✅ **Full functionality**: All features work in Hugging Face Spaces  
+✅ **Image storage**: Business cards saved to `business_cards/` folder  
+✅ **Excel exports**: Download both current run and cumulative files  
+✅ **Persistent storage**: All data preserved between sessions  
+✅ **Batch processing**: Efficient 5-cards-per-API-call processing  
+
+## Environment Variables Required
+- `Gemini_API`: Your Google Gemini API key (required)
+
+## Notes
+- The space will create necessary directories automatically
+- Logs are available in the space's terminal/logs
+- All uploaded images are processed and optionally saved
+- Excel files accumulate over time in the cumulative database