output-dev-step-function

# Creating Step Functions ## Overview This skill documents how to create step functions in `steps.ts` for Output SDK workflows. Steps are where all I/O operations happen - HTTP requests, LLM calls, database operations, file system access, etc. ## When to Use This Skill - Implementing I/O operations for a workflow - Adding HTTP client integrations - Implementing LLM-powered steps - Handling errors with FatalError and ValidationError - Creating reusable step components ## File Organization ### Option 1: Flat File (Default) For smaller workflows, use a single `steps.ts` file: ``` src/workflows/{workflow-name}/ ├── workflow.ts ├── steps.ts # All steps in one file ├── types.ts └── ... ``` ### Option 2: Folder-Based (Large workflows) For larger workflows with many steps, use a `steps/` folder: ``` src/workflows/{workflow-name}/ ├── workflow.ts ├── steps/ # Steps split into individual files │ ├── fetch_data.ts │ ├── process.ts │ └── validate.ts ├── types.ts └── ... ``` ## Component Location Rules **Important**: `step()` calls MUST be in files containing 'steps' in the path: - `src/workflows/my_workflow/steps.ts` ✓ - `src/workflows/my_workflow/steps/fetch_data.ts` ✓ - `src/shared/steps/common_steps.ts` ✓ - `src/workflows/my_workflow/helpers.ts` ✗ (cannot contain step() calls) ## Activity Isolation Constraints Steps are Temporal activities with strict import rules to ensure deterministic replay. ### Steps CAN import from: - Local workflow files: `./utils.js`, `./types.js`, `./helpers.js` - Local subdirectories: `./clients/pokeapi.js`, `./lib/helpers.js` - Shared utilities: `../../shared/utils/*.js` - Shared clients: `../../shared/clients/*.js` - Shared services: `../../shared/services/*.js` ### Steps CANNOT import: - Other step files (even shared steps - workflows import those) - Evaluator files - Workflow files **Example of WRONG imports:** ```typescript // WRONG - steps cannot import other steps import { otherStep } from '../../shared/steps/other.js'; // ✗ import { anotherStep } from './other_steps.js'; // ✗ ``` ## Critical Import Patterns ### Core Imports ```typescript // CORRECT - Import from @outputai/core import { step, z, FatalError, ValidationError } from '@outputai/core'; // WRONG - Never import z from zod import { z } from 'zod'; ``` ### HTTP Client Import ```typescript // CORRECT - Use @outputai/core/http wrapper import { createKyClient } from '@outputai/core/http'; // WRONG - Never use axios directly import axios from 'axios'; ``` **Related Skill**: `output-error-http-client` ### LLM Client Import ```typescript // CORRECT - Use @outputai/llm wrapper import { generateText, aiSdk } from '@outputai/llm'; // WRONG - Never call LLM providers directly import OpenAI from 'openai'; ``` ### ES Module Imports All imports MUST use `.js` extension: ```typescript // CORRECT import { InputSchema, OutputSchema } from './types.js'; import { GeminiService } from '../../shared/clients/gemini_client.js'; // WRONG - Missing .js extension import { InputSchema, OutputSchema } from './types'; ``` ## Basic Structure ```typescript import { step, z, FatalError, ValidationError } from '@outputai/core'; import { createKyClient } from '@outputai/core/http'; import { generateText, aiSdk } from '@outputai/llm'; import { StepInputSchema, StepOutputSchema } from './types.js'; export const myStep = step( { name: 'myStep', description: 'Description of what this step does', inputSchema: StepInputSchema, outputSchema: StepOutputSchema, fn: async input => { // Implementation with I/O operations return { /* output matching outputSchema */ }; } } ); ``` ## Required Properties ### name (string) Unique identifier for the step. Use camelCase. ```typescript name: 'generateImageIdeas' ``` ### description (string) Human-readable description of the step's purpose. ```typescript description: 'Generate creative infographic prompt ideas using Claude' ``` ### inputSchema (Zod schema) Schema for validating step input. Define in `types.ts` and import. ```typescript inputSchema: z.object( { content: z.string(), numberOfIdeas: z.number() } ) ``` ### outputSchema (Zod schema) Schema for validating step output. Define in `types.ts` and import. ```typescript outputSchema: z.array( z.string() ) ``` ### fn (async function) The step execution function. This is where I/O operations happen. ```typescript fn: async input => { const result = await someExternalService( input ); return result; } ``` ## HTTP Client Usage ### Creating an HTTP Client ```typescript import { createKyClient } from '@outputai/core/http'; import { FatalError, ValidationError } from '@outputai/core'; const RETRY_STATUS_CODES = [ 408, 429, 500, 502, 503, 504 ]; const FATAL_STATUS_CODES = [ 401, 403, 404 ]; const client = createKyClient( { timeout: 30000, retry: { limit: 3, statusCodes: RETRY_STATUS_CODES }, hooks: { beforeError: [ ( { error } ) => { const status = error.response?.status; const message = error.message; if ( status && FATAL_STATUS_CODES.includes( status ) ) { throw new FatalError( `HTTP ${status} error: ${message}. This is a permanent error.` ); } throw new ValidationError( `HTTP request failed: ${message}` ); } ] } } ); ``` ### Making HTTP Requests ```typescript // GET request const response = await client.get( 'https://api.example.com/data' ); const data = await response.json(); // POST request with JSON body const response = await client.post( 'https://api.example.com/submit', { json: { field: 'value' } } ); // HEAD request (check URL accessibility) const response = await client.head( url ); const contentType = response.headers.get( 'content-type' ); ``` When a non-`HEAD` request only uses response metadata, such as `response.url`, `response.status`, or headers, cancel the unused body in a `finally` block. Responses read with `.json()`, `.text()`, etc. are already consumed. ```typescript const response = await client.get( url ); try { return response.url; } finally { await response.body?.cancel(); } ``` **Related Skill**: `output-dev-http-client-create` for creating shared clients ## LLM Operations ### Important: Define LLM Schemas in types.ts Schemas used in `aiSdk.Output.object()` **must** be defined in `types.ts` and imported -- never defined inline in step functions. Inline schemas lead to duplication, drift between the step's `outputSchema` and the LLM schema, and make it harder to maintain types. ```typescript // WRONG - inline schema in aiSdk.Output.object() output: aiSdk.Output.object( { schema: z.object( { analysis: z.string() } ) } ) // CORRECT - import from types.ts import { AnalysisLlmSchema } from './types.js'; // ... output: aiSdk.Output.object( { schema: AnalysisLlmSchema } ) ``` ### Using generateText with aiSdk.Output.object() The `variables` field accepts scalars, nested objects, and arrays. Use Liquid loops and dot notation in the prompt when it owns presentation; pre-format in the step when the exact rendered text is application logic. `generateText` arguments: `prompt`, `promptDir`, `variables`, `tools`, `output`, `toolChoice`, `stopWhen`, `abortSignal`. ```typescript import { generateText, aiSdk } from '@outputai/llm'; import { AnalyzeContentInputSchema, AnalyzeContentOutputSchema, AnalysisLlmSchema } from './types.js'; export const analyzeContent = step( { name: 'analyzeContent', description: 'Analyze content using Claude', inputSchema: AnalyzeContentInputSchema, outputSchema: AnalyzeContentOutputSchema, fn: async ( { content } ) => { const { output } = await generateText( { prompt: 'analyzeContent@v1', variables: { content }, output: aiSdk.Output.object( { schema: AnalysisLlmSchema } ) } ); return { analysis: output.analysis }; } } ); ``` ### Using generateText ```typescript import { generateText } from '@outputai/llm'; import { SummarizeInputSchema, SummarizeOutputSchema } from './types.js'; export const generateSummary = step( { name: 'generateSummary', description: 'Generate a text summary', inputSchema: SummarizeInputSchema, outputSchema: SummarizeOutputSchema, fn: async ( { content } ) => { const { result } = await generateText( { prompt: 'summarize@v1', variables: { content } } ); return { summary: result }; } } ); ``` **Related Skill**: `output-dev-prompt-file` for creating prompt files ### Streaming LLM Progress Prefer `generateTextWithStreaming()` in steps when the caller needs progress callbacks and a complete result: ```typescript import { generateTextWithStreaming } from '@outputai/llm'; const reportProgress = ( chunk: string ) => process.stdout.write( chunk ); const result = await generateTextWithStreaming( { prompt: 'summarize@v1', variables: { content }, onChunk( { chunk } ) { if ( chunk.type === 'text-delta' ) { reportProgress( chunk.text ); } } } ); return result.result; ``` The returned promise rejects on stream failures, allowing Temporal to retry the activity. Use `streamText()` only when direct stream access is required; capture `onError` and throw the captured error after consumption. See `output-dev-llm-streaming` for complete patterns. ## Error Handling ### FatalError (Non-Retryable) Use FatalError for permanent failures that should not be retried: ```typescript import { FatalError } from '@outputai/core'; import { credentials } from '@outputai/core/credentials'; // Authentication failures if ( response.status === 401 ) { throw new FatalError( 'Invalid API key' ); } // Invalid input that cannot be fixed by retry if ( !input.requiredField ) { throw new FatalError( 'Missing required field: requiredField' ); } // Resource not found if ( response.status === 404 ) { throw new FatalError( `Resource not found: ${resourceId}` ); } // Configuration errors if ( !credentials.get( 'service.api_key' ) ) { throw new FatalError( 'service.api_key credential not set' ); } ``` ### ValidationError (Retryable) Use ValidationError for temporary failures that may succeed on retry: ```typescript import { ValidationError } from '@outputai/core'; // Rate limiting if ( response.status === 429 ) { throw new ValidationError( 'Rate limit exceeded, will retry' ); } // Temporary service unavailability if ( response.status === 503 ) { throw new ValidationError( 'Service temporarily unavailable' ); } // Network errors try { const response = await client.get( url ); } catch ( error ) { throw new ValidationError( `Network error: ${error.message}` ); } // Empty response that might be temporary if ( results.length === 0 ) { throw new ValidationError( 'No results returned, will retry' ); } ``` **Related Skill**: `output-error-try-catch` for proper error handling patterns ## Complete Example Based on a real workflow step: ```typescript import { step, z, FatalError, ValidationError } from '@outputai/core'; import { createKyClient } from '@outputai/core/http'; import { generateText, aiSdk } from '@outputai/llm'; import { GeminiImageService } from '../../shared/clients/gemini_client.js'; import { GenerateImageIdeasInputSchema, GenerateImagesInputSchema, ImageIdeasSchema } from './types.js'; const RETRY_STATUS_CODES = [ 408, 429, 500, 502, 503, 504 ]; const FATAL_STATUS_CODES = [ 401, 403, 404 ]; const client = createKyClient( { timeout: 30000, retry: { limit: 3, statusCodes: RETRY_STATUS_CODES }, hooks: { beforeError: [ ( { error } ) => {