Anatomy of a node

type: OpenAI
kind: PromiseNode

name: OpenAI
category: AI
color: "#2F6F66"
description: One prompt in, one completion out, with no streaming or tools
whenToUse: >-
  Single prompt to single completion, the plain one-shot text generator: summarise,
  rewrite, classify, answer. No streaming, no tools, no schema enforcement; reach for a
  heavier node only when a step genuinely needs token streaming, iterative tool use, or
  strict JSON output.

auth:
  required: false

capabilities:
  cacheable: false

capabilities:
  cacheable:
    ignore: [fileUrl]     # volatile config fields, dropped from the fingerprint
    key: [etag]           # input leaf fields that identify the content

capabilities:
  cacheable: false
  emitsExternally: true

inputs:
  - name: signal
    type: object
    description: Data from previous nodes that can be referenced in templates

outputs:
  - name: text
    type: string
    description: The generated text response
  - name: usage
    type: object
    description: Token burn (prompt_tokens, completion_tokens, total_tokens)

credentials:
  - name: openAICredential
    required: true
    displayName: OpenAI API
    description: OpenAI API credentials for authentication

configSchema:
  type: object
  required: [model, prompt]
  properties:
    model:
      type: string
      title: Model
      description: Select the OpenAI model to use
      enum: { $ref: models#enum }
      enumNames: { $ref: models#enumNames }
      default: { $ref: models#default }
      resolve: modelTier
    maxTokens:
      type: number
      title: Max Tokens
      description: >-
        Hard ceiling on the reply. The model stops when it hits this, mid-sentence and
        without an error, so raise it for long output rather than leaving it to trim.
      default: 1200
      minimum: 1
      maximum: 128000
    systemPrompt:
      type: string
      title: System Prompt
      description: >-
        Standing instructions for every run: the model's role, tone and limits. Optional.
        Shared blocks work here, e.g. {{prompt.markdownGuidelines}}.
      default: ""
      ui:field: template
    prompt:
      type: string
      title: Prompt
      description: The request to answer. Usually wired in from an upstream node.
      default: ""
      ui:field: template

ui:order: [model, maxTokens, systemPrompt, prompt]

- name: generate
  method: POST
  url: { $ref: endpoints#responses }

  credential:
    scheme: bearer
    token: "{{ credentials.openAICredential.apiKey }}"

  body:
    model: "{{ config.model }}"
    input: "{{ config.prompt }}"
    instructions: "{{ config.systemPrompt }}"
    max_output_tokens: "{{ config.maxTokens }}"

  timeoutMs: 120000

  retry:
    attempts: 3
    backoff: exponential
    on: [429, 500, 502, 503, 504, 520, 522, 524]

  transport: json

  error:
    when: "return !!response.error"
    message: "return response.error.message"

- emit: text
  value: >-
    return response.output
      .filter(item => item.type === 'message')
      .flatMap(item => item.content)
      .filter(part => part.type === 'output_text')
      .map(part => part.text)
      .join('')

- emit: usage
  value: "return response.usage"

- emit: stream
  from: response
  match: response.output_text.delta
  value: "return response.delta"
  accumulate: true
  throttleMs: 200

testData:
  config:
    model: gpt-5.6-terra
    maxTokens: 256
    systemPrompt: You are a concise assistant.
    prompt: Write a one-sentence summary of what a workflow engine does.
  inputs:
    signal:
      question: What does a workflow engine do?
  expect:
    text: "return output.text.length > 0"
    usage: "return output.usage.total_tokens > 0"