Development

Puzzlet provides several tools for developing and testing prompts:

​

Develop Locally

Start a local server to serve your prompts:

npx @puzzlet/cli@latest serve -p <port>

This creates a local CDN that serves your prompts from the puzzlet/templates directory.

​

Test your local server

You can test your local server by running the following command:

Replace <port> with the port you are running your local server on, and <path> with the path to the prompt you want to test.

curl http://localhost:<port>/v1/templates?path=<path>

Example:

curl http://localhost:9001/v1/templates?path=math.prompt.mdx

This will return the contents of the math.prompt.mdx prompt as an AST.

​

SDK Configuration

Configure the Puzzlet SDK to use your local server:

import Puzzlet from '@puzzlet/sdk';

const puzzletClient = new Puzzlet({
  apiKey: process.env.PUZZLET_API_KEY,
  appId: process.env.PUZZLET_APP_ID,
  baseUrl: process.env.PUZZLET_BASE_URL
});

# .env
PUZZLET_API_KEY=your-api-key # Not used in local development. Grab from Platform
PUZZLET_APP_ID=your-app-id # Not used in local development. Grab from Platform
PUZZLET_BASE_URL=http://localhost:<port> # Only required for local development

​

Running Prompts

Fetch and run prompts using the SDK and AgentMark:

import { runInference } from '@puzzlet/agentmark';

// Fetch the prompt
const prompt = await puzzletClient.fetchPrompt("example.prompt.mdx");

// Run inference
const props = { username: "Alice" };
const options = {};
const result = await runInference(prompt, props, options);

​

Creating New Prompts

1. Create new .prompt.mdx files in your puzzlet/templates directory
2. Test locally using the SDK or VSCode extension
3. Sync with Puzzlet by committing and pushing to the connected git branch

​

VSCode Extension

For a more integrated development experience:

1. Install the Puzzlet Studio VSCode extension
2. Open any .prompt.mdx file
3. Use the built-in prompt “Run” to test your prompts directly in VSCode

​

Development Workflow

1. Start the local server
2. Create or modify prompts in your templates directory
3. Test using the SDK or VSCode extension
4. Sync changes to Puzzlet, by committing and pushing to the connected git branch
5. Ensure environment variables are set correctly in your deployed environment

This workflow allows you to develop and test prompts locally before deploying them to your production environment.