@alvera-ai/platform-sdk 0.10.0-rc.2 → 0.10.0-rc.21

package/.agent/cookbook/contact-us-triage-with-llm.md

@@ -0,0 +1,603 @@
+---
+title: Triage inbound contact-us messages into three priority buckets via an LLM agent
+summary: End-to-end agent-driven workflow — a chat-completion LLM agent classifies each contact-us submission into appointment_request / job_inquiry / flag_spam, the workflow's decision interpolates the agent's category, three SMS actions (one per bucket) fan out, and the run is verified row-by-row so every WEL carries exactly one matched action and two skipped.
+industry: healthcare
+slug: contact-us-triage-with-llm
+vitest_source:
+  - integration-tests/tests/healthcare/agent-driven-workflow.test.ts
+  - integration-tests/tests/healthcare/generic-tables.test.ts
+  - integration-tests/tests/healthcare/tools.test.ts
+  - integration-tests/tests/healthcare/bootstrap.test.ts
+status: green
+---
+
+# Problem
+
+A clinic's "Contact Us" form is a firehose of mixed intent. One
+message asks to book an appointment, the next is a nurse applying
+for a job, the third is promotional spam. Routing all three to the
+same inbox means the appointment request waits behind the spam.
+
+A keyword filter handles the obvious cases and misses the rest —
+"I'd love to come in and see Dr. Johnson" has no booking keyword,
+"openings" appears in both a job inquiry and a spam blast. The
+classification is a language task, not a rules task.
+
+The Alvera platform's agent-driven workflow primitive turns the
+decision step into an LLM enrichment plus a Liquid interpolation.
+An AI agent receives the submission's free text via a
+context-mapping template, returns a JSON object whose `category`
+field is one of three enum values, and the workflow's
+decision_config interpolates that category into a one-element
+decision array (`["{{ additional_context["agent-slug"].category }}"]`).
+Three SMS actions are registered against the workflow, one per
+bucket; the agent's output picks which one runs.
+
+This cookbook walks the **whole** scenario: it provisions the
+generic table, agent, and workflow, ingests three contact-us
+submissions through the generic-table's auto-provisioned default
+DAC, runs the workflow so the agent classifies each row, and
+verifies the routing row-by-row — every Workflow Execution Log
+carries exactly one matched action and two skipped, proving the
+agent's category actually steered the fan-out.
+
+The scenario is anchored to
+`platform/integration-tests/tests/healthcare/agent-driven-workflow.test.ts`
+— a green end-to-end test whose positive branch (§1, §3, §4, §6,
+§7) is exactly this shape. The setup file `_setup/healthcare.md`
+already provisioned the tenant + datalake + tenant-scoped client;
+this cookbook starts from there.
+
+# Composition
+
+| Resource provisioned               | Owner       |
+|-------------------------------------|-------------|
+| Contact Us submissions dataset      | build       |
+| SMS tool (SNS-backed)               | build       |
+| LLM tool (Ollama chat completion)   | build       |
+| Contact Us Triage AI agent          | build       |
+| Contact Us Triage workflow          | build       |
+
+The generic table's **default DAC** — auto-provisioned by the
+platform when the generic table is created — is reused for
+ingestion; no separate data source / tool / interop contract / DAC
+is created. The setup file `_setup/healthcare.md` already
+provisioned the tenant + datalake + tenant-scoped client; this
+cookbook starts from there.
+
+# Walkthrough
+
+## 001 — create the Contact Us submissions generic table
+
+The agent-driven workflow targets a Generic Table dataset
+(`dataset_type: 'generic_table'`) rather than a regulated domain
+entity, because contact-us form rows do not fit a canonical FHIR
+entity. The table's columns mirror the shape a website form export
+would produce; the `message` column is what the agent reads, and
+`category` is what the agent eventually writes back in production.
+The server-derived `name` is captured — the workflow run in §009
+addresses the regulated table as `regulated_<name>`.
+
+```typescript
+const genericTableResp = await api.genericTables.create(tenantSlug, datalakeSlug, {
+  title: `Cookbook Contact Us ${runSuffix}`,
+  description: 'Inbound contact-us form submissions the Triage agent classifies.',
+  columns: [
+    {
+      name: 'submission_id',
+      title: 'Submission ID',
+      type: 'string',
+      description: 'Vendor-supplied unique submission id',
+      is_unique: true,
+      privacy_requirement: 'none',
+    },
+    {
+      name: 'name',
+      title: 'Name',
+      type: 'string',
+      description: 'Submitter full name',
+      is_unique: false,
+      privacy_requirement: 'tokenize',
+    },
+    {
+      name: 'email',
+      title: 'Email',
+      type: 'string',
+      description: 'Submitter email',
+      is_unique: false,
+      privacy_requirement: 'tokenize',
+    },
+    {
+      name: 'message',
+      title: 'Message',
+      type: 'string',
+      description: 'Free-text contact-us message — the agent classifies this',
+      is_unique: false,
+      privacy_requirement: 'none',
+    },
+    {
+      name: 'category',
+      title: 'Category',
+      type: 'string',
+      description: 'Triage bucket assigned by the Contact Us Triage agent',
+      is_unique: false,
+      privacy_requirement: 'none',
+    },
+  ],
+})
+genericTableId = genericTableResp.data.id!
+ctx.gtName = genericTableResp.data.name!
+```
+
+## 002 — create the SMS tool
+
+A single SMS tool dispatches every bucket's outbound message; the
+per-bucket SMS body lives on each workflow action, not on the tool.
+SNS-backed LocalStack wiring — `intent: 'sms'` tags it for
+workflow-action use.
+
+```typescript
+const smsToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook SMS Tool ${runSuffix}`,
+  description: 'SNS-backed SMS dispatcher for the Contact Us Triage workflow, wired to LocalStack.',
+  intent: 'sms',
+  status: 'active',
+  datalake_id: ctx.datalakeId,
+  body: {
+    tool_body_type: 'sns',
+    auth_method: 'access_key',
+    region: 'us-east-1',
+    phone_number: '+15551234567',
+    endpoint_url: 'http://localhost:4566',
+    access_key_id: 'test',
+    secret_access_key: 'test',
+  },
+})
+toolId = smsToolResp.data.id!
+```
+
+## 003 — create the LLM tool
+
+The Triage agent calls a chat-completion endpoint to classify each
+row. The tool's `intent: 'llm_enrichment'` distinguishes it from
+the SMS tool above; `tool_body_type: 'rest_api'` plus an
+OpenAI-compatible `base_url` lets the platform route Ollama,
+Anthropic, OpenAI, or any other compatible inference server
+through the same wire format. Local dev points at Ollama's
+OpenAI-compat shim on `http://localhost:11434/v1` — note the `/v1`
+root, not `/v1/chat/completions`; the platform's chat-completion
+protocol appends `/chat/completions` itself. The
+`api_key`/`auth_method` pair is required by the REST tool's
+discriminated-union schema even though Ollama ignores the header.
+
+```typescript
+const llmToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook LLM Tool ${runSuffix}`,
+  description: 'Ollama-backed chat-completion endpoint for Contact Us triage classification.',
+  intent: 'llm_enrichment',
+  status: 'active',
+  datalake_id: ctx.datalakeId,
+  body: {
+    tool_body_type: 'rest_api',
+    base_url: 'http://localhost:11434/v1',
+    auth_method: 'api_key',
+    api_key: 'ollama-noop',
+    api_key_name: 'Authorization',
+    api_key_location: 'header',
+    request_type: 'json',
+    response_type: 'json',
+    timeout_ms: 60_000,
+  },
+})
+ctx.llmToolId = llmToolResp.data.id!
+```
+
+## 004 — create the Contact Us Triage AI agent
+
+The agent binds three things: the model name (sent on every
+inference call), an input schema the workflow's context-mapping
+must satisfy, and a response schema the agent's output must match.
+The response schema's `enum: ['appointment_request','job_inquiry','flag_spam']`
+constraint is what guards the downstream decision interpolation
+from emitting a category the workflow has no SMS action for.
+`temperature: 0.0` removes sampling noise so identical inputs
+classify identically. `data_access: 'unregulated'` says the agent
+only ever sees the tokenized projection of each row.
+
+```typescript
+const TRIAGE_INPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    msg: { type: 'string' },
+    submission_id: { type: 'string' },
+  },
+  required: ['msg', 'submission_id'],
+}
+
+const TRIAGE_RESPONSE_SCHEMA = {
+  type: 'object',
+  properties: {
+    category: {
+      type: 'string',
+      enum: ['appointment_request', 'job_inquiry', 'flag_spam'],
+    },
+  },
+  required: ['category'],
+}
+
+const AGENT_PROMPT_BODY = `You are a triage assistant. Categorize the following message into EXACTLY ONE of these categories:
+
+- "appointment_request" — the user wants to book/reschedule a medical appointment
+- "job_inquiry" — the user is asking about employment or job opportunities
+- "flag_spam" — the message is promotional / spam / irrelevant
+
+Submission ID: {{ submission_id }}
+Message: {{ msg }}
+
+Respond with a JSON object: {"category": "<one of the three categories above>"}`
+
+const agentResp = await api.aiAgents.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook Contact Us Triage Agent ${runSuffix}`,
+  tool_id: ctx.llmToolId,
+  model: 'gemma3:1b',
+  data_access: 'unregulated',
+  temperature: 0.0,
+  max_tokens: 1024,
+  enabled: true,
+  input_schema: TRIAGE_INPUT_SCHEMA,
+  llm_response_schema: TRIAGE_RESPONSE_SCHEMA,
+  prompt_config: { type: 'custom', body: AGENT_PROMPT_BODY },
+})
+aiAgentId = agentResp.data.id!
+ctx.agentSlug = agentResp.data.slug!
+```
+
+## 005 — create the Contact Us Triage workflow
+
+The workflow has the standard shape — filter, decision, actions —
+but two things distinguish it from a static workflow. First, the
+`ai_agents` array binds the Triage agent into the workflow's
+enrichment phase, with a Liquid `context_mapping_config` that
+projects each submission row's fields into the agent's input
+schema. Second, the `decision_config` body is a Liquid template
+that interpolates the agent's `category` output (read from
+`additional_context["<agent-slug>"].category`) into a
+single-element decision array. The three `actions` are keyed
+`decision_key: appointment_request|job_inquiry|flag_spam`;
+whichever category the agent emits picks the action that fires,
+leaving the other two `:skipped`.
+
+Bracket access (`additional_context["..."]`) is used because the
+agent's slug contains hyphens, which a dotted Liquid lookup could
+misread as subtraction operators.
+
+```typescript
+const BUCKETS = ['appointment_request', 'job_inquiry', 'flag_spam'] as const
+
+const CONTEXT_MAPPING_BODY = JSON.stringify({
+  msg: '{{ event_dataset.message }}',
+  submission_id: '{{ event_dataset.submission_id }}',
+})
+
+const DECISION_CONFIG_BODY = `["{{ additional_context["${ctx.agentSlug}"].category }}"]`
+const DECISION_OUTPUT_SCHEMA = '{"type":"array","items":{"type":"string"}}'
+
+const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook Contact Us Triage Workflow ${runSuffix}`,
+  description: 'Triages contact-us submissions into appointment_request/job_inquiry/flag_spam via an LLM agent; one SMS action per bucket.',
+  dataset_type: 'generic_table',
+  generic_table_id: genericTableId,
+  skip_mdm_resolution: true,
+  status: 'live',
+  filter_config: {
+    type: 'custom',
+    body: 'true',
+    output_schema: '{"type":"boolean"}',
+  },
+  decision_config: {
+    type: 'custom',
+    body: DECISION_CONFIG_BODY,
+    output_schema: DECISION_OUTPUT_SCHEMA,
+  },
+  ai_agents: [
+    {
+      ai_agent_id: aiAgentId,
+      position: 0,
+      context_mapping_config: {
+        type: 'custom',
+        body: CONTEXT_MAPPING_BODY,
+        output_schema: '{"type":"object"}',
+      },
+    },
+  ],
+  actions: BUCKETS.map((bucket) => ({
+    decision_key: bucket,
+    action_type: 'sms',
+    tool_id: toolId,
+    position: 0,
+    trigger_template: 'now',
+    idempotency_template: `{{ subject_id }}-{{ action_id }}-${bucket}-{{ "" | uuid }}`,
+    tool_call: {
+      tool_call_type: 'sms_request',
+      to: { type: 'custom', body: '+15551234567' },
+      body: {
+        type: 'custom',
+        body: `Triage [${bucket}]: {{ event_dataset.message }}`,
+      },
+      sms_type: 'transactional',
+    },
+  })),
+})
+workflowId = workflowResp.data.id!
+ctx.workflowSlug = workflowResp.data.slug!
+```
+
+## 006 — find the generic table's auto-provisioned default DAC
+
+Creating a generic table provisions two things automatically: an
+identity interoperability contract and a default Data Activation
+Client bound to it (name pattern `<datalake> <gt_name>
+DataActivationClient`, `tool_call: manual_upload`). No data source,
+tool, interop contract, or DAC needs to be created by hand for
+plain row ingestion into the table — the default DAC is found by
+GT-name convention in the DAC listing.
+
+```typescript
+const deadline = Date.now() + 30_000
+let found: { slug?: string | null; name?: string | null } | undefined
+while (Date.now() < deadline && !found) {
+  const { data } = await api.dataActivationClients.list(tenantSlug, datalakeSlug)
+  found = (data.data ?? []).find((d) => (d.name ?? '').includes(ctx.gtName))
+  if (!found) await new Promise((r) => setTimeout(r, 1_000))
+}
+if (!found?.slug) {
+  throw new Error(`no default DAC found for GT ${ctx.gtName} within 30s`)
+}
+ctx.dacSlug = found.slug
+```
+
+## 007 — ingest three contact-us submissions through the default DAC
+
+Three rows, ingested as inline JSON through the default DAC. Each
+carries a deliberately distinct `message` — a clear appointment
+request, an unmistakable job inquiry, and obvious promotional spam
+— so the agent has something unambiguous to classify. The
+`category` column is left unset on ingest; it is the agent's job
+to assign one. Each ingest call returns its own batch id; all
+three are pinned for the run scope in §009.
+
+```typescript
+const submissionRows = [
+  {
+    submission_id: `SUB-APPT-${runSuffix}`,
+    name: 'Maria Garcia',
+    email: `maria-${runSuffix}@example.com`,
+    message:
+      'I would like to schedule an appointment with Dr. Johnson next week if possible.',
+  },
+  {
+    submission_id: `SUB-JOB-${runSuffix}`,
+    name: 'James Wilson',
+    email: `james-${runSuffix}@example.com`,
+    message:
+      'I am a registered nurse looking for employment opportunities at your clinic.',
+  },
+  {
+    submission_id: `SUB-SPAM-${runSuffix}`,
+    name: 'BestDeals2026',
+    email: `promo-${runSuffix}@cheapmeds.xyz`,
+    message:
+      'HUGE DISCOUNT on cheap medications and miracle cures! CLICK HERE NOW for 90% off!',
+  },
+]
+
+const ingestResults = await Promise.all(
+  submissionRows.map((row) =>
+    api.dataActivationClients.ingest(tenantSlug, datalakeSlug, ctx.dacSlug, { data: row }),
+  ),
+)
+ctx.submissionBatchIds = ingestResults.map((r) => r.data.batch_id!)
+if (ctx.submissionBatchIds.length !== 3) {
+  throw new Error(`expected 3 ingest batch ids, got ${ctx.submissionBatchIds.length}`)
+}
+```
+
+## 008 — wait for the three ingest batches to reach steady-state
+
+Ingestion is async — the DAC enqueues per-row jobs that drain into
+the generic table. Poll the DAC's activation logs until every
+batch shows a row with `dataset_updated >= 1` (the submission row
+was upserted into the table).
+
+```typescript
+const targetBatches = new Set<string>(ctx.submissionBatchIds)
+const deadline = Date.now() + 90_000
+let greenCount = 0
+while (Date.now() < deadline) {
+  const { data } = await api.dataActivationClients.logs.list(tenantSlug, datalakeSlug, ctx.dacSlug)
+  const green = new Set<string>()
+  for (const row of (data.data ?? []) as Array<Record<string, unknown>>) {
+    const b = row.batch_id
+    if (typeof b !== 'string' || !targetBatches.has(b)) continue
+    if (typeof row.dataset_updated !== 'number' || row.dataset_updated < 1) continue
+    green.add(b)
+  }
+  greenCount = green.size
+  if (greenCount === targetBatches.size) break
+  await new Promise((r) => setTimeout(r, 1_000))
+}
+if (greenCount !== targetBatches.size) {
+  throw new Error(`only ${greenCount}/3 submission batches reached steady-state within 90s`)
+}
+```
+
+## 009 — run the workflow against the three submissions
+
+`workflows.run` triggers the full agent-driven pipeline per row:
+filter → agent enrichment (the Ollama call that classifies the
+message) → decision (the category interpolated into the decision
+array) → action fan-out. The SQL where-clause scopes the run to
+exactly the three submission ids §007 ingested (`submission_id` is
+the generic table's unique column, so it pins the run directly).
+
+The Triage actions use `trigger_template: 'now'`, so they dispatch
+immediately and the run reaches a terminal status — poll
+`batchLogs.refresh` until it leaves `:pending`. The window is
+generous because each row's enrichment is a live LLM inference
+call.
+
+```typescript
+const submissionIds = [
+  `SUB-APPT-${runSuffix}`,
+  `SUB-JOB-${runSuffix}`,
+  `SUB-SPAM-${runSuffix}`,
+]
+const idList = submissionIds.map((id) => `'${id}'`).join(', ')
+
+const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
+  sql_where_clause: `submission_id IN (${idList})`,
+  mode: 'live',
+  manual_override: true,
+})
+ctx.runLogId = runResp.data.workflow_run_log_id!
+ctx.runBatchId = runResp.data.batch_id!
+
+const deadline = Date.now() + 240_000
+let status: string | null = null
+while (Date.now() < deadline) {
+  const { data: log } = await api.workflows.batchLogs.refresh(tenantSlug, datalakeSlug, ctx.workflowSlug, ctx.runLogId)
+  status = log.status ?? null
+  if (status && status !== 'pending') break
+  await new Promise((r) => setTimeout(r, 2_000))
+}
+if (status === 'failed') {
+  throw new Error('agent-driven workflow run reached :failed')
+}
+if (!status || status === 'pending') {
+  throw new Error('workflow run did not leave :pending within 240s')
+}
+```
+
+## 010 — verify the agent's category steered the fan-out
+
+Each submission produced a Workflow Execution Log. Every WEL has
+exactly **three** action execution logs — one per bucket — and
+exactly **one** is matched (`:pending` or `:completed`, the
+category the agent emitted) while the other **two** are
+`:skipped`. A run where a WEL had two matched actions, or zero,
+would mean the agent's output did not actually steer the decision;
+this step fails loudly in that case.
+
+```typescript
+const { data: wfLogs } = await api.workflows.workflowLogs.list(tenantSlug, datalakeSlug, ctx.workflowSlug)
+const ourWels = (wfLogs.data ?? []).filter(
+  (w) => (w as { batch_id?: string }).batch_id === ctx.runBatchId,
+)
+if (ourWels.length !== 3) {
+  throw new Error(`expected 3 WELs for the run, got ${ourWels.length}`)
+}
+
+for (const wel of ourWels) {
+  const welId = (wel as { id?: string }).id
+  const aels =
+    (wel as { action_execution_logs?: Array<{ status?: string; decision_key?: string }> })
+      .action_execution_logs ?? []
+  if (aels.length !== 3) {
+    throw new Error(`WEL ${welId}: expected 3 AELs (one per bucket), got ${aels.length}`)
+  }
+  const byStatus: Record<string, number> = {}
+  for (const ael of aels) {
+    const st = ael.status ?? 'unknown'
+    byStatus[st] = (byStatus[st] ?? 0) + 1
+  }
+  const matched = (byStatus.pending ?? 0) + (byStatus.completed ?? 0)
+  if (matched !== 1) {
+    throw new Error(`WEL ${welId}: expected exactly 1 matched AEL, got ${matched} — ${JSON.stringify(byStatus)}`)
+  }
+  if ((byStatus.skipped ?? 0) !== 2) {
+    throw new Error(`WEL ${welId}: expected 2 :skipped AELs — ${JSON.stringify(byStatus)}`)
+  }
+  const routed = aels.find((a) => a.status === 'pending' || a.status === 'completed')
+  if (!routed?.decision_key || !/^(appointment_request|job_inquiry|flag_spam)$/.test(routed.decision_key)) {
+    throw new Error(`WEL ${welId}: matched AEL has unexpected decision_key ${routed?.decision_key}`)
+  }
+}
+```
+
+# Branches
+
+- **The filter is permissive** — `filter_config.body: 'true'`
+  passes every row, so all three submissions reach the agent. The
+  interesting routing happens at the decision step, not the
+  filter. A production triage workflow might gate on a
+  not-yet-handled flag in the filter; that polarity is covered by
+  the `appointment-review-sms-workflow` cookbook.
+- **Agent emits an out-of-enum category** — the LLM response
+  schema's `enum` constraint guards the decision interpolation. If
+  the model returned an unexpected string the workflow row's
+  execution log would land `:failed`. The anchor vitest treats
+  that as a model-quality failure rather than a platform bug;
+  production deployments either tighten the prompt or add a
+  default SMS action as a fallback bucket.
+- **Transport failure on the LLM call** — the anchor vitest's §8
+  wires a second LLM tool to a deliberately wrong Ollama URL and
+  asserts the WEL lands `:failed` with `error_code:
+  tool_execution_failed` in its `error.json` artifact. This
+  cookbook walks only the happy path; the failure branch is the
+  anchor test's own coverage.
+
+# Rollback
+
+The cookbook doctest harness does not currently tear down created
+resources. The `_setup/healthcare.md` setup file's runSuffix-scoped
+tenant / datalake / user names mean each run is naturally isolated;
+the seeded local DB is cheap to reset (`mix ecto.reset` on the
+platform repo).
+
+# Outcome
+
+After this cookbook's ten steps run green:
+
+- A healthcare tenant exists with a healthcare-domain datalake
+- A Contact Us Generic Table, an SMS tool, a chat-completion LLM
+  tool, a Contact Us Triage AI agent (gemma3:1b, three-category
+  response schema), and a Contact Us Triage agent-driven workflow
+  are all registered
+- Three contact-us submissions have been ingested through the
+  table's auto-provisioned default DAC
+- Running the workflow drove each row through the agent: the LLM
+  classified the message, the decision interpolated the category,
+  and the matching bucket's SMS action fired
+- The routing is verified row-by-row — every Workflow Execution
+  Log carries exactly one matched action and two `:skipped`,
+  proving the agent's output actually steered the fan-out
+
+The business outcome — inbound contact-us messages triaged by an
+LLM and routed to bucket-specific outreach — is demonstrated
+end-to-end, not merely provisioned.
+
+# See also
+
+- `_setup/healthcare.md` — the inlined bootstrap that provisions
+  the tenant + datalake this cookbook starts from
+- `appointment-review-sms-workflow.md` — the static-decision
+  counterpart in healthcare; same SMS wiring, full data-activation
+  chain, no agent
+- `score-leads-with-llm-categorization.md` — the foundation
+  agent-driven cookbook; identical agent + generic-table shape,
+  four bands instead of three buckets
+- `.agent/tools.md` — SMS and chat-completion tool body shapes;
+  intent classification
+- `.agent/ai_agents.md` — AI agent registration shape; input +
+  response schemas; prompt config
+- `.agent/workflows.md` — standard and agent-driven workflow
+  primitives; `ai_agents`, `context_mapping_config`, and
+  agent-output decision interpolation
+- `.agent/generic_tables.md` — generic-table creation and the
+  auto-provisioned identity contract + default DAC
+- `integration-tests/tests/healthcare/agent-driven-workflow.test.ts` —
+  the anchor green test (positive branch §1, §3, §4, §6, §7) these
+  snippets are lifted from
+- `integration-tests/tests/healthcare/generic-tables.test.ts`,
+  `tools.test.ts` — the per-resource create snippets are lifted
+  from