[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 the Lilypad Discord for help!

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.

Requirements

1. 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.