Workflow Engine

@loop/workflow-engine is the deterministic orchestration core of the Health AI Platform.

It executes workflows defined as data and returns structured runtime output:

executed step IDs
per-step results
collected recommendations
execution errors

Why it matters

The engine gives the platform a reviewable decision layer that does not depend on ad hoc branching logic spread across applications.


import { WorkflowEngine } from '@loop/workflow-engine';
 
const workflow = WorkflowEngine.load({
  id: 'metabolic-review-v1',
  name: 'Metabolic Review',
  version: '1.0.0',
  steps: [{ id: 'check-a1c', type: 'check_biomarker' }],
});

What the package supports

Input formats

JavaScript objects
JSON strings
YAML strings


const workflow = WorkflowEngine.load(`
id: thyroid-review-v1
name: Thyroid Review
version: 1.0.0
steps:
  - id: check-tsh
    type: check_biomarker
`);

Trigger types


type TriggerType =
  | 'biomarker_result'
  | 'schedule'
  | 'manual'
  | 'event';

Step types


type StepType =
  | 'check_biomarker'
  | 'recommend_supplement'
  | 'order_lab'
  | 'check_contraindication'
  | 'send_notification'
  | 'run_tool';

Runtime context

The engine executes against a WorkflowContext.


interface WorkflowContext {
  patientId: string;
  data?: Record<string, unknown>;
  tools?: string[];
}

Typical usage:


const result = await workflow.execute({
  patientId: 'patient-42',
  data: {
    biomarker: { TSH: 4.2 },
    medications: ['metformin'],
  },
  tools: ['risk-calculator'],
});

Result shape


interface WorkflowResult {
  success: boolean;
  workflowId: string;
  executedSteps: string[];
  stepResults: Record<string, StepResult>;
  recommendations: Recommendation[];
  errors: WorkflowError[];
}

Example:


{
  "success": true,
  "workflowId": "thyroid-review-v1",
  "executedSteps": ["check-tsh", "recommend-selenium"],
  "recommendations": [
    {
      "type": "supplement",
      "details": {
        "supplement": "Selenium",
        "dosage": "200mcg"
      }
    }
  ],
  "errors": []
}

Step handlers in the current implementation

`check_biomarker`

Compares a numeric value in context.data against a threshold.


- id: check-tsh
  type: check_biomarker
  action:
    type: check_value
    params:
      biomarker: TSH
      threshold: 2.5
      operator: ">"

`recommend_supplement`

Adds a recommendation record to the workflow state.


- id: recommend-selenium
  type: recommend_supplement
  action:
    type: recommend
    params:
      supplement: Selenium
      dosage: 200mcg

`order_lab`

Returns a structured lab-order action result.


- id: order-thyroid-panel
  type: order_lab
  action:
    type: order
    params:
      test: thyroid_panel
      priority: urgent

`check_contraindication`

Checks whether a named medication exists in context.data.medications.


- id: check-warfarin
  type: check_contraindication
  action:
    type: check
    params:
      medication: warfarin
      supplement: Vitamin K

`send_notification`

Returns a notification action result including channel and message.


- id: notify-patient
  type: send_notification
  action:
    type: notify
    params:
      channel: email
      message: "Your review is ready."

`run_tool`

run_tool is implemented as a guarded extension point. It validates that the tool is allowed in context.tools and returns a stubbed execution record.


- id: invoke-risk-tool
  type: run_tool
  action:
    type: tool
    params:
      toolId: risk-calculator
      panel: advanced-metabolic


const result = await workflow.execute({
  patientId: 'patient-42',
  tools: ['risk-calculator'],
});

Validation behavior

The engine validates definitions on load and rejects:

missing id
missing name
missing version
empty steps
invalid step types
duplicate step IDs
unknown next references


WorkflowEngine.load({
  id: 'bad',
  name: 'Bad',
  version: '1.0.0',
  steps: [],
});
// throws

Where to use it

Use the workflow engine when you want:

deterministic clinical checks
repeatable branching logic
reviewable decision definitions
testable orchestration independent of UI

Do not use it as a substitute for:

broad agent reasoning
storage and retrieval
full external tool execution plumbing

Example: minimal health review


const workflow = WorkflowEngine.load(`
id: crp-review-v1
name: CRP Review
version: 1.0.0
steps:
  - id: check-crp
    type: check_biomarker
    action:
      type: check_value
      params:
        biomarker: CRP
        threshold: 3
        operator: ">"
  - id: notify
    type: send_notification
    condition: "check-crp.result === true"
    action:
      type: notify
      params:
        channel: email
        message: "Your inflammation markers may need follow-up."
`);
 
const result = await workflow.execute({
  patientId: 'patient-55',
  data: { biomarker: { CRP: 4.4 } },
});