[Advanced] DIY Module

Contribute your own module to Lilypad

Contributing your own module is currently a non-trivial process. The Lilypad team is aiming to make this DX easier as well as to add tutorials, walkthroughs and approaches to making modules over the next month. In the meantime if you try this and do get stuck - please reach out to us in Slack for help! Join the Community

Overview

Contributing your own module to use on Lilypad is possible and welcome! Essentially modules on Lilypad currently operate like Bacalhau Job Specifications do - take a look at this page on Creating your own Jobs to see more about how this works. In order that the modules on Lilypad are able to be verified and run on a trustless compute network, the modules also need to be deterministic, so that the job results can be verified by a mediator as needed. See V1 Research Documents for more information on this process.

Requirements

1. Modules must be deterministic: This means that the hash of the results directory will be the same given the same inputs (since we use the same hash tool as IPFS, in practice this means that the CIDs must match). Therefore, as long as a job always converges to the same answer, it does not matter which path it takes to get there. It just matters that the hash CID is the same as this is how mediators validate a result in the trustless network.

2. Modules should be either Docker or WASM Images that align to the Bacalhau job specifications (which then have some added metadata that defines the runtime options of the module).

Module Example

Here is an example of the SDXL module in python:

https://github.com/bacalhau-project/lilypad-modicum/blob/main/src/python/modules/sdxl.py

import yaml

def _sdxl(params: str):
    if params.startswith("{"):
        params = yaml.safe_load(params)
    else:
        prompt = params
        params = {"prompt": prompt, "seed": 0}
    if not isinstance(params, dict):
        raise Exception("Please set params to a dict like {'prompt': 'astronaut riding a horse', 'seed': 42}")
    return {
        "APIVersion": "V1beta1",
        "Metadata": {
            "CreatedAt": "0001-01-01T00:00:00Z",
            "Requester": {}
        },
        "Spec": {
            "Deal": {
                "Concurrency": 1
            },
            "Docker": {
                "Entrypoint": [
                    "bash", "-c",
                    # stderr logging is nondeterministic (includes timing information)
                    "python3 inference.py 2>/dev/null",
                ],
                "Image": "quay.io/lukemarsden/sdxl:v0.9-lilypad1-v2",
                "EnvironmentVariables": [
                    f"PROMPT={params.get('prompt', 'question mark floating in space')}",
                    f"RANDOM_SEED={params.get('seed', 0)}",
                    f"OUTPUT_DIR=/outputs/",
                    "HF_HUB_OFFLINE=1",
                ]
            },
            "Engine": "Docker",
            "Language": {
                "JobContext": {}
            },
            "Network": {
                "Type": "None"
            },
            "PublisherSpec": {
                "Type": "Estuary"
            },
            "Resources": {
                "GPU": "1"
            },
            "Timeout": 1800,
            "Verifier": "Noop",
            "Wasm": {
                "EntryModule": {}
            },
            "outputs": [
                {
                    "Name": "outputs",
                    "StorageSource": "IPFS",
                    "path": "/outputs"
                }
            ]
        }
    }

if __name__ == "__main__":
    print(_sdxl("{prompt: hello, seed: 99}"))
    print(_sdxl("{prompt: 'hello world', seed: 99}"))

It's a function that given a "string" will return a bacalhau docker job spec. That string can be whatever you want, JSON, csv, raw LLM prompt etc. In terms of output directories - you can see the SDXL example linked above names the "/outputs" folder and then will use that path in the command inside the Docker container. Any named folders like this that the Docker image can write files into - will be included as part of the results Lilypad gets back out of the job (and will change the result hash)

Using Bacalhau as a testing ground

It's currently advisable to develop your module with bacalhau first (because it's FAR easier to get setup as a development environment than Lilypad is currently). If you can get a function like the one shown above that will, given a string, write a bacalhau job spec that you can test with the bacalhau CLI - then you have already done 98% of the Lilypad module

To add this to Lilypad, submit a PR which also includes this file here.

Contributing Guidelines

See more in this guide on contributing to the Lilypad project: CONTRIBUTING.md

The Future of Community Contributed Modules

From Lilypad incentivised testnet [Q4 2023] onwards (and perhaps even earlier), its probable modules contributed by community members will be eligible for a % fee of jobs that run these modules in order to encourage the growth of the module ecosystem on the Lilypad Network.