Overview

Lilypad is developing a serverless, distributed compute network that enables internet-scale data processing, AI, ML & other arbitrary computation, while unleashing idle processing power & unlocking a new marketplace for compute.

You can use Lilypad to run AI workload models including Stable Diffusion and Stable Diffusion Video, or you can add your own module to run on the Lilypad Network. Using Lilypad's distributed compute nodes, you can build and run your own containerized workloads that require high-performance computing.

Job Modules

A Lilypad Job Module is a standard containerized (Docker) process for running compute workloads on Lilypad. Easily deploy an AI model or other compute intensive workloads to the Lilypad decentralized GPU network. Learn more about running AI workloads via Lilypad job modules, and use our inference API or CLI to start sending job requests.

Build your own Lilypad job modules either from an empty project or with our create-lilypad-modulepackage.

Resource Providers

The Lilypad Network aggregates idle compute (CPU and GPU) capacity from providers around the world. Compute providers on the network are referred to as Resource Providers.

If you're interested in becoming a Lilypad Resource Provider, first make sure that you meet our minimum hardware requirements, then register for the Lilypad Resource Provider Beta Program. Learn more about running a Resource Provider on Lilypad here!

Earn Lilybit Rewards

There are many ways to earn Lilybit rewards for participating in the Lilypad economy! Resource Providers earn rewards for running compute jobs and the community earns rewards for building on the network and supporting the ecosystem! Find all rewards opportunities below:

• Apply to the RP Beta program and earn Resource Providers rewards

• Join the Lilypad Ambassador Program by submitting info here

• Add a model to run on Lilypad or build a project listed in the Bounty Board

• Complete open source community issues

Join our Discord and start contributing!

Roadmap

View the Lilypad Roadmap.

Join the Community & Chat with Us

Lilypad Network

Lilypad Linktree

@Lilypad_Tech

Lilypad Blog

@LilypadNetwork

Lilypad-Tech Github

Lilypad Luma

Lilypad allows you to run on-demand compute jobs on the network, enabling AI inference and high-performance workloads without managing infrastructure.

Inference API

Submit inference jobs, process requests and retrieve results using Lilypad’s API

CLI

Run compute jobs, manage workloads and interact with the network directly from your terminal.

Lilypad allows you to run on-demand compute jobs on the network using the Lilypad API, enabling AI inference and high-performance workloads without managing infrastructure.

Overview

This guide will take you through:

• Obtaining API keys

• Basic usage

To interact with Lilypad's API, you'll first need to create an account and obtain an API key for authentication. This key allows you to submit jobs and retrieve results securely.

Sign Up

Visit the Lilypad API Dashboard and sign up using an email address.

Generate API key

Next, log in to the dashboard and click "Create API key".

Now that you've created a new API key you can copy and securely store your API key for usage.

Once you have your API key, you can start running AI inference jobs using Lilypad's Anura API. Below is a simple "Hello World" example to get started.

Get Available Models

Before running a job, check which models are supported:

curl -X GET "https://anura-testnet.lilypad.tech/api/v1/models" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Run a Job

Use the API to send a simple chat completion request using one of the available models:

curl -X POST "https://anura-testnet.lilypad.tech/api/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "MODEL_NAME:MODEL_VERSION",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful AI assistant"
      },
      {
        "role": "user",
        "content": "What order do frogs belong to?"
      }
    ],
    "temperature": 0.6
  }'

Replace "MODEL_NAME:MODEL_VERSION" with the model you want to use from the previous step.

Retreive Job Results

You can check the status of your job and retrieve outputs using the job ID:

curl -X GET "https://anura-testnet.lilypad.tech/api/v1/jobs/{job_id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

This will return details on whether the job is still processing or has completed.

For more advanced usage, including streaming completions, multi-turn conversations, and additional endpoints, check out the inference API Documentation.

Lilypad allows you to run on-demand compute jobs on the network using the Lilypad CLI, enabling AI inference and high-performance workloads without managing infrastructure.

Overview

This guide will take you through:

• Installing the Lilypad CLI.

• Setting up your wallet.

• Running a Cowsay job on Lilypad Network, the Lilypad module equivalent to Hello, World!

The installation process for the Lilypad CLI involves several automated steps to configure it for your specific system. Initially, the setup script identifies your computer's architecture and operating system to ensure compatibility. It will then download the latest production build of the Lilypad CLI directly from the official GitHub repository using curl and wget.

Once the CLI tool is downloaded, the script sets the necessary permissions to make the executable file runnable. It then moves the executable to a standard location in your system's path to allow it to be run from any terminal window.

Install via officially released binaries

Lilypad offers two distinct installation options to cater to different roles within the network:

• One for Lilypad users who wish to run compute jobs on the Lilypad Network.

• Another for resource providers who supply the computational resources to the Lilypad Network.

Select the appropriate installation based on your role:

# Detect your machine's architecture and set it as $OSARCH
OSARCH=$(uname -m | awk '{if ($0 ~ /arm64|aarch64/) print "arm64"; else if ($0 ~ /x86_64|amd64/) print "amd64"; else print "unsupported_arch"}') && export OSARCH;
# Detect your operating system and set it as $OSNAME
OSNAME=$(uname -s | awk '{if ($1 == "Darwin") print "darwin"; else if ($1 == "Linux") print "linux"; else print "unsupported_os"}') && export OSNAME;
# Download the latest production build
curl https://api.github.com/repos/lilypad-tech/lilypad/releases/latest | grep "browser_download_url.*lilypad-$OSNAME-$OSARCH-cpu" | cut -d : -f 2,3 | tr -d \" | wget -i - -O lilypad

# Make Lilypad executable and install it
chmod +x lilypad
sudo mv lilypad /usr/local/bin/lilypad

# Detect your machine's architecture and set it as $OSARCH
OSARCH=$(uname -m | awk '{if ($0 ~ /arm64|aarch64/) print "arm64"; else if ($0 ~ /x86_64|amd64/) print "amd64"; else print "unsupported_arch"}') && export OSARCH;
# Detect your operating system and set it as $OSNAME
OSNAME=$(uname -s | awk '{if ($1 == "Darwin") print "darwin"; else if ($1 == "Linux") print "linux"; else print "unsupported_os"}') && export OSNAME;
# Download the latest production build
curl https://api.github.com/repos/lilypad-tech/lilypad/releases/latest | grep "browser_download_url.*lilypad-$OSNAME-$OSARCH-gpu" | cut -d : -f 2,3 | tr -d \" | wget -i - -O lilypad

# Make Lilypad executable and install it
chmod +x lilypad
sudo mv lilypad /usr/local/bin/lilypad

Set WEB3_PRIVATE_KEY

You're required to set your private key environment variable, WEB3_PRIVATE_KEY, to interact securely with the network.

export WEB3_PRIVATE_KEY=<your private key>

To use the Lilypad CLI, the set private key will need to hold Lilypad testnet tokens and Arbitrum Sepolia ETH. You can find those instructions in the Setting Up Your Wallet documentation.

Verify installation

To verify the installation, running lilypad in the terminal should display a list of available commands, indicating that Lilypad CLI is ready to use.

Lilypad: <VERSION>
Commit: <COMMIT>

Usage:
  lilypad [command]

Available Commands:
  completion        Generate the autocompletion script for the specified shell
  help              Help about any command
  jobcreator        Start the lilypad job creator service.
  mediator          Start the lilypad mediator service.
  pow-signal        Send a pow signal to smart contract.
  resource-provider Start the lilypad resource-provider service.
  run               Run a job on the Lilypad network.
  solver            Start the lilypad solver service.
  version           Get the lilypad version

Flags:
  -h, --help             help for lilypad
  -n, --network string   Sets a target network configuration (default "testnet")

Use "lilypad [command] --help" for more information about a command.

Thats it! You've successfully installed the Lilypad CLI on your machine! 🎉

Uninstall Lilypad

To uninstall Lilypad, you'll need to remove the lilypad binary.

The following command detects where the lilypad binary is located and removes it.

🚨 Using sudo rm -rf can be dangerous if not used carefully. Proceed with caution.

sudo rm -rf $(which lilypad)

You can verify Lilypad has been uninstalled successfully with the following command:

which lilypad

If the uninstall was successful, you should see the message lilypad not found.

Both Resource Providers (GPU compute nodes) and those looking to run jobs on the Lilypad network need to set up a Metamask account in order to run jobs on Lilypad. The public key of your wallet address is how you are identified on the network, and is how you can look up the transactions you make on the Arbitrum Sepolia blockchain explorer. You need an account for running jobs, and a separate account for each GPU you want to set up on the network.

The wallet you use for your account must have both ETH (to run smart contracts on Ethereum) and Lilypad (LP) tokens in order to pay for jobs (or receive funds for jobs) on the network.

Create a MetaMask wallet

End users of Lilypad can decide which crypto wallet they would like to use. In this guide, we advise using a MetaMask crypto wallet.

• Install MetaMask Extension

Connect to the Arbitrum Sepolia Testnet in MetaMask.

The Lilypad Testnet (IncentiveNet) is currently running on the Arbitrum L2 network built on Ethereum.

In order to change to the Arbitrum network in the wallet, open MetaMask and click the network button in the top left of the menu bar:

Then select "Add network":

Next, select "Add a network manually":

Input the required Arbitrum Sepolia Testnet network info, and then "Save":

• Network name: Arbitrum Sepolia

• New RPC URL: https://sepolia-rollup.arbitrum.io/rpc

• Chain ID: 421614

• Currency symbol: ETH

• Block explorer URL: https://sepolia.arbiscan.io (optional)

Import the Testnet LP token

The wallet is now setup and will display an ETH (Arbitrum Sepolia) token balance. In order to also display the LP token balance, the LP token will need to be imported.

Select "Import tokens" from the three dot menu next to the network name:

Select "Custom token" and add the Lilypad token contract address and token symbol. Then "Save".

• Token contract address: 0x0352485f8a3cB6d305875FaC0C40ef01e0C06535

• Token symbol: LP

You should now see both ETH and LP listed in the wallet (initial ETH and LP balances will be 0).

Now you're ready to fund the wallet with testnet LP and ETH tokens!

Funding Your Wallet

Get Testnet Lilypad Tokens (LP) and Arbitrum Sepolia Testnet ETH

tldr: To obtain funds, first ensure the wallet is connected to the Arbitrum Sepolia network. then, collect LP and ETH tokens from these faucets:

• Lilypad Testnet tokens (LP)

• Arbitrum Sepolia ETH (3rd party faucet list)

Faucet Guide

Get Testnet LP tokens

Find out why you need tokens in the FAQs

Follow these steps to successfully claim your Testnet LP tokens:

1. Navigate to the Lilypad Testnet faucet.

2. Authenticate with Discord.

3. Copy your MetaMask wallet address into the input.

4. Click "Request".

Testnet LP tokens will be sent to the wallet address provided to the faucet.

Get Arbitrum Sepolia Testnet ETH

Get Arbitrum Sepolia ETH from this list of third party faucets. Each faucet is designed differently, so follow the instructions provided.

View tokens

With a balance of both LP and ETH, you're ready to run jobs with the Lilypad CLI!

Before you run a Lilypad job, make sure you have Lilypad CLI installed and have set a WEB3_PRIVATE_KEY env variable in your environment.

Run Cowsay

cowsay is a classic CLI tool that prints messages in a speech bubble from an ASCII cow. You can run it as a job on the Lilypad network.

Run the command:

lilypad run cowsay:v0.0.4 -i Message="moo"

Wait for the compute to take place and for the results to be published:

⠀⠀⠀⠀⠀⠀⣀⣤⣤⢠⣤⣀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⢴⣿⣿⣿⣿⢸⣿⡟⠀⠀⠀⠀⠀    ██╗     ██╗██╗  ██╗   ██╗██████╗  █████╗ ██████╗
⠀⠀⣰⣿⣦⡙⢿⣿⣿⢸⡿⠀⠀⠀⠀⢀⠀    ██║     ██║██║  ╚██╗ ██╔╝██╔══██╗██╔══██╗██╔══██╗
⠀⢰⣿⣿⣿⣿⣦⡙⣿⢸⠁⢀⣠⣴⣾⣿⡆    ██║     ██║██║   ╚████╔╝ ██████╔╝███████║██║  ██║
⠀⣛⣛⣛⣛⣛⣛⣛⠈⠀⣚⣛⣛⣛⣛⣛⣛    ██║     ██║██║    ╚██╔╝  ██╔═══╝ ██╔══██║██║  ██║
⠀⢹⣿⣿⣿⣿⠟⣡⣿⢸⣮⡻⣿⣿⣿⣿⡏    ███████╗██║███████╗██║   ██║     ██║  ██║██████╔╝
⠀⠀⢻⣿⡟⣩⣾⣿⣿⢸⣿⣿⣌⠻⣿⡟⠀    ╚══════╝╚═╝╚══════╝╚═╝   ╚═╝     ╚═╝  ╚═╝╚═════╝ v2.13.0
⠀⠀⠀⠉⢾⣿⣿⣿⣿⢸⣿⣿⣿⡷⠈⠀⠀
⠀⠀⠀⠀⠀⠈⠙⠛⠛⠘⠛⠋⠁⠀ ⠀⠀⠀   Decentralized Compute Network  https://lilypad.tech

