Upload README.md

README.md

@@ -0,0 +1,214 @@
+# 🔧 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**