world44 commited on
Commit
1af44b9
Β·
verified Β·
1 Parent(s): 48d0d60

Upload README.md with huggingface_hub

Browse files
Files changed (1) hide show
  1. README.md +215 -0
README.md ADDED
@@ -0,0 +1,215 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # humanize-e
2
+
3
+ > AI Model to Humanize AI Texts
4
+
5
+ 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.
6
+
7
+ **Developed by Mike Elistra (Mike Koci)**
8
+
9
+ **Training Notebook:** [Kaggle – humanize-e Training](https://www.kaggle.com/code/mick009/notebook9c4e543da9)
10
+
11
+ ## Quick Start
12
+
13
+ ### Local Installation
14
+
15
+ ```bash
16
+ # Install dependencies
17
+ pip install -r requirements.txt
18
+
19
+ # Run the server
20
+ python app.py
21
+ # Open http://localhost:8000
22
+ ```
23
+
24
+ ### Docker
25
+
26
+ ```bash
27
+ # Build
28
+ docker build -t humanize-e .
29
+
30
+ # Run (mount adapter weights)
31
+ docker run -p 8000:8000 -v /path/to/adapter:/app/humanize-e-adapter humanize-e
32
+ ```
33
+
34
+ ## Architecture
35
+
36
+ ```
37
+ humanize-e/
38
+ β”œβ”€β”€ app.py # FastAPI backend with web UI
39
+ β”œβ”€β”€ model.py # HumanizeModel class (inference)
40
+ β”œβ”€β”€ Dockerfile # Container build
41
+ β”œβ”€β”€ requirements.txt # Python dependencies (inference only)
42
+ β”œβ”€β”€ .gitignore # Git ignore patterns
43
+ └── README.md # This file
44
+ ```
45
+
46
+ ## API Endpoints
47
+
48
+ ### POST /humanize
49
+
50
+ ```bash
51
+ curl -X POST http://localhost:8000/humanize \
52
+ -H "Content-Type: application/json" \
53
+ -d '{"text": "In order to provide you with a comprehensive solution, it is important to note that we have conducted extensive research."}'
54
+ ```
55
+
56
+ **Response:**
57
+ ```json
58
+ {
59
+ "original": "In order to provide you with a comprehensive solution, it is important to note that we have conducted extensive research.",
60
+ "humanized": "To give you a comprehensive solution, we've done extensive research.",
61
+ "model": "qwen2.5-3b-lora"
62
+ }
63
+ ```
64
+
65
+ ### GET /health
66
+
67
+ Returns model status:
68
+ ```json
69
+ {"status": "ok", "model": "qwen2.5-3b-lora", "adapter_path": "/app/humanize-e-adapter"}
70
+ ```
71
+
72
+ ## Model Details
73
+
74
+ | Feature | Description |
75
+ |---------|-------------|
76
+ | **Base** | Qwen2.5-3B-Instruct |
77
+ | **Fine-tuning** | PEFT LoRA (r=32, Ξ±=64) |
78
+ | **Quantization** | 4-bit NF4 (GPU) / fp32 (CPU) |
79
+ | **Training Data** | 156 human↔AI-style synthetic pairs from Kaggle AI-vs-Human dataset |
80
+ | **Inference** | CPU/GPU compatible, fallback rule-based when adapter missing |
81
+
82
+ ## Environment Variables
83
+
84
+ | Variable | Default | Description |
85
+ |----------|---------|-------------|
86
+ | `HUMANIZE_BASE_MODEL` | `Qwen/Qwen2.5-3B-Instruct` | HuggingFace model ID |
87
+ | `HUMANIZE_ADAPTER` | `./humanize-e-adapter` | Path to LoRA adapter files |
88
+
89
+ ## Usage in Python
90
+
91
+ ```python
92
+ from model import HumanizeModel
93
+
94
+ model = HumanizeModel()
95
+ result = model.humanize("Your AI-generated text here")
96
+ print(result)
97
+ ```
98
+
99
+ ## Deploying with the Trained Model
100
+
101
+ ### Option 1: Local Drop-in
102
+
103
+ After training, copy adapter files to `humanize-e-adapter/`:
104
+ ```
105
+ humanize-e-adapter/
106
+ β”œβ”€β”€ adapter_config.json
107
+ β”œβ”€β”€ adapter_model.safetensors
108
+ β”œβ”€β”€ tokenizer.json
109
+ β”œβ”€β”€ tokenizer_config.json
110
+ β”œβ”€β”€ vocab.json
111
+ β”œβ”€β”€ merges.txt
112
+ └── special_tokens_map.json
113
+ ```
114
+
115
+ ### Option 2: HuggingFace Hub
116
+
117
+ ```bash
118
+ pip install huggingface_hub
119
+
120
+ # Install
121
+ huggingface-cli login
122
+ huggingface_hub.upload_folder(
123
+ folder_path="path/to/adapter",
124
+ repo_id="your-username/humanize-e-adapter",
125
+ repo_type="model"
126
+ )
127
+
128
+ # Then run:
129
+ HUMANIZE_ADAPTER=your-username/humanize-e-adapter python app.py
130
+ ```
131
+
132
+ ### Option 3: Docker Volume
133
+
134
+ ```bash
135
+ # On HuggingFace Hub
136
+ git lfs install
137
+ git clone https://huggingface.co/your-username/humanize-e-adapter
138
+ docker run -p 8000:8000 -v $(pwd)/humanize-e-adapter:/app/humanize-e-adapter humanize-e
139
+ ```
140
+
141
+ ## Training Notes
142
+
143
+ - Trained on [Kaggle AI vs Human Text Dataset](https://www.kaggle.com/datasets/alitaqishah/ai-vs-human-text-classification-dataset-2026)
144
+ - Synthetic pairs: human texts β†’ AI-style (base model rewrite) β†’ training samples
145
+ - 2 epochs, lr=2e-4, cosine scheduler, weight decay 0.01
146
+ - Loss: cross-entropy, prompt tokens masked (only learn style transfer)
147
+
148
+ ## API Key Management
149
+
150
+ ⚠️ **Security Notice**: This repo may require LLM API keys for generation (not used for inference). Store keys in `.env`:
151
+
152
+ ```env
153
+ HUMANIZE_BASE_MODEL=Qwen/Qwen2.5-3B-Instruct
154
+ HUMANIZE_ADAPTER=/path/to/adapter
155
+ ```
156
+
157
+ ## Development & Training
158
+
159
+ **Developed by:** Mike Elistra (Mike Koci)
160
+
161
+ **Kaggle Training Notebook:** https://www.kaggle.com/code/mick009/notebook9c4e543da9
162
+
163
+ The model was fine-tuned on Kaggle using QLoRA on Qwen2.5-3B-Instruct. The notebook contains the complete training pipeline:
164
+ - Synthetic AI-style generation
165
+ - QLoRA fine-tuning
166
+ - Evaluation metrics
167
+ - Adapter export
168
+
169
+ To retrain or experiment, open the Kaggle notebook and run all cells. The trained adapter should be exported to `humanize-e-adapter/`.
170
+
171
+ ## Testing
172
+
173
+ Run unit tests to verify functionality:
174
+
175
+ ```bash
176
+ # Run all tests
177
+ python -m unittest discover -s tests -p 'test_*.py'
178
+
179
+ # Or run specific test
180
+ python -m unittest tests.test_app.TestAPIEndpoints.test_health_endpoint
181
+ ```
182
+
183
+ Tests cover:
184
+ - Model fallback mode (no adapter)
185
+ - Rule-based humanizer
186
+ - FastAPI endpoints (/health, /humanize, /)
187
+ - Input validation
188
+
189
+ CI runs automatically on every push via GitHub Actions.
190
+
191
+ ## Contributing
192
+
193
+ Contributions are welcome! This project is open for anyone to improve, extend, or fix.
194
+
195
+ **How to contribute:**
196
+ 1. Fork the repository
197
+ 2. Create a feature branch (`git checkout -b feature/your-feature`)
198
+ 3. Make your changes and add tests if applicable
199
+ 4. Run tests locally to ensure everything works
200
+ 5. Commit your changes (`git commit -m 'Add your feature'`)
201
+ 6. Push to your fork and open a Pull Request
202
+
203
+ **Ideas for contributions:**
204
+ - Improved humanization rules for the fallback mode
205
+ - Support for additional base models
206
+ - Performance optimizations
207
+ - Better UI/UX for the web interface
208
+ - Docker improvements
209
+ - Documentation enhancements
210
+
211
+ Everyone is welcome to edit, improve, and contribute to humanize-e!
212
+
213
+ ## License
214
+
215
+ MIT - Feel free to use, modify, and train on your own data!