mike-elistra/humanize-e-adapter

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

Quick Start

Local Installation

# Install dependencies
pip install -r requirements.txt

# Run the server
python app.py
# Open http://localhost:8000

Docker

# 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

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:

{
  "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:

{"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

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

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

# 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
• 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:

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:

# 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!