# Development Guide

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

## Code Quality

```bash
# Run linting
uv run ruff check

# Format code
uv run ruff format

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

## Project Structure

```plain
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

```bash
# 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:

```bash
DEBUG=true uv run quantise.py <model_url>
```

This will show additional information about:

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