app.py

import os
import subprocess
import signal
os.environ["GRADIO_ANALYTICS_ENABLED"] = "False"
import gradio as gr
import tempfile

from huggingface_hub import HfApi, ModelCard, whoami
from gradio_huggingfacehub_search import HuggingfaceHubSearch
from pathlib import Path
from textwrap import dedent
from apscheduler.schedulers.background import BackgroundScheduler


# used for restarting the space
HF_TOKEN = os.environ.get("HF_TOKEN")
CONVERSION_SCRIPT = "./llama.cpp/convert_hf_to_gguf.py"

# escape HTML for logging
def escape(s: str) -> str:
    s = s.replace("&", "&") # Must be done first!
    s = s.replace("<", "&lt;")
    s = s.replace(">", "&gt;")
    s = s.replace('"', "&quot;")
    s = s.replace("\n", "<br/>")
    return s

def generate_importance_matrix(model_path: str, train_data_path: str, output_path: str):
    imatrix_command = [
        "./llama.cpp/llama-imatrix",
        "-m", model_path,
        "-f", train_data_path,
        "-ngl", "99",
        "--output-frequency", "10",
        "-o", output_path,
    ]

    if not os.path.isfile(model_path):
        raise Exception(f"Model file not found: {model_path}")

    print("Running imatrix command...")
    process = subprocess.Popen(imatrix_command, shell=False)

    try:
        process.wait(timeout=60)  # added wait
    except subprocess.TimeoutExpired:
        print("Imatrix computation timed out. Sending SIGINT to allow graceful termination...")
        process.send_signal(signal.SIGINT)
        try:
            process.wait(timeout=5)  # grace period
        except subprocess.TimeoutExpired:
            print("Imatrix proc still didn't term. Forecfully terming process...")
            process.kill()

    print("Importance matrix generation completed.")

def split_upload_model(model_path: str, outdir: str, repo_id: str, oauth_token: gr.OAuthToken | None, split_max_tensors=256, split_max_size=None):
    print(f"Model path: {model_path}")
    print(f"Output dir: {outdir}")

    if oauth_token.token is None:
        raise ValueError("You have to be logged in.")
    
    split_cmd = [
        "./llama.cpp/llama-gguf-split",
        "--split",
    ]
    if split_max_size:
        split_cmd.append("--split-max-size")
        split_cmd.append(split_max_size)
    else:
        split_cmd.append("--split-max-tensors")
        split_cmd.append(str(split_max_tensors))

    # args for output
    model_path_prefix = '.'.join(model_path.split('.')[:-1]) # remove the file extension
    split_cmd.append(model_path)
    split_cmd.append(model_path_prefix)

    print(f"Split command: {split_cmd}") 
    
    result = subprocess.run(split_cmd, shell=False, capture_output=True, text=True)
    print(f"Split command stdout: {result.stdout}") 
    print(f"Split command stderr: {result.stderr}") 
    
    if result.returncode != 0:
        stderr_str = result.stderr.decode("utf-8")
        raise Exception(f"Error splitting the model: {stderr_str}")
    print("Model split successfully!")

    # remove the original model file if needed
    if os.path.exists(model_path):
        os.remove(model_path)

    model_file_prefix = model_path_prefix.split('/')[-1]
    print(f"Model file name prefix: {model_file_prefix}") 
    sharded_model_files = [f for f in os.listdir(outdir) if f.startswith(model_file_prefix) and f.endswith(".gguf")]
    if sharded_model_files:
        print(f"Sharded model files: {sharded_model_files}")
        api = HfApi(token=oauth_token.token)
        for file in sharded_model_files:
            file_path = os.path.join(outdir, file)
            print(f"Uploading file: {file_path}")
            try:
                api.upload_file(
                    path_or_fileobj=file_path,
                    path_in_repo=file,
                    repo_id=repo_id,
                )
            except Exception as e:
                raise Exception(f"Error uploading file {file_path}: {e}")
    else:
        raise Exception("No sharded files found.")
    
    print("Sharded model has been uploaded successfully!")

