Realizar GGUF Export - Entrenar - Training & Optimization Library
Description: A comprehensive guide to building neural network training systems with autograd, optimizers, LoRA/QLoRA, and quantization using EXTREME TDD methodology

# Realizar GGUF Export

The ecosystem module provides GGUF export functionality for model quantization and distribution via integration with Realizar.

## Quantization Types

    #![allow(unused)]
    fn main() {
    use entrenar::ecosystem::QuantizationType;

    // Available quantization types
    let types = [
        QuantizationType::Q2K,   // 2.5 bits, extreme compression
        QuantizationType::Q3KM,  // 3.5 bits, aggressive compression
        QuantizationType::Q4KM,  // 4.5 bits, recommended balance
        QuantizationType::Q5KM,  // 5.5 bits, higher quality
        QuantizationType::Q6K,   // 6.5 bits, high quality
        QuantizationType::Q80,   // 8 bits, highest quantized quality
        QuantizationType::F16,   // 16 bits, no quantization
        QuantizationType::F32,   // 32 bits, full precision
    ];
    }

### Quantization Properties

Type | Bits/Weight | Quality Score | Size Ratio
--- | --- | --- | ---
Q2_K | 2.5 | 50 | 0.078x
Q3_K_M | 3.5 | 65 | 0.109x
Q4_K_M | 4.5 | 78 | 0.141x
Q5_K_M | 5.5 | 85 | 0.172x
Q6_K | 6.5 | 92 | 0.203x
Q8_0 | 8.0 | 97 | 0.250x
F16 | 16.0 | 100 | 0.500x
F32 | 32.0 | 100 | 1.000x

### Type Methods

    #![allow(unused)]
    fn main() {
    let quant = QuantizationType::Q4KM;

    println!("Type: {}", quant.as_str());           // "Q4_K_M"
    println!("Bits: {}", quant.bits_per_weight());  // 4.5
    println!("Quality: {}", quant.quality_score()); // 78

    // Estimate output size
    let original_size = 14_000_000_000u64; // 14GB model
    let estimated = quant.estimate_size(original_size);
    println!("Estimated size: {:.2} GB", estimated as f64 / 1e9);
    }

### Parsing

    #![allow(unused)]
    fn main() {
    // Parse from string (case-insensitive)
    assert_eq!(QuantizationType::parse("Q4_K_M"), Some(QuantizationType::Q4KM));
    assert_eq!(QuantizationType::parse("q4km"), Some(QuantizationType::Q4KM));
    assert_eq!(QuantizationType::parse("F16"), Some(QuantizationType::F16));
    assert_eq!(QuantizationType::parse("fp16"), Some(QuantizationType::F16));
    }

## GgufExporter

The main export interface:

    #![allow(unused)]
    fn main() {
    use entrenar::ecosystem::{GgufExporter, QuantizationType};

    let exporter = GgufExporter::new(QuantizationType::Q4KM)
        .with_threads(8)
        .without_validation();
    }

### Adding Metadata

    #![allow(unused)]
    fn main() {
    use entrenar::ecosystem::{GgufExporter, GeneralMetadata, ExperimentProvenance};

    let exporter = GgufExporter::new(QuantizationType::Q5KM)
        .with_general(GeneralMetadata::new("llama", "my-finetuned-model")
            .with_author("PAIML")
            .with_description("LoRA fine-tuned LLaMA model")
            .with_license("MIT"))
        .with_provenance(ExperimentProvenance::new("exp-001", "run-123")
            .with_config_hash("abc123def456")
            .with_dataset("custom-dataset")
            .with_base_model("llama-2-7b")
            .with_metric("loss", 0.125)
            .with_metric("accuracy", 0.92)
            .with_git_commit("deadbeef")
            .with_custom("framework", "entrenar"));
    }

## Experiment Provenance

Track model lineage and training metadata:

    #![allow(unused)]
    fn main() {
    use entrenar::ecosystem::ExperimentProvenance;

    let provenance = ExperimentProvenance::new("experiment-id", "run-id")
        .with_config_hash("sha256-of-config")
        .with_dataset("imagenet-1k")
        .with_base_model("llama-7b")
        .with_metric("final_loss", 0.123)
        .with_metric("perplexity", 4.56)
        .with_git_commit("abc123")
        .with_custom("trainer", "entrenar")
        .with_custom("epochs", "10");

    // Convert to GGUF metadata pairs
    let pairs = provenance.to_metadata_pairs();
    for (key, value) in &pairs {
        println!("{}: {}", key, value);
    }
    // entrenar.experiment_id: experiment-id
    // entrenar.run_id: run-id
    // entrenar.timestamp: 2024-01-15T10:30:00Z
    // entrenar.metric.final_loss: 0.123
    // entrenar.custom.trainer: entrenar
    }

## General Metadata

Standard GGUF metadata fields:

    #![allow(unused)]
    fn main() {
    use entrenar::ecosystem::GeneralMetadata;

    let general = GeneralMetadata::new("mistral", "my-model")
        .with_author("Your Name")
        .with_description("Fine-tuned Mistral model for code generation")
        .with_license("Apache-2.0");
    }

## Exporting Models

    #![allow(unused)]
    fn main() {
    let exporter = GgufExporter::new(QuantizationType::Q4KM)
        .with_general(general)
        .with_provenance(provenance);

    // Export model
    let result = exporter.export("input_model.safetensors", "output_model.gguf")?;

    println!("Output: {:?}", result.output_path);
    println!("Quantization: {}", result.quantization);
    println!("Metadata keys: {}", result.metadata_keys);
    println!("Estimated size: {} bytes", result.estimated_size_bytes);
    }

### Collecting Metadata

Get all metadata as key-value pairs:

    #![allow(unused)]
    fn main() {
    let pairs = exporter.collect_metadata();

    for (key, value) in &pairs {
        println!("{} = {}", key, value);
    }
    }

## Error Handling

    #![allow(unused)]
    fn main() {
    use entrenar::ecosystem::GgufExportError;

    match exporter.export("model.safetensors", "model.gguf") {
        Ok(result) => println!("Exported to {:?}", result.output_path),
        Err(GgufExportError::InvalidQuantization(msg)) => {
            eprintln!("Quantization error: {}", msg);
        }
        Err(GgufExportError::IoError(msg)) => {
            eprintln!("I/O error: {}", msg);
        }
        Err(e) => eprintln!("Export failed: {}", e),
    }
    }

## Integration with Research Artifacts

Combine with research module for full provenance:

    #![allow(unused)]
    fn main() {
    use entrenar::research::ResearchArtifact;
    use entrenar::ecosystem::{GgufExporter, ExperimentProvenance};

    // Create research artifact
    let artifact = ResearchArtifact::new(
        "model-artifact",
        "Fine-tuned LLaMA for Code",
        ArtifactType::Model,
        License::Mit,
    );

    // Create provenance from artifact
    let provenance = ExperimentProvenance::new(&artifact.id, "run-001")
        .with_custom("artifact_version", &artifact.version);

    // Export with full provenance
    let exporter = GgufExporter::new(QuantizationType::Q4KM)
        .with_provenance(provenance);
    }

## See Also

- Ecosystem Overview
- Model I/O - Other model formats
- GGUF Format - GGUF specification