@alvera-ai/platform-sdk 0.17.0 → 0.18.0

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

@@ -1,663 +0,0 @@
----
-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. It is a **provider adapter**: `base_body` authors
-the provider's request — here Ollama's native `/api/chat` shape with
-`think: false` and a `format` schema so the model returns clean,
-schema-constrained JSON — and `response_extractor` maps the provider's
-envelope back to the canonical `{ output_json, … }` the platform reads.
-The extractor's `output_schema` is required for an `llm_enrichment`
-tool. The `api_key`/`auth_method` pair satisfies the REST tool's schema
-even though Ollama ignores the header.
-
-```typescript
-const ENRICHMENT_OUTPUT_SCHEMA = {
-  type: 'object',
-  properties: {
-    output_json: {},
-    input_tokens: { type: ['integer', 'null'] },
-    output_tokens: { type: ['integer', 'null'] },
-    total_tokens: { type: ['integer', 'null'] },
-    explanation: { type: ['string', 'null'] },
-  },
-  required: ['output_json'],
-}
-
-const OLLAMA_BASE_BODY =
-  '{"model": "{{ model }}", "messages": [{"role": "user", "content": "{{ rendered_prompt | json_escape }}", "images": [{% for img in images %}{% unless forloop.first %}, {% endunless %}"{{ img.data }}"{% endfor %}]}], "stream": false, "think": false, "options": {"temperature": 0, "num_ctx": 40960}, "format": {{ schema | to_json }}}'
-
-const OLLAMA_EXTRACTOR =
-  '{"output_json": "{{ msg.message.content | json_escape }}", "explanation": "{{ msg.message.thinking | json_escape }}", "input_tokens": {{ msg.prompt_eval_count | default: 0 }}, "output_tokens": {{ msg.eval_count | default: 0 }}, "total_tokens": {{ msg.prompt_eval_count | default: 0 | plus: msg.eval_count }}}'
-
-const llmToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook LLM Tool ${runSuffix}`,
-  description: 'Ollama-backed chat-completion adapter for Contact Us triage classification.',
-  intent: 'llm_enrichment',
-  status: 'active',
-  datalake_id: ctx.datalakeId,
-  response_extractor: { type: 'custom', body: OLLAMA_EXTRACTOR, output_schema: ENRICHMENT_OUTPUT_SCHEMA },
-  body: {
-    tool_body_type: 'rest_api',
-    base_url: 'http://localhost:11434',
-    base_path: { type: 'custom', body: '/api/chat' },
-    auth_method: 'api_key',
-    api_key: 'stub-key',
-    api_key_name: 'Authorization',
-    api_key_location: 'header',
-    request_type: 'json',
-    response_type: 'json',
-    timeout_ms: 60_000,
-    base_body: { type: 'custom', body: OLLAMA_BASE_BODY },
-  },
-})
-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: 'qwen3-vl:8b-instruct',
-  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
-Triage agent is **nested** in the workflow create body (the
-`workflow_ai_agents` array — a `cast_assoc`, not a separate attach
-call), binding it 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',
-  tags: ['support', 'triage'],
-  filter_config: {
-    type: 'custom',
-    body: 'true',
-    output_schema: { type: 'boolean' },
-  },
-  decision_config: {
-    type: 'custom',
-    body: DECISION_CONFIG_BODY,
-    output_schema: DECISION_OUTPUT_SCHEMA,
-  },
-  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}`,
-    tool_call: {
-      tool_call_type: 'sms_request',
-      to: { type: 'custom', body: '+15551234567' },
-      body: {
-        type: 'custom',
-        body: `Triage [${bucket}]: {{ event_dataset.message }}`,
-      },
-      sms_type: 'transactional',
-    },
-  })),
-  // Nest the triage agent inline. Workflow joins omit output_schema —
-  // the server pins it from the agent's input_schema.
-  workflow_ai_agents: [
-    {
-      ai_agent_id: aiAgentId,
-      position: 0,
-      context_mapping_config: { type: 'custom', body: CONTEXT_MAPPING_BODY },
-    },
-  ],
-})
-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,
-})
-// run-workflow only SCHEDULES the run. The log id and batch id are
-// written when it fires, so read them back via workflowRuns.get.
-const fired = await ctx.waitForFiredRun(datalakeSlug, runResp.data.workflow_run_id)
-ctx.runLogId = fired.workflowRunLogId
-ctx.runBatchId = fired.batchId!
-
-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}`)
-  }
-}
-```
-
-## 011 — write the integration test
-
-End the build with a test you keep: re-read the workflow and prove the
-pipeline still executes — without a side effect. `mode: 'dry_run'` with a
-never-matching selection runs the FULL pipeline (selection → filter →
-decision) and intercepts only the final action call, so no message
-leaves, yet the acknowledgement proves the workflow is runnable. This
-block runs live under `make validate-cookbook`.
-
-```typescript
-// Re-GET — the workflow must still be live, or nothing will run.
-const { data: wfRow } = await api.workflows.get(tenantSlug, datalakeSlug, workflowId)
-if (wfRow.status !== 'live') {
-  throw new Error(`workflow regressed from live: ${wfRow.status}`)
-}
-// Behavioural probe — a dry run against a selection no row can match:
-// the pipeline executes end-to-end, the final action call is
-// intercepted, and the acknowledgement carries the scheduled run id. The
-// clause speaks this workflow's selection dialect: a GENERIC-TABLE
-// dataset is addressed by its own columns (no `ra.` dataset alias —
-// that alias exists only for system-dataset selections).
-const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
-  sql_where_clause: "submission_id = 'test-never-matching-submission'",
-  mode: 'dry_run',
-  manual_override: false,
-})
-// The run-log id does not exist until the run fires — wait, do not read a null.
-const probeFired = await ctx.waitForFiredRun(datalakeSlug, probeRun.workflow_run_id)
-if (probeFired.workflowRunLogId.length === 0) {
-  throw new Error('dry-run probe never produced a workflow_run_log_id')
-}
-```
-
-If the probe fails in production, escalate with the run response as
-evidence — don't flip the workflow's status or rewrite its configs to
-chase the error.
-
-# 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 (qwen3-vl:8b-instruct, 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