README.md

---
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.

![Python](https://img.shields.io/badge/Python-3.10-blue)
![Gradio](https://img.shields.io/badge/Gradio-5.9-orange)
![License](https://img.shields.io/badge/License-MIT-green)

## 🌟 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:
```bash
git clone <repository-url>
cd makerspace-inventory
```

2. Install system dependencies (Ubuntu/Debian):
```bash
sudo apt-get update
sudo apt-get install -y tesseract-ocr poppler-utils
```

3. Install Python dependencies:
```bash
pip install -r requirements.txt
```

4. Run the application:
```bash
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:
```bash
export GEMINI_API_KEY="your-api-key-here"
```

## 📊 Data Format

### items.csv
```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
```csv
location_id,x,y,capacity
L001,0,0,1
```

### checkouts.csv
```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**