Develop

Important

We use Python for sdbx, nnll, Zodiac
and React Flow/Typescript for Singularity

Development Installation

• Review the Contributing documentation

  This will help you understand our project's guidelines and what you might enjoy helping with.

• Our python tools are set up to use using uv. Simply git clone the repo, cd into it, then:

  uv sync
  

  You can also try Zodiac, sdbx, or nnll commands without any installation:

  uvx --from git+https://github.com/darkshapes/zodiac zodiac
  

• For singularity :

  Install Yarn, Bun or use Node.js

  Clone the repo

  git clone https://github.com/darkshapes/singularity
  

  Then install and open your dev copy:

  cd singularity
  yarn install
  yarn run dev
  

  Or use bun or npm as preferred.

Setup

---

• Follow the Python instructions

Install Git (Windows only)

---

1. Download Git

2. In the installer, ensure the Git LFS box is marked

   • Git LFS (Large File Support)

3. Set Git to be usable from Windows Command line

   • Git from the command line and also from 3rd-party software.

4. Set the option to Use Windows' default console window

   • Use Windows' default console window

5. Confirm the git install by opening Command Prompt or Powershell and using the where command. Hit Windows + R and write

   cmd /k where git && pause
   

   This should print a line that says something similar to C:\Program Files\Git\git.exe If not, check your spelling, reboot and try again, or repeat the install step, double-checking that the options are selected.

6. While the terminal window is open, change the behavior of Command Prompt so it does not freeze when clicked:

   i. right click the Command Prompt title bar

   ii. choose Properties and uncheck the QuickEdit Mode box. Hit OK.

   • QuickEdit Mode

Optional build tool prerequisites

Be sure to run these commands in a terminal environment prepped by your compilers of choice (gcc, Visual Studio Code).

pip install --upgrade packaging wheel ninja twine

pip install flash-attn --no-build-isolation

• Clone your repo(s)

  For sdbx :

  git clone https://github.com/darkshapes/sdbx
  pip install -e sdbx
  sdbx
  

  For Zodiac :

  git clone https://github.com/darkshapes/zodiac.git
  pip install -e "zodiac[dev]"
  zodiac
  

  Furthermore, Zodiac is designed to work on a mobile device using the serve command. An independent session can be opened with the method from the same Wi-Fi network using browser or SSH.

  For nnll :

  git clone https://github.com/darkshapes/nnll
  

  • install select packages:

  pip install -e "nnll[nnll_33,nnll_56]"
  

  • install all packages :

  pip install -e "nnll[dev]"
  

Warning

Be aware that even though Zodiac is local first, huggingface/ollama/vllm/operating system may not be set up this way. Zodiac changes the options in Python, but you can also change environment settings to ensure that you are only using cached data before the program launches:

Linux/MacOS

export HF_HUB_DISABLE_TELEMETRY=1
export export HF_HUB_OFFLINE=1

Windows

set HF_HUB_DISABLE_TELEMETRY=1
set export HF_HUB_OFFLINE=1

General Development Reference

*  Environment   : uv
   Telemetry     : False
HFHub Cache Only : True
*  Logging       : structlog (viztrace on crashes) to `/log` folder
*  Testing       : pytest -vv tests
*  Formatting    : ruff/better align
*  Linting       : ruff/pylint
*  Type Checking : pylance/pyright
*  Spelling      : typos vsc
*  Docstrings    : sphinx

Zodiac CLI Commands

zodiac  [-h] [-n] [-t]            = Run Zodiac in the current terminal window
  -h, --help   show this help message and exit
  -n, --net    Allow network access (for downloading requirements)
  -t, --trace  Enable full tracelogging
textual     console [-x EVENTS]  = Run a live console logging session (use before textual --devzodiac/textual serve --dev)
textual     serve [--dev] zodiac = Host a localmachine server (shows CSS edits live, Python edits on refresh)
textual     run --dev zodiac     = Run an instance in command prompt using dev options (shows CSS edits live, relaunch for Python edits)

Zodiac Keyboard Reference

        Tab          : Switch Focus
Up/Down Arrow        : Change option
        Enter        : Begin recording audio
        Space        : Playback audio
        Ctrl-Z       : Undo
        Ctrl-Shift-Z : Redo
        ALT-Backspace: Clear input
        ESC          : Cancel Generation
        ESC/Ctrl-Qx2 : Quit
        Ctrl-C       : Copy (only in console mode)
        Ctrl-V/⌘-V   : Paste (only in console mode)
        Ctrl-X       : Cut (only in console mode)

nnll CLI commands

astra         - Live diagnostic console<br>
nnll-hash    - Hash the layer metadata from models within a directory and write out to console.<br>
nnll-parse   - Process metadata headers from a model file or directory of models and write out to individual JSON files.<br>
nnll-find    - Search a local directory of model layer files (HuggingFace🤗 index.json, JSON from `nnll-parse`)<br>

Notes about nnll

Each module contains 1-5 functions or 1-2 classes and its own test routines. There are multiple ways to integrate nnll into a project (sorted by level of involvement)

• Recommended : Add the project as a dependency including only modules that are needed with "nnll[nnll_04,nnll_16]" @ git+https://github.com/darkshapes/nnll
• Install the entire project as a dependency via nnll @ git+https://github.com/darkshapes/nnll
• Basic clone or fork of the project
• Use a submodule
• Filter a clone of the project to a single subfolder and include it in your own

nnll is a 'living' project. Like a spoken language, it evolves over time. For this reason, we prefer 'living' duplications of the repo. If you still want a static hard copy, you are welcome to copy and paste folders or code wherever you please.

Happy Hacking!