README.md

metadata

title: Makerspace Inventory AI
emoji: 🔧
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.50.0
app_file: app.py
pinned: false

🔧 Makerspace Inventory Management System

An intelligent, AI-powered inventory management system designed for makerspaces, workshops, and educational facilities. This system combines computer vision, natural language processing, and optimization algorithms to streamline inventory tracking and improve workspace efficiency.

🌟 Features

🛒 Smart Check-Out System

• AI-Powered Image Recognition: Upload photos or use your webcam to automatically identify tools and equipment
• Gemini Vision AI: Utilizes Google's Gemini 2.5 Flash model for accurate item detection
• Vector Search: ChromaDB-powered semantic search for fuzzy matching between detected items and inventory
• Real-time Inventory Updates: Automatic quantity tracking and session logging
• Multi-Item Support: Scan multiple items in a single image

📦 Intelligent Item Addition

• OCR Receipt Processing: Upload PDF or image receipts to automatically extract items
• Fuzzy Matching: Smart name matching to find items even with typos or variations
• Interactive Editing: Review and modify detected items before adding to inventory
• Manual Entry: Quick single-item updates with auto-completion
• Update History: Complete audit trail of all inventory changes

📊 Data-Driven Layout Optimization

• Pattern Mining: Discovers which items are frequently checked out together
• Association Rules: Calculates support, confidence, and lift metrics for item pairs
• Distance Optimization: Uses greedy relocation algorithm to minimize walking distance
• Visual Analytics: Side-by-side comparison of current vs. optimized layouts
• Actionable Recommendations: Specific move suggestions with quantified benefits

🚀 How to Use

Check Out Items

1. Click "🛒 Check Out Items" on the main menu
2. Upload an image of items or use your webcam
   • Or manually type item names (comma-separated)
3. Review detected items and adjust quantities
4. Confirm checkout (optionally enter user ID)

Add Items to Inventory

1. Click "📦 Add Items" on the main menu
2. Receipt Upload Tab:
   • Upload a PDF or image receipt
   • Review extracted items
   • Check/uncheck items to include
   • Edit quantities if needed
   • Click "Apply Updates"
3. Manual Entry Tab:
   • Type item name
   • Enter quantity
   • Click "Add to Inventory"

Analyze Layout Efficiency

1. Click "📊 Inventory Analysis" on the main menu
2. Adjust analysis parameters:
   • Minimum Support: Pattern frequency threshold (0.02 = 2%)
   • Top K Pairs: Number of frequent pairs to optimize (25)
   • Maximum Moves: Limit on relocations (10)
   • Minimum Gain: Distance improvement threshold (0.05 units)
3. Click "🔍 Run Analysis"
4. Review:
   • Frequent item pairs
   • Relocation recommendations
   • Distance savings
   • Visual layout comparison

📈 Key Metrics Explained

Support

Frequency of items appearing together in checkout sessions

• Example: 0.10 = items appear together in 10% of checkouts

Lift

How much more likely items are checked out together vs. randomly

• Lift > 1: Positive correlation (should be near each other)
• Lift = 2: Items are 2× more likely to be checked out together

Confidence A→B

Probability of checking out item B when checking out item A

• Example: 0.80 = 80% chance of checking B with A

Distance Saved

Reduction in walking distance by relocating items

• Measured in grid units (1 unit ≈ 1 meter)

🛠️ Technology Stack

• Frontend: Gradio 5.9 (Interactive web interface)
• AI/ML:
  • Google Gemini 2.5 Flash (Vision AI for image recognition)
  • Sentence Transformers (Semantic embeddings)
  • ChromaDB (Vector database for similarity search)
• OCR: Tesseract + Pytesseract
• Data Processing: Pandas, NumPy
• Optimization: Custom greedy algorithm for layout optimization
• Visualization: Matplotlib
• Fuzzy Matching: RapidFuzz

📂 File Structure

.
├── app.py                    # Main application file
├── requirements.txt          # Python dependencies
├── README.md                # This file
├── items.csv                # Inventory database
├── locations.csv            # Physical location grid
├── checkouts.csv            # Checkout history
├── update_log.csv           # Inventory update log
├── screwdriver.png          # Example checkout image
└── mcmaster_receipt.pdf     # Example receipt

🔧 Local Setup

Prerequisites

• Python 3.10 or higher
• Tesseract OCR installed on your system

Installation

1. Clone the repository:

git clone <repository-url>
cd makerspace-inventory

2. Install system dependencies (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install -y tesseract-ocr poppler-utils

3. Install Python dependencies:

pip install -r requirements.txt

4. Run the application:

python app.py

5. Open your browser to http://localhost:7860

Environment Variables

The Gemini API key is currently hardcoded. For production use, set it as an environment variable:

export GEMINI_API_KEY="your-api-key-here"

📊 Data Format

items.csv

item_id,item_name,category,quantity,unit,description,location_id
I0001,Hex Key Set,Hand Tools,12,sets,Standard SAE hex key sets,L001

locations.csv

location_id,x,y,capacity
L001,0,0,1

checkouts.csv

timestamp,user_id,session_id,item_id
2025-12-05T10:30:00Z,U0001,S00001,I0001

🎯 Use Cases

• Makerspaces & Fab Labs: Track tools and equipment usage
• Educational Workshops: Monitor student equipment checkouts
• Tool Libraries: Manage community tool sharing
• Research Labs: Optimize equipment layout based on usage patterns
• Manufacturing Facilities: Improve tool room efficiency

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Development Roadmap

• Barcode/QR code scanning
• User authentication system
• Advanced analytics dashboard
• Mobile app integration
• Multi-location support
• Automated reorder suggestions
• Integration with purchasing systems

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Authors

Developed as part of a makerspace automation project.

🙏 Acknowledgments

• Google Gemini AI for vision capabilities
• Anthropic Claude for development assistance
• Open-source community for amazing tools and libraries

📞 Support

For questions, issues, or feature requests, please open an issue on GitHub or contact the development team.

---

Built with ❤️ for makers, by makers