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

AMD drivers

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]"
  

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)

Notes about Zodiac

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

Zodiac works by graphing available local model services, then pathing a route through the graph to complete the user request. The system relies heavily on the Textual, dspy, and networkx libraries.

Currently we support models hosted using:

• Ollama
• LMStudio
• Cortex
• Llamafile

Support is being considered for: TensorBlock and VLLM (Compile-only for cpu).

Support is planned for:

• STS/TTS/Image/Video/LoRA models and MLX from Huggingface/CivitAI/ModelScope using sdbx
• Model recognition for non-diffusers standards using nnll
• No-code node-graph workflow modification using Singularity

As mentioned above, the system can be served to a mobile device on the LAN (textual serve). Because the interface runs in terminal console, Zodiac can also be run via ssh from a remotely-accessed computer.

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.

Discussion topics, issue requests, reviews, and code updates are encouraged. Talk to us in our Discord to catch up-to-date information.

Happy Hacking!