def process_model(model_id, q_method, use_imatrix, imatrix_q_method, private_repo, train_data_file, split_model, split_max_tensors, split_max_size, oauth_token: gr.OAuthToken | None):
    if oauth_token is None or oauth_token.token is None:
        raise ValueError("You must be logged in to use GGUF-my-repo")
    model_name = model_id.split('/')[-1]

    try:
        api = HfApi(token=oauth_token.token)

        dl_pattern = ["*.md", "*.json", "*.model"]

        pattern = (
            "*.safetensors"
            if any(
                file.path.endswith(".safetensors")
                for file in api.list_repo_tree(
                    repo_id=model_id,
                    recursive=True,
                )
            )
            else "*.bin"
        )

        dl_pattern += [pattern]

        if not os.path.exists("downloads"):
            os.makedirs("downloads")

        if not os.path.exists("outputs"):
            os.makedirs("outputs")

        with tempfile.TemporaryDirectory(dir="outputs") as outdir:
            fp16 = str(Path(outdir)/f"{model_name}.fp16.gguf")

            with tempfile.TemporaryDirectory(dir="downloads") as tmpdir:
                # Keep the model name as the dirname so the model name metadata is populated correctly
                local_dir = Path(tmpdir)/model_name
                print(local_dir)
                api.snapshot_download(repo_id=model_id, local_dir=local_dir, local_dir_use_symlinks=False, allow_patterns=dl_pattern)
                print("Model downloaded successfully!")
                print(f"Current working directory: {os.getcwd()}")
                print(f"Model directory contents: {os.listdir(local_dir)}")

                config_dir = local_dir/"config.json"
                adapter_config_dir = local_dir/"adapter_config.json"
                if os.path.exists(adapter_config_dir) and not os.path.exists(config_dir):
                    raise Exception('adapter_config.json is present.<br/><br/>If you are converting a LoRA adapter to GGUF, please use <a href="https://huggingface.co/spaces/ggml-org/gguf-my-lora" target="_blank" style="text-decoration:underline">GGUF-my-lora</a>.')

                result = subprocess.run([
                    "python", CONVERSION_SCRIPT, local_dir, "--outtype", "f16", "--outfile", fp16
                ], shell=False, capture_output=True)
                print(result)
                if result.returncode != 0:
                    stderr_str = result.stderr.decode("utf-8")
                    raise Exception(f"Error converting to fp16: {stderr_str}")
                print("Model converted to fp16 successfully!")
                print(f"Converted model path: {fp16}")

            imatrix_path = Path(outdir)/"imatrix.dat"

            if use_imatrix:
                if train_data_file:
                    train_data_path = train_data_file.name
                else:
                    train_data_path = "llama.cpp/groups_merged.txt" #fallback calibration dataset

                print(f"Training data file path: {train_data_path}")

                if not os.path.isfile(train_data_path):
                    raise Exception(f"Training data file not found: {train_data_path}")

                generate_importance_matrix(fp16, train_data_path, imatrix_path)
            else:
                print("Not using imatrix quantization.")
            
            # Quantize the model
            quantized_gguf_name = f"{model_name.lower()}-{imatrix_q_method.lower()}-imat.gguf" if use_imatrix else f"{model_name.lower()}-{q_method.lower()}.gguf"
            quantized_gguf_path = str(Path(outdir)/quantized_gguf_name)
            if use_imatrix:
                quantise_ggml = [
                    "./llama.cpp/llama-quantize",
                    "--imatrix", imatrix_path, fp16, quantized_gguf_path, imatrix_q_method
                ]
            else:
                quantise_ggml = [
                    "./llama.cpp/llama-quantize",
                    fp16, quantized_gguf_path, q_method
                ]
            result = subprocess.run(quantise_ggml, shell=False, capture_output=True)
            if result.returncode != 0:
                stderr_str = result.stderr.decode("utf-8")
                raise Exception(f"Error quantizing: {stderr_str}")
            print(f"Quantized successfully with {imatrix_q_method if use_imatrix else q_method} option!")
            print(f"Quantized model path: {quantized_gguf_path}")

            # Create empty repo
            username = whoami(oauth_token.token)["name"]
            new_repo_url = api.create_repo(repo_id=f"{username}/{model_name}-GGUF", exist_ok=True, private=private_repo)
            new_repo_id = new_repo_url.repo_id
            print("Repo created successfully!", new_repo_url)

            try:
                card = ModelCard.load(model_id, token=oauth_token.token)
            except:
                card = ModelCard("")
            if card.data.tags is None:
                card.data.tags = []
            card.data.tags.append("llama-cpp")
            card.data.tags.append("matrixportal")            
            card.data.base_model = model_id

            card.text = dedent(
                f"""
                # {new_repo_id}
                   This model was converted to GGUF format from [`{model_id}`](https://huggingface.co/{model_id}) using llama.cpp via the ggml.ai's [all-gguf-same-where](https://huggingface.co/spaces/matrixportal/all-gguf-same-where) space.
                Refer to the [original model card](https://huggingface.co/{model_id}) for more details on the model.
                """
            )
            readme_path = Path(outdir)/"README.md"
            card.save(readme_path)
            

            # Quant listesi oluşturma
            quant_list = f"""
## ✅ Quantized Models Download List

### 🔍 Recommended Quantizations
- **✨ General CPU Use:** [`Q4_K_M`](https://huggingface.co/{new_repo_id}/resolve/main/{model_name.lower()}-q4_k_m.gguf) (Best balance of speed/quality)
- **📱 ARM Devices:** [`Q4_0`](https://huggingface.co/{new_repo_id}/resolve/main/{model_name.lower()}-q4_0.gguf) (Optimized for ARM CPUs)
- **🏆 Maximum Quality:** [`Q8_0`](https://huggingface.co/{new_repo_id}/resolve/main/{model_name.lower()}-q8_0.gguf) (Near-original quality)

### 📦 Full Quantization Options
| 🚀 Download | 🔢 Type | 📝 Notes |
|:---------|:-----|:------|
| [Download](https://huggingface.co/{new_repo_id}/resolve/main/{model_name.lower()}-q2_k.gguf) | ![Q2_K](https://img.shields.io/badge/Q2_K-1A73E8) | Basic quantization |
| [Download](https://huggingface.co/{new_repo_id}/resolve/main/{model_name.lower()}-q3_k_s.gguf) | ![Q3_K_S](https://img.shields.io/badge/Q3_K_S-34A853) | Small size |
| [Download](https://huggingface.co/{new_repo_id}/resolve/main/{model_name.lower()}-q3_k_m.gguf) | ![Q3_K_M](https://img.shields.io/badge/Q3_K_M-FBBC05) | Balanced quality |
| [Download](https://huggingface.co/{new_repo_id}/resolve/main/{model_name.lower()}-q3_k_l.gguf) | ![Q3_K_L](https://img.shields.io/badge/Q3_K_L-4285F4) | Better quality |
| [Download](https://huggingface.co/{new_repo_id}/resolve/main/{model_name.lower()}-q4_0.gguf) | ![Q4_0](https://img.shields.io/badge/Q4_0-EA4335) | Fast on ARM |
| [Download](https://huggingface.co/{new_repo_id}/resolve/main/{model_name.lower()}-q4_k_s.gguf) | ![Q4_K_S](https://img.shields.io/badge/Q4_K_S-673AB7) | Fast, recommended |
| [Download](https://huggingface.co/{new_repo_id}/resolve/main/{model_name.lower()}-q4_k_m.gguf) | ![Q4_K_M](https://img.shields.io/badge/Q4_K_M-673AB7) ⭐ | Best balance |
| [Download](https://huggingface.co/{new_repo_id}/resolve/main/{model_name.lower()}-q5_0.gguf) | ![Q5_0](https://img.shields.io/badge/Q5_0-FF6D01) | Good quality |
| [Download](https://huggingface.co/{new_repo_id}/resolve/main/{model_name.lower()}-q5_k_s.gguf) | ![Q5_K_S](https://img.shields.io/badge/Q5_K_S-0F9D58) | Balanced |
| [Download](https://huggingface.co/{new_repo_id}/resolve/main/{model_name.lower()}-q5_k_m.gguf) | ![Q5_K_M](https://img.shields.io/badge/Q5_K_M-0F9D58) | High quality |
| [Download](https://huggingface.co/{new_repo_id}/resolve/main/{model_name.lower()}-q6_k.gguf) | ![Q6_K](https://img.shields.io/badge/Q6_K-4285F4) 🏆 | Very good quality |
| [Download](https://huggingface.co/{new_repo_id}/resolve/main/{model_name.lower()}-q8_0.gguf) | ![Q8_0](https://img.shields.io/badge/Q8_0-EA4335) ⚡ | Fast, best quality |
| [Download](https://huggingface.co/{new_repo_id}/resolve/main/{model_name.lower()}-f16.gguf) | ![F16](https://img.shields.io/badge/F16-000000) | Maximum accuracy |

💡 **Tip:** Use `F16` for maximum precision when quality is critical

# GGUF Model Quantization & Usage Guide with llama.cpp

## What is GGUF and Quantization?

**GGUF** (GPT-Generated Unified Format) is an efficient model file format developed by the `llama.cpp` team that:
- Supports multiple quantization levels
- Works cross-platform
- Enables fast loading and inference

**Quantization** converts model weights to lower precision data types (e.g., 4-bit integers instead of 32-bit floats) to:
- Reduce model size
- Decrease memory usage
- Speed up inference
- (With minor accuracy trade-offs)

## Step-by-Step Guide

### 1. Prerequisites

```bash
# System updates
sudo apt update && sudo apt upgrade -y

# Dependencies
sudo apt install -y build-essential cmake python3-pip

# Clone and build llama.cpp
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
make -j4
```

### 2. Using Quantized Models from Hugging Face

My automated quantization script produces models in this format:
```
https://huggingface.co/{new_repo_id}/resolve/main/{model_name.lower()}-q4_k_m.gguf
```

Download your quantized model directly:

```bash
wget https://huggingface.co/{new_repo_id}/resolve/main/{model_name.lower()}-q4_k_m.gguf
```

### 3. Running the Quantized Model

Basic usage:
```bash
./main -m {model_name.lower()}-q4_k_m.gguf -p "Your prompt here" -n 128
```

Example with a creative writing prompt:
```bash
./main -m {model_name.lower()}-q4_k_m.gguf \
       -p "[INST] Write a short poem about AI quantization in the style of Shakespeare [/INST]" \
       -n 256 -c 2048 -t 8 --temp 0.7
```

Advanced parameters:
```bash
./main -m {model_name.lower()}-q4_k_m.gguf \
       -p "Question: What is the GGUF format?\nAnswer:" \
       -n 256 -c 2048 -t 8 --temp 0.7 --top-k 40 --top-p 0.9
```

### 4. Python Integration

Install the Python package:
```bash
pip install llama-cpp-python
```

Example script:
```python
from llama_cpp import Llama

# Initialize the model
llm = Llama(
    model_path="{model_name.lower()}-q4_k_m.gguf",
    n_ctx=2048,
    n_threads=8
)

# Run inference
response = llm(
    "[INST] Explain GGUF quantization to a beginner [/INST]",
    max_tokens=256,
    temperature=0.7,
    top_p=0.9
)

print(response["choices"][0]["text"])
```

## Performance Tips

1. **Hardware Utilization**:
   - Set thread count with `-t` (typically CPU core count)
   - Compile with CUDA/OpenCL for GPU support

2. **Memory Optimization**:
   - Lower quantization (like q4_k_m) uses less RAM
   - Adjust context size with `-c` parameter

3. **Speed/Accuracy Balance**:
   - Higher bit quantization is slower but more accurate
   - Reduce randomness with `--temp 0` for consistent results

## FAQ

**Q: What quantization levels are available?**  
A: Common options include q4_0, q4_k_m, q5_0, q5_k_m, q8_0

**Q: How much performance loss occurs with q4_k_m?**  
A: Typically 2-5% accuracy reduction but 4x smaller size

**Q: How to enable GPU support?**  
A: Build with `make LLAMA_CUBLAS=1` for NVIDIA GPUs

## Useful Resources

1. [llama.cpp GitHub](https://github.com/ggerganov/llama.cpp)
2. [GGUF Format Specs](https://github.com/ggerganov/ggml/blob/master/docs/gguf.md)
3. [Hugging Face Model Hub](https://huggingface.co/models)
"""

            # README'yi güncelle (ModelCard kullanarak)
            card.text += quant_list
            readme_path = Path(outdir)/"README.md"
            card.save(readme_path)
            
            if split_model:
                split_upload_model(str(quantized_gguf_path), outdir, new_repo_id, oauth_token, split_max_tensors, split_max_size)
            else:
                try:
                    print(f"Uploading quantized model: {quantized_gguf_path}")
                    api.upload_file(
                        path_or_fileobj=quantized_gguf_path,
                        path_in_repo=quantized_gguf_name,
                        repo_id=new_repo_id,
                    )
                except Exception as e:
                    raise Exception(f"Error uploading quantized model: {e}")
            
            if os.path.isfile(imatrix_path):
                try:
                    print(f"Uploading imatrix.dat: {imatrix_path}")
                    api.upload_file(
                        path_or_fileobj=imatrix_path,
                        path_in_repo="imatrix.dat",
                        repo_id=new_repo_id,
                    )
                except Exception as e:
                    raise Exception(f"Error uploading imatrix.dat: {e}")

            api.upload_file(
                path_or_fileobj=readme_path,
                path_in_repo="README.md",
                repo_id=new_repo_id,
            )
            print(f"Uploaded successfully with {imatrix_q_method if use_imatrix else q_method} option!")

        # end of the TemporaryDirectory(dir="outputs") block; temporary outputs are deleted here

        return (
            f'<h1>✅ DONE</h1><br/>Find your repo here: <a href="{new_repo_url}" target="_blank" style="text-decoration:underline">{new_repo_id}</a>',
            "llama.png",
        )
    except Exception as e:
        return (f'<h1>❌ ERROR</h1><br/><pre style="white-space:pre-wrap;">{escape(str(e))}</pre>', "error.png")


