|
Download README.md from mike-elistra/humanize-e-adapter: direct link, hf CLI and curl.
- Browser
- Download file 5.83 kB
-
https://huggingface.co/mike-elistra/humanize-e-adapter/resolve/main/README.md
- Command line
-
hf download hf://mike-elistra/humanize-e-adapter/README.md
-
curl -L -o README.md https://huggingface.co/mike-elistra/humanize-e-adapter/resolve/main/README.md
5.83 kB
| # 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! |