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!