Spaces:
Configuration error
Configuration error
File size: 7,665 Bytes
6595ce6 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 | # humanize-e
<img width="1024" height="559" alt="image" src="https://github.com/user-attachments/assets/b647751e-da57-4fa8-8175-b60800c44440" />
> 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)
**HuggingFace Model:** [mike-elistra/humanize-e-adapter](https://huggingface.co/mike-elistra/humanize-e-adapter)
## 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 |
## Getting the Model Weights
### Base Model Qwen2.5-3B-Instruct
The base model is downloaded automatically from HuggingFace on first run. You can also cache it manually:
```bash
huggingface-cli download Qwen/Qwen2.5-3B-Instruct --local-dir ./models/qwen2.5-3b-instruct
```
Then set:
```env
HUMANIZE_BASE_MODEL=./models/qwen2.5-3b-instruct
```
### LoRA Adapter Weights
The trained LoRA adapter was created on Kaggle. Download it from the training notebook outputs:
1. Open [Kaggle Notebook](https://www.kaggle.com/code/mick009/notebook9c4e543da9)
2. Download the `model_files.zip` output
3. Extract to `humanize-e-adapter/`:
```
humanize-e-adapter/
βββ adapter_config.json
βββ adapter_model.safetensors
βββ tokenizer.json
βββ ...
```
4. Run with local path:
```bash
HUMANIZE_ADAPTER=./humanize-e-adapter python app.py
```
### Uploading Weights to HuggingFace
To share the adapter:
```bash
pip install huggingface_hub
huggingface-cli login
python upload_adapter_to_hf.py
```
Or manually:
```python
from huggingface_hub import upload_folder
upload_folder(
folder_path="./humanize-e-adapter",
repo_id="mike-elistra/humanize-e-adapter",
repo_type="model"
)
```
### Uploading Weights to GitHub
Adapter files are large β use Git LFS:
```bash
git lfs install
git lfs track "humanize-e-adapter/*"
git add .gitattributes humanize-e-adapter/
git commit -m "Add LoRA adapter weights"
git push origin main
```
The repo is already configured with `.gitattributes` for LFS. Keep weights in `humanize-e-adapter/` and push with LFS.
## 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="mike-elistra/humanize-e-adapter",
repo_type="model"
)
# Then run:
HUMANIZE_ADAPTER=mike-elistra/humanize-e-adapter python app.py
```
### Option 3: Docker Volume
```bash
# On HuggingFace Hub
git lfs install
git clone https://huggingface.co/mike-elistra/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!
|