# humanize-e > AI Model to Humanize AI Texts A PyTorch-based transformer model (QLoRA fine-tune of Qwen2.5-3B-Instruct) that rewrites AI-generated text to sound more natural and human-written. **Developed by Mike Elistra (Mike Koci)** **Training Notebook:** [Kaggle – humanize-e Training](https://www.kaggle.com/code/mick009/notebook9c4e543da9) ## Quick Start ### Local Installation ```bash # Install dependencies pip install -r requirements.txt # Run the server python app.py # Open http://localhost:8000 ``` ### Docker ```bash # Build docker build -t humanize-e . # Run (mount adapter weights) docker run -p 8000:8000 -v /path/to/adapter:/app/humanize-e-adapter humanize-e ``` ## Architecture ``` humanize-e/ ├── app.py # FastAPI backend with web UI ├── model.py # HumanizeModel class (inference) ├── Dockerfile # Container build ├── requirements.txt # Python dependencies (inference only) ├── .gitignore # Git ignore patterns └── README.md # This file ``` ## API Endpoints ### POST /humanize ```bash curl -X POST http://localhost:8000/humanize \ -H "Content-Type: application/json" \ -d '{"text": "In order to provide you with a comprehensive solution, it is important to note that we have conducted extensive research."}' ``` **Response:** ```json { "original": "In order to provide you with a comprehensive solution, it is important to note that we have conducted extensive research.", "humanized": "To give you a comprehensive solution, we've done extensive research.", "model": "qwen2.5-3b-lora" } ``` ### GET /health Returns model status: ```json {"status": "ok", "model": "qwen2.5-3b-lora", "adapter_path": "/app/humanize-e-adapter"} ``` ## Model Details | Feature | Description | |---------|-------------| | **Base** | Qwen2.5-3B-Instruct | | **Fine-tuning** | PEFT LoRA (r=32, α=64) | | **Quantization** | 4-bit NF4 (GPU) / fp32 (CPU) | | **Training Data** | 156 human↔AI-style synthetic pairs from Kaggle AI-vs-Human dataset | | **Inference** | CPU/GPU compatible, fallback rule-based when adapter missing | ## Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `HUMANIZE_BASE_MODEL` | `Qwen/Qwen2.5-3B-Instruct` | HuggingFace model ID | | `HUMANIZE_ADAPTER` | `./humanize-e-adapter` | Path to LoRA adapter files | ## Usage in Python ```python from model import HumanizeModel model = HumanizeModel() result = model.humanize("Your AI-generated text here") print(result) ``` ## Deploying with the Trained Model ### Option 1: Local Drop-in After training, copy adapter files to `humanize-e-adapter/`: ``` humanize-e-adapter/ ├── adapter_config.json ├── adapter_model.safetensors ├── tokenizer.json ├── tokenizer_config.json ├── vocab.json ├── merges.txt └── special_tokens_map.json ``` ### Option 2: HuggingFace Hub ```bash pip install huggingface_hub # Install huggingface-cli login huggingface_hub.upload_folder( folder_path="path/to/adapter", repo_id="your-username/humanize-e-adapter", repo_type="model" ) # Then run: HUMANIZE_ADAPTER=your-username/humanize-e-adapter python app.py ``` ### Option 3: Docker Volume ```bash # On HuggingFace Hub git lfs install git clone https://huggingface.co/your-username/humanize-e-adapter docker run -p 8000:8000 -v $(pwd)/humanize-e-adapter:/app/humanize-e-adapter humanize-e ``` ## Training Notes - Trained on [Kaggle AI vs Human Text Dataset](https://www.kaggle.com/datasets/alitaqishah/ai-vs-human-text-classification-dataset-2026) - Synthetic pairs: human texts → AI-style (base model rewrite) → training samples - 2 epochs, lr=2e-4, cosine scheduler, weight decay 0.01 - Loss: cross-entropy, prompt tokens masked (only learn style transfer) ## API Key Management ⚠️ **Security Notice**: This repo may require LLM API keys for generation (not used for inference). Store keys in `.env`: ```env HUMANIZE_BASE_MODEL=Qwen/Qwen2.5-3B-Instruct HUMANIZE_ADAPTER=/path/to/adapter ``` ## Development & Training **Developed by:** Mike Elistra (Mike Koci) **Kaggle Training Notebook:** https://www.kaggle.com/code/mick009/notebook9c4e543da9 The model was fine-tuned on Kaggle using QLoRA on Qwen2.5-3B-Instruct. The notebook contains the complete training pipeline: - Synthetic AI-style generation - QLoRA fine-tuning - Evaluation metrics - Adapter export To retrain or experiment, open the Kaggle notebook and run all cells. The trained adapter should be exported to `humanize-e-adapter/`. ## Testing Run unit tests to verify functionality: ```bash # Run all tests python -m unittest discover -s tests -p 'test_*.py' # Or run specific test python -m unittest tests.test_app.TestAPIEndpoints.test_health_endpoint ``` Tests cover: - Model fallback mode (no adapter) - Rule-based humanizer - FastAPI endpoints (/health, /humanize, /) - Input validation CI runs automatically on every push via GitHub Actions. ## Contributing Contributions are welcome! This project is open for anyone to improve, extend, or fix. **How to contribute:** 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/your-feature`) 3. Make your changes and add tests if applicable 4. Run tests locally to ensure everything works 5. Commit your changes (`git commit -m 'Add your feature'`) 6. Push to your fork and open a Pull Request **Ideas for contributions:** - Improved humanization rules for the fallback mode - Support for additional base models - Performance optimizations - Better UI/UX for the web interface - Docker improvements - Documentation enhancements Everyone is welcome to edit, improve, and contribute to humanize-e! ## License MIT - Feel free to use, modify, and train on your own data!