<div align="center">
<img src="docs/logo.png" alt="Atuna Logo" width="200" />
**A tasty layer on top of Unsloth for Large Language Model fine-tuning**
</div>
Atuna: A fine-tuning assistant for large language models with built-in hyperparameter optimization.
## Features
- **Easy fine-tuning** with Unsloth integration for efficient training
- **Hyperparameter optimization** with Optuna for automated tuning
- **Built-in evaluation** and monitoring capabilities
- **TensorBoard integration** for training visualization
## Installation
### From source (development)
```bash
git clone https://github.com/mapa17/atuna.git
cd atuna
uv sync
uv pip install -e .
```
### Using the library
```bash
pip install atuna # When published to PyPI
```
## Quick Start
### Basic Fine-tuning
```python
from tuna import Tuna, TunaConfig, TrainingConfig, model_registry
# Configure your model
model = model_registry["unsloth/Qwen3-4B-Instruct-2507"]
config = TunaConfig(
model_cfg=model,
dataset_path="./data/training_set.csv",
max_seq_length=2048,
precision=16, # Use 16-bit precision
)
# Create trainer
tuna = Tuna(config=config)
# Configure training
training_config = TrainingConfig(
num_train_epochs=3,
batch_size=1,
learning_rate=5e-5,
eval_epochs=1.0,
enable_early_stopping=True,
)
# Train the model
result = tuna.train(config=training_config)
print(f"Training completed: {result.stop_reason}")
```
### Hyperparameter Optimization
```python
from tuna import Tuna, TunaConfig, TrainingConfig, HyperparpamConfig, model_registry
# Setup configuration
model = model_registry["unsloth/Qwen3-4B-Instruct-2507"]
config = TunaConfig(
model_cfg=model,
dataset_path="./data/training_set.csv",
max_seq_length=2048,
precision=4, # Use 4-bit quantization for efficiency
)
tuna = Tuna(config=config)
# Configure training
training_config = TrainingConfig(
num_train_epochs=2,
eval_epochs=0.25,
batch_size=1,
data_sample=0.3, # Use subset for faster experimentation
)
# Configure hyperparameter search
hyper_config = HyperparpamConfig(
n_trials=10,
learning_rate=[1e-5, 5e-5, 7e-5, 1e-4],
weight_decay=[0.001, 0.01, 0.1],
peft_r=[16, 32],
lora_alpha=[32, 50, 64],
enable_slora=True,
)
# Run optimization
study = tuna.hyperparam_tune(
study_name="MyOptimization",
train_config=training_config,
hyper_config=hyper_config,
)
print(f"Best parameters: {study.best_trial.params}")
```
### Model Evaluation
```python
# Evaluate trained model
responses = tuna.evaluate_prompts([
"What is machine learning?",
"Explain fine-tuning in simple terms.",
])
for response in responses:
print(f"Response: {response}")
```
## CLI Usage
```bash
# Show version
tuna --version
# List available models
tuna --list-models
```
## Data Format
Your training data should be a CSV file with `request` and `response` columns:
```csv
request,response
"What is Python?","Python is a programming language..."
"How does machine learning work?","Machine learning works by..."
```
## Monitoring and Visualization
### Optuna Dashboard
```bash
# View hyperparameter optimization results
optuna-dashboard sqlite:///./atuna_workspace/optuna_studies.db
```
### TensorBoard
```bash
# View training metrics
tensorboard --logdir ./atuna_workspace/logs
```
## Supported Models
- `unsloth/Qwen3-4B-Instruct-2507`
- `unsloth/Qwen3-0.6B-GGUF`
More models can be easily added to the `model_registry`.
## Configuration Options
### TunaConfig
- `model_cfg`: Model configuration from registry
- `dataset_path`: Path to training CSV file
- `max_seq_length`: Maximum sequence length (default: 2048)
- `precision`: Training precision - 4, 8, or 16 bit (default: 16)
- `peft_r`: LoRA rank parameter (default: 32)
- `workspace`: Working directory (default: "./atuna_workspace")
### TrainingConfig
- `learning_rate`: Learning rate (default: 2e-5)
- `batch_size`: Batch size (default: 1)
- `num_train_epochs`: Number of training epochs (default: 1.0)
- `eval_epochs`: Evaluation frequency in epochs
- `enable_early_stopping`: Enable early stopping (default: True)
- `data_sample`: Fraction of data to use (default: 1.0)
### HyperparpamConfig
- `n_trials`: Number of optimization trials
- `learning_rate`: List of learning rates to try
- `peft_r`: List of LoRA rank values to try
- `lora_alpha`: List of LoRA alpha values to try
- `weight_decay`: List of weight decay values to try
## Examples
See the `examples/` directory for complete usage examples:
- `examples/basic_finetuning.py` - Basic fine-tuning workflow
- `examples/hyperparameter_search.py` - Hyperparameter optimization
## Requirements
- Python 3.12+
- CUDA-capable GPU
- See `pyproject.toml` for full dependency list
## Development
```bash
# Clone repository
git clone https://github.com/mapa17/atuna.git
cd atuna
# Install development dependencies
uv sync --group dev
# Install pre-commit hooks
pre-commit install
# Run tests
pytest
# Build package
uv build
```
## License
MIT License - see LICENSE file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Raw data
{
"_id": null,
"home_page": null,
"name": "atuna",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "fine-tuning, llm, machine-learning, optuna, transformers, unsloth",
"author": null,
"author_email": "Pasieka Manuel <manuel.pasieka@protonmail.ch>",
"download_url": "https://files.pythonhosted.org/packages/cd/91/441a529eaaa6835a9a97d115f879d24ff59a05c9d1cdd2cf20975668639b/atuna-0.3.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img src=\"docs/logo.png\" alt=\"Atuna Logo\" width=\"200\" />\n\n **A tasty layer on top of Unsloth for Large Language Model fine-tuning**\n</div>\n\nAtuna: A fine-tuning assistant for large language models with built-in hyperparameter optimization.\n\n## Features\n\n- **Easy fine-tuning** with Unsloth integration for efficient training\n- **Hyperparameter optimization** with Optuna for automated tuning\n- **Built-in evaluation** and monitoring capabilities\n- **TensorBoard integration** for training visualization\n\n## Installation\n\n### From source (development)\n\n```bash\ngit clone https://github.com/mapa17/atuna.git\ncd atuna\nuv sync\nuv pip install -e .\n```\n\n### Using the library\n\n```bash\npip install atuna # When published to PyPI\n```\n\n## Quick Start\n\n### Basic Fine-tuning\n\n```python\nfrom tuna import Tuna, TunaConfig, TrainingConfig, model_registry\n\n# Configure your model\nmodel = model_registry[\"unsloth/Qwen3-4B-Instruct-2507\"]\nconfig = TunaConfig(\n model_cfg=model,\n dataset_path=\"./data/training_set.csv\",\n max_seq_length=2048,\n precision=16, # Use 16-bit precision\n)\n\n# Create trainer\ntuna = Tuna(config=config)\n\n# Configure training\ntraining_config = TrainingConfig(\n num_train_epochs=3,\n batch_size=1,\n learning_rate=5e-5,\n eval_epochs=1.0,\n enable_early_stopping=True,\n)\n\n# Train the model\nresult = tuna.train(config=training_config)\nprint(f\"Training completed: {result.stop_reason}\")\n```\n\n### Hyperparameter Optimization\n\n```python\nfrom tuna import Tuna, TunaConfig, TrainingConfig, HyperparpamConfig, model_registry\n\n# Setup configuration\nmodel = model_registry[\"unsloth/Qwen3-4B-Instruct-2507\"]\nconfig = TunaConfig(\n model_cfg=model,\n dataset_path=\"./data/training_set.csv\",\n max_seq_length=2048,\n precision=4, # Use 4-bit quantization for efficiency\n)\n\ntuna = Tuna(config=config)\n\n# Configure training\ntraining_config = TrainingConfig(\n num_train_epochs=2,\n eval_epochs=0.25,\n batch_size=1,\n data_sample=0.3, # Use subset for faster experimentation\n)\n\n# Configure hyperparameter search\nhyper_config = HyperparpamConfig(\n n_trials=10,\n learning_rate=[1e-5, 5e-5, 7e-5, 1e-4],\n weight_decay=[0.001, 0.01, 0.1],\n peft_r=[16, 32],\n lora_alpha=[32, 50, 64],\n enable_slora=True,\n)\n\n# Run optimization\nstudy = tuna.hyperparam_tune(\n study_name=\"MyOptimization\",\n train_config=training_config,\n hyper_config=hyper_config,\n)\n\nprint(f\"Best parameters: {study.best_trial.params}\")\n```\n\n### Model Evaluation\n\n```python\n# Evaluate trained model\nresponses = tuna.evaluate_prompts([\n \"What is machine learning?\",\n \"Explain fine-tuning in simple terms.\",\n])\n\nfor response in responses:\n print(f\"Response: {response}\")\n```\n\n## CLI Usage\n\n```bash\n# Show version\ntuna --version\n\n# List available models\ntuna --list-models\n```\n\n## Data Format\n\nYour training data should be a CSV file with `request` and `response` columns:\n\n```csv\nrequest,response\n\"What is Python?\",\"Python is a programming language...\"\n\"How does machine learning work?\",\"Machine learning works by...\"\n```\n\n## Monitoring and Visualization\n\n### Optuna Dashboard\n```bash\n# View hyperparameter optimization results\noptuna-dashboard sqlite:///./atuna_workspace/optuna_studies.db\n```\n\n### TensorBoard\n```bash\n# View training metrics\ntensorboard --logdir ./atuna_workspace/logs\n```\n\n## Supported Models\n\n- `unsloth/Qwen3-4B-Instruct-2507`\n- `unsloth/Qwen3-0.6B-GGUF`\n\nMore models can be easily added to the `model_registry`.\n\n## Configuration Options\n\n### TunaConfig\n- `model_cfg`: Model configuration from registry\n- `dataset_path`: Path to training CSV file\n- `max_seq_length`: Maximum sequence length (default: 2048)\n- `precision`: Training precision - 4, 8, or 16 bit (default: 16)\n- `peft_r`: LoRA rank parameter (default: 32)\n- `workspace`: Working directory (default: \"./atuna_workspace\")\n\n### TrainingConfig\n- `learning_rate`: Learning rate (default: 2e-5)\n- `batch_size`: Batch size (default: 1)\n- `num_train_epochs`: Number of training epochs (default: 1.0)\n- `eval_epochs`: Evaluation frequency in epochs\n- `enable_early_stopping`: Enable early stopping (default: True)\n- `data_sample`: Fraction of data to use (default: 1.0)\n\n### HyperparpamConfig\n- `n_trials`: Number of optimization trials\n- `learning_rate`: List of learning rates to try\n- `peft_r`: List of LoRA rank values to try\n- `lora_alpha`: List of LoRA alpha values to try\n- `weight_decay`: List of weight decay values to try\n\n## Examples\n\nSee the `examples/` directory for complete usage examples:\n\n- `examples/basic_finetuning.py` - Basic fine-tuning workflow\n- `examples/hyperparameter_search.py` - Hyperparameter optimization\n\n## Requirements\n\n- Python 3.12+\n- CUDA-capable GPU\n- See `pyproject.toml` for full dependency list\n\n## Development\n\n```bash\n# Clone repository\ngit clone https://github.com/mapa17/atuna.git\ncd atuna\n\n# Install development dependencies\nuv sync --group dev\n\n# Install pre-commit hooks\npre-commit install\n\n# Run tests\npytest\n\n# Build package\nuv build\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Fine-tuning assistant for large language models",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/mapa17/atuna",
"Issues": "https://github.com/mapa17/atuna/issues",
"Repository": "https://github.com/mapa17/atuna"
},
"split_keywords": [
"fine-tuning",
" llm",
" machine-learning",
" optuna",
" transformers",
" unsloth"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "078b60d06263ad7860df787f2eaedf4c2d0cb24ee65a66951f4d7f971d5902eb",
"md5": "5995b8393467887853fd64860c804ea3",
"sha256": "3f613ee6e5ed8001c2014db58b2aa4a9a3ee449732cbdb44286684dd565ddb27"
},
"downloads": -1,
"filename": "atuna-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5995b8393467887853fd64860c804ea3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 4274,
"upload_time": "2025-11-06T01:14:31",
"upload_time_iso_8601": "2025-11-06T01:14:31.661520Z",
"url": "https://files.pythonhosted.org/packages/07/8b/60d06263ad7860df787f2eaedf4c2d0cb24ee65a66951f4d7f971d5902eb/atuna-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cd91441a529eaaa6835a9a97d115f879d24ff59a05c9d1cdd2cf20975668639b",
"md5": "412595a488efbbb0d85fdbc5d6a89944",
"sha256": "36baa3678cd02f5a40a2f4bd8665627a97daaaa7cbc40594cfa785e6258397df"
},
"downloads": -1,
"filename": "atuna-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "412595a488efbbb0d85fdbc5d6a89944",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 14828,
"upload_time": "2025-11-06T01:14:33",
"upload_time_iso_8601": "2025-11-06T01:14:33.019919Z",
"url": "https://files.pythonhosted.org/packages/cd/91/441a529eaaa6835a9a97d115f879d24ff59a05c9d1cdd2cf20975668639b/atuna-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-06 01:14:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mapa17",
"github_project": "atuna",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "atuna"
}
JSON
