llm-gguf-tools/docs/development.md

Development Guide

This guide covers development setup, code quality standards, and project structure for contributors.

Code Quality

# Run linting
uv run ruff check

# Format code
uv run ruff format

# Run with debug logging
DEBUG=true uv run <script>

Project Structure

llm-gguf-tools/
├── quantise.py                    # Bartowski quantisation tool
├── direct_safetensors_to_gguf.py  # Direct conversion tool
├── helpers/                       # Shared utilities
│   ├── __init__.py
│   └── logger.py                  # Colour-coded logging
├── resources/                     # Resource files
│   └── imatrix_data.txt          # Calibration data for imatrix
├── docs/                          # Detailed documentation
│   ├── quantise.md
│   ├── direct_safetensors_to_gguf.md
│   └── development.md
└── pyproject.toml                # Project configuration

Contributing Guidelines

Contributions are welcome! Please ensure:

1. Code follows the existing style (run uv run ruff format)
2. All functions have Google-style docstrings
3. Type hints are used throughout
4. Tests pass (if applicable)

Development Workflow

Setting Up Development Environment

# Clone the repository
git clone https://git.tomfos.tr/tom/llm-gguf-tools.git
cd llm-gguf-tools

# Install all dependencies including dev
uv sync --all-groups

Code Style

• Follow PEP 8 with ruff enforcement
• Use UK English spelling in comments and documentation
• Maximum line length: 100 characters
• Use type hints for all function parameters and returns

Testing

While formal tests are not yet implemented, ensure:

• Scripts run without errors on sample models
• Logger output is correctly formatted
• File I/O operations handle errors gracefully

Debugging

Enable debug logging for verbose output:

DEBUG=true uv run quantise.py <model_url>

This will show additional information about:

• Model download progress
• Conversion steps
• File operations
• Error details