Thirty-minute Blueprint tutorial

This tutorial turns the quickstart scaffold into one narrow Classifier and adds it to a TypeScript application boundary. The target is a complete development loop, not a claim of production model quality.

0 to 5 minutes: create the unit

Complete the five-minute quickstart. It creates:

blueprints/expense-category/
├── expense-category.yaml
├── README.md
├── evaluations/
│   └── expense-category.yaml
└── tests/
    └── expense-category.contract.test.ts

This directory is the change unit. Keep its declaration, policy, dataset, and offline test versioned together.

5 to 12 minutes: narrow the contract

Edit expense-category.yaml. Keep one operation: classify one normalized expense description into one caller-defined category. Do not also extract a receipt, approve payment, update a ledger, or send a notification.

Use a contract shaped like this:

name: Expense category
version: 0.1.0
role: assistant
temperature: 0
input_placeholders:
  - name: input
    type: string
    required: true
input_schema:
  type: object
  additionalProperties: false
  required: [input]
  properties:
    input: { type: string, minLength: 1, pattern: '\S' }
prompt: |
  Classify exactly one normalized expense description from {{ input }}.
  Return the category only. Do not approve, reimburse, or update records.
  Return only JSON matching the output schema.
output_schema:
  type: object
  additionalProperties: false
  required: [result]
  properties:
    result:
      type: string
      enum: [travel, meals, lodging, software, other]

The categories above are an example policy. A production Blueprint should take changing business policy as versioned caller input or a bounded tool rather than hide it in application code or assume it from general knowledge.

Update the generated contract test at the same time: make its fixture provider return { result: 'software' } and assert that exact result instead of echoing the seeded input. The test must always return a value accepted by the current output schema.

12 to 18 minutes: make expected behavior explicit

Edit evaluations/expense-category.yaml. Add ordinary, boundary, ambiguous, and unsupported inputs. Each case needs a stable ID, inputs, expected output, and comparison policy. Start with exact comparison:

schema: pixiecore.blueprint-eval-dataset/v1
name: Expense category evaluation
version: 0.1.0
blueprint:
  path: ../expense-category.yaml
  version: 0.1.0
tags: [classifier, tutorial]
cases:
  - id: canonical-software
    tags: [canonical]
    inputs: { input: annual source-control subscription }
    expected_output: { result: software }
    comparison: { mode: exact }

Add cases for descriptions with insufficient evidence instead of forcing a guess. If the contract needs an ambiguous status, change the output schema and expected outputs before changing the prompt.

18 to 23 minutes: run the offline contract

Install the TypeScript test loader and execute the generated public-API test:

npm install --save-dev typescript tsx @types/node
TEST_SEED=tutorial-replay-1 node --test --import tsx \
  blueprints/expense-category/tests/expense-category.contract.test.ts
npx --package @pixieworks/pixiecore pixiecore blueprint validate \
  blueprints/expense-category/expense-category.yaml
npx --package @pixieworks/pixiecore pixiecore blueprint test blueprints/expense-category
npx --package @pixieworks/pixiecore pixiecore blueprint play \
  blueprints/expense-category/evaluations/expense-category.yaml \
  --case=canonical-software

The generated test injects an offline Provider through the public PromptRuntime API. Replace its fixture output as the schema evolves. A fixed TEST_SEED reproduces one failure; omit it during normal project test runs to generate one seed for that run.

blueprint play defaults to an offline expected-output fixture. It proves the runtime and comparison path, not remote-model accuracy. Use blueprint eval with an explicitly configured provider when measuring actual model behavior.

23 to 30 minutes: add the call to an application

Keep orchestration in TypeScript. The application validates deterministic inputs, calls the Blueprint, handles its typed result, and owns side effects:

import { PromptRuntime } from '@pixieworks/pixiecore';

export async function classifyExpense(description: string): Promise<string> {
  if (!description.trim()) throw new TypeError('description must be non-blank');

  await using runtime = new PromptRuntime();
  const result = await runtime.execute(
    './blueprints/expense-category/expense-category.yaml',
    { input: description },
  );
  return String(result.result);
}

In a larger application, pass one shared runtime into the composition root instead of creating one per function. Map fields explicitly between Blueprint calls, propagate one AbortSignal, and perform persistence, authorization, notification, approval, and retries at their documented owner boundary.

Before merging:

Next, read the architecture guide and the complete application composition guide.