@stepbook/runner

The execution engine behind stepbook — Storybook for typed pipelines, especially LLM ones. A stepbook pipeline is a set of typed async units you compose in code — a line for a pipeline, a loop for an agent — with optional Zod schemas, assertions, and per-unit caching. This package runs them; it has no UI.

Most people drive the runner through @stepbook/cli. You import it directly to author unit files and the pipeline entrypoint.

Install

npm install @stepbook/runner zod

Defining a unit

Each unit is a default-exported defineStep({...}) — its name is inferred from the filename, and it returns a callable you compose from the entrypoint:

import { z } from 'zod'
import { defineStep } from '@stepbook/runner'

export default defineStep({
  type: 'derive',
  schema: z.object({
    longWords: z.array(z.string()),
    density: z.enum(['concise', 'balanced', 'verbose']),
  }),
  runner: async (input: { words: string[]; wordCount: number }) => {
    const longWords = input.words.filter((w) => w.length >= 5)
    const ratio = longWords.length / input.wordCount
    const density = ratio < 0.2 ? 'concise' : ratio < 0.4 ? 'balanced' : 'verbose'
    return { longWords, density }
  },
  assertions: (o) => [
    { name: 'density is known', pass: ['concise', 'balanced', 'verbose'].includes(o.density) },
  ],
})

The entrypoint

A definePipeline({ name, runner }) composes units by calling them — no deps, the wiring is the code. stepbook run executes the runner and records every unit call as a first-class node in the run's trajectory:

import { definePipeline } from '@stepbook/runner'
import parse from './steps/parse.step'
import analyze from './steps/analyze.step'

export default definePipeline({
  name: 'demo',
  runner: async (input) => analyze(await parse(input)),
})

Step types — input | parse | llm | derive | eval — signal intent and drive the dashboard's coloring. For LLM units, ctx.report({ model, tokens, cost, latencyMs }) records telemetry the dashboard reads and stepbook run rolls up into a per-run cost.

Docs

• Step-author API
• Public API surface
• Concepts & guide

License

MIT