Develop

Important

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

Development

• 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 uv. Simply git clone a repo:

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

  git clone https://github.com/darkshapes/zodiac
  cd zodiac
  

  git clone https://github.com/darkshapes/sdbx
  cd sdbx
  

  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.

Tip

For best results, we recommend using 3D graphics cards for AI work. Please ensure you have the current driver installed for your card.

NVIDIA Drivers / CUDA Toolkit (for gguf)

AMD Drivers / ROCm/HIP Windows / ROCm Linux (for gguf)

Intel drivers

Pip Setup

---

• Follow the Python instructions

• Install Git (Windows Only)

• Configure advanced GPU settings (OPTIONAL. Linux, flash-attn, PyTorch compile, etc)

• Clone your repo(s)

  For sdbx :

  git clone https://github.com/darkshapes/sdbx
  pip install -e sdbx
  sdbx
  ```<hr>
  

  For Zodiac :

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

  Linux users want to ensure libportaudio2 is installed via system package manager. This doesn't apply to Windows or MacOS.

  Ensure Ollama, LMStudio, Cortex, Llamafile is running your models of choice. Then use this command to open the terminal client:

  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
  

  • bare minimum (no dependencies):

  pip install nnll
  

  • install select packages:

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

  • install all packages :

  pip install -e "nnll[dev]"
  

Directions for use

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

Happy Hacking!