Getting Started

Use this guide when you want to validate the Health AI Platform locally without learning every subsystem first.

What you will verify

By the end of this page you will have confirmed:

The docs app runs
The workflow engine loads and executes a workflow
The Patient Graph client can be configured
The ML service boundary responds to a health check

Prerequisites

Node.js 20+
pnpm 9.x
Python 3.11+ for the ML service
Access to the same environment variables used by the surrounding Loop apps

1. Install dependencies


pnpm install

2. Start the docs site


pnpm --filter @loop/docs dev

Open the docs site at the local docs URL configured for this app.

3. Run a minimal workflow example

The fastest sanity check is to execute a tiny workflow directly from @loop/workflow-engine.


import { WorkflowEngine } from '@loop/workflow-engine';
 
const workflow = WorkflowEngine.load(`
id: getting-started-v1
name: Getting Started Workflow
version: 1.0.0
steps:
  - id: check-tsh
    type: check_biomarker
    action:
      type: check_value
      params:
        biomarker: TSH
        threshold: 2.5
        operator: ">"
  - id: recommend-selenium
    type: recommend_supplement
    condition: "check-tsh.result === true"
    action:
      type: recommend
      params:
        supplement: Selenium
        dosage: 200mcg
`);
 
const result = await workflow.execute({
  patientId: 'patient-42',
  data: {
    biomarker: { TSH: 4.2 },
  },
});
 
console.log(result.recommendations);

Expected outcome:


[
  {
    "type": "supplement",
    "details": {
      "supplement": "Selenium",
      "dosage": "200mcg"
    }
  }
]

4. Configure Patient Graph access

The platform gets most patient context from the Patient Graph API.


import { PatientGraphClientImpl } from '@loop/patient-graph-client';
 
const patientGraph = new PatientGraphClientImpl({
  baseUrl: process.env.PATIENT_GRAPH_API_URL!,
  getAuthToken: async () => process.env.PATIENT_GRAPH_API_KEY!,
  timeout: 5000,
});
 
const profile = await patientGraph.getPatientContext('user_123');

Relevant environment variables already exist in the consumer app config:


PATIENT_GRAPH_API_URL=http://localhost:3005
PATIENT_GRAPH_API_KEY=replace-me

5. Check optional integration boundaries

Some platform surfaces are integration contracts rather than fully local-only implementations.

Junction

The repo validates Junction-related environment variables even though the concrete integration can vary by deployment.


JUNCTION_HEALTH_API_KEY=replace-me
JUNCTION_HEALTH_CLIENT_ID=replace-me
JUNCTION_HEALTH_CLIENT_SECRET=replace-me

ML service

The checked-in ML service currently exposes a health endpoint.


cd apps/ml-service
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

Then verify:


curl http://localhost:8000/health

Example response:


{
  "status": "ok",
  "python_version": "3.11.8",
  "dependencies": {
    "pandas": true,
    "scikit_learn": true,
    "scipy": true
  }
}

6. Verify the full platform handshake

This is the smallest end-to-end script that combines workflow loading, patient context access, and ML service health.


import { WorkflowEngine } from '@loop/workflow-engine';
import { PatientGraphClientImpl } from '@loop/patient-graph-client';
import { MLClient } from '@loop/ml-client';
 
const patientGraph = new PatientGraphClientImpl({
  baseUrl: process.env.PATIENT_GRAPH_API_URL!,
  getAuthToken: async () => process.env.PATIENT_GRAPH_API_KEY!,
});
 
const ml = new MLClient({ baseUrl: 'http://localhost:8000' });
 
const workflow = WorkflowEngine.load({
  id: 'platform-smoke-test',
  name: 'Platform Smoke Test',
  version: '1.0.0',
  steps: [{ id: 'check', type: 'check_biomarker' }],
});
 
const [profile, health] = await Promise.all([
  patientGraph.getPatientContext('user_123'),
  ml.healthCheck(),
]);
 
console.log({
  patientGraphOk: profile.ok,
  mlStatus: health.status,
  workflowRegistered: WorkflowEngine.get('platform-smoke-test') !== undefined,
});

Common local workflows

Troubleshooting

Workflow executes but returns no recommendations

Make sure your condition references the actual step ID:


condition: "check-tsh.result === true"

Patient Graph calls fail

Verify both the base URL and auth token callback:


const client = new PatientGraphClientImpl({
  baseUrl: 'http://localhost:3005',
  getAuthToken: async () => 'your-api-key-or-jwt',
});

Research ingestion appears unavailable

That may be expected in this repo snapshot. The reusable ingestion pipeline exists in @loop/ai, but the admin hook currently wraps a placeholder that returns an internal error until the export is restored.