css="""/* Custom CSS to allow scrolling */
.gradio-container {overflow-y: auto;}
"""
# Create Gradio interface
with gr.Blocks(css=css) as demo: 
    gr.Markdown("You must be logged in to use GGUF-my-repo.")
    gr.LoginButton(min_width=250)

    model_id = HuggingfaceHubSearch(
        label="Hub Model ID",
        placeholder="Search for model id on Huggingface",
        search_type="model",
    )

    q_method = gr.Dropdown(
        ["Q2_K", "Q3_K_S", "Q3_K_M", "Q3_K_L", "Q4_0", "Q4_K_S", "Q4_K_M", "Q5_0", "Q5_K_S", "Q5_K_M", "Q6_K", "Q8_0", "F16"],
        label="Quantization Method",
        info="GGML quantization type",
        value="Q4_K_M",
        filterable=False,
        visible=True
    )

    imatrix_q_method = gr.Dropdown(
        ["IQ3_M", "IQ3_XXS", "Q4_0", "Q4_K_M", "Q4_K_S", "IQ4_NL", "IQ4_XS", "Q5_K_M", "Q5_K_S", "Q6_K", "Q8_0", "F16"],
        label="Imatrix Quantization Method",
        info="GGML imatrix quants type",
        value="IQ4_NL", 
        filterable=False,
        visible=False
    )

    use_imatrix = gr.Checkbox(
        value=False,
        label="Use Imatrix Quantization",
        info="Use importance matrix for quantization."
    )

    private_repo = gr.Checkbox(
        value=False,
        label="Private Repo",
        info="Create a private repo under your username."
    )

    train_data_file = gr.File(
        label="Training Data File",
        file_types=["txt"],
        visible=False
    )

    split_model = gr.Checkbox(
        value=False,
        label="Split Model",
        info="Shard the model using gguf-split."
    )

    split_max_tensors = gr.Number(
        value=256,
        label="Max Tensors per File",
        info="Maximum number of tensors per file when splitting model.",
        visible=False
    )

    split_max_size = gr.Textbox(
        label="Max File Size",
        info="Maximum file size when splitting model (--split-max-size). May leave empty to use the default. Accepted suffixes: M, G. Example: 256M, 5G",
        visible=False
    )

    def update_visibility(use_imatrix):
        return gr.update(visible=not use_imatrix), gr.update(visible=use_imatrix), gr.update(visible=use_imatrix)
    
    use_imatrix.change(
        fn=update_visibility,
        inputs=use_imatrix,
        outputs=[q_method, imatrix_q_method, train_data_file]
    )

    iface = gr.Interface(
        fn=process_model,
        inputs=[
            model_id,
            q_method,
            use_imatrix,
            imatrix_q_method,
            private_repo,
            train_data_file,
            split_model,
            split_max_tensors,
            split_max_size,
        ],
        outputs=[
            gr.Markdown(label="output"),
            gr.Image(show_label=False),
        ],
        title="Create your own GGUF Quants, blazingly fast ⚡!",
        description="The space takes an HF repo as an input, quantizes it and creates a Public repo containing the selected quant under your HF user namespace.",
        api_name=False
    )

    def update_split_visibility(split_model):
        return gr.update(visible=split_model), gr.update(visible=split_model)

    split_model.change(
        fn=update_split_visibility,
        inputs=split_model,
        outputs=[split_max_tensors, split_max_size]
    )

def restart_space():
    HfApi().restart_space(repo_id="matrixportal/all-gguf-same-where", token=HF_TOKEN, factory_reboot=True)

scheduler = BackgroundScheduler()
scheduler.add_job(restart_space, "interval", seconds=21600)
scheduler.start()

# Launch the interface
demo.queue(default_concurrency_limit=1, max_size=5).launch(debug=True, show_api=False)