|
|
--- |
|
|
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: |
|
|
```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** |
|
|
|