🌟  Lilypad submitting job
2025-03-05T12:56:38-06:00 WRN ../runner/work/lilypad/lilypad/cmd/lilypad/utils.go:63 > failed to get GPU info: gpuFillInfo not implemented on darwin
2025-03-05T12:56:38-06:00 INF ../runner/work/lilypad/lilypad/pkg/web3/sdk.go:209 > Connected to arbitrum-sepolia-rpc.publicnode.com
2025-03-05T12:56:38-06:00 INF ../runner/work/lilypad/lilypad/pkg/jobcreator/run.go:27 > Public Address: 0xB86bCAe21AC95BCe7a49C057dC8d911033f8CB7c
Enumerating objects: 42, done.
Counting objects: 100% (22/22), done.
Compressing objects: 100% (4/4), done.
Total 42 (delta 18), reused 19 (delta 18), pack-reused 20 (from 1)
💌  Deal agreed. Running job...
🤔  Results submitted. Awaiting verification...
🤔  Results submitted. Awaiting verification...
✅  Results accepted. Downloading result...
🆔  Data ID: QmP2SQttNC3Hrh2xpY7bNHzV2jHq7MbfLahRC46DVzn5rG

🍂 Lilypad job completed, try 👇
    open /tmp/lilypad/data/downloaded-files/QmQHrsiAuzTLn5VU6jg5LoXBRrAkEVRKiYeJE29w54gg9Q
    cat /tmp/lilypad/data/downloaded-files/QmQHrsiAuzTLn5VU6jg5LoXBRrAkEVRKiYeJE29w54gg9Q/stdout
    cat /tmp/lilypad/data/downloaded-files/QmQHrsiAuzTLn5VU6jg5LoXBRrAkEVRKiYeJE29w54gg9Q/stderr

View your results:

cat /tmp/lilypad/data/downloaded-files/QmQHrsiAuzTLn5VU6jg5LoXBRrAkEVRKiYeJE29w54gg9Q/stdout

~ % cat /tmp/lilypad/data/downloaded-files/QmQHrsiAuzTLn5VU6jg5LoXBRrAkEVRKiYeJE29w54gg9Q/stdout
 ________________ 
< hello, lilypad >
 ---------------- 
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Lilypad provides distributed computational services underpinned by the Bacalhau Project. The network provides infrastructure for use cases like AI inference, ML training, DeSci and more. Lilypad strategically collaborates with decentralized infrastructure networks, such as Filecoin, to formulate a transparent, efficient, and accessible computational ecosystem.

Perform off-chain decentralized compute over data, with on-chain guarantees. Call this functionality directly from a smart contract, CLI, and an easy to use abstraction layer.

The network is actively laying groundwork for multi-chain integration and the deployment of an incentivized testnet.

Lilypad has evolved from earlier versions (v0, v1 & v2), where the network served as a proof of concept for verifiable, decentralized compute directly from smart contracts. These earlier iterations established the groundwork for what is now a robust, scalable platform with expanded features and multichain support.

Bacalhau has been integral to Lilypad since its early versions (v0 and v1), serving as the backbone for verifiable off-chain compute. In these early iterations, Bacalhau was used for Proof of Concept projects, helping users execute decentralized compute jobs from smart contracts.

Find Lilypad on GitHub or visit the blog.

Objective and problem statement

Lilypad aims to mitigate the challenges predominantly associated with the accessibility of high-performance computational hardware. At present, numerous barriers impede developers and organizations from smoothly integrating projects that require high-performance computing, such as AI technologies, into their applications.

Unlike conventional centralized systems, where access to powerful compute hardware is restricted and costly, Lilypad endeavors to democratize this access. Through its verifiable, trustless, and decentralized computational network, Lilypad extends unrestricted, global access to computational power. By leveraging decentralized infrastructure networks such as Filecoin, Lilypad is strategically positioned to enhance the efficiency, transparency, and accessibility of high-performance computing hardware.

Applications

Perform off-chain decentralized compute over data, with on-chain guarantees, and to call this functionality directly from a smart contract, CLI, API and an easy to use abstraction layer, opens the door to a multitude of possible applications including:

• Inference AI jobs

• ML training jobs

• Invoking & supporting generic ZK computations

• Cross-chain interoperability complement to bridge protocols

• Federated Learning consensus (with Bacalhau insulated jobs)

• IOT & Sensor Data integrations

• Providing a platform for Digital twins

• Supply chain tracking & analysis

• ETL & data preparation jobs

Key features

Some of the key features of Lilypad include:

1. Verifiable Serverless Decentralized Compute Network: Lilypad is a decentralized compute network that aims to provide global, permissionless access to compute power. The Network orchestrates off-chain compute (a global GPU marketplace) and uses on-chain verification (Arbitrum L2 on Ethereum) to provide guarantees of compute success.

2. Mainstream Web3 Application Support: Lilypad is designed to enable mainstream web3 applications to use its compute network with the API, Lilypad CLI and Smart Contracts. It aims to make decentralized AI compute more accessible, efficient, and transparent for developers and users.

3. Open Compute Network: Lilypad is an open compute network allowing users to access and run AI models/other programs in a serverless manner. Module creators and general users can access a curated set of modules or can easily create their own Lilypad module to run an AI model/other program on the network.

4. Multichain Support: The Lilypad Incentivized Testnet first launched on Arbitrum in June 2024 with plans to go multi-chain in the near future. Supporting multiple blockchain networks will increase the scalability and interoperability of the network, allowing users to choose the blockchain that best suits their needs.

5. Incentivized Test Net: The Lilypad IncentiveNet is live! The IncentiveNet program provide users with Lilybit_ rewards to participate in running nodes, testing, and improving the network. Learn more by checking out the IncentiveNet Leaderboard.

6. Decentralization of Mediators: The team also aims to decentralize the mediators in the network. This means that the decision-making process and governance of the network will be distributed among multiple participants, ensuring a more decentralized and resilient system.

There are multiple ways to participate in the Lilypad ecosystem and earn rewards for your contributions.

Developers

• Bounty Board

Community Members

• Community Leaderboard

• Ambassador Program

Resource Providers

In exchange for providing compute power to Lilypad's decentralized compute network, Resource Providers (RPs) accumulate Lilybit_ credits based on their contributions to the network.

RP incentives on Testnet will be provided via the Lilypad RP Beta Program. Any RP can submit info to join the RP beta program, although RPs with more resources will be prioritized in order to run large models on Lilypad Network.

• Minimum hardware requirements

• Lilypad RP Beta Program

• Lilybit_ Rewards

Builder-verse is a space for developers, labs, and builders to create powerful tools and workflows on the Lilypad Network. It’s part of our mission to accelerate open source AI through decentralized compute infrastructure and accessible tooling.

What is it?

An open, ongoing program designed to help you build with Lilypad. There are no deadlines or fixed formats. Whether you're creating modules, building agent workflows or integrating Lilypad into a larger stack, Builder-verse gives you the space, support and rewards to grow your ideas.

How to participate

Lilypad rewards contributors who help grow the network, whether you're building modules and agents or providing GPU compute.

You don’t need to wait for a hackathon. Submit anytime and track your impact on the leaderboard. Top contributors may also be eligible for additional support, amplification, and future grant opportunities.

Builders

• Creating and publishing modules

• Building agents or full-stack applications that use Lilypad modules

• Driving usage. The more your module or agent is used, the more rewards you earn

Resource Providers

Participating and receiving rewards isn't just for builders. Resource providers (GPU node operators) can earn by contributing compute to the network.

We’re rolling out the RP Beta Program, which includes:

• Node verification

• Updated hardware and connectivity standards

• A new reward structure aligned with Mainnet

The goal is to ensure high-quality compute jobs and support reliable contributors. Stay tuned in the #updates-rp channel in Discord, and sign up for the RP Beta Program here.

What can I build?

• Your own custom AI modules

• Agent pipelines using existing modules

• Apps using Lilypad’s CLI or API

• Integrations with your existing tools or workflows

Tools & Guides

Looking for inspiration or guidance? Check out these resources to get you started!

• Build a module guide - Step-by-step guide to creating your own Lilypad module

• create-lilypad-module - CLI tool to scaffold a new module with everything you need to get started

• Agents on Lilypad - Create composable AI workflows powered by Lilypad modules

Check out our awesome-lilypad repo for a curated collection of modules, templates, and community examples!

Get Involved

Join the Lilypad Discord and follow us on socials to stay up to date with the action!

• Discord

• Twitter/X

• GitHub

• Read the full blog announcement

• Explore awesome-lilypad on GitHub

🍃 General Questions

What is the Lilypad Network?

Lilypad is developing a serverless, distributed compute network that enables internet-scale data processing for AI, ML & other arbitrary computation from blockchains, while unleashing idle processing power & unlocking a new marketplace for compute.

Lilypad provides decentralized AI computational services. By extending unrestricted, global access to computational power, Lilypad strategically collaborates with decentralized infrastructure networks, such as Filecoin, to formulate a transparent, efficient, and accessible computational ecosystem.

Perform off-chain decentralized compute over data, with on-chain guarantees, and to call this functionality directly from a smart contract, CLI and an easy to use abstraction layer, opens the door to a multitude of possible applications.

Lilypad Whitepaper

The Lilypad Whitepaper was planned to release by end of Q4 2024, but required further review from our team and advisors. See our roadmap for the current timeline.

Roadmap

Find the full Lilypad Network roadmap on our website!

What is the Bacalhau Project?

Bacalhau is a peer to peer computation network enabling compute over data jobs like GPU-enabled AI, ML, analytics, data engineering, data science, de-sci and more. With the open-source Bacalhau Project, you can streamline your existing workflows without rewriting by running Docker containers and WebAssembly (WASM) images as tasks. This architecture is also referred to as Compute Over Data (or CoD).

• To find out more about it, see the Bacalhau Docs

Wait, didn’t Lilypad used to rely on determinism and optimistic reproducibility for verifiable compute?

Previously, Lilypad required deterministic jobs on the network and used optimistic reproducibility to randomly re-run jobs to ensure trust, however this method has been deprecated due to:

1. The limitation the determinism requirement placed on what jobs were available to run on the network

2. The inability to realistically be able to determine a “deterministic” job to be deterministic easily

Has Lilypad raised VC money?

Yes, Lilypad closed our seed round of funding in March 2024.

🌐 Incentivized Testnet Questions

When will the Incentivized Testnet launch?

The Lilypad Incentivized testnet launched in mid June 2024.

How do LilyBit_ rewards work?

Lilybit_ rewards will be awarded to nodes for time on the network (up to a 4x multiplier) and compute power brought to the network. Rewards will be redeemable, for the Lilypad ERC20 Utility Token at Mainnet Launch, with between 5% and 10% of the total token supply (depending on IncentiveNet demand and tokenomics finalization) being allocated to this phase of the Lilypad Network.

Resource Providers (RP) can track their Lilybit_ earnings with the RP Leaderboard.

Who can earn LilyBit_ rewards?

Phase 1 of the Incentivized Testnet is focused on rewarding nodes on the network, referred to as Resource Providers. The earlier a provider joins the network, the more Lilybits_ will be available.

Phases 2 and onward will provide rewards for Lilypad modules created as well as developer tools/apps (in addition to rewarding nodes).

How do I check my Lilybit_ rewards?

You can check your rewards by pasting your nodes wallet address into the following interfaces:

• Grafana dashboard

• Lilypad leaderboard

• Open Source contributor dashboard

How does Lilypad use blockchain, and why do I need both ETH and Lilypad tokens to run a job?

On the Lilypad network, The blockchain is used for

• Payment rails

• Storing the deals transparently (on-chain guarantees about the compute)

• Storing any disputes & results

Lilypad Tokens are used to transact on the Lilypad network. They are used as payment by those who want to run jobs (to the resource providers who run them), and as collateral by resource providers.

You need ETH tokens to pay for the gas fees for smart contracts the facilitate transactions, and for records of transactions and disputes that are posted to the Ethereum blockchain.

⚙️ Hardware Provider Questions

What do I need to do before I can run a Lilypad node?

The required steps before running a Lilypad node include adding the node, adding the Lilypad network information, obtaining tokens and installing the required software.

Refer to the Run a node documentation and select your preferred platform (Linux or Docker) for a detailed guide on the prerequisites.

What are the hardware requirements to run a Lilypad node?

For more information, please visit Hardware Requirements.

What are the updates required for maintaining my node software?

Resource providers are expected to have the latest Lilypad versions installed on their machines. These will be included in the Docker files in each release. For more information, please refer to the Resource Provider docs.

How can I check the status of my Lilypad node?

Find more information check out the Run a node docs.

👩‍💻 Developer Questions

What is a Lilypad Module?

View the Modules section.

How to run a ML job on Lilypad

Follow the quickstart guides to get started.

To build an application with Lilypad compute and modules on the backend, check out this guide.

How to add a ML model to run on Lilypad

A Lilypad module is a Git repository that can be used to perform various tasks using predefined templates and inputs. This "build a job module" guide will walk you through the process of creating a Lilypad module, including defining a JSON template, handling inputs, ensuring determinism, and other best practices.

How to run a Lilypad node

Lilypad is an open network that allows anyone to contribute GPU computing capacity. Find instructions for running a node in our Run a node documentation.

