SDK Reference

1npm install @relayplane/sdk
2# or
3pnpm add @relayplane/sdk
4# or
5yarn add @relayplane/sdk

1import { relay } from '@relayplane/sdk';
2
3// Configure providers
4relay.configure({
5  providers: {
6    openai: { apiKey: process.env.OPENAI_API_KEY! },
7    anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! }
8  }
9});
10
11// Create and run a workflow
12const result = await relay
13  .workflow('my-workflow')
14  .step('extract', {
15    schema: MySchema,
16    systemPrompt: 'Extract data from the input'
17  })
18  .with('openai:gpt-4o')
19  .step('summarize')
20  .with('anthropic:claude-3.5-sonnet')
21  .depends('extract')
22  .run({ input: 'Your data here' });
23
24console.log(result.steps.summarize);

1import { relay } from '@relayplane/sdk';
2
3// Create a workflow
4const workflow = relay.workflow('name');
5
6// Configure globally
7relay.configure({ ... });
8
9// Get current config
10const config = relay.getConfig();
11
12// Reset config (for testing)
13relay.resetConfig();

1interface StepConfig {
2  /** JSON Schema for structured output */
3  schema?: JSONSchema;
4
5  /** System prompt for AI behavior */
6  systemPrompt?: string;
7
8  /** User prompt with template variables */
9  userPrompt?: string;
10
11  /** Retry configuration */
12  retry?: {
13    maxRetries: number;
14    backoffMs?: number;
15  };
16
17  /** Custom metadata */
18  metadata?: Record;
19}

1interface RunOptions {
2  /** Execution mode */
3  mode?: 'local' | 'cloud';
4
5  /** Provider configuration overrides */
6  providers?: Record;
7
8  /** Timeout in milliseconds */
9  timeout?: number;
10
11  /** Run metadata */
12  metadata?: Record;
13
14  /** Abort signal for cancellation */
15  signal?: AbortSignal;
16}

1interface WorkflowResult {
2  /** Whether workflow succeeded */
3  success: boolean;
4
5  /** Step outputs by name */
6  steps: Record;
7
8  /** Final step output */
9  finalOutput?: any;
10
11  /** Error if failed */
12  error?: {
13    message: string;
14    stepName?: string;
15    cause?: any;
16  };
17
18  /** Execution metadata */
19  metadata: {
20    workflowName: string;
21    startTime: Date;
22    endTime: Date;
23    duration: number;
24  };
25}

1interface GlobalConfig {
2  /** Provider configurations */
3  providers?: Record;
4
5  /** Telemetry settings */
6  telemetry?: {
7    enabled: boolean;
8    apiEndpoint?: string;
9    apiKey?: string;
10  };
11
12  /** Cloud features */
13  cloud?: {
14    enabled: boolean;
15    teamId?: string;
16    accessToken?: string;
17  };
18}

1interface ProviderConfig {
2  /** API key for the provider */
3  apiKey: string;
4
5  /** Custom base URL */
6  baseUrl?: string;
7
8  /** Organization ID (for OpenAI) */
9  organization?: string;
10}

1import { relay } from '@relayplane/sdk';
2import { z } from 'zod';
3
4// Define your schema with Zod
5const InvoiceSchema = z.object({
6  invoiceNumber: z.string(),
7  vendor: z.string(),
8  totalAmount: z.number(),
9  currency: z.enum(['USD', 'EUR', 'GBP']),
10  items: z.array(z.object({
11    description: z.string(),
12    quantity: z.number(),
13    unitPrice: z.number(),
14  })),
15  dueDate: z.string().optional(),
16});
17
18// TypeScript infers the output type from your schema
19type Invoice = z.infer;
20
21// Use the schema in your workflow
22const result = await relay
23  .workflow('invoice-processor')
24  .step('extract', { schema: InvoiceSchema })
25  .with('openai:gpt-4o')
26  .prompt('Extract invoice data from this document: {{input.document}}')
27  .run({ document: pdfText });
28
29// result.steps.extract is typed based on your schema
30if (result.success) {
31  const invoice: Invoice = result.steps.extract;
32  console.log(`Invoice #${invoice.invoiceNumber}`);
33  console.log(`Total: ${invoice.totalAmount} ${invoice.currency}`);
34}

1import { relay, WorkflowResult } from '@relayplane/sdk';
2
3async function processData(input: string): Promise {
4  const result: WorkflowResult = await relay
5    .workflow('processor')
6    .step('analyze')
7    .with('openai:gpt-4o')
8    .prompt('Analyze: {{input.data}}')
9    .run({ data: input });
10
11  if (!result.success) {
12    // TypeScript knows result.error exists when success is false
13    throw new Error(`Step ${result.error?.stepName} failed: ${result.error?.message}`);
14  }
15
16  // TypeScript knows steps exist when success is true
17  return result.steps.analyze;
18}

1import { relay, WorkflowResult } from '@relayplane/sdk';
2import { z } from 'zod';
3
4// Create a typed workflow function
5async function runWorkflow(
6  name: string,
7  schema: T,
8  input: Record
9): Promise> {
10  const result = await relay
11    .workflow(name)
12    .step('process', { schema })
13    .with('openai:gpt-4o')
14    .prompt('Process the input according to the schema.')
15    .run(input);
16
17  if (!result.success) {
18    throw new Error(result.error?.message);
19  }
20
21  return result.steps.process as z.infer;
22}
23
24// Usage with full type inference
25const SentimentSchema = z.object({
26  sentiment: z.enum(['positive', 'negative', 'neutral']),
27  confidence: z.number().min(0).max(1),
28});
29
30const sentiment = await runWorkflow('sentiment', SentimentSchema, { text: 'I love this!' });
31// sentiment is typed as { sentiment: 'positive' | 'negative' | 'neutral', confidence: number }

1import { checkForUpdates } from '@relayplane/sdk';
2
3// Check for updates manually
4const result = await checkForUpdates();
5if (result?.updateAvailable) {
6  console.log(`Update available: ${result.current} → ${result.latest}`);
7}
8
9// Disable automatic checks
10process.env.RELAY_NO_VERSION_CHECK = 'true';
11
12// Quiet mode (suppress optional updates)
13process.env.RELAY_QUIET_VERSION_CHECK = 'true';