Metadata-Version: 2.4
Name: model-explorer-gguf
Version: 1.0.1.post1.dev1
Summary: Unofficial GGUF adapter extension for Google Model Explorer - visualize llama.cpp GGUF format models
Author-email: John Gallegos <johnnyjg75@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/johnjg75dev/model-explorer-gguf
Project-URL: Repository, https://github.com/johnjg75dev/model-explorer-gguf
Project-URL: Issues, https://github.com/johnjg75dev/model-explorer-gguf/issues
Keywords: gguf,llama.cpp,model-explorer,visualization,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: ai-edge-model-explorer>=0.1.0
Requires-Dist: numpy>=1.20.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# GGUF Adapter for Model Explorer

> **Unofficial third-party extension.** This project is not affiliated with or endorsed by the llama.cpp project, Georgi Gerganov, or Google. GGUF is the file format of the [llama.cpp](https://github.com/ggml-org/llama.cpp) project.

Visualize GGUF format models in [Google Model Explorer](https://github.com/google-ai-edge/model-explorer).

[![CI](https://github.com/johnjg75dev/model-explorer-gguf/actions/workflows/main.yaml/badge.svg)](https://github.com/johnjg75dev/model-explorer-gguf/actions/workflows/main.yaml)
[![PyPI](https://img.shields.io/pypi/v/model-explorer-gguf)](https://pypi.org/project/model-explorer-gguf/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue)](LICENSE)
[![Python](https://img.shields.io/pypi/pyversions/model-explorer-gguf)](https://pypi.org/project/model-explorer-gguf/)

## Installation

```bash
pip install model-explorer-gguf
```

This automatically installs `ai-edge-model-explorer` as a dependency.

## Usage

### Command Line

```bash
ggufvis path/to/model.gguf
```

Or directly via model-explorer:

```bash
model-explorer --extensions=model_explorer_gguf path/to/model.gguf
```

### Python API

```python
from model_explorer_gguf import GGUFAdapter

adapter = GGUFAdapter()
graph = adapter.convert("path/to/model.gguf")
# graph is a model_explorer Graph — render with model-explorer or inspect programmatically
```

## Features

- Full GGUF v1/v2/v3 spec support
- Hierarchical tensor layout (embeddings, transformer blocks, output)
- Rich metadata display (architecture, context length, layer count, quantization, etc.)
- All quantization types recognized (F32, F16, Q4_0, Q8_0, K-quants, I-quants, etc.)
- Works with any GGUF model (Llama, Mistral, Falcon, Gemma, Phi, etc.)

## Supported Formats

| Feature | Status |
|---|---|
| GGUF v1, v2, v3 | ✓ |
| All metadata types (scalars, strings, arrays) | ✓ |
| Tensor information (names, shapes, types, offsets) | ✓ |
| Hierarchical graph layout | ✓ |
| Multi-shard / split models | ✓ |

## Development

```bash
git clone https://github.com/johnjg75dev/model-explorer-gguf.git
cd model-explorer-gguf
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
```

Run tests with:

```bash
pytest
```

Report issues at https://github.com/johnjg75dev/model-explorer-gguf/issues

## License

Apache 2.0 — see [LICENSE](LICENSE).

## Trademarks

GGUF and llama.cpp are trademarks of the llama.cpp project. This project is not endorsed by or affiliated with the llama.cpp project or its maintainers.

## References

- [GGUF Specification](https://github.com/ggml-org/llama.cpp/blob/master/docs/gguf.md)
- [llama.cpp](https://github.com/ggml-org/llama.cpp)
- [Model Explorer](https://github.com/google-ai-edge/model-explorer)