Node hardware specs

• Linux (latest Ubuntu LTS recommended)

• Nvidia GPU

• Nvidia drivers

• Docker

• Nvidia docker drivers

For more information on the requirements to run a Lilypad node, please refer to the hardware requirements documentation.

📖 Token Questions

Expected TGE

Although the launch date is not finalized, the launch of Lilypad Mainnet and the TGE is scheduled for 2025.

Getting Started

Use Anura to start running AI inference job modules on Lilypad's decentralized compute network:

1. Get an API key from the Anura website.

2. Find which models we support:

curl GET "https://anura-testnet.lilypad.tech/api/v1/models" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

1. Choose a model and customize your request:

curl -X POST "https://anura-testnet.lilypad.tech/api/v1/chat/completions" \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "model": "MODEL_NAME:MODEL_VERSION",
  "messages": [{
    "role": "system",
    "content": "you are a helpful AI assistant"
  },
  {
    "role": "user",
    "content": "what order do frogs belong to?"
  }],
  "stream": true,
  "temperature": 0.6
}'

API Endpoints

API Clients

Get Available Models

To see which models are available:

curl -X GET "https://anura-testnet.lilypad.tech/api/v1/models" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY"

Chat Completions API

Chat Completions

POST /api/v1/chat/completions

Note: Due to the decentralized nature of the Lilypad Network we recommend using the streaming variant where possible at this time

This endpoint provides both a streaming interface using Server-Sent Events (SSE) and non-streaming interface for chat completions which is compliant with the OpenAI specification. This means that you can plug and play Anura using the OpenAI SDK by simply passing in the Anura Url and API Key into your client like so:

import OpenAI from 'openai';

const client = new OpenAI({
    baseURL: 'https://anura-testnet.lilypad.tech/api/v1',
    apiKey: process.env.ANURA_API_KEY || '',
});

const completion = await client.chat.completions.create({
  model: 'llama3.1:8b',
  messages: [
    { role: 'system', content: 'You are a helpful AI assistant.' },
    { role: 'user', content: 'Are semicolons optional in JavaScript?' },
  ],
});

return completion.choices[0].message.content;

Request Headers

• Content-Type: application/json*

• Accept: text/event-stream (recommended for streaming)

• Authorization: Bearer YOUR_API_KEY*

Request Parameters

Request Body (non-streaming)

{
  "model": "llama3.1:8b",
  "messages": [
    {
      "role": "system",
      "content": "you are a helpful AI assistant"
    },
    {
      "role": "user",
      "content": "write a haiku about lilypads"
    }
  ],
  "temperature": 0.6
}

Response Format (non-streaming)

The response is an OpenAI ChatCompletion Object with the following format:

{
    "id": "jobId-Qmds4fif8RLVKrSKfWVGHe7fDkBwizzV5omd3kPSnc8Xdf-jobState-ResultsSubmitted",
    "object": "chat.completion",
    "created": 1742509938,
    "model": "llama3.1:8b",
    "system_fingerprint": "",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Lily pads dance\nOn the water's gentle lap\nSerene beauty"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 2048,
        "completion_tokens": 184,
        "total_tokens": 2232
    }
}

Response Codes

• 200 OK: Request successful, stream begins

• 400 Bad Request: Invalid request parameters

• 401 Unauthorized: Invalid or missing API key

• 404 Not Found: Requested model not found

• 500 Internal Server Error: Server error processing request

Response Object Fields

The response data contains the following fields:

Request Body (streaming)

{
  "model": "llama3.1:8b",
  "messages": [
    {
      "role": "system",
      "content": "you are a helpful AI assistant"
    },
    {
      "role": "user",
      "content": "write a haiku about lilypads"
    }
  ],
  "stream": true,
  "temperature": 0.6

Response Format (streaming)

The response is a stream of Server-Sent Events (SSE) with chunked OpenAI ChatCompletion objects with the following format:

Initial response:

data: {
    "id": "jobId-QmZXDGS7m8VuJrURqsKvByGKHCM749NMVFmEA2hH2DtDWs-jobState-DealNegotiating",
    "object": "chat.completion.chunk",
    "created": 1742425132,
    "model": "llama3.1:8b",
    "system_fingerprint": "",
    "choices": [
        {
            "index": 0,
            "delta": {
                "role": "assistant",
                "content": null
            },
            "finish_reason": null
        }
    ],
    "usage": {
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "total_tokens": 0
    }
}

Processing updates:

data: {
    "id": "jobId-QmZXDGS7m8VuJrURqsKvByGKHCM749NMVFmEA2hH2DtDWs-jobState-DealAgreed",
    "object": "chat.completion.chunk",
    "created": 1742425135,
    "model": "llama3.1:8b",
    "system_fingerprint": "",
    "choices": [
        {
            "index": 0,
            "delta": {
                "role": "assistant",
                "content": null
            },
            "finish_reason": null
        }
    ],
    "usage": {
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "total_tokens": 0
    }
}

Content delivery:

data: {
    "id": "jobId-QmZXDGS7m8VuJrURqsKvByGKHCM749NMVFmEA2hH2DtDWs-jobState-ResultsSubmitted",
    "object": "chat.completion.chunk",
    "created": 1742425147,
    "model": "llama3.1:8b",
    "system_fingerprint": "",
    "choices": [
        {
            "index": 0,
            "delta": {
                "role": "assistant",
                "content": "Lily pads dance\nOn the water's gentle lap\nSerene beauty"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 2048,
        "completion_tokens": 456,
        "total_tokens": 2504
    }
}

Completion marker:

data: [DONE]

Response Codes

• 200 OK: Request successful, stream begins

• 400 Bad Request: Invalid request parameters

• 401 Unauthorized: Invalid or missing API key

• 404 Not Found: Requested model not found

• 500 Internal Server Error: Server error processing request

Response Object Fields

The delta event data contains the following fields:

Conversation Context

The API supports multi-turn conversations by including previous messages in the request:

{
    "model": "llama2:7b",
    "messages": [
        {
            "role": "user",
            "content": "write a haiku about lilypads"
        },
        {
            "role": "assistant",
            "content": "Lily pads dance\nOn the water's gentle lap\nSerene beauty"
        },
        {
            "role": "user",
            "content": "Now write one about frogs"
        }
    ],
    "temperature": 0.6
}

This allows for contextual follow-up questions and maintaining conversation history.

Tooling Calls

The Anura chat completions endpoint supports requests with tooling allowing for function calling through many popular AI frameworks and sdks.

At the moment only a select number models support tooling including:

• llama3.1:8b

• qwen2.5:7b

• qwen2.5-coder:7b

• phi4-mini:3.8b

• mistral:7b

Below is a sample request and response

Request:

{
    "model": "mistral:7b",
    "messages": [
        {
            "role": "system",
            "content": "you are a helpful AI assistant"
        },
        {
            "role": "user",
            "content": "What's the weather in Tokyo?"
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "Get the current weather for a city",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "city": {
                            "type": "string",
                            "description": "The name of the city"
                        }
                    },
                    "required": [
                        "city"
                    ]
                }
            }
        }
    ],
    "temperature": 0.6,
    "stream": false
}

Response:

{
    "id": "jobId-QmTm3E4oEu4TYp1FLykHdnrkPyX6cLz2UUYS45YrmrzqdN-jobState-ResultsSubmitted",
    "object": "chat.completion",
    "created": 1742790608,
    "model": "mistral:7b",
    "system_fingerprint": "",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "",
                "tool_calls": [
                    {
                        "id": "call_syyia0kt",
                        "index": 0,
                        "type": "function",
                        "function": {
                            "name": "get_current_weather",
                            "arguments": "{\"city\":\"Tokyo\"}"
                        }
                    }
                ]
            },
            "finish_reason": "tool_calls"
        }
    ],
    "usage": {
        "prompt_tokens": 88,
        "completion_tokens": 22,
        "total_tokens": 110
    }
}

Jobs

• GET /api/v1/jobs/:id - Get status and details of a specific job

Get Status/Details of a Job

You can use another terminal to check job status while the job is running.

curl -X GET "https://anura-testnet.lilypad.tech/api/v1/jobs/{job_id}" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your_api_key_here"

Get Outputs from a Job

Once your job has run, you should get output like this:

data: {
    "id": "cmpl-e654be2df70700d27c155d4d",
    "object": "text_completion",
    "created": 1738614839,
    "model": "llama2",
    "choices": [{
        "text": "<output text here>
        "finish_reason": "stop"
    }]
}

Cowsay

• POST /api/v1/cowsay - Create a new cowsay job

  • Request body: {"message": "text to display"}

• GET /api/v1/cowsay/:id/results - Get results of a cowsay job

Lilypad makes it easy to deploy and run AI models with an AI model hub called the Lilypad Module Marketplace.

Currently setup in the awesome-lilypad github repo, the Module Marketplace makes it easy for AI model creators to distribute their work and for the community to quickly get started running a wide range of open source AI models.

There are two ways that participants in the network can interact with Lilypad Modules: As Job Creators who run modules, or as Module Creators who create modules.

Running Modules

Running Jobs (participating as a 'Job Creator') is just a few simple steps:

• Use the Lilypad AI inference API or install our CLI

• Choose a module to run and send a job request

Example Modules

Try out some of the Lilypad team modules:

• Cowsay

• Llama2

• Stable Diffusion Turbo Pipeline

Additional modules from the community are available in the awesome-lilypad repo.

Creating Modules

A Lilypad Module is a standard containerized (Docker) process for running compute workloads on Lilypad.

Modules can be developed by any member of the community (participating as a 'Module Creator'). If there is an AI model (or other compute job) you wish to run using the Lilypad Network resources, create a new Module and add it to the Module Marketplace!

Developer Resources

• Build a Job Module

• create-lilypad-module

• Module Builder Guide

A Lilypad module is a Git repository that allows you to perform various tasks using predefined templates and inputs. This guide will walk you through creating a Lilypad module, including defining a JSON template, handling inputs, and following best practices.

For a more in-depth look at building modules, refer to this end-to-end guide.

Modules on Lilypad

Below are a few examples of modules you can run on Lilypad. From language models to image generators and fun utilities, the network supports a growing list of AI modules.

To view the full list of available modules on Lilypad, please check out the awesome-lilypad repo!

Module Structure

Start by creating a Git repository for your Lilypad module. The module's versions will be represented as Git tags. Below is the basic structure of a Lilypad Module.

your-module/
├── model-directory            # Stores locally downloaded model files 
├── download_model.[py/js/etc] # Script to download model files locally
├── requirements.txt           # Module dependencies
├── Dockerfile                 # Container definition
├── run_script.[py/js/etc]     # Main execution script
├── lilypad_module.json.tmpl   # Lilypad configuration
└── README.md                  # Documentation

Prepare Your Model

• Download model files

• Handle all dependencies (requirements.txt)

• Implement input/output through environment variables

• Write outputs to /outputs directory

1. Download the model locally

To use a model offline, you first need to download it and store it in a local directory. This guarantees that your code can load the model without requiring an internet connection. Here's a simple process to achieve this:

1. Install required libraries

2. Use a script to download the model (eg: python download_model.py)

3. Verify that the model files are in your directory

from transformers import AutoTokenizer, AutoModelForSeq2SeqLM

def download_model():
    model_name = "<namespace>/<model_identifier>"
    # Ensure you have a directory named 'model' in your current working directory or specify a path
    tokenizer = AutoTokenizer.from_pretrained(model_name)
    model = AutoModelForSeq2SeqLM.from_pretrained(model_name)

    # Save the tokenizer and model
    tokenizer.save_pretrained('./model')
    model.save_pretrained('./model')

if __name__ == "__main__":
    download_model()

2. Create Run Script (run_model.py for example) that will be used in conjunction with Docker

import os
import json
from transformers import AutoModel, AutoTokenizer

def main():
    # Load model and tokenizer from local directory
    model_path = '/model'  # Path to the local model directory
    tokenizer = AutoTokenizer.from_pretrained(model_path)
    model = AutoModel.from_pretrained(model_path)

    # Get inputs from environment variables
    input_var = os.environ.get('INPUT_VAR', 'default')
    
    # Your model code here
    result = your_model_function(input_var, model, tokenizer)
    
    # Save outputs
    output_path = '/outputs/result.json'
    with open(output_path, 'w') as f:
        json.dump({'result': result}, f)

if __name__ == "__main__":
    main()

3. Create a Dockerfile that functions with your run script

# Use specific base image
FROM base-image:version

# Set working directory
WORKDIR /workspace

