# GGUF Loader
[](https://badge.fury.io/py/ggufloader)
[](https://pypi.org/project/ggufloader/)
[](https://opensource.org/licenses/MIT)
**Advanced GGUF Model Loader with Smart Floating Assistant**
GGUF Loader is a production-ready Python application that provides a robust GGUF model loader with an innovative Smart Floating Assistant addon. Transform how you work with AI across all your applications with global text selection and processing capabilities.
## ✨ Key Features
### 🚀 Smart Floating Assistant
- **Global Text Selection**: Works across ALL applications (browsers, editors, documents)
- **AI-Powered Processing**: Summarize and comment on any selected text
- **Floating UI**: Non-intrusive, always-accessible interface
- **Privacy-First**: All processing happens locally on your machine
### 🎯 Core Capabilities
- **GGUF Model Support**: Load and run any GGUF format model
- **Modern GUI**: Built with PySide6 for a native desktop experience
- **Addon System**: Extensible architecture for custom functionality
- **Cross-Platform**: Works on Windows, macOS, and Linux
- **GPU Acceleration**: Optional CUDA and Metal support
### 🔧 Developer-Friendly
- **Rich API**: Comprehensive addon development framework
- **Hot Loading**: Load and unload addons without restarting
- **Open Source**: MIT licensed and community-driven
## 🚀 Quick Start
### Installation
```bash
pip install ggufloader
```
### Launch
```bash
ggufloader
```
### First Steps
1. **Download a GGUF model** from [Hugging Face](https://huggingface.co/models?library=gguf)
2. **Click "Select GGUF Model"** in the application
3. **Load your model** and start chatting
4. **Try the Smart Assistant**: Select text anywhere and click the ✨ button!
## 📋 System Requirements
- **Python**: 3.8 or higher
- **RAM**: 4GB minimum (8GB+ recommended)
- **Storage**: 2GB+ free space for models
- **OS**: Windows 10/11, macOS 10.14+, or Linux (Ubuntu 18.04+)
### Platform-Specific Requirements
#### Windows
- Windows 10 or 11
- Automatically installs `pywin32` for enhanced system integration
#### macOS
- macOS 10.14 (Mojave) or later
- Optional: Install enhanced macOS integration with `pip install ggufloader[macos]`
#### Linux
- Ubuntu 18.04+, Fedora 30+, or equivalent
- X11 display server (Wayland support coming soon)
- Optional: Install enhanced Linux integration with `pip install ggufloader[linux]`
## 🎮 Usage Examples
### Basic Chat
```python
# Launch the application
ggufloader
# Or use programmatically
from ggufloader import addon_main
addon_main()
```
### Smart Floating Assistant Workflow
1. **Reading an article** → Select key paragraph → Click ✨ → "Summarize"
2. **Code review** → Select complex function → Click ✨ → "Comment"
3. **Email writing** → Select draft → Click ✨ → "Comment" for suggestions
4. **Research** → Select academic text → Click ✨ → "Summarize"
### Command Line Options
```bash
# Show version
ggufloader --version
# Show help
ggufloader --help
```
## 🔧 Advanced Installation
### GPU Acceleration
#### NVIDIA GPU (CUDA)
```bash
pip uninstall llama-cpp-python
pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu121
```
#### Apple Silicon (Metal)
```bash
pip uninstall llama-cpp-python
CMAKE_ARGS="-DLLAMA_METAL=on" pip install llama-cpp-python
```
### Platform-Specific Enhanced Features
#### Windows Enhanced Integration
```bash
pip install ggufloader[windows]
```
#### macOS Enhanced Integration
```bash
pip install ggufloader[macos]
```
#### Linux Enhanced Integration
```bash
pip install ggufloader[linux]
```
### Performance Monitoring (Optional)
```bash
pip install ggufloader[performance]
```
### All Optional Features
```bash
pip install ggufloader[all]
```
### Development Installation
```bash
git clone https://github.com/GGUFloader/gguf-loader.git
cd gguf-loader
pip install -e .[dev]
```
## 📚 Documentation
### Quick Links
- **[Installation Guide](ggufloader/docs/installation.md)** - Detailed setup instructions
- **[Quick Start Guide](ggufloader/docs/quick-start.md)** - Get running in minutes
- **[Addon Development](ggufloader/docs/addon-development.md)** - Create custom addons
- **[API Reference](ggufloader/docs/addon-api.md)** - Complete API documentation
### Key Documentation Files
- **[Package Structure](ggufloader/docs/package-structure.md)** - Understanding the codebase
- **[Smart Floater Example](ggufloader/docs/smart-floater-example.md)** - Learn from the built-in addon
## 🛠️ Development
### Project Structure
```
ggufloader/
├── __init__.py # Package initialization
├── gguf_loader_main.py # Main application entry point
├── addon_manager.py # Addon system management
├── config.py # Configuration utilities
├── addons/ # Built-in addons
├── docs/ # Documentation
├── models/ # Model loading components
├── ui/ # User interface components
└── widgets/ # Custom UI widgets
```
### Creating Addons
```python
# Example addon structure
def register_addon(parent_app):
"""Register addon with the main application"""
return MyAddonWidget(parent_app)
class MyAddonWidget(QWidget):
def __init__(self, parent_app):
super().__init__()
self.parent_app = parent_app
# Your addon implementation
```
## 🤝 Contributing
We welcome contributions! Here's how to get started:
1. **Fork the repository**
2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
3. **Make your changes** and add tests
4. **Run tests**: `pytest`
5. **Submit a pull request**
### Development Setup
```bash
git clone https://github.com/GGUFloader/gguf-loader.git
cd gguf-loader
pip install -e .[dev]
```
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🔗 Links
- **Homepage**: [https://ggufloader.github.io](https://ggufloader.github.io)
- **Repository**: [https://github.com/GGUFloader/gguf-loader](https://github.com/GGUFloader/gguf-loader)
- **PyPI Package**: [https://pypi.org/project/ggufloader/](https://pypi.org/project/ggufloader/)
- **Bug Reports**: [https://github.com/GGUFloader/gguf-loader/issues](https://github.com/GGUFloader/gguf-loader/issues)
## 👨💻 Author
**Hussain Nazary**
- Email: [hussainnazary475@gmail.com](mailto:hussainnazary475@gmail.com)
- GitHub: [@GGUFloader](https://github.com/GGUFloader)
## 🙏 Acknowledgments
- **llama.cpp** team for the excellent GGUF format and inference engine
- **PySide6** team for the robust GUI framework
- **Hugging Face** for model hosting and transformers library
- **Open source community** for continuous support and contributions
## 📊 Stats
- **Language**: Python 3.8+
- **GUI Framework**: PySide6
- **AI Backend**: llama-cpp-python
- **Package Size**: ~50MB
- **Supported Models**: All GGUF format models
---
**Transform your text workflow with AI-powered assistance! 🚀**
*Made with ❤️ by the GGUF Loader team*
Raw data
{
"_id": null,
"home_page": null,
"name": "ggufloader",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Hussain Nazary <hussainnazary475@gmail.com>",
"keywords": "gguf, llama, ai, model-loader, gui, pyside6",
"author": null,
"author_email": "Hussain Nazary <hussainnazary475@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d6/72/716003f2d8cb8ca39349e07243ae10c1b123843c22342112b16847e1454d/ggufloader-2.0.1.tar.gz",
"platform": null,
"description": "# GGUF Loader\r\n\r\n[](https://badge.fury.io/py/ggufloader)\r\n[](https://pypi.org/project/ggufloader/)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\n**Advanced GGUF Model Loader with Smart Floating Assistant**\r\n\r\nGGUF Loader is a production-ready Python application that provides a robust GGUF model loader with an innovative Smart Floating Assistant addon. Transform how you work with AI across all your applications with global text selection and processing capabilities.\r\n\r\n## \u2728 Key Features\r\n\r\n### \ud83d\ude80 Smart Floating Assistant\r\n- **Global Text Selection**: Works across ALL applications (browsers, editors, documents)\r\n- **AI-Powered Processing**: Summarize and comment on any selected text\r\n- **Floating UI**: Non-intrusive, always-accessible interface\r\n- **Privacy-First**: All processing happens locally on your machine\r\n\r\n### \ud83c\udfaf Core Capabilities\r\n- **GGUF Model Support**: Load and run any GGUF format model\r\n- **Modern GUI**: Built with PySide6 for a native desktop experience\r\n- **Addon System**: Extensible architecture for custom functionality\r\n- **Cross-Platform**: Works on Windows, macOS, and Linux\r\n- **GPU Acceleration**: Optional CUDA and Metal support\r\n\r\n### \ud83d\udd27 Developer-Friendly\r\n- **Rich API**: Comprehensive addon development framework\r\n- **Hot Loading**: Load and unload addons without restarting\r\n- **Open Source**: MIT licensed and community-driven\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n### Installation\r\n\r\n```bash\r\npip install ggufloader\r\n```\r\n\r\n### Launch\r\n\r\n```bash\r\nggufloader\r\n```\r\n\r\n### First Steps\r\n\r\n1. **Download a GGUF model** from [Hugging Face](https://huggingface.co/models?library=gguf)\r\n2. **Click \"Select GGUF Model\"** in the application\r\n3. **Load your model** and start chatting\r\n4. **Try the Smart Assistant**: Select text anywhere and click the \u2728 button!\r\n\r\n## \ud83d\udccb System Requirements\r\n\r\n- **Python**: 3.8 or higher\r\n- **RAM**: 4GB minimum (8GB+ recommended)\r\n- **Storage**: 2GB+ free space for models\r\n- **OS**: Windows 10/11, macOS 10.14+, or Linux (Ubuntu 18.04+)\r\n\r\n### Platform-Specific Requirements\r\n\r\n#### Windows\r\n- Windows 10 or 11\r\n- Automatically installs `pywin32` for enhanced system integration\r\n\r\n#### macOS\r\n- macOS 10.14 (Mojave) or later\r\n- Optional: Install enhanced macOS integration with `pip install ggufloader[macos]`\r\n\r\n#### Linux\r\n- Ubuntu 18.04+, Fedora 30+, or equivalent\r\n- X11 display server (Wayland support coming soon)\r\n- Optional: Install enhanced Linux integration with `pip install ggufloader[linux]`\r\n\r\n## \ud83c\udfae Usage Examples\r\n\r\n### Basic Chat\r\n```python\r\n# Launch the application\r\nggufloader\r\n\r\n# Or use programmatically\r\nfrom ggufloader import addon_main\r\naddon_main()\r\n```\r\n\r\n### Smart Floating Assistant Workflow\r\n1. **Reading an article** \u2192 Select key paragraph \u2192 Click \u2728 \u2192 \"Summarize\"\r\n2. **Code review** \u2192 Select complex function \u2192 Click \u2728 \u2192 \"Comment\" \r\n3. **Email writing** \u2192 Select draft \u2192 Click \u2728 \u2192 \"Comment\" for suggestions\r\n4. **Research** \u2192 Select academic text \u2192 Click \u2728 \u2192 \"Summarize\"\r\n\r\n### Command Line Options\r\n```bash\r\n# Show version\r\nggufloader --version\r\n\r\n# Show help\r\nggufloader --help\r\n```\r\n\r\n## \ud83d\udd27 Advanced Installation\r\n\r\n### GPU Acceleration\r\n\r\n#### NVIDIA GPU (CUDA)\r\n```bash\r\npip uninstall llama-cpp-python\r\npip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu121\r\n```\r\n\r\n#### Apple Silicon (Metal)\r\n```bash\r\npip uninstall llama-cpp-python\r\nCMAKE_ARGS=\"-DLLAMA_METAL=on\" pip install llama-cpp-python\r\n```\r\n\r\n### Platform-Specific Enhanced Features\r\n\r\n#### Windows Enhanced Integration\r\n```bash\r\npip install ggufloader[windows]\r\n```\r\n\r\n#### macOS Enhanced Integration\r\n```bash\r\npip install ggufloader[macos]\r\n```\r\n\r\n#### Linux Enhanced Integration\r\n```bash\r\npip install ggufloader[linux]\r\n```\r\n\r\n### Performance Monitoring (Optional)\r\n```bash\r\npip install ggufloader[performance]\r\n```\r\n\r\n### All Optional Features\r\n```bash\r\npip install ggufloader[all]\r\n```\r\n\r\n### Development Installation\r\n```bash\r\ngit clone https://github.com/GGUFloader/gguf-loader.git\r\ncd gguf-loader\r\npip install -e .[dev]\r\n```\r\n\r\n## \ud83d\udcda Documentation\r\n\r\n### Quick Links\r\n- **[Installation Guide](ggufloader/docs/installation.md)** - Detailed setup instructions\r\n- **[Quick Start Guide](ggufloader/docs/quick-start.md)** - Get running in minutes \r\n- **[Addon Development](ggufloader/docs/addon-development.md)** - Create custom addons\r\n- **[API Reference](ggufloader/docs/addon-api.md)** - Complete API documentation\r\n\r\n### Key Documentation Files\r\n- **[Package Structure](ggufloader/docs/package-structure.md)** - Understanding the codebase\r\n- **[Smart Floater Example](ggufloader/docs/smart-floater-example.md)** - Learn from the built-in addon\r\n\r\n## \ud83d\udee0\ufe0f Development\r\n\r\n### Project Structure\r\n```\r\nggufloader/\r\n\u251c\u2500\u2500 __init__.py # Package initialization\r\n\u251c\u2500\u2500 gguf_loader_main.py # Main application entry point\r\n\u251c\u2500\u2500 addon_manager.py # Addon system management\r\n\u251c\u2500\u2500 config.py # Configuration utilities\r\n\u251c\u2500\u2500 addons/ # Built-in addons\r\n\u251c\u2500\u2500 docs/ # Documentation\r\n\u251c\u2500\u2500 models/ # Model loading components\r\n\u251c\u2500\u2500 ui/ # User interface components\r\n\u2514\u2500\u2500 widgets/ # Custom UI widgets\r\n```\r\n\r\n### Creating Addons\r\n\r\n```python\r\n# Example addon structure\r\ndef register_addon(parent_app):\r\n \"\"\"Register addon with the main application\"\"\"\r\n return MyAddonWidget(parent_app)\r\n\r\nclass MyAddonWidget(QWidget):\r\n def __init__(self, parent_app):\r\n super().__init__()\r\n self.parent_app = parent_app\r\n # Your addon implementation\r\n```\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nWe welcome contributions! Here's how to get started:\r\n\r\n1. **Fork the repository**\r\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\r\n3. **Make your changes** and add tests\r\n4. **Run tests**: `pytest`\r\n5. **Submit a pull request**\r\n\r\n### Development Setup\r\n```bash\r\ngit clone https://github.com/GGUFloader/gguf-loader.git\r\ncd gguf-loader\r\npip install -e .[dev]\r\n```\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83d\udd17 Links\r\n\r\n- **Homepage**: [https://ggufloader.github.io](https://ggufloader.github.io)\r\n- **Repository**: [https://github.com/GGUFloader/gguf-loader](https://github.com/GGUFloader/gguf-loader)\r\n- **PyPI Package**: [https://pypi.org/project/ggufloader/](https://pypi.org/project/ggufloader/)\r\n- **Bug Reports**: [https://github.com/GGUFloader/gguf-loader/issues](https://github.com/GGUFloader/gguf-loader/issues)\r\n\r\n## \ud83d\udc68\u200d\ud83d\udcbb Author\r\n\r\n**Hussain Nazary**\r\n- Email: [hussainnazary475@gmail.com](mailto:hussainnazary475@gmail.com)\r\n- GitHub: [@GGUFloader](https://github.com/GGUFloader)\r\n\r\n## \ud83d\ude4f Acknowledgments\r\n\r\n- **llama.cpp** team for the excellent GGUF format and inference engine\r\n- **PySide6** team for the robust GUI framework\r\n- **Hugging Face** for model hosting and transformers library\r\n- **Open source community** for continuous support and contributions\r\n\r\n## \ud83d\udcca Stats\r\n\r\n- **Language**: Python 3.8+\r\n- **GUI Framework**: PySide6\r\n- **AI Backend**: llama-cpp-python\r\n- **Package Size**: ~50MB\r\n- **Supported Models**: All GGUF format models\r\n\r\n---\r\n\r\n**Transform your text workflow with AI-powered assistance! \ud83d\ude80**\r\n\r\n*Made with \u2764\ufe0f by the GGUF Loader team*\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Advanced GGUF Model Loader with Smart Floating Assistant",
"version": "2.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/GGUFloader/gguf-loader/issues",
"Documentation": "https://ggufloader.github.io",
"Homepage": "https://ggufloader.github.io",
"Repository": "https://github.com/GGUFloader/gguf-loader"
},
"split_keywords": [
"gguf",
" llama",
" ai",
" model-loader",
" gui",
" pyside6"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fcfa7e4c49bbe09f8e8a26388608d883e7d38c04a6e2dceb35d7e12af3c51307",
"md5": "a69d1e813a9d5a0d6e2e98ae5a1e6525",
"sha256": "1c5e9946050fe77073ad321dddfe1936c945a94344002b0104a1db8bc415a0f8"
},
"downloads": -1,
"filename": "ggufloader-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a69d1e813a9d5a0d6e2e98ae5a1e6525",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 197748,
"upload_time": "2025-07-27T14:18:36",
"upload_time_iso_8601": "2025-07-27T14:18:36.245033Z",
"url": "https://files.pythonhosted.org/packages/fc/fa/7e4c49bbe09f8e8a26388608d883e7d38c04a6e2dceb35d7e12af3c51307/ggufloader-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d672716003f2d8cb8ca39349e07243ae10c1b123843c22342112b16847e1454d",
"md5": "b2b5fd34ada150be4e7fd2feba2eca23",
"sha256": "79f702c499f4ef39153cf14418ffa65758c6f153a57a0c89bd5d9c4a74ebf6cc"
},
"downloads": -1,
"filename": "ggufloader-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "b2b5fd34ada150be4e7fd2feba2eca23",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 180715,
"upload_time": "2025-07-27T14:18:42",
"upload_time_iso_8601": "2025-07-27T14:18:42.809828Z",
"url": "https://files.pythonhosted.org/packages/d6/72/716003f2d8cb8ca39349e07243ae10c1b123843c22342112b16847e1454d/ggufloader-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 14:18:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "GGUFloader",
"github_project": "gguf-loader",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "llama-cpp-python",
"specs": []
},
{
"name": "PySide6",
"specs": []
}
],
"lcname": "ggufloader"
}
JSON
