Upload 2 files

README.md

@@ -1,12 +1,219 @@
----
-title: Tin Checker
-emoji: 🏆
-colorFrom: pink
-colorTo: gray
-sdk: gradio
-sdk_version: 5.41.1
-app_file: app.py
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🆔 TIN Validator - Hugging Face Spaces
+
+A Gradio-based web application for validating Philippine Tax Identification Numbers (TIN) with multiple name combination testing.
+
+## 🌟 Features
+
+- **Multiple Name Combinations**: Automatically tests various name formatting combinations
+- **Parallel Processing**: Simultaneous validations for faster results  
+- **User-Friendly Interface**: Clean Gradio UI with real-time results
+- **Detailed Results**: See which combinations worked and failure reasons
+- **CSV Export**: Download validation results for record keeping
+- **Mobile Responsive**: Works on desktop and mobile devices
+
+## 🚀 Quick Start
+
+### Deploy to Hugging Face Spaces
+
+1. **Create New Space**:
+   - Go to [Hugging Face Spaces](https://huggingface.co/spaces)
+   - Click "Create new Space"
+   - Choose "Gradio" as the SDK
+   - Set visibility (Public/Private)
+
+2. **Upload Files**:
+   ```
+   your-space/
+   ├── app.py
+   ├── requirements.txt
+   └── README.md
+   ```
+
+3. **Files Content**: Use the provided files in this repository
+
+4. **Space will auto-deploy** once files are uploaded
+
+### Local Development
+
+```bash
+# Clone repository
+git clone <your-repo-url>
+cd tin-validator
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run application
+python app.py
+```
+
+## 📁 File Structure
+
+```
+tin-validator/
+├── app.py              # Main Gradio application
+├── requirements.txt    # Python dependencies
+├── README.md          # This documentation
+└── .gitignore         # Git ignore file (optional)
+```
+
+## 🔧 Configuration Required
+
+⚠️ **Important**: This is a demonstration version. To make it fully functional, you need to:
+
+### 1. Find the Real API Endpoint
+
+The current code uses a placeholder endpoint. You need to:
+
+1. **Inspect Network Traffic**:
+   - Open [BIR TIN Validation](https://revie.bir.gov.ph/tin-validation) in browser
+   - Open Developer Tools (F12) → Network tab
+   - Submit a test form
+   - Find the actual API endpoint being called
+
+2. **Update the Endpoint**:
+   ```python
+   # In app.py, update this line:
+   url = "https://revie.bir.gov.ph/api/validate-tin"  # Replace with real endpoint
+   ```
+
+### 2. Analyze Response Format
+
+Update the response parsing logic based on actual API response:
+
+```python
+def validate_tin(self, ...):
+    # Update this section based on real API response
+    if response.status_code == 200:
+        result = response.json()  # or response.text if not JSON
+        # Parse based on actual response format
+```
+
+### 3. Handle CSRF/Security Tokens
+
+If the site uses CSRF protection:
+
+```python
+def __init__(self):
+    # Add session initialization to get CSRF tokens
+    self.session = requests.Session()
+    # Get initial page to extract tokens
+    self.session.get("https://revie.bir.gov.ph/tin-validation")
+```
+
+## 🎯 Usage
+
+1. **Enter Personal Information**:
+   - First Name (required)
+   - Middle Name (optional)
+   - Last Name (required) 
+   - TIN ID (9 digits)
+   - Birth Date
+   - Sex
+
+2. **Configure Settings**:
+   - Adjust parallel workers (1-5)
+   - Higher numbers = faster but more server load
+
+3. **Click "Validate TIN"** and wait for results
+
+4. **Review Results**:
+   - Summary shows success/failure
+   - Table shows all combinations tested
+   - Download CSV for records
+
+## 🔍 Name Combinations Tested
+
+The system automatically tests these name format variations:
+
+1. **Standard**: `First | Middle | Last`
+2. **Combined**: `First Middle | | Last` 
+3. **No Middle**: `First | | Last`
+4. **Dotted Middle**: `First | Middle. | Last`
+5. **Full with Dot**: `First Middle. | | Last`
+6. **Reversed**: `Last | First | Middle`
+7. **Rearranged**: `Middle Last | | First`
+
+## 🔒 Security & Privacy
+
+- **No Data Storage**: Personal information is not stored permanently
+- **Secure Transmission**: HTTPS requests to BIR servers
+- **Local Processing**: Validation logic runs in your browser session
+- **No Logging**: Sensitive data is not logged to files
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+1. **"Request Error" Messages**:
+   - Check internet connection
+   - Verify BIR website is accessible
+   - API endpoint may need updating
+
+2. **All Validations Fail**:
+   - Double-check input data format
+   - Verify TIN number is correct
+   - Try reducing parallel workers
+
+3. **Slow Performance**:
+   - Reduce number of parallel workers
+   - Check Hugging Face Spaces resource limits
+
+### Debug Mode
+
+For local development, add debug logging:
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+## 📊 Hugging Face Spaces Configuration
+
+### Space Settings
+
+- **SDK**: Gradio
+- **Python Version**: 3.8+
+- **Hardware**: CPU Basic (sufficient for this app)
+- **Timeout**: Default (should be adequate)
+
+### Environment Variables (if needed)
+
+```bash
+# Add in Space settings if you need custom configuration
+API_BASE_URL=https://revie.bir.gov.ph
+MAX_WORKERS=3
+TIMEOUT_SECONDS=30
+```
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit changes (`git commit -m 'Add amazing feature'`)
+4. Push to branch (`git push origin feature/amazing-feature`)
+5. Open Pull Request
+
+## 📄 License
+
+This project is for educational and demonstration purposes. Ensure compliance with BIR terms of service when using with real data.
+
+## ⚠️ Disclaimer
+
+- This tool is for **demonstration purposes**
+- Always verify results through official BIR channels
+- Respect BIR website terms of service and rate limits
+- Keep personal TIN information secure and private
+
+## 📞 Support
+
+If you encounter issues:
+
+1. Check this README for troubleshooting
+2. Review Hugging Face Spaces documentation
+3. Open an issue in the repository
+4. Contact the maintainer
+
+---
+
+**Made with ❤️ for the Philippine developer community**

requirements.txt

@@ -0,0 +1,5 @@
+gradio==4.44.0
+pandas==2.0.3
+requests==2.31.0
+beautifulsoup4==4.12.2
+python-dateutil==2.8.2