{"id":16786476,"url":"https://github.com/db0/hordelib","last_synced_at":"2025-03-16T23:23:26.769Z","repository":{"id":157676834,"uuid":"622701548","full_name":"db0/hordelib","owner":"db0","description":"A thin wrapper around ComfyUI to allow use by AI Horde.","archived":false,"fork":false,"pushed_at":"2023-05-25T16:22:48.000Z","size":96043,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-01-23T09:33:16.388Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"Haidra-Org/hordelib","license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/db0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-02T21:41:20.000Z","updated_at":"2023-07-09T23:02:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"46b30091-3cb5-4c02-b9c2-7fe2e87f73e4","html_url":"https://github.com/db0/hordelib","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/db0%2Fhordelib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/db0%2Fhordelib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/db0%2Fhordelib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/db0%2Fhordelib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/db0","download_url":"https://codeload.github.com/db0/hordelib/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243945716,"owners_count":20372920,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-13T08:12:20.625Z","updated_at":"2025-03-16T23:23:26.738Z","avatar_url":"https://github.com/db0.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hordelib\n\n[![PyPI Version][pypi-image]][pypi-url]\n[![Downloads][downloads-image]][downloads-url]\n![GitHub license][license-url]\n\n[![Build][build-image]][build-url]\n[![Test Images][main-test-image]][main-test-url]\n[![Test Images][pr-test-image]][pr-test-url]\n[![All Models][all-model-images]][all-model-url]\n[![Release Changelog][changelog-image]][changelog-url]\n\n`hordelib` is a wrapper around [ComfyUI](https://github.com/comfyanonymous/ComfyUI) primarily to enable the [AI Horde](https://aihorde.net/) to run inference pipelines designed visually in the ComfyUI GUI.\n\nThe developers of `hordelib` can be found in the AI Horde Discord server: [https://discord.gg/3DxrhksKzn](https://discord.gg/3DxrhksKzn)\n\n`hordelib` has been the default inference backend library of the [AI Horde](https://aihorde.net/) since `hordelib` v1.0.0.\n\n## Purpose\n\nThe goal here is to be able to design inference pipelines in the excellent ComfyUI, and then call those inference pipelines programmatically. Whilst providing features that maintain compatibility with the existing horde implementation.\n\n## Installation\n\nIf being installed from pypi, use a requirements file of the form:\n```\n--extra-index-url https://download.pytorch.org/whl/cu118\nhordelib\n\n...your other dependencies...\n```\n\n#### Linux Installation\n\nOn Linux you will need to install the Nvidia CUDA Toolkit. Linux installers are provided by Nvidia at https://developer.nvidia.com/cuda-downloads\n\nNote if you only have 16GB of RAM and a default /tmp on tmpfs, you will likely need to increase the size of your temporary space to install the CUDA Toolkit or it may fail to extract the archive. One way to do that is just before installing the CUDA Toolkit:\n```bash\nsudo mount -o remount,size=16G /tmp\n```\nIf you only have 16GB of RAM you will also need swap space. So if you typically run without swap, add some. You won't be able to run this library without it.\n\n## Usage\n\nHorde payloads can be processed simply with (for example):\n\n```python\nimport os\nimport hordelib\nhordelib.initialise()\n\nfrom hordelib.horde import HordeLib\nfrom hordelib.shared_model_manager import SharedModelManager\n\n# Wherever your models are\nos.environ[\"AIWORKER_CACHE_HOME\"] = \"f:/ai/models\"\n\ngenerate = HordeLib()\nSharedModelManager.loadModelManagers(compvis=True)\nSharedModelManager.manager.load(\"Deliberate\")\n\ndata = {\n    \"sampler_name\": \"k_dpmpp_2m\",\n    \"cfg_scale\": 7.5,\n    \"denoising_strength\": 1.0,\n    \"seed\": 123456789,\n    \"height\": 512,\n    \"width\": 512,\n    \"karras\": True,\n    \"tiling\": False,\n    \"hires_fix\": False,\n    \"clip_skip\": 1,\n    \"control_type\": None,\n    \"image_is_control\": False,\n    \"return_control_map\": False,\n    \"prompt\": \"an ancient llamia monster\",\n    \"ddim_steps\": 25,\n    \"n_iter\": 1,\n    \"model\": \"Deliberate\",\n}\npil_image = generate.basic_inference(data)\npil_image.save(\"test.png\")\n```\n\nNote that `hordelib.initialise()` will erase all command line arguments from argv. So make sure you parse them before you call that.\n\nSee `tests/run_*.py` for more standalone examples.\n\n### Logging\n\nIf you don't want `hordelib` to setup and control the logging configuration initialise with:\n\n```python\nimport hordelib\nhordelib.initialise(setup_logging=False)\n```\n\n## Acknowledgments\n\n`hordelib` depends on a large number of open source projects, and most of these dependencies are automatically downloaded and installed when you install `hordelib`. Due to the nature and purpose of `hordelib` some dependencies are bundled directly _inside_ `hordelib` itself.\n\n### [ComfyUI](https://github.com/comfyanonymous/ComfyUI)\nA powerful and modular stable diffusion GUI with a graph/nodes interface. Licensed under the terms of the GNU General Public License v3.0.\n\nThe entire purpose of `hordelib` is to access the power of ComfyUI.\n\n### [Controlnet Preprocessors for ComfyUI](https://github.com/Fannovel16/comfy_controlnet_preprocessors)\nCustom nodes for ComfyUI providing Controlnet preprocessing capability. Licened under the terms of the Apache License 2.0.\n\n### [ComfyUI Face Restore Node](https://civitai.com/models/24690/comfyui-facerestore-node)\n\nCustom nodes for ComfyUI providing face restoration.\n\n## Development\n\nRequirements:\n- `git` (install git)\n- `tox` (`pip install tox`)\n- Set the environmental variable `AIWORKER_CACHE_HOME` to point to a model directory.\n\nNote the model directory must currently be in the original AI Horde directory structure:\n```\n\u003cAIWORKER_CACHE_HOME\u003e\\\n   nataili\\\n        clip\\\n        codeformer\\\n        compvis\\\n            Deliberate.ckpt\n            ...etc...\n        controlnet\\\n        embeds\\\n        esrgan\\\n        gfpgan\\\n        safety_checker\\\n```\n\n### Running the Tests\n\nSimply execute: `tox` (or `tox -q` for less noisy output)\n\nThis will take a while the first time as it installs all the dependencies.\n\nIf the tests run successfully images will be produced in the `images/` folder.\n\n#### Running a specific test file\n\n`tox -- -k \u003cfilename\u003e` for example `tox -- -k test_initialisation`\n\n#### Running a specific predefined test suite\n\n`tox list`\n\nThis will list all groups of tests which are involved in either the development, build or CI proccess. Tests which have the word 'fix' in them will automatically apply changes when run, such as to linting or formatting. You can do this by running:\n\n`tox -e [test_suite_name_here]`\n\n### Directory Structure\n\n`hordelib/pipeline_designs/`\nContains ComfyUI pipelines in a format that can be opened by the ComfyUI web app. These saved directly from the web app.\n\n`hordelib/pipelines/`\nContains the above pipeline JSON files converted to the format required by the backend pipeline processor. These are converted from the web app, see _Converting ComfyUI pipelines_ below.\n\n`hordelib/nodes/` These are the custom ComfyUI nodes we use for `hordelib` specific processing.\n\n### Running ComfyUI Web Application\n\nIn this example we install the dependencies in the OS default environment. When using the git version of `hordelib`, from the project root:\n\n`pip install -r requirements.txt --extra-index-url https://download.pytorch.org/whl/cu118 --upgrade`\n\nEnsure ComfyUI is installed and patched, one way is running the tests:\n\n`tox`\n\nFrom then on to run ComfyUI:\n\n`cd ComfyUI`\n`python main.py`\n\nThen open a browser at: http://127.0.0.1:8188/\n\n### Designing ComfyUI Pipelines\n\nUse the standard ComfyUI web app. Use the \"title\" attribute to name the nodes, these names become parameter names in the `hordelib`. For example, a KSampler with the \"title\" of \"sampler2\" would become a parameter `sampler2.seed`, `sampler2.cfg`, etc. Load the pipeline `hordelib/pipeline_designs/pipeline_stable_diffusion.json` in the ComfyUI web app for an example.\n\nSave any new pipeline in `hordelib/pipeline_designs` using the naming convention \"pipeline_\\\u003cname\\\u003e.json\".\n\nConvert the JSON for the model (see _Converting ComfyUI pipelines_ below) and save the resulting JSON in `hordelib/pipelines` using the same filename as the previous JSON file.\n\nThat is all. This can then be called from `hordelib` using the `run_image_pipeline()` method in `hordelib.comfy.Comfy()`\n\n### Converting ComfyUI pipelines\n\nIn addition to the design file saved from the UI, we need to save the pipeline file in the backend format. This file is created in the `hordelib` project root named `comfy-prompt.json` automatically if you run a pipeline through the ComfyUI version embedded in `hordelib`. Running ComfyUI with `tox -e comfyui` automatically patches ComfyUI so this JSON file is saved.\n\n### Build Configuration\n\nThe main config files for the project are: `pyproject.toml`, `tox.ini` and `requirements.txt`\n\n### PyPi Publishing\n\nPypi publishing is automatic all from the GitHub website.\n\n1. Create a PR from `main` to `releases`\n1. Label the PR with \"release:patch\" (0.0.1) or \"release:minor\" (0.1.0)\n1. Merge the PR with a standard merge commit (not squash)\n\n\n### Standalone \"clean\" environment test from Pypi\n\nHere's an example:\n\nStart in a new empty directory. Create requirements.txt:\n```\n--extra-index-url https://download.pytorch.org/whl/cu118\nhordelib\n```\n\nCreate the directory `images/` and copy the `test_db0.jpg` into it.\n\nCopy `run_controlnet.py` from the `hordelib/tests/` directory.\n\nBuild a venv:\n```\npython -m venv venv\n.\\venv\\Scripts\\activate\npip install -r requirements.txt\n```\n\nRun the test we copied:\n```\npython run_controlnet.py\n\nThe `images/` directory should have our test images.\n```\n\n### Updating the embedded version of ComfyUI\n\nWe use a ComfyUI version pinned to a specific commit, see `hordelib/consts.py:COMFYUI_VERSION`\n\nTo test if the latest version works and upgrade to it, from the project root simply:\n\n1. `cd ComfyUI` _Change CWD to the embedded comfy_\n1. `git checkout master` _Switch to master branch_\n1. `git pull` _Get the latest comfyui code_\n1. `git rev-parse HEAD` _Update the hash in `hordelib.consts:COMFYUI_VERSION`_\n1. `cd ..` _Get back to the hordelib project root_\n1. `tox` _See if everything still works_\n\nNow ComfyUI is pinned to a new version.\n\n### ComfyUI Patching\n\nWe patch the ComfyUI source code to:\n\n1. Modify the model manager to allow us to dynamically move models between VRAM, RAM and disk cache.\n2. Allow make ComfyUI output some handy JSON we need for development purposes.\n\nTo create a patch file:\n- Make the required changes to a clean install of ComfyUI and then run `git diff \u003e yourfile.patch` then move the patch file to wherever you want to save it.\n\nNote that the patch file _really_ needs to be in UTF-8 format and some common terminals, e.g. Powershell, won't do this by default. In Powershell to create a patch file use: `git diff | Set-Content -Encoding utf8 -Path yourfile.patch`\n\nPatches can be applied with the `hordelib.install_comfyui.Installer` classes `apply_patch()` method.\n\n\u003c!-- Badges: --\u003e\n\n[pypi-image]: https://badge.fury.io/py/hordelib.svg?branch=main\u0026kill_cache=1\n[pypi-url]: https://badge.fury.io/py/hordelib\n[downloads-image]: https://pepy.tech/badge/hordelib\n[downloads-url]: https://pepy.tech/project/hordelib\n[license-url]: https://img.shields.io/github/license/jug-dev/hordelib\n[build-image]: https://github.com/jug-dev/hordelib/actions/workflows/maintests.yml/badge.svg?branch=main\n[all-model-images]: https://badgen.net/badge/all-models/images/blue?icon=awesome\n[build-url]: http://hordelib.s3-website-eu-west-1.amazonaws.com/\n[main-test-image]: https://badgen.net/badge/main/latest-images/blue?icon=awesome\n[main-test-url]: http://hordelib.s3-website-eu-west-1.amazonaws.com/\n[pr-test-image]: https://badgen.net/badge/develop/latest-images/blue?icon=awesome\n[pr-test-url]: http://hordelib.s3-website-eu-west-1.amazonaws.com/unstable\n[all-model-url]: http://hordelib.s3-website-eu-west-1.amazonaws.com/all_models/\n[changelog-image]: https://img.shields.io/badge/Release-Changelog-yellow\n[changelog-url]: https://github.com/jug-dev/hordelib/blob/releases/CHANGELOG.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdb0%2Fhordelib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdb0%2Fhordelib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdb0%2Fhordelib/lists"}