loom

This package implements Loom as a Python library and CLI.

Key Features

• build and traverse branching trees of completions for text (base) and chat (instruction-tuned/RL[AI|H]F'd) language models
  • optional base model emulation for chat models when completion_method is set to base_emulation (quality varies)
  • A/B test comma-separated values or interpolate between parameters to evaluate effects on output
  • perform recursive inference to probe pockets of latent space with minimal effort
• import markdown documents as a branch of text nodes
• export trees to compatible formats (Loomsidian only, currently)

Setup

For full glyph support, install a Nerd Font, or patch your existing font (neither is required).

1. Clone and enter the repository directory, create a virtual environment with uv venv and source it, and install the package with uv run loom.

2. Copy the .env.example file to .env and fill in any API keys you want to use. Suggested base model providers are Hyperbolic for llama3.1-405b and Together for mixtral-8x7b. ollama is also supported (llama3.1:8b-text-q5_K_M is a good starting point).

3. If using the CLI, ensure you are in the project directory before running to load keys from the .env file.

Usage

See docs/cli.md for documentation covering core concepts and functionality, or run loom --help for a list of commands.

Inference with local providers

Providers ollama, lmstudio, and llama-cpp are supported as local backends.

Override default hosts/ports in ~/.config/loom/config.yaml:

providers:
  ollama:
    host: 192.168.1.100
    port: 11435
  lmstudio:
    host: remote-server.local
  llama-cpp:
    port: 8001

# optionally define model aliases
model_map:
  lmstudio:
    afm-4.5:
      model_str: afm-4.5-base@q4_k_m
      type: text
  ollama:
    llama-3.1-8b:
      model_str: llama3.1:8b-text-q5_K_M
      type: text
  llama-cpp:
    llama-3.1-70b:
      model_str: Meta-Llama-3.1-70B-Instruct-Q4_K_M.gguf
      type: both

Example commands

Getting started

# create a new text document
loom new

# add and select a node to use as input
loom add "the beautiful thing about a loom is that it weaves"

# request completions for the selected node
loom inference --model llama3.1-405b --temperature 0.7 -n 4 --max-tokens 40

input:
╭─────────────────────────────────── 6c32 ───────────────────────────────────╮
│ the beautiful thing about a loom is that it weaves                         │
╰────────────────────────────────────────────────────────────────────────────╯

output:
 model        llama3.1-405b
 temperature  0.7
 top_p        1.0
 max_tokens   40

╭──────────────────────────────── d8c0 (1/4) ────────────────────────────────╮
│ , if set up properly, exactly the pattern you wanted it to. But you can    │
│ also stick your fingers in and tangle the threads, move the shuttle in new │
│ ways, and just see what happens                                            │
╰──────────────────────────────────────────────────────────────────────── 󰎲 ─╯

╭──────────────────────────────── 2b26 (2/4) ────────────────────────────────╮
│ by itself. i do the work of setting up the warp, get it all nice and tidy, │
│ then i do the work of tying it all on to the front (a process i have yet   │
│ to                                                                         │
╰──────────────────────────────────────────────────────────────────── 󰎨 ─ 󰎫 ─╯

╭──────────────────────────────── 06fa (3/4) ────────────────────────────────╮
│ while you sleep. the greater the time you take setting it up the easier    │
│ the weaving will be. There are a lot of things in life that I find myself  │
│ fighting to get right, but I know                                          │
╰──────────────────────────────────────────────────────────────────── 󰎫 ─ 󰎨 ─╯

╭──────────────────────────────── 801a (4/4) ────────────────────────────────╮
│ in both directions The Beautiful Thing About a Loom is That It Weaves in   │
│ Both Directions THE BEAUTIFUL THING ABOUT A LOOM IS THAT IT WEAVES IN BOTH │
│ D                                                                          │
╰───────────────────────────────────────────────────────────────────── 󰎲 ─  ─╯

Adding nodes

# manually add a node to guide/influence output
loom add "... I mean,"

# show the currently-selected node with context (colorized where supported)
loom show --lineage --colorize

> loom show --lineage --colorize
the beautiful thing about a loom is that it weaves... I mean,

> loom inference --model llama3.1-405b --temperature 0.7 -n 2 --max-tokens 80

input:
╭─────────────────────────────────── 508a ───────────────────────────────────╮
│ ... I mean,                                                                │
╰───────────────────────────────────────────────────────────────────── 󰎯 ─  ─╯

output:
 model        llama3.1-405b
 temperature  0.7
 top_p        1.0
 max_tokens   80

╭──────────────────────────────── 6640 (1/2) ────────────────────────────────╮
│ you could have a loom that weaves in the middle of the woods. If you took  │
│ the warp off the loom and brought it to a studio, it would still be        │
│ weaving, without anyone watching. Anyone could make a loom that weaves,    │
│ and leave it there, and it would still be weaving. The warp and the weft,  │
│ the heddles, and the shafts                                                │
╰──────────────────────────────────────────────────────────────────── 󰎽 ─ 󰎨 ─╯

╭──────────────────────────────── 0404 (2/2) ────────────────────────────────╮
│ it does the work. I do a lot of work to get it to that point, but once the │
│ loom is dressed it does what it was made to do. I am so thankful for that. │
│ I've been weaving every day. A few inches a day. I'm not in a hurry, but I │
│ am consistent. And every day I look at the cloth that is building and I    │
│ think                                                                      │
╰───────────────────────────────────────────────────────────────────── 󰏀 ─  ─╯

Selecting/targeting nodes

Nodes can be selected with select [id/reference].

❯ loom select 0404
Selected node: ID = 0404c6b7-9749-42b9-bcd8-934ac7c3d32e

╭─────────────────────────────────── 0404 ───────────────────────────────────╮
│ it does the work. I do a lot of work to get it to that point, but once the │
│ loom is dressed it does what it was made to do. I am so thankful for that. │
│ I've been weaving every day. A few inches a day. I'm not in a hurry, but I │
│ am consistent. And every day I look at the cloth that is building and I    │
│ think                                                                      │
╰───────────────────────────────────────────────────────────────────── 󰏀 ─  ─╯

Node references can be full or partial node IDs, or a relative position specified with '<' or '>' for siblings, and ^ for ancestors (multiple characters can be used to multiply the distance).

Numbers can also be appended to positional references to specify the number of nodes to jump, e.g. ^2 for the parent of the parent node, or ^-1 for the root node.

# select the sibling node to the left
loom select "<"

# show the root node
loom show ^-1

# show the parent node
loom show ^

# show the lineage (panel per node) of the node two siblings to the right
loom show ">>" --lineage

# show the lineage (single string) of the node whose ID starts with 6640
loom show 6640 --lineage

License

This project is licensed under the MPL 2.0 license.