humanize-e-adapter / README.md
world44's picture
Upload README.md with huggingface_hub
1af44b9 verified
|
Raw History Blame Contribute Delete
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!