Upload 12 files

ARCHITECTURE.md

@@ -0,0 +1,594 @@
+# 🏗️ Architecture Diagram - Hugging Face Integration
+
+## 📐 System Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                          USER INTERFACE                                  │
+│  ┌────────────────────────────────────────────────────────────────────┐  │
+│  │  Browser (Chrome, Firefox, Safari, etc.)                           │  │
+│  │  • Upload CAPTCHA image                                            │  │
+│  │  • Drag & Drop support                                             │  │
+│  │  • Image preview                                                   │  │
+│  │  • Result display                                                  │  │
+│  └────────────────────────────────────────────────────────────────────┘  │
+└──────────────────────────┬───────────────────────────────────────────────┘
+                           │ HTTP/HTTPS
+                           │ FormData (multipart/form-data)
+                           ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                       FRONTEND LAYER                                      │
+│  ┌────────────────────────────────────────────────────────────────────┐  │
+│  │  JavaScript (assets/js/script.js)                                  │  │
+│  │  ┌──────────────────────────────────────────────────────────────┐ │  │
+│  │  │  • File validation (type, size)                              │ │  │
+│  │  │  • FormData creation                                         │ │  │
+│  │  │  • Fetch API call to backend                                 │ │  │
+│  │  │  • Loading state management                                  │ │  │
+│  │  │  • Error handling & display                                  │ │  │
+│  │  │  • Result rendering                                          │ │  │
+│  │  │  • Copy to clipboard                                         │ │  │
+│  │  └──────────────────────────────────────────────────────────────┘ │  │
+│  └────────────────────────────────────────────────────────────────────┘  │
+└──────────────────────────┬───────────────────────────────────────────────┘
+                           │ POST request
+                           │ FormData { captcha: File }
+                           ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                        BACKEND LAYER (PHP)                                │
+│  ┌────────────────────────────────────────────────────────────────────┐  │
+│  │  API Handler (api/process.php)                                     │  │
+│  │  ┌──────────────────────────────────────────────────────────────┐ │  │
+│  │  │  1. Validate Request Method (POST only)                      │ │  │
+│  │  │  2. Check File Upload                                        │ │  │
+│  │  │  3. Validate File Type (JPEG, PNG, GIF)                      │ │  │
+│  │  │  4. Validate File Size (max 5MB)                             │ │  │
+│  │  │  5. Convert Image to Base64                                  │ │  │
+│  │  │     • Read file contents                                     │ │  │
+│  │  │     • Get MIME type                                          │ │  │
+│  │  │     • Create data URI                                        │ │  │
+│  │  │  6. Prepare API Request                                      │ │  │
+│  │  │     • JSON payload with base64 image                         │ │  │
+│  │  │     • Add Authorization header                               │ │  │
+│  │  │  7. Call Hugging Face API (cURL)                             │ │  │
+│  │  │  8. Parse Response                                           │ │  │
+│  │  │  9. Format & Return JSON                                     │ │  │
+│  │  └──────────────────────────────────────────────────────────────┘ │  │
+│  └────────────────────────────────────────────────────────────────────┘  │
+│                                                                           │
+│  ┌────────────────────────────────────────────────────────────────────┐  │
+│  │  Configuration (config.php)                                        │  │
+│  │  • HF_API_URL                                                      │  │
+│  │  • HF_API_KEY                                                      │  │
+│  │  • Upload limits & validation rules                               │  │
+│  └────────────────────────────────────────────────────────────────────┘  │
+└──────────────────────────┬───────────────────────────────────────────────┘
+                           │ HTTP POST
+                           │ Authorization: Bearer {API_KEY}
+                           │ Content-Type: application/json
+                           │ Body: { image_base64: "..." }
+                           ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                    HUGGING FACE SPACE                                     │
+│  ┌────────────────────────────────────────────────────────────────────┐  │
+│  │  Flask Server (app.py)                                             │  │
+│  │  ┌──────────────────────────────────────────────────────────────┐ │  │
+│  │  │  Endpoint: /predict                                          │ │  │
+│  │  │  ┌────────────────────────────────────────────────────────┐ │ │  │
+│  │  │  │  1. Authenticate Request                               │ │ │  │
+│  │  │  │     • Check Authorization header                       │ │ │  │
+│  │  │  │     • Verify API_KEY_SECRET                            │ │ │  │
+│  │  │  │  2. Decode Base64 Image                                │ │ │  │
+│  │  │  │  3. Auto-Crop Image (YOLO)                             │ │ │  │
+│  │  │  │     • Detect captcha area using YOLO                   │ │ │  │
+│  │  │  │     • Crop to highest confidence box                   │ │ │  │
+│  │  │  │     • Fallback to original if no detection             │ │ │  │
+│  │  │  │  4. Preprocess Image                                   │ │ │  │
+│  │  │  │     • Convert to RGB                                   │ │ │  │
+│  │  │  │     • Resize (Albumentations)                          │ │ │  │
+│  │  │  │     • Normalize                                        │ │ │  │
+│  │  │  │     • ToTensor                                         │ │ │  │
+│  │  │  │  5. Model Inference                                    │ │ │  │
+│  │  │  │  6. Decode Predictions                                 │ │ │  │
+│  │  │  │  7. Calculate Confidence                               │ │ │  │
+│  │  │  │  8. Return JSON Response                               │ │ │  │
+│  │  │  └────────────────────────────────────────────────────────┘ │ │  │
+│  │  └──────────────────────────────────────────────────────────────┘ │  │
+│  └────────────────────────────────────────────────────────────────────┘  │
+│                                                                           │
+│  ┌────────────────────────────────────────────────────────────────────┐  │
+│  │  AI Model (PyTorch)                                                │  │
+│  │  ┌──────────────────────────────────────────────────────────────┐ │  │
+│  │  │  Multi-Head Model Architecture                               │ │  │
+│  │  │                                                              │ │  │
+│  │  │  ┌─────────────────────────────────────────────────────┐    │ │  │
+│  │  │  │  Backbone: EfficientNet (timm)                      │    │ │  │
+│  │  │  │  • Feature extraction                               │    │ │  │
+│  │  │  │  • Drop path regularization                         │    │ │  │
+│  │  │  └──────────────┬──────────────────────────────────────┘    │ │  │
+│  │  │                 │                                            │ │  │
+│  │  │       ┌─────────┴─────────┬─────────────────┐              │ │  │
+│  │  │       ▼                   ▼                 ▼              │ │  │
+│  │  │  ┌─────────┐       ┌──────────┐      ┌──────────┐         │ │  │
+│  │  │  │  Type   │       │  Object  │      │   Text   │         │ │  │
+│  │  │  │  Head   │       │   Head   │      │   Head   │         │ │  │
+│  │  │  ├─────────┤       ├──────────┤      ├──────────┤         │ │  │
+│  │  │  │ Linear  │       │  Linear  │      │ Conv2D   │         │ │  │
+│  │  │  │ Softmax │       │ Softmax  │      │ BiLSTM   │         │ │  │
+│  │  │  │         │       │          │      │ Linear   │         │ │  │
+│  │  │  │ Output: │       │ Output:  │      │ CTC      │         │ │  │
+│  │  │  │ text/   │       │ class    │      │ Output:  │         │ │  │
+│  │  │  │ object  │       │ (0-N)    │      │ sequence │         │ │  │
+│  │  │  └─────────┘       └──────────┘      └──────────┘         │ │  │
+│  │  │                                                             │ │  │
+│  │  └──────────────────────────────────────────────────────────┘ │  │
+│  │                                                                │  │
+│  │  Model Details:                                               │  │
+│  │  • Quantized INT8 (CPU optimized)                             │  │
+│  │  • File: best_model_quantized.pth                             │  │
+│  │  • Size: ~44MB                                                │  │
+│  │  • Mappings: mappings.json                                    │  │
+│  │  • YOLO Crop Model: best_model.onnx                           │  │
+│  └──────────────────────────────────���─────────────────────────────┘  │
+└──────────────────────────┬───────────────────────────────────────────────┘
+                           │ JSON Response
+                           │ {
+                           │   predicted_type: "text|object",
+                           │   prediction: "ABC123",
+                           │   confidence: "97.8%",
+                           │   ...
+                           │ }
+                           ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                        RESPONSE FLOW                                      │
+│                                                                           │
+│  Backend (PHP) → Frontend (JS) → User Interface                          │
+│                                                                           │
+│  Formatted JSON → Display Result → Show to User                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🔄 Data Flow Diagram
+
+```
+┌─────────────┐
+│   User      │
+│  Uploads    │
+│  CAPTCHA    │
+└──────┬──────┘
+       │
+       │ [Image File: captcha.png]
+       ▼
+┌─────────────────────────────┐
+│  Frontend Validation        │
+│  • Type check: image/*      │
+│  • Size check: < 5MB        │
+│  • Preview generation       │
+└──────┬──────────────────────┘
+       │
+       │ [FormData]
+       ▼
+┌─────────────────────────────┐
+│  Backend Processing         │
+│  ┌─────────────────────────┐│
+│  │ 1. Receive Upload       ││
+│  │    File: $_FILES        ││
+│  └─────────┬───────────────┘│
+│  ┌─────────▼───────────────┐│
+│  │ 2. Validate             ││
+│  │    Type: JPEG/PNG/GIF   ││
+│  │    Size: < 5MB          ││
+│  │    Upload OK            ││
+│  └─────────┬───────────────┘│
+│  ┌─────────▼───────────────┐│
+│  │ 3. Convert to Base64    ││
+│  │    Read: file_contents  ││
+│  │    Encode: base64       ││
+│  │    Format: data:...     ││
+│  └─────────┬───────────────┘│
+│  ┌─────────▼───────────────┐│
+│  │ 4. Prepare API Call     ││
+│  │    URL: HF_API_URL      ││
+│  │    Key: HF_API_KEY      ││
+│  │    Body: JSON           ││
+│  └─────────┬───────────────┘│
+└────────────┼─────────────────┘
+             │
+             │ [HTTP POST]
+             │ Headers:
+             │   Authorization: Bearer xxx
+             │   Content-Type: application/json
+             │ Body:
+             │   { image_base64: "data:..." }
+             ▼
+┌─────────────────────────────────────┐
+│  Hugging Face Space                 │
+│  ┌─────────────────────────────────┐│
+│  │ 1. Authenticate                 ││
+│  │    Verify API key               ││
+│  └─────────┬───────────────────────┘│
+│  ┌─────────▼───────────────────────┐│
+│  │ 2. Decode Image                 ││
+│  │    Base64 → Binary              ││
+│  │    Binary → PIL Image           ││
+│  │    PIL → RGB                    ││
+│  └─────────┬───────────────────────┘│
+│  ┌─────────▼────────────────���──────┐│
+│  │ 3. Preprocess                   ││
+│  │    Resize: Albumentations       ││
+│  │    Normalize: ImageNet stats    ││
+│  │    ToTensor: [1, 3, H, W]       ││
+│  └─────────┬───────────────────────┘│
+│  ┌─────────▼───────────────────────┐│
+│  │ 4. Model Inference              ││
+│  │    Input: Tensor [1,3,H,W]      ││
+│  │    Forward pass                 ││
+│  │    Output: 3 heads              ││
+│  │      • Type logits              ││
+│  │      • Object logits            ││
+│  │      • Text log_probs           ││
+│  └─────────┬───────────────────────┘│
+│  ┌─────────▼───────────────────────┐│
+│  │ 5. Post-processing              ││
+│  │    Softmax: Type & Object       ││
+│  │    CTC Decode: Text             ││
+│  │    Confidence: Max prob         ││
+│  └─────────┬───────────────────────┘│
+│  ┌─────────▼───────────────────────┐│
+│  │ 6. Format Response              ││
+│  │    JSON:                        ││
+│  │      predicted_type             ││
+│  │      prediction                 ││
+│  │      confidence                 ││
+│  └─────────┬───────────────────────┘│
+└────────────┼─────────────────────────┘
+             │
+             │ [HTTP 200 OK]
+             │ JSON Response
+             ▼
+┌─────────────────────────────┐
+│  Backend Parsing            │
+│  • Extract data             │
+│  • Add timestamp            │
+│  • Calculate process time   │
+│  • Format response          │
+└──────┬──────────────────────┘
+       │
+       │ [JSON]
+       │ {
+       │   success: true,
+       │   data: { ... }
+       │ }
+       ▼
+┌─────────────────────────────┐
+│  Frontend Rendering         │
+│  • Parse JSON               │
+│  • Update DOM               │
+│  • Show result              │
+│  • Enable copy button       │
+└──────┬──────────────────────┘
+       │
+       ▼
+┌─────────────┐
+│   User      │
+│  Sees       │
+│  Result     │
+└─────────────┘
+```
+
+---
+
+## 🧩 Component Interaction
+
+### Frontend Components
+
+```
+index.php
+├── Header (Navigation)
+├── Hero Section
+├── Demo Section
+│   ├── Upload Area
+│   │   ├── Click to upload
+│   │   ├── Drag & drop
+│   │   └── File input
+│   ├── Preview Area
+│   │   ├── Image preview
+│   │   └── Remove button
+│   ├── Process Button
+│   │   ├── Loading spinner
+│   │   └── Click handler
+│   └── Result Area
+│       ├── Prediction text
+│       ├── Confidence score
+│       ├── Process time
+│       └── Copy button
+├── Features Section
+├── Pricing Section
+└── Footer
+
+assets/js/script.js
+├── Particles animation
+├── Smooth scroll
+├── Upload handling
+│   ├── File validation
+│   ├── Preview generation
+│   └── Drag & drop events
+├── API calling
+│   ├── FormData creation
+│   ├── Fetch request
+│   └── Response handling
+├── Result display
+│   ├── DOM updates
+│   └── Copy to clipboard
+└── Notification system
+```
+
+### Backend Components
+
+```
+api/process.php
+├── Request validation
+│   ├── Method check (POST)
+│   ├── File check
+│   ├── Type check
+│   └── Size check
+├── Image processing
+│   ├── Read file
+│   ├── Get MIME type
+│   └── Base64 encoding
+├── API communication
+│   ├── cURL initialization
+│   ├── Headers setup
+│   │   ├── Content-Type
+│   │   └── Authorization
+│   ├── POST request
+│   ├── Response handling
+│   └── Error handling
+└── Response formatting
+    ├── Parse HF response
+    ├── Calculate metrics
+    └── Return JSON
+
+config.php
+├── Site configuration
+├── Upload configuration
+├── API configuration
+│   ├── HF_API_URL
+│   └── HF_API_KEY
+├── Database configuration
+└── Helper functions
+```
+
+### Model Components
+
+```
+Hugging Face Space
+├── app.py (Flask Server)
+│   ├── Route: /
+│   ├── Route: /predict
+│   ├── Authentication
+│   ├── Image preprocessing
+│   ├── Model inference
+│   └── Response formatting
+├── Model (MultiHeadModel)
+│   ├── Backbone (EfficientNet)
+│   │   └── Feature extraction
+│   ├── Type Head
+│   │   ├── AdaptiveAvgPool2d
+│   │   ├── Linear
+│   │   └── Softmax
+│   ├── Object Head
+│   │   ├── AdaptiveAvgPool2d
+│   │   ├── Linear
+│   │   └── Softmax
+│   └── Text Head
+│       ├── Conv2d projection
+│       ├── BiLSTM
+│       ├── Linear
+│       └── CTC Loss/Decode
+├── Preprocessing (Albumentations)
+│   ├── Resize
+│   ├── Normalize
+│   └── ToTensor
+└── Post-processing
+    ├── Softmax (type/object)
+    ├── CTC Decoder (text)
+    └── Confidence calculation
+```
+
+---
+
+## 🔐 Security Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│          Security Layers                    │
+├─────────────────────────────────────────────┤
+│                                             │
+│  Layer 1: Frontend Validation               │
+│  • File type check (client-side)           │
+│  • File size check (client-side)           │
+│  • CSRF token (if implemented)             │
+│                                             │
+├─────────────────────────────────────────────┤
+│                                             │
+│  Layer 2: Backend Validation                │
+│  • HTTP method check (POST only)           │
+│  • File upload validation                  │
+│  • MIME type verification                  │
+│  • File size enforcement (5MB)             │
+│  • Input sanitization                      │
+│                                             │
+├─────────────────────────────────────────────┤
+│                                             │
+│  Layer 3: API Authentication                │
+│  • Bearer token required                   │
+│  • API key verification                    │
+│  • Request header validation               │
+│                                             │
+├─────────────────────────────────────────────┤
+│                                             │
+│  Layer 4: Hugging Face Security             │
+│  • Environment secrets                     │
+│  • API key stored securely                 │
+│  • Request authentication                  │
+│  • Rate limiting (HF platform)             │
+│                                             │
+├─────────────────────────────────────────────┤
+│                                             │
+│  Layer 5: Error Handling                    │
+│  • Try-catch blocks                        │
+│  • Graceful degradation                    │
+│  • User-friendly errors                    │
+│  • Detailed logging (server-side)          │
+│                                             │
+└─────────────────────────────────────────────┘
+
+API Key Flow:
+1. Generate: generate_api_key.php
+2. Store: Hugging Face Space Secrets (API_KEY_SECRET)
+3. Configure: config.php (HF_API_KEY)
+4. Use: api/process.php (Authorization header)
+5. Verify: app.py (authenticate request)
+
+Security Best Practices:
+✅ API key not in Git (.gitignore)
+✅ HTTPS in production
+✅ Input validation (multiple layers)
+✅ Error messages (no sensitive info exposed)
+✅ Rate limiting (can be added)
+✅ Logging (for audit trails)
+```
+
+---
+
+## 📊 Performance Architecture
+
+```
+Performance Optimization Points:
+
+┌──────────────────────────┐
+│  Frontend                │
+│  • Image compression     │
+│  • Lazy loading          │
+│  • Debouncing            │
+│  • Caching results       │
+└──────────┬───────────────┘
+           │
+           ▼
+┌──────────────────────────┐
+│  Network                 │
+│  • Compression (gzip)    │
+│  • Keep-alive            │
+│  • CDN (assets)          │
+└──────────┬───────────────┘
+           │
+           ▼
+┌──────────────────────────┐
+│  Backend                 │
+│  • cURL optimization     │
+│  • Connection pooling    │
+│  • Response caching      │
+└──────────┬───────────────┘
+           │
+           ▼
+┌──────────────────────────┐
+│  Hugging Face            │
+│  • Model quantization    │
+│  • Batch processing      │
+│  • Keep space awake      │
+│  • Warm start (ping)     │
+└──────────┬───────────────┘
+           │
+           ▼
+┌──────────────────────────┐
+│  Model                   │
+│  • INT8 quantization     │
+│  • CPU optimized         │
+│  • Efficient backbone    │
+│  • Single thread         │
+└──────────────────────────┘
+
+Expected Response Times:
+• Cold Start: 30-60 seconds (first request)
+• Warm: 1-3 seconds (subsequent)
+• Optimal: < 2 seconds (good connection)
+
+Optimization Strategies:
+1. Keep Space Awake: Ping every 10 min
+2. Image Optimization: Resize before upload
+3. Connection Pooling: Reuse cURL handles
+4. Response Caching: Cache similar images
+5. Upgrade HF Plan: No cold start (Pro)
+```
+
+---
+
+## 🗂️ File Structure
+
+```
+Captchakings.com/
+│
+├── index.php                       # Main landing page
+├── login.php                       # Login page
+├── register.php                    # Registration page
+├── dashboard.php                   # User dashboard
+├── config.php                      # ⚙️ Configuration (HF_API_KEY here!)
+│
+├── api/
+│   ├── process.php                 # 🔄 Main API handler (HF integration)
+│   └── auth.php                    # Authentication API
+│
+├── assets/
+│   ├── css/
+│   │   └── style.css               # Styles
+│   ├── js/
+│   │   └── script.js               # 🔄 Frontend logic (API calls)
+│   └── images/                     # Static images
+│
+├── HF/                             # 🤗 Hugging Face files
+│   ├── app.py                      # Flask server
+│   ├── best_model_quantized.pth    # Model weights (44MB)
+│   ├── best_model.onnx             # ONNX model (43MB)
+│   ├── mappings.json               # Class mappings
+│   ├── requirements.txt            # Python dependencies
+│   ├── Dockerfile                  # Docker config
+│   ├── README.md                   # HF Space README
+│   ├── INTEGRATION_GUIDE.md        # 📚 Detailed guide
+│   ├── README_INTEGRATION.md       # 📖 Quick reference
+│   ├── SETUP_INSTRUCTIONS.txt      # 📋 Visual setup
+│   ├── QUICK_REFERENCE.md          # 🚀 Quick ref card
+│   ├── ARCHITECTURE.md             # 🏗️ This file!
+│   └── generate_api_key.php        # 🔑 Key generator
+│
+├── includes/
+│   ├── db.php                      # Database connection
+│   └── auth.php                    # Auth functions
+│
+├── uploads/                        # User uploads (temp)
+│
+├── test_hf_integration.php         # 🧪 Test utility
+├── test_integration.bat            # Windows test script
+├── INTEGRATION_SUMMARY.md          # 📄 Complete summary
+│
+├── .gitignore                      # Git ignore rules
+├── database.sql                    # Database schema
+└── README.md                       # Project README
+
+Legend:
+🔄 = Modified for HF integration
+⚙️ = Configuration file (sensitive!)
+🤗 = Hugging Face specific
+📚 = Documentation
+🧪 = Testing utility
+🔑 = Security/API keys
+```
+
+---
+
+**Made with ❤️ for CaptchaKings.com**  
+**Architecture Design: Multi-layer, Secure, Scalable**  
+**Last Updated: 2024-01-01**
+

SETUP_INSTRUCTIONS.txt

@@ -0,0 +1,296 @@
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                                                                              ║
+║  🚀 SETUP INTEGRASI HUGGING FACE MODEL - CAPTCHAKINGS.COM                  ║
+║                                                                              ║
+║  Model sudah tidak dummy lagi! Sekarang menggunakan AI prediction real      ║
+║  dari Hugging Face Space.                                                    ║
+║                                                                              ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+
+
+📋 LANGKAH-LANGKAH SETUP (Total: 5 menit)
+═══════════════════════════════════════════════════════════════════════════════
+
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ STEP 1: Generate API Key                                                    │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+  1. Buka terminal/command prompt
+  2. Navigate ke folder project:
+     
+     cd C:\Users\Administrator\Desktop\Captchakings.com
+
+  3. Run generator:
+     
+     php HF\generate_api_key.php
+
+  4. Copy salah satu generated key (contoh):
+     
+     a7f3d9e2b1c8f5a6d4e9b2c7f1a5d8e3b6c9f2a7d4e1b8c5f9a3d6e2b1c7f4a8
+
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ STEP 2: Setup Hugging Face Space                                            │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+  1. Buka browser, kunjungi:
+     
+     https://huggingface.co/spaces/doniramdani820/Textbaru
+
+  2. Login ke Hugging Face account Anda
+
+  3. Klik tab "Settings" (icon gear/roda)
+
+  4. Scroll ke bagian "Variables and secrets"
+
+  5. Klik "New secret" button
+
+  6. Isi form:
+     Name:  API_KEY_SECRET
+     Value: [paste key dari Step 1]
+     
+  7. Klik "Save"
+
+  8. PENTING: Restart space jika diminta
+     (Biasanya otomatis restart setelah add secret)
+
+  9. Tunggu hingga status Space = "Running" (biasanya 30-60 detik)
+
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ STEP 3: Update config.php                                                   │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+  1. Buka file config.php dengan text editor
+
+  2. Cari baris ini:
+     
+     define('HF_API_KEY', 'YOUR_HUGGINGFACE_API_KEY');
+
+  3. Ganti dengan key yang sama dari Step 1:
+     
+     define('HF_API_KEY', 'a7f3d9e2b1c8f5a6d4e9b2c7f1a5d8e3b6c9f2a7d4e1b8c5f9a3d6e2b1c7f4a8');
+     
+     ⚠️  Gunakan KEY YANG SAMA dengan yang di Hugging Face!
+
+  4. Save file config.php
+
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ STEP 4: Test Integration                                                    │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+  1. Pastikan web server (XAMPP/WAMP) sudah running
+
+  2. Buka browser, kunjungi:
+     
+     http://localhost/Captchakings.com/test_hf_integration.php
+
+  3. Check semua status indicators:
+     
+     ✓ Hugging Face API URL            → Harus ada URL
+     ✓ Hugging Face API Key             → Harus masked (xxxxxxxx...xxxxxxxx)
+     ✓ PHP Extension: curl              → Loaded
+     ✓ PHP Extension: json              → Loaded
+     ✓ PHP Extension: fileinfo          → Loaded
+     ✅ Semua konfigurasi OK!
+     ✅ Connection successful!
+     ✅ Hugging Face Space is running correctly!
+
+  4. Jika ada ❌ atau ⚠️:
+     - Baca error message
+     - Periksa kembali Step 1-3
+     - Lihat troubleshooting di bawah
+
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ STEP 5: Test Live Prediction                                                │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+  A. Dari Test Page (test_hf_integration.php):
+     
+     1. Scroll ke bagian "Live CAPTCHA Test"
+     2. Klik "Choose File"
+     3. Pilih gambar CAPTCHA (test_captcha.html punya contoh)
+     4. Klik "🚀 Test Prediction"
+     5. Tunggu hasil (first time bisa 30-60 detik karena cold start)
+     6. Lihat hasil prediksi dengan confidence score!
+
+  B. Dari Main Website:
+     
+     1. Buka: http://localhost/Captchakings.com/
+     2. Scroll ke section "Demo"
+     3. Upload/drag gambar CAPTCHA
+     4. Klik "Process CAPTCHA"
+     5. Lihat hasil REAL prediction dari AI model! 🎉
+
+
+═══════════════════════════════════════════════════════════════════════════════
+🎉 SELESAI! Integrasi Berhasil!
+═══════════════════════════════════════════════════════════════════════════════
+
+Sekarang sistem Anda menggunakan AI model yang REAL dari Hugging Face!
+
+✅ Prediction REAL (bukan dummy)
+✅ Confidence score REAL
+✅ Support text & object CAPTCHA
+✅ Process time tracking
+
+
+═══════════════════════════════════════════════════════════════════════════════
+🐛 TROUBLESHOOTING
+═══════════════════════════════════════════════════════════════════════════════
+
+
+╔════════════════════════════════════════════════════════════════════════════╗
+║ Problem: "API key not configured"                                          ║
+╚════════════════════════════════════════════════════════════════════════════╝
+
+  ❌ Cause: API key di config.php masih default
+
+  ✅ Solution:
+     1. Check config.php
+     2. Pastikan BUKAN 'YOUR_HUGGINGFACE_API_KEY'
+     3. Harus API key yang real
+
+
+╔════════════════════════════════════════════════════════════════════════════╗
+║ Problem: "Connection Error" atau "Connection timeout"                      ║
+╚════════════════════════════════════════════════════════════════════════════╝
+
+  ❌ Possible Causes:
+     - Hugging Face Space sedang sleep (cold start)
+     - Internet connection issue
+     - Space sedang building/restarting
+
+  ✅ Solutions:
+     1. Buka Space URL di browser untuk "wake up":
+        https://doniramdani820-textbaru.hf.space/
+        
+     2. Tunggu 30-60 detik untuk cold start
+     
+     3. Check internet connection
+     
+     4. Check Space status di Hugging Face (harus "Running")
+
+
+╔════════════════════════════════════════════════════════════════════════════╗
+║ Problem: "Akses ditolak" (HTTP 403)                                        ║
+╚═════���══════════════════════════════════════════════════════════════════════╝
+
+  ❌ Cause: API key tidak match
+
+  ✅ Solution:
+     API key di config.php HARUS SAMA PERSIS dengan API_KEY_SECRET di HF Space!
+     
+     1. Check API_KEY_SECRET di Hugging Face Space Settings
+     2. Check HF_API_KEY di config.php
+     3. Pastikan match persis (no extra spaces/newlines)
+     4. If needed, delete & create new secret
+
+
+╔════════════════════════════════════════════════════════════════════════════╗
+║ Problem: PHP Extension not loaded (curl/json/fileinfo)                     ║
+╚════════════════════════════════════════════════════════════════════════════╝
+
+  ❌ Cause: PHP extension tidak terinstall
+
+  ✅ Solution:
+     
+     Windows (XAMPP/WAMP):
+     1. Open php.ini
+     2. Uncomment (remove ;):
+        extension=curl
+        extension=json
+        extension=fileinfo
+     3. Restart Apache
+     
+     Linux:
+     sudo apt-get install php-curl php-json
+     sudo systemctl restart apache2
+
+
+╔════════════════════════════════════════════════════════════════════════════╗
+║ Problem: Space status "Building" atau "Sleeping"                           ║
+╚════════════════════════════════════════════════════════════════════════════╝
+
+  ❌ Cause: Space tidak ready
+
+  ✅ Solution:
+     1. Wait for status to become "Running"
+     2. Building biasanya 2-5 menit (pertama kali)
+     3. Sleeping: kunjungi URL untuk wake up
+     4. Monitor logs di Hugging Face Space page
+
+
+╔════════════════════════════════════════════════════════════════════════════╗
+║ Problem: Prediction lambat (> 10 detik)                                    ║
+╚════════════════════════════════════════════════════════════════════════════╝
+
+  ❌ Cause: Cold start atau model loading
+
+  ✅ Solutions:
+     
+     A. Keep Space Awake (Recommended):
+        - Ping space setiap 10 menit
+        - Create cron job (Linux) atau Task Scheduler (Windows)
+        - Command: curl https://doniramdani820-textbaru.hf.space/
+     
+     B. Upgrade Hugging Face Plan:
+        - Free tier: Space sleep after inactivity
+        - Pro plan: Persistent space (no sleep)
+     
+     C. Optimize:
+        - Resize image before upload
+        - Use PNG/JPEG (not GIF)
+        - Keep image size < 500KB
+
+
+═══════════════════════════════════════════════════════════════════════════════
+📚 DOKUMENTASI LENGKAP
+═══════════════════════════════════════════════════════════════════════════════
+
+  📖 Panduan Detail:       HF\INTEGRATION_GUIDE.md
+  📝 Changelog & Info:     HF\README_INTEGRATION.md
+  🧪 Test Utility:         test_hf_integration.php
+  🔑 API Key Generator:    HF\generate_api_key.php
+
+
+═══════════════════════════════════════════════════════════════════════════════
+🔐 SECURITY CHECKLIST
+═══════════════════════════════════════════════════════════════════════════════
+
+  Before Production:
+  
+  [ ] API key TIDAK di-commit ke Git
+  [ ] Add config.php ke .gitignore
+  [ ] HTTPS enabled
+  [ ] Error reporting OFF (production)
+  [ ] File upload validation active
+  [ ] Rate limiting implemented
+  [ ] Monitoring & logging active
+  [ ] Backup strategy ready
+
+
+═══════════════════════════���═══════════════════════════════════════════════════
+📞 NEED HELP?
+═══════════════════════════════════════════════════════════════════════════════
+
+  1. Run test page: test_hf_integration.php
+  2. Check error logs (PHP & Hugging Face)
+  3. Read INTEGRATION_GUIDE.md
+  4. Verify all configurations
+  5. Check Hugging Face Space status & logs
+
+
+═══════════════════════════════════════════════════════════════════════════════
+
+  Made with ❤️ for CaptchaKings.com
+  Model: Multi-head CAPTCHA Prediction (Text + Object)
+  Powered by: Hugging Face Spaces + PyTorch
+  
+  👑 Raja Otomatisasi CAPTCHA
+  
+═══════════════════════════════════════════════════════════════════════════════
+

app.py

@@ -1,6 +1,7 @@
 # server.py
 # Server Flask untuk prediksi multi-head captcha yang disesuaikan untuk Hugging Face Spaces.
 # Versi ini sudah dioptimalkan untuk memuat model yang terkuantisasi (INT8).
+# Dengan tambahan cropping otomatis menggunakan YOLO sebelum prediksi.
 
 from flask import Flask, request, jsonify
 from flask_cors import CORS
@@ -18,6 +19,7 @@ import base64
 from io import BytesIO
 import sys
 import logging
+from ultralytics import YOLO
 
 torch.set_num_threads(1)
 
@@ -33,6 +35,7 @@ MODEL = None
 MAPPINGS = None
 DEVICE = None
 TRANSFORMS = None
+YOLO_MODEL = None
 
 # ==============================================================================
 #  BAGIAN 2: DEFINISI MODEL (TIDAK ADA PERUBAHAN)
@@ -77,9 +80,60 @@ class MultiHeadModel(nn.Module):
         return type_logits, object_logits, text_log_probs
 
 # ==============================================================================
-#  BAGIAN 3: FUNGSI HELPER (TIDAK ADA PERUBAHAN)
+#  BAGIAN 3: FUNGSI HELPER (TERMASUK CROPPING)
 # ==============================================================================
 
+def crop_image_with_yolo(image_array):
+    """
+    Crop gambar menggunakan YOLO untuk mendeteksi area captcha.
+    
+    Args:
+        image_array: numpy array gambar dalam format RGB
+        
+    Returns:
+        numpy array gambar yang sudah di-crop, atau gambar asli jika tidak ada deteksi
+    """
+    global YOLO_MODEL
+    
+    if YOLO_MODEL is None:
+        logging.warning("YOLO model tidak tersedia, menggunakan gambar asli tanpa crop")
+        return image_array
+    
+    try:
+        # YOLO membutuhkan format BGR untuk prediksi
+        image_bgr = cv2.cvtColor(image_array, cv2.COLOR_RGB2BGR)
+        
+        # Prediksi menggunakan YOLO
+        results = YOLO_MODEL.predict(image_bgr, verbose=False, device="cpu")
+        
+        if not results[0].boxes or len(results[0].boxes) == 0:
+            logging.info("Tidak ada objek terdeteksi oleh YOLO, menggunakan gambar asli")
+            return image_array
+        
+        # Ambil box dengan confidence tertinggi
+        best_box = sorted(results[0].boxes, key=lambda box: box.conf, reverse=True)[0]
+        x1, y1, x2, y2 = best_box.xyxy[0].cpu().numpy().astype(int)
+        
+        # Crop gambar (YOLO bekerja pada BGR, jadi crop dari image_bgr)
+        cropped_bgr = image_bgr[y1:y2, x1:x2]
+        
+        if cropped_bgr is None or cropped_bgr.size == 0:
+            logging.warning("Crop kosong, menggunakan gambar asli")
+            return image_array
+        
+        # Convert kembali ke RGB
+        cropped_rgb = cv2.cvtColor(cropped_bgr, cv2.COLOR_BGR2RGB)
+        
+        confidence = best_box.conf.item()
+        logging.info(f"Gambar berhasil di-crop dengan confidence: {confidence:.2%}")
+        
+        return cropped_rgb
+        
+    except Exception as e:
+        logging.error(f"Error saat cropping dengan YOLO: {e}", exc_info=True)
+        logging.info("Menggunakan gambar asli tanpa crop")
+        return image_array
+
 def get_transforms(img_height, img_width):
     interpolation_method = cv2.INTER_AREA
     return A.Compose([
@@ -113,14 +167,28 @@ def ctc_decoder_with_confidence(log_probs, idx_to_char_map, blank_idx):
     return final_text, avg_confidence
 
 # ==============================================================================
-#  BAGIAN 4: INISIALISASI SERVER (VERSI UNTUK MODEL KUANTISASI)
+#  BAGIAN 4: INISIALISASI SERVER (VERSI UNTUK MODEL KUANTISASI + YOLO)
 # ==============================================================================
 
-def initialize_server(model_path, mappings_path):
-    global MODEL, MAPPINGS, DEVICE, TRANSFORMS
-    logging.info("Memulai inisialisasi server dengan model terkuantisasi...")
+def initialize_server(model_path, mappings_path, yolo_model_path=None):
+    global MODEL, MAPPINGS, DEVICE, TRANSFORMS, YOLO_MODEL
+    logging.info("Memulai inisialisasi server dengan model terkuantisasi dan YOLO cropping...")
     DEVICE = torch.device("cpu") # Kuantisasi INT8 dioptimalkan untuk CPU
     logging.info(f"Menggunakan device: {DEVICE}")
+    
+    # Load YOLO model untuk cropping
+    if yolo_model_path and os.path.exists(yolo_model_path):
+        try:
+            YOLO_MODEL = YOLO(yolo_model_path)
+            logging.info(f"YOLO model berhasil dimuat dari: {yolo_model_path}")
+        except Exception as e:
+            logging.error(f"Gagal memuat YOLO model: {e}")
+            logging.info("Server akan berjalan tanpa fitur auto-cropping")
+            YOLO_MODEL = None
+    else:
+        logging.warning(f"YOLO model tidak ditemukan di: {yolo_model_path}")
+        logging.info("Server akan berjalan tanpa fitur auto-cropping")
+        YOLO_MODEL = None
 
     try:
         if not os.path.exists(mappings_path):
@@ -220,8 +288,14 @@ def predict_endpoint():
         return jsonify({"error": "Gagal memproses gambar."}), 500
 
     try:
+        # Step 1: Convert gambar ke numpy array
         image_rgb = np.array(img_pil)
-        img_tensor = TRANSFORMS(image=image_rgb)['image'].unsqueeze(0).to(DEVICE)
+        
+        # Step 2: Crop gambar menggunakan YOLO (jika tersedia)
+        cropped_image = crop_image_with_yolo(image_rgb)
+        
+        # Step 3: Transform dan convert ke tensor untuk prediksi
+        img_tensor = TRANSFORMS(image=cropped_image)['image'].unsqueeze(0).to(DEVICE)
 
         with torch.no_grad():
             type_logits, object_logits, text_log_probs = MODEL(img_tensor)
@@ -263,9 +337,10 @@ def predict_endpoint():
 # Menggunakan file model baru yang sudah terkuantisasi
 MODEL_FILE_PATH = "best_model_quantized.pth"
 MAPPINGS_FILE_PATH = "mappings.json"
+YOLO_MODEL_FILE_PATH = "best_model.onnx"  # YOLO model untuk cropping
 
 # Inisialisasi server saat aplikasi dimulai
-initialize_server(MODEL_FILE_PATH, MAPPINGS_FILE_PATH)
+initialize_server(MODEL_FILE_PATH, MAPPINGS_FILE_PATH, YOLO_MODEL_FILE_PATH)
 
 # Berguna untuk pengujian lokal
 if __name__ == '__main__':

best_model copy.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2ec634c29dcbfebf68a802163da23c3047dc9acd9ae6b1e5d0c07033f97013f6
+size 103606591

generate_api_key.php

@@ -0,0 +1,56 @@
+<?php
+/**
+ * API Key Generator
+ * Generate secure random API keys untuk Hugging Face authentication
+ */
+
+function generateSecureAPIKey($length = 32) {
+    // Generate random bytes
+    $randomBytes = random_bytes($length);
+    
+    // Convert to hexadecimal
+    $hexKey = bin2hex($randomBytes);
+    
+    return $hexKey;
+}
+
+// Generate 3 different API keys
+echo "=================================================\n";
+echo "   🔐 Secure API Key Generator for HF Space\n";
+echo "=================================================\n\n";
+
+echo "Generated API Keys (pilih salah satu):\n\n";
+
+for ($i = 1; $i <= 3; $i++) {
+    $apiKey = generateSecureAPIKey();
+    echo "API Key #{$i}:\n";
+    echo $apiKey . "\n\n";
+}
+
+echo "=================================================\n";
+echo "Setup Instructions:\n";
+echo "=================================================\n\n";
+
+echo "1. HUGGING FACE SPACE:\n";
+echo "   - Buka: https://huggingface.co/spaces/doniramdani820/Textbaru\n";
+echo "   - Klik: Settings → Variables and secrets\n";
+echo "   - Add Secret:\n";
+echo "     Name: API_KEY_SECRET\n";
+echo "     Value: [paste salah satu key di atas]\n\n";
+
+echo "2. CONFIG.PHP:\n";
+echo "   - Edit file: config.php\n";
+echo "   - Update HF_API_KEY dengan key yang sama\n";
+echo "   define('HF_API_KEY', 'paste_key_disini');\n\n";
+
+echo "3. VERIFY:\n";
+echo "   - Buka: http://localhost/Captchakings.com/test_hf_integration.php\n";
+echo "   - Check status: semua harus hijau ✅\n\n";
+
+echo "⚠️  SECURITY WARNING:\n";
+echo "   - JANGAN share API key ke siapa pun\n";
+echo "   - JANGAN commit API key ke Git\n";
+echo "   - Simpan di tempat yang aman\n";
+echo "=================================================\n";
+?>
+

gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

requirements.txt

@@ -9,4 +9,5 @@ torch==2.0.1
 torchvision==0.15.2
 timm
 albumentations
-opencv-python-headless==4.8.0.74
+opencv-python-headless==4.8.0.74
+ultralytics>=8.0.0