# Install dependencies
RUN apt-get update && apt-get install -y \
    your-dependencies && \
    rm -rf /var/lib/apt/lists/*

# Install model requirements
RUN pip install your-requirements

# Environment variables for running offline and using the local model 
# HF_HOME points to the directory where the model code is
ENV HF_HOME=/model
ENV TRANSFORMERS_OFFLINE=1

# Create necessary directories
RUN mkdir -p /outputs

# Copy execution script
COPY run_script.* /workspace/

# Set entrypoint
ENTRYPOINT ["command", "/workspace/run_script"]

4. Build and Publish Image

To make sure your Docker image is compatible with Lilypad, you need to define the architecture explicitly during the build process. This is particularly important if you are building the image on a system like macOS, which uses a different architecture (darwin/arm64) than Lilypad's infrastructure (linux/amd64).

The examples below are for building, tagging and pushing an image to DockerHub, but you can use any platform you prefer for hosting the image.

For Linux: docker buildx build -t <USERNAME>/<MODULE_NAME>:<MODULE_TAG> --push .

For MacOS:

docker buildx build \
--platform linux/amd64 \
-t <USERNAME>/<MODULE_NAME>:<MODULE_TAG> \
--push \
.

5. Create a lilypad_module.json.tmpl Template

{
    "machine": {
        "gpu": 1,          # Set to 0 if GPU not needed
        "cpu": 1000,       # CPU allocation
        "ram": 8000        # Minimum RAM needed to run the module
    },
    "gpus": [ { "vram": 100 }, { "vram": 4096 } ] # VRAM in MBs. Solver will default to largest one 
    "job": {
        "APIVersion": "V1beta1",
        "Spec": {
            "Deal": {
                "Concurrency": 1
            },
            "Docker": {
                "Entrypoint": ["command", "/workspace/run_script"],
                "WorkingDirectory": "/workspace",
                "EnvironmentVariables": [
                    # Environment variables with defaults
                    {{ if .var_name }}"VAR_NAME={{ js .var_name }}"{{ else }}"VAR_NAME=default_value"{{ end }}
                ],
                # Specify the Docker image to use for this module
                "Image": "repo-owner/repo-name:tag"
            },
            "Engine": "Docker",
            "Network": {
                "Type": "None"
            },
            "Outputs": [
                {
                    "Name": "outputs",
                    "Path": "/outputs"
                }
            ],
            "PublisherSpec": {
                "Type": "ipfs"
            },
            "Resources": {
                "GPU": "1"    # Must match machine.gpu
            },
            "Timeout": 1800
        }
    }
}

Environment Variables

Format in template:

{{ if .variable }}"VARNAME={{ js .variable }}"{{ else }}"VARNAME=default"{{ end }}

Usage in CLI:

lilypad run repo:tag -i variable=value

Formatting your module run command

During development, you will need to use the Git hash to test your module. This allows you to verify that your module functions correctly and produces the expected results.

Below is a working Lilypad module run cmd for reference. (you can use this to run a Lilypad job within the Lilypad CLI):

Test Module before running on Lilypad

Use the following command syntax to run your Module on Lilypad Testnet.

lilypad run github.com/Lilypad-Tech/module-sdxl:6cf06f4038f1cff01a06c4eabc8135fd9835a78a --web3-private-key <your-private-key> -i prompt="a lilypad floating on a pond"

If the job run appears to be stuck after a few minutes (sometimes it takes time for the Module to download to the RP node), cancel the job and try again. Open a ticket in Discord with any issues that persist.

Run Module on Lilypad

lilypad run github.com/noryev/module-sdxl-ipfs:ae17e969cadab1c53d7cabab1927bb403f02fd2a -i prompt="your prompt here"

Examples

Here are some example Lilypad modules for reference:

• Cowsay: Lilypad "Hello World" example

• Llama2: Text to text

• SDXL-turbo pipeline: Text to image generation

• create-lilypad-module

Deprecated examples:

• lora-training: An example module for LoRa training tasks.

• lora-inference: An example module for LoRa inference tasks.

• duckdb: An example module related to DuckDB.

These examples can help you understand how to structure your Lilypad modules and follow best practices.

Conclusion

In this guide, we've covered the essential steps to create a Lilypad module, including defining a JSON template, handling inputs, and testing your module. By following these best practices, you can build reliable and reusable modules for Lilypad.

For more information and additional examples, refer to the official Lilypad documentation and the Cowsay example module.

These instructions provide steps for running the Llama2 module on the Lilypad network using Docker and the Lilypad CLI. Find the module repo here.

Getting Started

Before running llama2, make sure you have the Lilypad CLI installed on your machine and your private key environment variable is set. This is necessary for operations within the Lilypad network.

export WEB3_PRIVATE_KEY=<YOUR_PRIVATE_KEY>

Learn more about installing the Lilypad CLI and running a Lilypad job with this video guide.

Run Llama2

Run Llama2

lilypad run github.com/noryev/module-llama2:6d4fd8c07b5f64907bd22624603c2dd54165c215 -i prompt="your prompt here"

Example:

lilypad run github.com/noryev/module-llama2:6d4fd8c07b5f64907bd22624603c2dd54165c215 -i prompt="what is a giant sand trout on arrakis?"

Notes

• Ensure you have the necessary permissions and resources to run Docker containers with GPU support.

• The module version (6d4fd8c07b5f64907bd22624603c2dd54165c215) may be updated. Check for the latest version before running.

• Adjust port mappings and volume mounts as needed for your specific setup.

Output

To view the results in a local directory, navigate to the local folder provided by the job result.

open /tmp/lilypad/data/downloaded-files/<fileID>

These instructions provide steps for running the SDXL Turbo Pipeline module on the Lilypad network using Docker and Lilypad CLI. Find the module repo here.

Getting Started

Before running sdxl turbo, make sure you have the Lilypad CLI installed on your machine and your private key environment variable is set. This is necessary for operations within the Lilypad network.

export WEB3_PRIVATE_KEY=<YOUR_PRIVATE_KEY>

Learn more about installing the Lilypad CLI and running a Lilypad job with this video guide.

Run SDXL Turbo

lilypad run github.com/noryev/module-sdxl-ipfs:ae17e969cadab1c53d7cabab1927bb403f02fd2a -i prompt="your prompt here"

Example:

lilypad run github.com/noryev/module-sdxl-ipfs:ae17e969cadab1c53d7cabab1927bb403f02fd2a -i prompt="a spaceship parked on mountain"

Notes

• Ensure you have the necessary permissions and resources to run Docker containers with GPU support.

• The module version (ae17e969cadab1c53d7cabab1927bb403f02fd2a) may be updated. Check for the latest version before running.

• Adjust port mappings and volume mounts as needed for your specific setup.

Output

To view the results in a local directory, navigate to the local folder.

open /tmp/lilypad/data/downloaded-files/<fileID>

cowsay is a simple, text-based program originally written for Unix-like operating systems that generates ASCII pictures of a cow with a speech bubble containing a specified message.

This module was created as a "Hello World" for the Lilypad Network!

Getting Started

Before running cowsay, make sure you have the Lilypad CLI installed on your machine and your private key environment variable is set. This is necessary for operations within the Lilypad network.

export WEB3_PRIVATE_KEY=<YOUR_PRIVATE_KEY>

Run cowsay

Once you've installed the CLI, run the cowsay command:

lilypad run cowsay:v0.0.4 -i Message="hello, lilypad"  

Output

⠀⠀⠀⠀⠀⠀⣀⣤⣤⢠⣤⣀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⢴⣿⣿⣿⣿⢸⣿⡟⠀⠀⠀⠀⠀    ██╗     ██╗██╗  ██╗   ██╗██████╗  █████╗ ██████╗
⠀⠀⣰⣿⣦⡙⢿⣿⣿⢸⡿⠀⠀⠀⠀⢀⠀    ██║     ██║██║  ╚██╗ ██╔╝██╔══██╗██╔══██╗██╔══██╗
⠀⢰⣿⣿⣿⣿⣦⡙⣿⢸⠁⢀⣠⣴⣾⣿⡆    ██║     ██║██║   ╚████╔╝ ██████╔╝███████║██║  ██║
⠀⣛⣛⣛⣛⣛⣛⣛⠈⠀⣚⣛⣛⣛⣛⣛⣛    ██║     ██║██║    ╚██╔╝  ██╔═══╝ ██╔══██║██║  ██║
⠀⢹⣿⣿⣿⣿⠟⣡⣿⢸⣮⡻⣿⣿⣿⣿⡏    ███████╗██║███████╗██║   ██║     ██║  ██║██████╔╝
⠀⠀⢻⣿⡟⣩⣾⣿⣿⢸⣿⣿⣌⠻⣿⡟⠀    ╚══════╝╚═╝╚══════╝╚═╝   ╚═╝     ╚═╝  ╚═╝╚═════╝ v2.13.0
⠀⠀⠀⠉⢾⣿⣿⣿⣿⢸⣿⣿⣿⡷⠈⠀⠀
⠀⠀⠀⠀⠀⠈⠙⠛⠛⠘⠛⠋⠁⠀ ⠀⠀⠀   Decentralized Compute Network  https://lilypad.tech

🌟  Lilypad submitting job
2025-03-05T12:56:38-06:00 WRN ../runner/work/lilypad/lilypad/cmd/lilypad/utils.go:63 > failed to get GPU info: gpuFillInfo not implemented on darwin
2025-03-05T12:56:38-06:00 INF ../runner/work/lilypad/lilypad/pkg/web3/sdk.go:209 > Connected to arbitrum-sepolia-rpc.publicnode.com
2025-03-05T12:56:38-06:00 INF ../runner/work/lilypad/lilypad/pkg/jobcreator/run.go:27 > Public Address: 0xB86bCAe21AC95BCe7a49C057dC8d911033f8CB7c
Enumerating objects: 42, done.
Counting objects: 100% (22/22), done.
Compressing objects: 100% (4/4), done.
Total 42 (delta 18), reused 19 (delta 18), pack-reused 20 (from 1)
💌  Deal agreed. Running job...
🤔  Results submitted. Awaiting verification...
🤔  Results submitted. Awaiting verification...
✅  Results accepted. Downloading result...
🆔  Data ID: QmP2SQttNC3Hrh2xpY7bNHzV2jHq7MbfLahRC46DVzn5rG

🍂 Lilypad job completed, try 👇
    open /tmp/lilypad/data/downloaded-files/QmQHrsiAuzTLn5VU6jg5LoXBRrAkEVRKiYeJE29w54gg9Q
    cat /tmp/lilypad/data/downloaded-files/QmQHrsiAuzTLn5VU6jg5LoXBRrAkEVRKiYeJE29w54gg9Q/stdout
    cat /tmp/lilypad/data/downloaded-files/QmQHrsiAuzTLn5VU6jg5LoXBRrAkEVRKiYeJE29w54gg9Q/stderr

To view the results in a local directory, navigate to the local folder.

open /tmp/lilypad/data/downloaded-files/QmQHrsiAuzTLn5VU6jg5LoXBRrAkEVRKiYeJE29w54gg9Q

Here, you can view the stdout and stderr as well as the outputs folder for the run:

~ % cat /tmp/lilypad/data/downloaded-files/QmQHrsiAuzTLn5VU6jg5LoXBRrAkEVRKiYeJE29w54gg9Q/stdout
 ________________ 
< hello, lilypad >
 ---------------- 
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

create-lilypad-module is an officially supported package that provides a simple scaffolding for building Lilypad modules. It offers a modern Docker setup with minimal configuration.

Overview

• Getting Started: install and run create-lilypad-module

• Folder Structure: output and explanation of create-lilypad-module files

• Configuration: requirements and explanations of Lilypad module configuration

• Creating Your Module: a step-by-step guide on how to create a simple Lilypad module using create-lilypad-module

Installation

First, you'll need to install the package:

pip install create-lilypad-module

If you've previously installed create-lilypad-module, you should to ensure that you're using the latest version:

pip install --upgrade create-lilypad-module

Now run create-lilypad-module:

create-lilypad-module

The CLI will ask for the name of your project. Alternatively, you can run:

create-lilypad-module project_name
cd project_name

Output

project_name
├── config
│   └── constants.py
├── scripts
│   ├── docker_build.py
│   ├── download_models.py
│   └── run_module.py
├── src
│   └── run_inference.py
├── .dockerignore
├── .env
├── .gitignore
├── Dockerfile
├── lilypad_module.json.tmpl
├── README.md
└── requirements.txt

Output

After creation, your project should look like this:

project_name
├── config
│   └── constants.py
├── scripts
│   ├── docker_build.py
│   ├── download_models.py
│   └── run_module.py
├── src
│   └── run_inference.py
├── .dockerignore
├── .env
├── .gitignore
├── Dockerfile
├── lilypad_module.json.tmpl
├── README.md
└── requirements.txt

For the module to run, these files must exist with exact filenames:

• src/run_inference.py

  • The Dockerfile ENTRYPOINT.

  • If you change this files name or location, you must also update the ENTRYPOINT in your Dockerfile and lilypad_module.json.tmpl file to match.

• config/constants.py

  • The configuration file that stores the DOCKER_REPO, DOCKER_TAG, MODULE_REPO, and TARGET_COMMIT.

  • If you change this files name or location, you must also update the import statements in scripts/docker_build.py and scripts/run_module.py.

• Dockerfile

  • Required to build your module into a Docker image, and push the image to Docker Hub where it can be accessed by Lilypad Network.

• requirements.txt

  • Used by the Dockerfile to install dependencies required by your module.

  • Technically, this file can be deleted or renamed, but this naming convention is highly recommended as an industry standard best practice.

• lilypad_module.json.tmpl

  • The Lilypad configuration file.

You can delete or rename the other files.

You may create subdirectories inside src. For faster builds and smaller Docker images, only files inside src are copied by Docker. You need to put any files required to run your module inside src, otherwise Docker won’t copy them.

You can create more top-level directories. They will not be included in the final Docker image so you can use them for things like documentation.

If you have Git installed and your project is not part of a larger repository, then a new repository will be initialized resulting in an additional top-level .git directory.

Configure Your Module

After bootstrapping your module, additional configuration is required to run it.

.env

WEB3_PRIVATE_KEY = ""

WEB3_PRIVATE_KEY

🚨 DO NOT SHARE THIS KEY 🚨

The private key for the wallet that will be used to run the job.

This is required to run the module on Lilypad Network.

A new development wallet is highly recommended to use for development. The wallet must have enough LP tokens and Arbitrum Sepolia ETH to fund the job.

• Funding your wallet

config/constants.py

DOCKER_REPO = ""
MODULE_REPO = ""
TARGET_COMMIT = ""

DOCKER_REPO

The Docker Hub repository storing the container image of the module code.

This is required to push the image to Docker Hub and run the module on Lilypad Network.

e.g. "<dockerhub_username>/<dockerhub_image>"

DOCKER_TAG

The specific tag of the DOCKER_REPO containing the module code.

Default: "latest"

MODULE_REPO

The URL for the GitHub repository storing the lilypad_module.json.tmpl file. The visibility of the repository must be public.

The lilypad_module.json.tmpl file points to a DOCKER_REPO and Lilypad runs the module from the image.

e.g. "github.com/<github_username>/<github_repo>"

TARGET_COMMIT

The git branch or commit hash that contains the lilypad_module.json.tmpl file you want to run.

Use git log to easily find commit hashes.

Default: "main"

Available Scripts

Your module will be bootstrapped with some handy scripts to help you download the model(s) for your module, build and push Docker images, and run your module locally or on Lilypad Network. Some additional configuration may be required.

In the project directory, you can run:

python -m scripts.download_models

A basic outline for downloading a model from Hugging Face is provided, but the structure of the script and the methods for downloading a model can differ between models and libraries. It’s important to tailor the process to the specific requirements of the model you're working with.

Most (but not all) models that utilize machine learning use the 🤗 Transformers library, which provides APIs and tools to easily download and train pretrained models.

• Learn more about downloading models from Hugging Face

• Learn more about the 🤗 Transformers library

No matter which model you are using, be sure to thoroughly read the documentation to learn how to properly download and use the model locally.

python -m scripts.docker_build

Builds and optionally publishes a Docker image for the module to use.

For most use cases, this script should be sufficient and won't require any configuration or modification (aside from setting your DOCKER_REPO and DOCKER_TAG).

COPY requirements.txt .
COPY src /src
COPY models /models

--push Flag

Running the script with --push passed in pushes the Docker image to Docker Hub.

--no-cache Flag

Running the script with --no-cache passed in builds the Docker image without using the cache. This flag is useful if you need a fresh build to debug caching issues, force system or dependency updates, pull the latest base image, or ensure clean builds in CI/CD pipelines.

python -m scripts.run_module

This script is provided for convenience to speed up development. It is equivalent to running the Lilypad module with the provided input and private key (unless running the module locally, then no private key is required). Depending on how your module works, you may need to change the default behavior of this script.

--local Flag

Running the script with --local passed in runs the Lilypad module Docker image locally instead of on Lilypad's Network.

--demonet Flag

Running the script with --demonet passed in runs the Lilypad module Docker image on Lilypad's Demonet.

lilypad_module.json.tmpl

The default lilypad_module.json.tmpl file is below. Make sure to update the Docker Image to point to your Docker Hub image with the correct tag.

The default lilypad_module.json.tmpl should work for low complexity modules. If your module requires additional resources (such as a GPU) make sure to configure the applicable fields.

{
  "machine": { "gpu": 1, "cpu": 8000, "ram": 16000 },
  "gpus": [{ "vram": "24Gb" }]
  "job": {
    "APIVersion": "V1beta1",
    "Spec": {
      "Deal": { "Concurrency": 1 },
      "Docker": {
        "Entrypoint": [
          "/app/src/run_model", {{ .request }}
        ],
        "Image": "DOCKER_HUB_USERNAME/DOCKER_IMAGE@INDEX_DIGEST"
      },
      "Engine": "Docker",
      "Network": { "Type": "None" },
      "Outputs": [{ "Name": "outputs", "Path": "/outputs" }],
      "Resources": { "GPU": "1", "CPU": "8", "Memory": "16Gb" },
      "Timeout": 1800,
      "Verifier": "Noop"
    }
  }
}

Template Fields

• Machine: Specifies the system resources.

• GPUs: Specifies the minimum VRAM required.

• Job: Specifies the job details.

  • APIVersion: Specifies the API version for the job.

  • Metadata: Specifies the metadata for the job.

  • Spec: Contains the detailed job specifications.

    • Deal: Sets the concurrency to 1, ensuring only one job instance runs at a time.

    • Docker: Configures the Docker container for the job

      • WorkingDirectory: Defines the working directory of the Docker image.

      • Entrypoint: Defines the command(s) to be executed in the container as part of its initial startup runtime.

      • EnvironmentVariables: This can be utilised to set env vars for the containers runtime, in the example above we use Go templating to set the INPUT variable dynamically from the CLI.

      • Image: Specifies the image to be used (DOCKERHUB_USERNAME/IMAGE:TAG).

    • Engine: Sets the container runtime (Default: "Docker").

    • Network: Specifies that the container does not require networking (Default: "Type": "None").

    • Outputs: Specifies name and path of the directory that will store module outputs.

    • Resources: Specify additional resources.

    • Timeout: Sets the maximum duration for the job. (Default: 600 [10 minutes]).

Getting Started

This guide will walk you through creating a basic sentiment analysis module using create-lilypad-module and distilbert/distilbert-base-uncased-finetuned-sst-2-english (which will be referred to as Distilbert from now on). We will be referring back to the Hugging Face page throughout this guide, so it's best to keep it open and accessible.

Input:

lilypad run --network demonet github.com/DevlinRocha/lilypad-module-sentiment:main --web3-private-key 0ec38dd1ee0898dae8460b269859b4fb3cb519b35d82014c909ec4741c790831 -i input="LILYPAD IS AWESOME"

Output:

{
  "input": "LILYPAD IS AWESOME",
  "sentiment": "POSITIVE",
  "status": "success"
}

• View the final source code for the module

If you prefer to follow along with a video guide, you can view our live workshop below! 👇

Prerequisites

To build and run a module on Lilypad Network, you'll need to have the Lilypad CLI, Python and Docker on your machine, as well as GitHub and Docker Hub accounts.

For this guide, we'll be using create-lilypad-module which requires pip and uses Python.

Downloading The Model

The first thing you'll need for your module is a local model to use.

A basic outline for downloading a model from Hugging Face is provided in scripts/download_models.py. The structure of the script and the methods for downloading a model can differ between models and libraries. It’s important to tailor the process to the specific requirements of the model you're working with.

You can get started by attempting to run the download_models.py script.

python -m scripts.download_models

Since the script hasn't been properly configured yet, it will return an error and point you to the file.

❌ Error: Model download script is not configured.
👉 /scripts/download_models.py

Open scripts/download_models.py and you will see some TODO comments with instructions. Let's go through them each in order. You can remove each TODO comment after completing the task.

# TODO: Update ../requirements.txt
# from transformers import AutoTokenizer, AutoModelForSequenceClassification

First we have a reminder to update our requirements.txt file, which is used by the Dockerfile to install the module's dependencies. In the next line is a commented out import statement.

To find the dependencies that our model requires, we can refer back to Distilbert's Hugging Face page and click on the "Use this model" dropdown, where you will see the 🤗 Transformers library as an option. Click it.

You should see a handy modal explaining how to use the model with the Transformers library. For most models, you'd want to use this. However, Distilbert has a specific tokenizer and model class. Close the modal and scroll to the How to Get Started With the Model section of the model card. We're going to use this instead.

For now, let's look at the top 2 lines of the provided code block:

import torch
from transformers import DistilBertTokenizer, DistilBertForSequenceClassification

Notice that torch is also being used. Copy the transformers import statement and paste it over the existing import statement in our download_models.py file.

Now open requirements.txt:

# torch==2.4.1
# transformers==4.47.1

These are 2 of the most common libraries when working with models. Similar to the import statement in the download_models.py file, they are provided by default for convenience, but commented out because although they are common, not every model will use them.

Since this model happens to use both of these libraries, we can uncomment both lines and close the file after saving.

Return to the download_models.py file, and look for the next TODO comment.

# TODO: Set this to your model's Hugging Face identifier
MODEL_IDENTIFIER = ""

If we take a look at the Distilbert Hugging Face page, we can use the copy button next to the name of the module to get the MODULE_IDENTIFIER. Paste that in as the value.

For our use case, it should look like this:

MODEL_IDENTIFIER = "distilbert/distilbert-base-uncased-finetuned-sst-2-english"

You're almost ready to download the model. All you need to do now is replace the following 2 lines after the TODO comment:

# TODO: Initialize `model` and `tokenizer`
# tokenizer = AutoTokenizer.from_pretrained(MODEL_IDENTIFIER)
# model = AutoModelForSequenceClassification.from_pretrained(MODEL_IDENTIFIER)

Instead of using AutoTokenizer and AutoModelForSequenceClassification, replace those with the DistilBertTokenizer and DistilBertForSequenceClassification we imported.

tokenizer = DistilBertTokenizer.from_pretrained(MODEL_IDENTIFIER)
model = DistilBertForSequenceClassification.from_pretrained(MODEL_IDENTIFIER)

The script is now configured! Try running the command again.

python -m scripts.download_models

The models directory should now appear in your project. 🎉

Building Your Model

Now for the fun part, it's time to start using the model!

This time we'll get started by running the run_module script.

python -m scripts.run_module

You should see an error with some instructions.

❌ Error: No job configured. Implement the module's job before running the module.
        1. Implement job module
                👉 /src/run_inference.py
        2. Delete this code block
                👉 /scripts/run_module.py

1. Implement Job Module

Let's tackle the run_inference.py script first. This is where your modules primary logic and functionality should live. There is a TODO comment near the top of the file.

# TODO: Update ../requirements.txt
# import torch
# from transformers import AutoTokenizer, AutoModelForSeq2SeqLM

We've already updated the requirements.txt file, so we can skip that step. Go ahead and uncomment the import statements and replace the transformers line with the DistilBertTokenizer and DistilBertForSequenceClassification.

We should refer back to the "How to Get Started With the Model" section of Distilbert's model card to figure out how to use the model.

tokenizer = DistilBertTokenizer.from_pretrained("distilbert-base-uncased-finetuned-sst-2-english")
model = DistilBertForSequenceClassification.from_pretrained("distilbert-base-uncased-finetuned-sst-2-english")

inputs = tokenizer("Hello, my dog is cute", return_tensors="pt")
with torch.no_grad():
    logits = model(**inputs).logits

predicted_class_id = logits.argmax().item()
model.config.id2label[predicted_class_id]

Let's implement this into our run_inference script. Scroll down to the main() function and you'll see another TODO comment.

# TODO: Initialize `model` and `tokenizer`
# tokenizer = AutoTokenizer.from_pretrained(MODEL_DIRECTORY)
# model = AutoModelForSeq2SeqLM.from_pretrained(MODEL_DIRECTORY)

Same as before, uncomment and replace AutoTokenizer with DistilBertTokenizer and AutoModelForSeq2SeqLM with DistilBertForSequenceClassification. This is now functionally identical to the first 2 lines of code from Distilbert's example.

Below that, the tokenizer and model are passed into the run_job() function. Let's scroll back up and take a look at the function. This is where we'll want to implement the rest of the code from Distilbert's example. The inputs are already functionally identical, so let's adjust the output.

From the Distilbert model card, copy all of the code below the inputs variable declaration, and paste it over the output variable declaration in your modules code.

inputs = tokenizer(
    input,
    return_tensors="pt",
    truncation=True,
    padding=True,
)

with torch.no_grad():
    logits = model(**inputs).logits

predicted_class_id = logits.argmax().item()
model.config.id2label[predicted_class_id]

return output

All we need to do from here is set the output to the last line we pasted.

output = model.config.id2label[predicted_class_id]

return output

That's everything we'll need for the modules source code!

2. Delete Code Block

We still need to finish step 2 that the error in the console gave us earlier. Open the run_module.py script.

Find the TODO comment and delete the code block underneath.

# TODO: Remove the following print and sys.exit statements and create the module job.
print(
    "❌ Error: No job configured. Implement the module's job before running the module.",
    file=sys.stderr,
    flush=True,
)
print("\t1. Implement job module")
print("\t\t👉 /src/run_inference.py")
print("\t2. Delete this code block")
print("\t\t👉 /scripts/run_module.py")
sys.exit(1)

Preparing Your Module

Before you are able to run your module, we need to build the Docker image. You can run the following command:

python -m scripts.docker_build

You should see the following response in the console:

❌ Error: DOCKER_REPO is not set in config/constants.py.

Open the constants.py file, it should look like this:

# TODO: Set the Docker Hub repository before pushing the image.
# Example: "devlinrocha/lilypad-module-sentiment"
DOCKER_REPO = ""

# TODO: Set the tag for the Docker image.
# Example: "latest", "v1.0", or a commit SHA
DOCKER_TAG = "latest"

# TODO: Set the GitHub repository URL where your module is stored.
# Example: "github.com/devlinrocha/lilypad-module-sentiment".
MODULE_REPO = ""

# TODO: Specify the target branch name or commit hash.
# Example: "main" or "c3ed392c11060337cae010862b1af160cd805e67"
TARGET_COMMIT = "main"

For now, we'll be testing the module locally, so all we need to worry about is the DOCKER_REPO variable. We'll use MODULE_REPO when it's time to run the module on Lilypad Network. For help or more information, view the configuration documentation

You should be able to successfully build the Docker image now.

COPY requirements.txt .
COPY src /src
COPY models /models

Running Your Module

It's finally time to see your module in action.

Local

Let's start by running it locally.

python -m scripts.run_module --local

The CLI should ask you for an input. Enter whatever you like and hit enter. The module will analyze the sentiment of your input and output the results at outputs/result.json.

{
  "input": "LILYPAD IS AWESOME",
  "result": "POSITIVE",
  "status": "success"
}

You just used a local LLM! 🎉

Lilypad Network

Before you can run the module on Lilypad Network, you'll need to push the Docker image to Docker Hub.

python -m scripts.docker_build --push

While the Docker image is being built and pushed, you should configure the rest of the variables in constants.py. Make sure that you push your code to a public GitHub repository.

The last thing we'll need to do is edit the Lilypad module configuration file, lilypad_module.json.tmpl. For the purposes of this module, the default configuration is mostly correct. However, the "Image" field needs to be configured.

Replace the default value with your Docker Hub username, module image, and tag.

"Image": "devlinrocha/lilypad-module-sentiment:latest"

Once your Docker image is pushed to Docker Hub and your most recent code is pushed to a public GitHub repository, you can test your module on Lilypad's DemoNet by replacing the --local flag with --demonet

python -m scripts.run_module --demonet

You can also remove the --demonet flag and supply your WEB3_PRIVATE_KEY to run the module on Lilypad's IncentiveNet.

You just used an LLM on Lilypad's decentralized network! 🎉

Now anyone who has the Lilypad CLI installed can also run your module:

lilypad run github.com/<MODULE_REPO>:<TARGET_COMMIT> --web3-private-key <WEB3_PRIVATE_KEY>

The Lilypad CLI wrapper can run locally to create an API endpoint for running jobs on the Lilypad network. This gives developers full control to build a decentralized system running jobs on Lilypad. Github repo can be found here.

Build a front end or AI agent workflow that uses this API endpoint for running jobs! For inspiration, check out this JS CLI wrapper + Gradio example. Spin up a Webui with Gradio and use the api with a frontend!

Note: This is a beta tool and would mostly be expected to run locally. When implementing this tool, note that the POST request includes the user's Web3 private key. Stay tuned for a hosted API from Lilypad that will supplement this local CLI Wrapper.

Getting Started

Prerequisites

Installing and Setting up Lilypad Binary

1. Build the Lilypad binary:

git clone https://github.com/Lilypad-Tech/lilypad
cd lilypad
go build -v -o lilypad

# For Linux: Move to /usr/bin
sudo mv lilypad /usr/bin/

# For Mac: Move to /usr/local/bin
sudo mv lilypad /usr/local/bin

Usage

Run node src/index.js to create a local endpoint using the js wrapper with either src/run.js or src/stream.js, then send a post request containing json with your funded WEB3_PRIVATE_KEY key set, see the quick start for more on Quickstart.

In inputs, each input must be preceded by the -i flag, including tunables. For example: "inputs": "-i Prompt='an astronaut floating against a white background' -i Steps=50"

Note: This tool is for demonstration purposes and can be used to run jobs on Lilypad for free. The tooling will be improved upon in the coming weeks for greater scalability. Use the following post request with the WEB3_PRIVATE_KEY below to run jobs on Lilypad. The wallet/private key below is funded with testnet tokens only and has been setup to simplify the use of this developer tool.

The endpoint can then be tested using curl

curl -X POST http://localhost:3000 \
-H "Content-Type: application/json" \
-d '{"pk": "'"your-private-key"'", "module": "github.com/lilypad-tech/lilypad-module-lilysay:0.1.0", "inputs": "-i Message=test"}'

// run.js
const { run } = require("./")

run(
  "private-key",
  "module name"
  '-i payload (key=value)'
).then((res) => {
  console.log(res)
})

// stream.js
const { stream } = require("./")

stream(
  "private-key",
  "module name"
  '-i payload (key=value)'
  { stream: true },
).then(() => {
  console.log("Result in ./output/result")
})

// index.js
const fetch = require("node-fetch")
const fs = require("fs")

const URL = "http://js-cli-wrapper.lilypad.tech"
const METHOD = "POST"
const HEADERS = {
  Accept: "application/json",
  "Content-Type": "application/json",
}
const OUTPUT = "./output"

function stream(pk, module, inputs, opts) {
  const body = JSON.stringify({ pk, module, inputs, opts })

  return fetch(URL, {
    headers: HEADERS,
    method: METHOD,
    body,
  }).then(function (res) {
    const fileStream = fs.createWriteStream(`./${OUTPUT}/result`)
    res.body.pipe(fileStream)
    res.body.on("error", (error) => {
      return { error }
    })
    fileStream.on("finish", () => {
      return { status: "done" }
    })
  })
}

function run(pk, module, inputs) {
  const body = JSON.stringify({ pk, module, inputs })

  return fetch(URL, {
    headers: HEADERS,
    method: METHOD,
    body,
  }).then((raw) => raw.json())
}

module.exports = { run, stream }

Guides

Building RAG Agents on Lilypad

Can an AI Agent Solve the Crypto UI Problem?

Build a chatbot on Lilypad

Module Builder guide

Build a Open-source Perplexity Clone

Video Tutorials

AI Resources

• RAG vs Finetuning

• The promise and challenges of crypto + AI - Vitalik Buterin

• Data on Notable AI Models

• Towards decentralized AI

• Understanding the Intersection of Crypto and AI - Galaxy Digital Research

GPU Info

• How do graphics cards work?

• Nvidia CUDA Toolkit

• Nvidia CUDA in 100 Seconds

Bacalhau Resources

• Bacalhau.org

• Impact of Compute over Data - Juan Benet

• CoD vision & goals - Juan Benet

• Lessons for building Distributed Compute - Juan Benet & Molly Mackinlay

• State of CoD 2023 - David Aronchick

• Containers at the Edge - David Aronchick

Lilypad Blog

View blog

Lilypad YouTube

Watch videos

Encode x Filecoin Open Data Hack Video [Sept 23]

Watch video

Encode x Filecoin Open Data Hack Slides [Sept 23]

View slide

AI tooling provides the essential infrastructure and frameworks that support the development, deployment and monitoring of AI-powered applications. This section highlights tools that help streamline workflows, enhance visibility and enable customization when building with AI on Lilypad, with examples and guides for integrating them into your projects.

Anything LLM

GPT Desktop Client for Lilypad

Rivet

Agentic Workflows

Lilypad Llama3 Chatbot

AI-powered chatbot running on the Lilypad Network using Llama3 for intelligent responses.

Lilypad ML Workbench

A platform for running, fine-tuning and deploying AI models on the Lilypad Network, with support for Jupyter notebooks and multi-module workflow

Getting Started

Prerequisites:

• A basic understanding of the Lilypad API and Anything LLM

• Access to an Anura Dashboard account

Set up Open AI Endpoint in Rivet

1. Download and Install AnythingLLM from https://anythingllm.com/

2. Start AnythingLLM App.

3. Navigate to the Settings page by clicking wrench icon at bottom left

4. Click on LLM under AI Providers

5. Select Generic OpenAI under LLM Provider

6. In the BaseURL input field, paste the URL: https://anura-testnet.lilypad.tech/api/v1

Obtain an Anura API Key

1. Log in to your Anura account at https://anura.lilypad.tech/

2. Click Get Started

3. Create a new API key by clicking the “Create API Key” button.

4. Copy the generated API key and paste it into the APIIey input field on the LLM Screen.

Specify Chat Model Name

1. Paste in "llama3.1:8b"

Getting Started

Prerequisites:

• A basic understanding of the Lilypad API and Rivet

• Access to an Anura Dashboard account

• Basic knowledge of workflow configuration

Set up Open AI Endpoint in Rivet

1. Download and Install Rivet from https://rivet.ironcladapp.com/

2. Start Rivet App.

3. Navigate to the Settings page. App>Settings

4. Click on the “Open AI” tab.

5. In the Open AI endpoint input field, paste the URL: https://anura-testnet.lilypad.tech/api/v1/chat/completions

Obtain an Anura API Key

1. Log in to your Anura account at https://anura.lilypad.tech/

2. Click Get Started

3. Create a new API key by clicking the “Create API Key” button.

4. Copy the generated API key and paste it into the Open AI API key input field in Rivet.

The Lilypad Llama3 Chatbot is a conversational agent designed to deliver engaging, real-time AI-powered interactions. Leveraging the Llama3 8B model through the Lilypad API, this chatbot provides context-aware and dynamic responses, making it useful for applications such as automated support, interactive Q&A and virtual assistance.

Features

• AI-Powered Conversations – Utilizes Llama3 8B via the Lilypad Network to generate intelligent responses.

• Lilypad API Connectivity – Simple integration with Lilypad, allowing flexible use of all available models on the Lilypad API.

This chatbot can be extended with:

• Memory & Context Awareness – Store conversation history for more personalized interactions.

• External APIs – Integrate with knowledge bases, search engines, or database lookups.

• Multi-Model AI – Swap Llama3 with other AI models as needed.

How It Works

1. User Input – The chatbot interface captures the user's message.

2. API Request – The message is sent to the Lilypad API, which runs the job on the Llama3 model.

3. Response Generation – Llama3 processes the input, considers context and generates a natural language response.

4. Response Display – The response is rendered in the chatbot interface.

Installation

1. Get Anura API key.

2. Clone the repository:

   Copy

   git clone https://github.com/PBillingsby/lilypad-llama3-chatbot.git
   cd lilypad-llama3-chatbot

3. Install dependencies: npm install

4. Add the Lilypad API key to .env: LILYPAD_API_TOKEN=<ANURA_API_KEY>

5. Start the development server: npm run dev

Usage

Access the chatbot at: http://localhost:3000 and enter prompt to start a conversation.

Resources

• Source code

The Lilypad ML workbench provides ML researchers, businesses, and more a simple interface for leveraging the Lilypad network.

The ML workbench provides an interface to:

• Run models that are currently available on the Lilypad GPU network

• Add a new model to run on the network as a Lilypad module

• Leverage Jupyter notebooks with Lilypad

• Create multi-module flows

• Fine tune models

• Create an AI agent

In order to run an AI model on the Lilypad network, a docker image must be created for the program using the Lilypad module spec.

AI Inference

Run existing Lilypad modules with a simple text or image prompt. The workbench will output an IPFS CID with the result.

Implement the Lilypad module allowlist and cache the models locally before they are needed! Pin the files to a local IPFS node packaged with the workbench platform.

Finetuning

Import a dataset and use the the "Data" tool to finetune a model for a specific end user. Create a Lilypad module and save the module on IPFS. More on this soon!

Create an AI agent and run on Lilypad

The ML workbench provides a simple interface for creating and training AI agents. The Lilypad team is currently testing a variety of models and fine tuning techniques to determine the optimal path forward for this feature. More on this soon!

Resources

• Source code

This section features hands-on tools and resources designed to support developers building with Lilypad. From code editor extensions to social app integrations, it highlights ways to prototype, automate and ship AI jobs more efficiently. Explore how these utilities fit into real workflows and help extend the power of the network.

VS Code Helper Extension

Enhances development with smart suggestions, automation and simple Lilypad integration.

Farcaster Frame

Allow users to generate AI-powered outputs directly within interactive Farcaster posts

Need some inspiration? Visit the Helpful Resources page!

The Lilypad VS Code Extension allows developers to interact with the Lilypad Anura API within Visual Studio Code. By highlighting code blocks, users can query the available LLMs on Lilypad for explanations, improvements, or suggestions, receiving responses in a formatted webview panel.

Features

• AI-Powered Code Assistance – Select any code in your editor, choose an AI model, and ask Lilypad questions about it

• Formatted Responses – View AI-generated insights in a structured webview panel

• Secure API Configuration – Store your Lilypad API token securely

• Context Menu Integration – Quickly access the extension’s features via the right-click menu

Installation

From the Repository

1. Get Anura API key.

2. Clone the repo: git clone git@github.com:PBillingsby/lilypad-vscode-extension.git

3. Install the extension in VS Code: code --install-extension lilypad-vscode-extension.vsix

4. Add Anura API key to .env: LILYPAD_API_TOKEN=<ANURA_API_KEY>

5. If you make changes to the extension and need to recompile it:

   1. Recompile the code: npm run compile

   2. Repackage the extension: vsce package

   3. Reinstall the updated .vsix file: code --install-extension lilypad-vscode-extension.vsix

Usage

1. Select a block of code in your editor.

2. Right-click and select "Ask Lilypad about this code", or:

   • Open the Command Palette (Ctrl+Shift+P) and select "Ask Lilypad about this code".

3. Choose an AI model to process the query.

4. Enter your question related to the selected code.

5. Wait for Lilypad AI to process your query.

6. View the AI’s response in the webview panel that opens.

Resources

• Source code

In this guide we will be building a Farcaster frame for local development that runs a Lilysay prompt on the Lilypad Network.

Users of the frame can input a prompt and a generate an image. The generated image will appear in the box above the input and will allow a user to view the ASCII art as an image.

Project Setup

Generate project

For this frame, create a NextJS 14 app:

npx create-next-app lilypad-farcaster-example
cd lilypad-farcaster-example

Next, install the required dependencies. Coinbase onchain kit is used in this project:

npm install @coinbase/onchainkit uuid sharp@0.32.6 path fs

Open the project in your code editor.

Get testnet tokens

We will need to fund a wallet with Lilypad and Arbitrum Sepolia testnet tokens. Follow the first 2 sections labelled "Setting up MetaMask" and "Funding your wallet" from our Quick Start docs.

Add .env.local

Add the following into your .env.local file. The private key is used to run the CLI jobs. Make sure that your .env.local file is added to the .gitignore file as your private key should not be exposed or pushed.

1. WEB3_PRIVATE_KEY=YOUR_PRIVATE_KEY

2. NEXT_PUBLIC_BASE_URL=http://localhost:3000

Install Lilypad CLI

Run through this guide to install the Lilypad CLI on your machine. Select the CLI User script.

Run Framegear

Framegear is a simple tool provided by the @coinbase/onchainkit package that allows you to run and test your frames locally without publishing the frame.

In a separate terminal, clone down the onchainkit repo and run Framegear:

git clone https://github.com/coinbase/onchainkit.git
cd onchainkit/framegear
npm i
npm run dev

Navigate to http://localhost:1337 and keep that window open for when we start to write the frame.

Configuration for frame

We will need to set up the metadata for our Next.js application that includes Farcaster frame information. It will configure the elements and a URL for frame posting, while also specifying Open Graph metadata for improved social sharing.

In app/page.tsx, add the following before the Home function declaration:

import { getFrameMetadata } from '@coinbase/onchainkit/frame';
import type { Metadata } from 'next';
const frameMetadata = getFrameMetadata({
  buttons: [
    {
      label: "Let's go!"
    }
  ],
  image: `${process.env.NEXT_PUBLIC_BASE_URL}/initial.gif`,
  post_url: `${process.env.NEXT_PUBLIC_BASE_URL}/api/frame?id=1`,
});

export const metadata: Metadata = {
  title: 'Lilysay Farcaster frame',
  description: 'Initial frame',
  openGraph: {
    title: 'Lilysay Farcaster frame',
    description: 'Initial frame',
    images: ["/initial.png"],
  },
  other: {
    ...frameMetadata,
  },
};

UI Components

The UI elements for this frame are all rendered in the app/api/route.ts file, which acts as a request handler for different routes or endpoints within the web application. It defines the logic for handling user input, generating responses, and managing application state. The main functions include processing user prompts, handling status checks, and generating images asynchronously.

Routes

Here’s how the routes are structured for this frame:

• /api/frame?action=input: This route displays the initial user interface, which includes a text input field for the prompt and a button to submit the form. The user interface also updates dynamically based on the processing status, such as showing a placeholder image or the final generated image.

• /api/frame?action=submit: This route processes the user input. When a prompt is submitted, the server initiates the image generation process asynchronously. While the image is being generated, the user sees a loading state, and they can check the progress.

• /api/frame?action=check: This route checks the status of the image generation process. It updates the frame with either a completed image, an error message if the generation fails, or the processing state if the image is still being generated.

• We also include a fallback just in case an error occurs during the processing of job.

• /api/frame?action=save: Though not explicitly included, this could be an additional route for handling the logic of saving the generated image to a location for future access.

generateImage

The generateImage function handles the user input and generates the final image for display by utilizing the functions in app/services/cli.ts. It ensures that the image is generated asynchronously and the result is available for display in the frame, or handled properly in case of any errors during the generation process.

Frame images

Throughout the interaction process, various images are used. These images serve as visual cues during each step of the frame, such as when the user is prompted for input, while the image is being processed and once the final result is ready or if an error occurs.

To obtain the images used in this guide, save them from the source code here.

Create route.ts

Create the api/frame directories in your project. Inside of the app/api/frame directory, create a file named route.ts and add the following code:

import { NextRequest, NextResponse } from 'next/server';
import { v4 as uuidv4 } from 'uuid';
import { runCliCommand } from '@/app/services/cli';
import * as fs from 'fs/promises';
import path from 'path';

interface RequestData {
  prompt: string;
  status: 'processing' | 'completed' | 'error';
}

const requestStore: { [key: string]: RequestData } = {};

async function getResponse(req: NextRequest): Promise<NextResponse> {
  const searchParams = req.nextUrl.searchParams;
  const action = searchParams.get("action") || "input";
  const requestId = searchParams.get("id");
  const data = await req.json();
  const prompt = data.untrustedData?.inputText;

  switch (action) {
    case "input":
      return new NextResponse(`<!DOCTYPE html><html><head>
        <title>Input Prompt</title>
        <meta property="fc:frame" content="vNext" />
        <meta property="og:image" content="${process.env.NEXT_PUBLIC_BASE_URL}/enter-prompt.png" />
        <meta property="fc:frame:image" content="${process.env.NEXT_PUBLIC_BASE_URL}/enter-prompt.png" />
        <meta property="fc:frame:button:1" content="Submit" />
        <meta property="fc:frame:input:text" content="Enter your prompt" />
        <meta property="fc:frame:post_url" content="${process.env.NEXT_PUBLIC_BASE_URL}/api/frame?action=submit" />
      </head></html>`);

    case "submit":
      if (prompt) {
        const id = uuidv4();
        requestStore[id] = { prompt, status: 'processing' };

        // Start the image generation process asynchronously
        generateImage(id, prompt);

        // Immediately return the loading state
        return new NextResponse(`<!DOCTYPE html><html><head>
          <title>Request Submitted</title>
          <meta property="fc:frame" content="vNext" />
          <meta property="og:image" content="${process.env.NEXT_PUBLIC_BASE_URL}/loading.gif" />
          <meta property="fc:frame:image" content="${process.env.NEXT_PUBLIC_BASE_URL}/loading.gif" />
          <meta property="fc:frame:button:1" content="Check Status" />
          <meta property="fc:frame:post_url" content="${process.env.NEXT_PUBLIC_BASE_URL}/api/frame?action=check&id=${id}" />
        </head></html>`);
      }
      break;

    case "check":
      if (requestId && requestId in requestStore) {
        const request = requestStore[requestId];
        switch (request.status) {
          case 'completed':
            const imageUrl = `${process.env.NEXT_PUBLIC_BASE_URL}/result.png`;
            return new NextResponse(`<!DOCTYPE html><html><head>
              <title>Result</title>
              <meta property="fc:frame" content="vNext" />
              <meta property="og:image" content="${imageUrl}" />
              <meta property="fc:frame:image" content="${imageUrl}" />
              <meta property="fc:frame:button:1" content="New Request" />
              <meta property="fc:frame:post_url" content="${process.env.NEXT_PUBLIC_BASE_URL}/api/frame?action=input" />
            </head></html>`);
          case 'error':
            return new NextResponse(`<!DOCTYPE html><html><head>
              <title>Error</title>
              <meta property="fc:frame" content="vNext" />
              <meta property="og:image" content="${process.env.NEXT_PUBLIC_BASE_URL}/error.png" />
              <meta property="fc:frame:image" content="${process.env.NEXT_PUBLIC_BASE_URL}/error.png" />
              <meta property="fc:frame:button:1" content="Try Again" />
              <meta property="fc:frame:post_url" content="${process.env.NEXT_PUBLIC_BASE_URL}/api/frame?action=input" />
            </head></html>`);
          case 'processing':
            return new NextResponse(`<!DOCTYPE html><html><head>
              <title>Processing</title>
              <meta property="fc:frame" content="vNext" />
              <meta property="og:image" content="${process.env.NEXT_PUBLIC_BASE_URL}/loading.gif" />
              <meta property="fc:frame:image" content="${process.env.NEXT_PUBLIC_BASE_URL}/loading.gif" />
              <meta property="fc:frame:button:1" content="Check Again" />
              <meta property="fc:frame:post_url" content="${process.env.NEXT_PUBLIC_BASE_URL}/api/frame?action=check&id=${requestId}" />
            </head></html>`);
        }
      }
      break;
  }

  // Fallback response
  return new NextResponse(`<!DOCTYPE html><html><head>
    <title>Error</title>
    <meta property="fc:frame" content="vNext" />
    <meta property="og:image" content="${process.env.NEXT_PUBLIC_BASE_URL}/error.png" />
    <meta property="fc:frame:image" content="${process.env.NEXT_PUBLIC_BASE_URL}/error.png" />
    <meta property="fc:frame:button:1" content="Start Over" />
    <meta property="fc:frame:post_url" content="${process.env.NEXT_PUBLIC_BASE_URL}/api/frame?action=input" />
  </head></html>`);
}

// Runs the CLI command and saves the result as an image
async function generateImage(id: string, prompt: string) {
  try {
    const imageBuffer: any = await runCliCommand(prompt);
    const imagePath = path.join(process.cwd(), 'public', 'result.png');
    await fs.writeFile(imagePath, imageBuffer);
    requestStore[id] = { prompt, status: 'completed' };
  } catch (error) {
    console.error('Error generating image:', error);
    requestStore[id] = { prompt, status: 'error' };
  }
}

export async function POST(req: NextRequest): Promise<Response> {
  return getResponse(req);
}

export const dynamic = 'force-dynamic';

Create cli.ts

This is where the execution of the Lilysay job happens. It will run the job, wait for it to finish and then create an image from the return value.

Inside of the app directory, create a new directory named services and inside of that create a file named cli.ts. The functions inside this file will allow us to send a prompt to the Lilypad Network using the user prompt and a predefined command that runs asynchronously in the terminal. Once the command is executed, Lilypad processes the input through its Lilysay module and outputs the results in the form of an ASCII image, which is then converted into a displayable image using an SVG-to-PNG transformation.

Here are the 3 functions inside this file:

• createImageBufferFromAscii: Converts ASCII text into an SVG image and then uses the sharp library to convert the SVG into a PNG image buffer. This allows the display or saving of an image representation of the ASCII text.

• runCliCommand: Executes a Lilypad CLI command to process the user's input text, captures the command's output, and converts it into an image buffer. It handles the entire process of running the command, capturing the output, and managing errors.

• extractStdoutFilePath: Parses the CLI command's stdout to extract the file path where the Lilypad CLI has saved the output. It uses a regex pattern to identify the path in the command's output.

The following code snippet demonstrates the process:

import { spawn } from 'child_process';
import { promises as fs } from 'fs';
import * as path from 'path';
import { fileURLToPath } from 'url';
import sharp from 'sharp';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const MODULE_VERSION = "cowsay:v0.0.4";

// Function to generate an image buffer from ASCII text
async function createImageBufferFromAscii(asciiText, aspectRatio = 1.91) {
  const fontSize = 14;
  const lineHeight = fontSize + 6;
  const padding = 20;

  const lines = asciiText.split('\\n');

  const textHeight = lines.length * lineHeight + padding * 2;

  let width, height;
  if (aspectRatio === 1.91) {
    width = Math.max(textHeight * aspectRatio, 800);
    height = textHeight;
  } else if (aspectRatio === 1) {
    width = height = Math.max(textHeight, 800);
  }

  const escapeXML = (unsafe) => {
    return unsafe.replace(/&/g, "&")
      .replace(/</g, "&lt;")
      .replace(/>/g, "&gt;")
      .replace(/"/g, "&quot;")
      .replace(/'/g, "&#039;");
  };

  const escapedLines = lines.map(line => escapeXML(line));

  const textWidth = Math.max(...escapedLines.map(line => line.length)) * fontSize * 0.6;
  const xPosition = Math.max((width - textWidth) / 2, 10);

  // Generate SVG markup with the ASCII content
  const svgImage = `
    <svg width="${width}" height="${height}" xmlns="<http://www.w3.org/2000/svg>">
      <rect width="100%" height="100%" fill="white" />
      <style>
        .text-content { font-family: monospace; font-size: ${fontSize}px; fill: black; white-space: pre; }
      </style>
      <text x="${xPosition}" y="${padding}" class="text-content">
        ${escapedLines.map((line, index) => `<tspan x="${xPosition}" dy="${index === 0 ? '0' : lineHeight}">${line}</tspan>`).join('')}
      </text>
    </svg>
  `;

  // Convert the SVG to a PNG image buffer using sharp
  return sharp(Buffer.from(svgImage)).png().toBuffer();
}

// Function to run the Lilypad CLI command
export async function runCliCommand(inputs) {
  console.log("Lilypad Starting...");

  const web3PrivateKey = process.env.WEB3_PRIVATE_KEY;
  if (!web3PrivateKey) {
    throw new Error('WEB3_PRIVATE_KEY is not set in the environment variables.');
  }

  // Construct the command to run Lilypad with the user input
  const command = `lilypad run ${MODULE_VERSION} -i Message="${inputs}"`;
  console.log("Command to be executed:", command);

  // Execute the command as a shell process
  return new Promise((resolve, reject) => {
    const child = spawn('bash', ['-c', `export WEB3_PRIVATE_KEY=${web3PrivateKey} && ${command}`]);

    let stdoutData = '';
    let stderrData = '';

    // Capture stdout from the CLI command
    child.stdout.on('data', (data) => {
      stdoutData += data.toString();
      console.log(`Stdout: ${data}`);
    });

    child.stderr.on('data', (data) => {
      stderrData += data.toString();
      console.error(`Stderr: ${data}`);
    });

    child.on('close', async (code) => {
      if (code !== 0) {
        reject(new Error(`Process exited with code ${code}`));
        return;
      }

      if (stderrData) {
        reject(new Error(stderrData));
        return;
      }

      console.log("Process completed successfully!");

      try {
        // Extracts the file path, reads the ASCII content and converts it to an image buffer
        const stdoutFilePath = extractStdoutFilePath(stdoutData);
        const asciiContent = await fs.readFile(stdoutFilePath, 'utf-8');
        const imageBuffer = await createImageBufferFromAscii(asciiContent);
        resolve(imageBuffer);
      } catch (error) {
        reject(new Error(`Error processing output: ${error.message}`));
      }
    });

    child.on('error', (error) => {
      reject(new Error(`Error with spawning process: ${error.message}`));
    });
  });
}

// Helper function to extract the stdout file path from the CLI output
function extractStdoutFilePath(stdoutData) {
  const match = stdoutData.match(/cat (\/tmp\/lilypad\/data\/downloaded-files\/\w+\/stdout)/);
  if (!match || !match[1]) {
    throw new Error('Stdout file path not found in CLI output');
  }
  return match[1];
}

• Sending the Request: The user's input text is passed directly into the Lilypad CLI command using a shell process. The input text is embedded within the command's arguments and executed asynchronously in the terminal.

• Handling the Response: After the CLI command completes, the output is captured and processed. The response includes the file path to the generated ASCII image, which is then read from the file system and converted into a PNG image for further use.

• Error Handling: If an error occurs during the execution of the CLI command or file processing, it is logged to the console, and the process is terminated with appropriate error messaging.

Testing

The Framegear server is running. Next, run your local server in your frame project. We will need to make sure it is running on port 3000:

npm run dev

Navigate to the Framegear host http://localhost:1337 and you will see an input labeled "Enter your frame URL". Add http://localhost:3000 to that and click "Fetch".

You should now see your frame and be able to interact with it. Enter a prompt to display in the Lilysay ACSII image!

Rendering results

As the job is processed, a “Check Status” button will be displayed. Clicking this will check if the job has been completed. Once a job is completed, the results will be displayed in the frame. If there is an issue along the way, an error message will be displayed and the user will be prompted to try again.

Potential Use Cases

Running Lilysay jobs is just one of the ways you can utilize Lilypad in a frame, but you can run jobs with any available modules on the Lilypad Network. Some of these include:

• Stable Diffusion image

• Stable Diffusion video

• Ollama

Resources

• Source code

• Farcaster frames documentation

AI agents can autonomously process information, make decisions and interact with users or systems. This section explores different use cases for AI agents on Lilypad, providing examples and step-by-step guides on how to build and run them using the network.

AI Oncologist Agent

A multi-agent system that searches, extracts, and analyzes oncology research papers for key insights.

RAG Support Agent

Retrieves context and generates AI-driven support responses using the Lilypad Network.

An intelligent system for analyzing oncological research papers using a multi-agent approach. The system employs three specialized agents to search, extract, and analyze information from medical research papers.

Agent Details

The system consists of three main agents:

Paper Relevance Agent

• Searches through PDF documents in the documents directory

• Uses embeddings and cosine similarity for initial filtering

• Verifies relevance using LLM-based analysis

• Returns a list of most relevant paper filenames

Top Paragraphs Agent

• Extracts text from identified papers

• Splits content into manageable chunks

• Scores paragraph relevance using LLM

• Returns top-scoring paragraphs with relevance scores

Text Query Agent

• Analyzes provided text passages

• Generates focused answers to specific queries

• Uses contextual understanding to provide accurate responses

Getting Started

Prerequisites

• Python 3.8+

• OpenAI API key or compatible API (e.g., DeepSeek)

• PDF files

Installation

1. Clone the repository:

git clone https://github.com/mavericb/ai-oncologist.git
cd ai-oncologist

1. Install required packages:

pip install -r requirements.txt

1. Create a .env file in the project root with the following variables:

# OpenAI-Like API configuration
BASE_URL="https://api.deepseek.com"
OPENAI_API_KEY=your_deepseek_api_key
MODEL="deepseek-chat"

ANURA_BASE_URL=https://anura-testnet.lilypad.tech
ANURA_API_KEY=your_anura_api_key
ANURA_MODEL=phi4:14b

# Search configuration
MAX_RESULTS=3
SIMILARITY_THRESHOLD=0.3

• BASE_URL: API endpoint for OpenAI Compatible LLM service (default: "https://api.deepseek.com")

• OPENAI_API_KEY: Your OpenAI Compatible API key (for example: DeepSeek API Docs)

• MODEL: One OpenAI Compatible model to use (default: "deepseek-chat")

• ANURA_BASE_URL: API endpoint for the Anura LLM service (default: "https://anura-testnet.lilypad.tech")

• ANURA_API_KEY: Your Anura API key (get it here: Lilypad Inference API Docs)

• ANURA_MODEL: The Anura model to use (default: "phi4:14b")

• MAX_RESULTS: Maximum number of papers to return (default: 3)

• SIMILARITY_THRESHOLD: Minimum similarity score for document selection (default: 0.3)

Usage

1. Place your PDF research papers in the documents/ directory.

2. Run the main script:

python AIOncologist.py

Resources

• GitHub

The Lilypad RAG Support Agent is a Retrieval-Augmented Generation (RAG) AI assistant that retrieves relevant information and generates AI-powered responses using the Lilypad Network. It enables automated support and troubleshooting by leveraging vector search and AI-based text generation.

Features

• Context-Aware Responses – Uses all-MiniLM-L6-v2 embeddings to retrieve relevant information.

• AI-Powered Answer Generation – Sends retrieved context and user query to the Lilypad API, which processes it using Llama3 8B.

• Customizable Knowledge Base – Modify the agent’s context source (issues.md) to adapt it for different use cases.

How It Works

1. Embedding Queries with all-MiniLM

   • Converts user queries and stored knowledge into dense vector embeddings for similarity-based retrieval

2. Retrieving Relevant Context

   • Searches a pre-indexed database to find the most relevant information.

3. Generating Responses with Llama3 using the Lilypad API

   • Sends retrieved context and user prompt to the Lilypad API, where Llama3 8B generates a structured response

Expanding to Your Own Support Agent

The Lilypad RAG Support Agent can be adapted to different projects by modifying its retrieval source.

Updating the Knowledge Base (issues.md)

By default, the agent retrieves information from issues.md, a markdown file containing troubleshooting steps.

To customize:

• Open issues.md in the repository.

• Replace or expand the content with relevant support information for your project.

• Format the content clearly to improve retrieval accuracy.

• Restart the agent to index the updated knowledge base.

For more advanced use cases, the agent can be extended to support multiple files or external knowledge sources.

Installation

Follow these steps to set up the RAG Support Agent and configure it with your Lilypad API key.

Get a Lilypad API Key

Sign up at Anura API and generate an API key.

Clone the Repository

git clone https://github.com/PBillingsby/lilypad-rag-agent.git
cd lilypad-rag-agent

Configure Your API Key

Export your Lilypad API Token as an environment variable:

export LILYPAD_API_TOKEN="your-api-key-here"

To make it persistent, add it to ~/.bashrc or ~/.zshrc.

Install Dependencies

Ensure Python 3 is installed, then run:

pip install -r requirements.txt

Usage

After setting up the API key and dependencies, the agent is ready to process queries using Lilypad’s AI-powered retrieval system.

Run the Agent

Execute the agent from the project's root directory:

python3 cli.py

Resources

• Lilypad Docs

• Lilypad Anura API

• Source code

Explore real-world applications leveraging the Lilypad Network!

End User Apps

Lilytree

Stylized tree art from ETH addresses.

Gradio x Lilypad Interface

Run AI jobs from Gradio interface.

Waterlily.ai

Ethical generative AI-Art DApp.

Sir Croaksworth's Roast dApp

Get your portfolio roasted.

EthGlobal HackFS - May-June '24

CipherCraft

A decentralized hub for federated model training on access controlled private datasets.

Source code

NexTown

A decentralized AI computation and storage platform allowing users to run AI models via LilyPad, encrypt results with their public key, and securely store outputs on Lighthouse, accessible only by the user’s private key.

Source code

Filecoin ML Engine

Onchain ML engine to create dApp ML agents on top of Filecoin.

Source code

Dogtoken ai erc404

ERC404 token with custom Lilypad stable diffusion to generate unique images for holders.

Source code

Rock Paper Ninja

A web3 take on Rock Paper Scissors, utilizing Lilypad to create generative avatars.

EthGlobal Sydney - May '24

Learnr Idle Mining

An innovative NFT game where characters evolve and improve their tasks over time. Source code

SlickCI One click deployment of CI/CD workflows on to decentralised cloud infrastructure. Source code

On-Chain Personality - Honorable mention

Leverages on-chain Ethereum mainnet transactions to classify wallets into six predefined buckets/sub-ecosystems: Airdrop Farmer, NFT Collectooor, Snipoor, Shitcoinooor, EVM Enjoyoor, and NPCs.

Privacy Avengers - Could use Lilypad tech

A protocol for verifiable machine unlearning, solving AI privacy issues by securely and efficiently detecting and removing user data.

Source code

EthGlobal Istanbul - November '23

dub3.ai dub3.ai is an innovative marketplace harnessing the power of Cartesi, enabling users to transform their voice into unique NFTs and generate text-to-speech content using cutting-edge AI technology. Source code

HuggingLily

Run HuggingFace pipelines via dashboard with just one click.

Source code

ETHOnline - October '23

Lilypad-Kamu

A custom lilypad module for SQL streaming through kamu.dev, this provides provenance, version control, and provenance of derivative datasets. Integrates the desci project kamu.dev into a bacalhau job to be consumed by lilypad v2. Source code

Project C

Dive into the cosmic engineering that propels your personalized galaxy of knowledge. Source code

Open Data Hack - September '23

AI Capwyn

ML Tooling for Security Audits. Validate and test the status of deployed Lilypad Compute Networks. The contracts ensure seamless interaction with the network, while the test script checks for network availability and contract functionality. Source code

Lilypad Hub

This platform, much like Docker Hub, is a one-stop destination for all your module needs as a Lilypad user. Includes a feature-rich playground where you can seamlessly test job specifications, experiment and fine-tune your code in a safe environment. Source code

Obsidian-Lilypad

A user can plug obsidian-lilypad into their obsidian instance to fetch dpids from desci labs, have chat gpt summarize it, and use that as a prompt in runSDXL in lilypad. Helia/ipfs and kubo delegated content routing is used to splay dags and fetch content from IPFS. Source code

Decenter AI

DeCenter AI functions as a PaaS infrastructure, empowering machine learning engineers to expedite and make the training of AI models more cost-effective through decentralized parallel training methods.

The core objective of DeCenter AI is to democratize and decentralize AI model training. Source code

Lilylatte

Lilylatte is a DataDAO designed to bridge the gap between onchain and offchain data, focusing on web3 market research. Data owners, or web3 citizens, link their wallets and engage in dialogues generated by our LLM model, 'Lily.' Source code

Tiny Hops

An intents computational framework for describing lilypad workflows with a serialization format that allows you to replace variables within solidity, onchain which allows you to configure the receiveResults to feedback and trigger future jobs. Source code

Saturn Observatory

The goal of my project is to increase the transparency of Filecoin Saturn network – the fastest growing, community-run distributed content delivery network (CDN) for Web3.

I use historical data about the network gathered by Saturn Moonlet to prepare and publish analytical reports on Saturn Observatory website every month. Source code

Rejuvenate AI

RejuvenateAI is the first community blockchain based project powered by community built for community to promote healthy living and achieve healthy locations where people live up to a 100 years all around the world. Source code

StoryChain

StoryChain, a multi-level AI based story telling NFT dapp, is a new take on the ages old classic chain of stories, where different users collaboratively create stories.

Using this dapp, users create stories that have unique chapters and arts using web3, AI, NFTs, IPFS. Each page can belong to a different user.

Lilypad Javascript Wrapper

This project provides a JavaScript wrapper to interact with the Lilypad CLI using Node.js. The wrapper utilizes the node-pty package to spawn a pseudo-terminal for executing the Lilypad CLI commands. It will enable the front-end developers to integrate Lilypad with other tools. Source code

Lilywrite

LilyWrite combines blockchain technology and artistic expression, enabling users to craft and own unique poetic artworks. Users generate poems using credits, represented by LW tokens, and acquire them as distinctive non-fungible tokens (NFTs), each symbolizing a unique blend of creativity and expression. Source code

GreenBadge

GreenBadge is an innovative on-chain funding platform dedicated to fostering sustainability and a brighter future for our planet. Within our platform, organizations committed to these crucial goals will gain access to a vast network of donors and like-minded brands who share a passionate vision for the future of our environment. Source code