Skip to main content

Client Basics

Learn how to connect to a running Pie server and interact with inferlets.

Prerequisites​

  • Pie server running (pie serve)
  • Client library installed

Python Client​

Installation​

pip install pie-client

Basic Usage​

import asyncio
from pie import PieClient

async def main():
    async with PieClient("ws://127.0.0.1:8080") as client:
        # Authenticate (required even if auth is disabled)
        await client.authenticate("username")
        
        # Launch an inferlet from the registry
        instance = await client.launch_instance_from_registry(
            "text-completion",
            ["--prompt", "Hello, world!"]
        )
        
        # Receive output
        while True:
            event, message = await instance.recv()
            
            if event.name == "Stdout":
                print(message, end="", flush=True)
            elif event.name == "Completed":
                break
            elif event.name == "Exception":
                print(f"Error: {message}")
                break

asyncio.run(main())

Sending Messages​

For interactive inferlets:

async with PieClient("ws://127.0.0.1:8080") as client:
    await client.authenticate("username")
    
    instance = await client.launch_instance_from_registry("chat")
    
    # Send a message
    await instance.send("What is the capital of France?")
    
    # Receive response
    event, response = await instance.recv()
    print(response)

Upload Custom Inferlet​

async with PieClient("ws://127.0.0.1:8080") as client:
    await client.authenticate("username")
    
    # Upload the Wasm binary
    with open("my_inferlet.wasm", "rb") as f:
        await client.upload_program(f.read())
    
    # Get the program hash (blake3)
    import hashlib
    program_hash = "..."  # Compute blake3 hash
    
    # Launch
    instance = await client.launch_instance(program_hash, ["--arg", "value"])

JavaScript Client​

Installation​

npm install @pie-project/client

Basic Usage​

import { PieClient } from '@pie-project/client';

const client = new PieClient('ws://127.0.0.1:8080');

async function main() {
    await client.connect();
    await client.authenticate('username');
    
    const instance = await client.launchInstanceFromRegistry(
        'text-completion',
        ['--prompt', 'Hello, world!']
    );
    
    while (true) {
        const { event, msg } = await instance.recv();
        
        if (event === 'Stdout') {
            process.stdout.write(msg);
        } else if (event === 'Completed') {
            break;
        } else if (event === 'Exception') {
            console.error('Error:', msg);
            break;
        }
    }
    
    await client.close();
}

main();

Sending Messages​

const instance = await client.launchInstanceFromRegistry('chat');

// Send a message
await instance.send('What is 2 + 2?');

// Receive response
const { event, msg } = await instance.recv();
console.log(msg);

Event Types​

Both clients receive events from inferlets:

EventDescription
MessageText message from the inferlet
StdoutStreaming stdout output
StderrStreaming stderr output
BlobBinary data
CompletedInferlet finished successfully
AbortedInferlet was aborted
ExceptionInferlet raised an exception
ServerErrorServer-side error
OutOfResourcesResource limit reached

Authentication​

Pie supports public key authentication:

from pie import PieClient, ParsedPrivateKey

key = ParsedPrivateKey.from_file("~/.ssh/id_ed25519")

async with PieClient("ws://127.0.0.1:8080") as client:
    await client.authenticate("username", key)

For development with --no-auth:

await client.authenticate("any_username")  # No key needed

Next Steps​