@alvera-ai/platform-sdk 0.10.0-rc.8 → 0.11.0

package/.agent/cookbook/action-status-updaters.md

@@ -0,0 +1,212 @@
+---
+title: "Capability: reconcile delivery status of the messages you send"
+summary: A capability walk for action status updaters. Register a poller tool that reads a delivery-log source (here CloudWatch via LocalStack) and an action status updater that runs on a cron, maps log events back to the messages that produced them, and updates their status (`api.actionStatusUpdaters.create`). So a "sent" SMS becomes "delivered" / "failed" without you polling by hand.
+industry: accounts_receivable
+slug: action-status-updaters
+vitest_source:
+  - integration-tests/tests/accounts_receivable/action-status-updaters.test.ts
+  - integration-tests/tests/accounts_receivable/bootstrap.test.ts
+status: green
+---
+
+# Capability
+
+**What you get:** the messages you send (SMS, etc.) get their real delivery
+outcome written back automatically — "sent" becomes "delivered" or "failed" —
+on a schedule, with no manual polling.
+
+An **action status updater (ASU)** is a scheduled reconciler:
+
+- a **poller tool** reads a delivery-log source (CloudWatch log group here;
+  LocalStack stands in locally),
+- the ASU runs on a `cron_expression`,
+- its `message_config` Liquid maps each log event back to the message it came
+  from (by `external_id`) and the new `status`,
+- `sender_tool_ids` scopes it to the messages a given sender tool produced.
+
+This is **global** — the same shape reconciles any sender's delivery status. See
+`action_status_updaters.md` for the wire reference and `tools.md` for the
+poller-tool body.
+
+# Walkthrough
+
+The `_setup/accounts_receivable.md` bootstrap left `api`, `tenantSlug`,
+`datalakeSlug`, and `ctx.datalakeId` populated.
+
+## 001 — register a data source for the tools
+
+Tools attach to a data source — the origin registration. Create one for the SMS
+gateway / log source.
+
+```typescript
+const { data: ds } = await api.dataSources.create(tenantSlug, datalakeSlug, {
+  name: `ASU Source ${runSuffix}`,
+  uri: 'sns.local',
+  description: 'SNS / CloudWatch origin for the dunning-SMS delivery reconciler.',
+  status: 'active',
+  is_default: false,
+})
+dataSourceId = ds.id!
+```
+
+## 002 — create the SMS sender tool
+
+The ASU reconciles the delivery status of messages a sender tool produced. Create
+an SNS-backed SMS tool (pointed at LocalStack locally) to be that sender.
+
+```typescript
+const { data: smsTool } = await api.tools.create(tenantSlug, datalakeSlug, {
+  name: `ASU SMS Sender ${runSuffix}`,
+  description: 'SNS-backed SMS sender whose delivery status the ASU reconciles.',
+  intent: 'sms',
+  status: 'active',
+  datalake_id: ctx.datalakeId,
+  data_source_id: dataSourceId,
+  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',
+  },
+})
+ctx.smsToolId = smsTool.id!
+```
+
+## 003 — create the CloudWatch poller tool
+
+The poller tool supplies the credentials + region for reading the delivery log
+group. `intent: 'status_poller'` tags it as a reconciler source (not a sender),
+and `tool_body_type: 'cloud_watch_log_group'` selects the CloudWatch reader.
+
+```typescript
+const { data: cwTool } = await api.tools.create(tenantSlug, datalakeSlug, {
+  name: `ASU CloudWatch Poller ${runSuffix}`,
+  description: 'CloudWatch log-group poller — reads SNS delivery events for reconciliation.',
+  intent: 'status_poller',
+  status: 'active',
+  datalake_id: ctx.datalakeId,
+  data_source_id: dataSourceId,
+  body: {
+    tool_body_type: 'cloud_watch_log_group',
+    auth_method: 'access_key',
+    region: 'us-east-1',
+    endpoint_url: 'http://localhost:4566',
+    access_key_id: 'test',
+    secret_access_key: 'test',
+  },
+})
+ctx.cwToolId = cwTool.id!
+```
+
+## 004 — create the action status updater
+
+The ASU ties it together: a `cron_expression` schedule, the `updater_tool_id`
+(the poller), the `sender_tool_ids` it reconciles for, and an `updater_body`
+naming the log group + the time window (Liquid `now` filters). The
+`message_config` Liquid loops the fetched `events` and emits, per event, the
+`external_id` of the message to update and the `set_params` (the new `status`).
+
+```typescript
+const { data: asu } = await api.actionStatusUpdaters.create(tenantSlug, datalakeSlug, {
+  name: `Dunning SMS Delivery Updater ${runSuffix}`,
+  cron_expression: '*/30 * * * *',
+  updater_type: 'cloud_watch',
+  updater_tool_id: ctx.cwToolId,
+  sender_tool_ids: [ctx.smsToolId],
+  datalake_id: ctx.datalakeId,
+  updater_body: {
+    updater_body_type: 'cloud_watch_request',
+    log_group_name: 'sns/us-east-1/000000000000/DirectPublishToPhoneNumber',
+    start_time: '{{ now | minutes_ago: 45 }}',
+    end_time: '{{ now }}',
+  },
+  message_config: {
+    type: 'custom',
+    body: '{% for event in events %}{"external_id": "{{ event.message_id }}", "set_params": {"status": "{{ event.status }}"}}{% endfor %}',
+  },
+})
+actionStatusUpdaterId = asu.id!
+```
+
+## 005 — verify it persisted (read-back + checksum parity)
+
+`get` returns the stored row; its fields echo what you sent. `checksum` recomputes
+the fingerprint from the same body without persisting — it must equal the stored
+row's `checksum`, which is how drift is detected.
+
+```typescript
+const { data: row } = await api.actionStatusUpdaters.get(tenantSlug, datalakeSlug, actionStatusUpdaterId)
+if (row.cron_expression !== '*/30 * * * *') {
+  throw new Error(`cron mismatch on read-back: ${row.cron_expression}`)
+}
+
+const { data: ck } = await api.actionStatusUpdaters.checksum(tenantSlug, datalakeSlug, {
+  name: row.name,
+  cron_expression: row.cron_expression,
+  updater_type: 'cloud_watch',
+  updater_tool_id: ctx.cwToolId,
+  sender_tool_ids: [ctx.smsToolId],
+  datalake_id: ctx.datalakeId,
+  updater_body: {
+    updater_body_type: 'cloud_watch_request',
+    log_group_name: 'sns/us-east-1/000000000000/DirectPublishToPhoneNumber',
+    start_time: '{{ now | minutes_ago: 45 }}',
+    end_time: '{{ now }}',
+  },
+  message_config: {
+    type: 'custom',
+    body: '{% for event in events %}{"external_id": "{{ event.message_id }}", "set_params": {"status": "{{ event.status }}"}}{% endfor %}',
+  },
+})
+if (typeof ck.checksum !== 'string' || ck.checksum.length === 0) {
+  throw new Error('expected a checksum for the ASU body')
+}
+```
+
+## 006 — discover it (list + metadata)
+
+The ASU shows up in the paginated list, and `metadata` / `metadataDetails`
+return the markdown catalog an agent reads to understand what reconcilers exist.
+
+```typescript
+const { data: list } = await api.actionStatusUpdaters.list(tenantSlug, datalakeSlug)
+if (!(list.data ?? []).some((u) => u.id === actionStatusUpdaterId)) {
+  throw new Error('created ASU not found in the list')
+}
+
+const { data: catalog } = await api.actionStatusUpdaters.metadata(tenantSlug, datalakeSlug)
+if (typeof catalog !== 'string' || catalog.length === 0) {
+  throw new Error('expected a non-empty ASU metadata catalog')
+}
+
+const { data: detail } = await api.actionStatusUpdaters.metadataDetails(tenantSlug, datalakeSlug, actionStatusUpdaterId)
+if (typeof detail !== 'string' || detail.length === 0) {
+  throw new Error('expected non-empty ASU metadata details')
+}
+```
+
+# Gotchas
+
+- **The poller tool's intent is `status_poller`, not the sender's intent.** The
+  reconciler reads logs; it doesn't send. `sender_tool_ids` is the separate list
+  of sender tools whose messages it updates.
+- **`message_config` maps events back to messages by `external_id`.** The Liquid
+  emits, per fetched event, the `external_id` of the message to touch and the
+  `set_params` to apply. Get the `external_id` field name wrong and nothing
+  updates.
+- **The schedule is a cron, evaluated platform-side.** Creating the ASU registers
+  the schedule; you don't trigger it. The `updater_body` time window
+  (`{{ now | minutes_ago: 45 }}` … `{{ now }}`) bounds each run's log query.
+- **`checksum` parity is your drift signal.** The fingerprint of the desired body
+  must match the stored row's; a mismatch means the resource drifted.
+
+# See also
+
+- `action_status_updaters.md` — wire shape, `updater_body` variants, `message_config`
+- `tools.md` — `sns` sender body + `cloud_watch_log_group` poller body
+- `_setup/accounts_receivable.md` — the bootstrap this walk starts from
+- `integration-tests/tests/accounts_receivable/action-status-updaters.test.ts` —
+  the green test these calls are lifted from

package/.agent/cookbook/ai-agent-invoke.md

@@ -0,0 +1,243 @@
+---
+title: "Capability: read an uploaded document and pull structured fields out of it"
+summary: A capability walk for direct AI-agent invocation with file vision. Upload a PDF + image, register an LLM-enrichment tool (the provider adapter) and an AI agent constrained to an output schema, then invoke the agent with the files (`api.aiAgents.invoke`) to get structured JSON back. This is the correct path for reading an uploaded file — the file is uploaded to storage and the agent reads it; the agent does NOT ingest the file as a dataset row.
+industry: healthcare
+slug: ai-agent-invoke
+vitest_source:
+  - integration-tests/tests/healthcare/ai-agent-invoke.test.ts
+  - integration-tests/tests/healthcare/bootstrap.test.ts
+status: green
+---
+
+# Capability
+
+**What you get:** structured JSON pulled out of an uploaded document or image —
+a scanned form, a PDF, an ID — by an AI agent, in one call.
+
+The shape:
+
+1. **Upload** the file(s) to storage (`datalakes.createUploadLink` + a raw PUT)
+   and keep the returned `key`s.
+2. Register an **LLM-enrichment tool** — the provider adapter. Its `base_body`
+   authors the provider's multimodal request and its `response_extractor` maps
+   the provider's envelope back to a canonical `{ output_json, … }`.
+3. Register an **AI agent** that points at the tool, constrained by an
+   `llm_response_schema` (the JSON shape you want back) and an `input_schema`.
+4. `aiAgents.invoke(..., { input, files: [{ key, content_type }] })` → the
+   parsed JSON, an explanation, and token usage.
+
+> **File-ingestion note (read this).** This is how you make an agent *read* a
+> file. It is **not** how you turn a file into dataset rows — that is bulk
+> ingestion (`dataActivationClients.ingestFile`; see `bulk-ingest.md`). An AI
+> agent does **enrichment / extraction** on content handed to it; it does not
+> ingest files. When a contract needs per-row vision enrichment during
+> ingestion, nest the agent on the contract (`interoperability_contracts.md`
+> §6) — the row references the uploaded file's key and the agent reads it as
+> enrichment. The file→row step is always the DAC, never the agent.
+
+This is **global** to every datalake. See `ai_agents.md` for the agent
+reference. The walk uses a WireMock-stubbed provider so it runs deterministically
+on the mock stack; swap the tool's `base_url` + adapter for a real provider
+unchanged.
+
+# Walkthrough
+
+The `_setup/healthcare.md` bootstrap left `api`, `tenantSlug`, `datalakeSlug`,
+and `ctx.datalakeId` populated.
+
+## 001 — upload the document and image
+
+Mint a presigned URL per file and PUT the bytes with a **raw `fetch`** (the
+upload goes to object storage, not through the SDK). Keep each returned `key` —
+that is how you hand the file to the agent. The fixtures are a 2-page PDF and a
+document image.
+
+```typescript
+const { readFileSync } = await import('node:fs')
+const { join } = await import('node:path')
+
+async function uploadFixture(filename: string, contentType: string): Promise<string> {
+  const bytes = readFileSync(join(process.env.COOKBOOK_FIXTURES_DIR!, 'healthcare', filename))
+  const { data: link } = await api.datalakes.createUploadLink(tenantSlug, datalakeSlug, {
+    filename,
+    content_type: contentType,
+  })
+  const put = await fetch(link.url!, { method: 'PUT', headers: { 'Content-Type': contentType }, body: bytes })
+  if (put.status !== 200) throw new Error(`upload of ${filename} failed: ${put.status}`)
+  return link.key!
+}
+
+ctx.pdfKey = await uploadFixture('sample_two_page.pdf', 'application/pdf')
+ctx.imageKey = await uploadFixture('memorandum-of-association-01.png', 'image/png')
+```
+
+## 002 — register the LLM-enrichment tool (the provider adapter)
+
+The tool is the complete provider adapter. `base_body` authors the provider's
+multimodal request (here the OpenAI chat-completions shape, with the agent's
+`llm_response_schema` injected as `{{ schema }}` and uploaded images appended as
+`image_url` parts). `response_extractor` reads the provider's envelope back into
+the canonical `{ output_json, explanation, …_tokens }`; its `output_schema` is
+required for an `llm_enrichment` tool.
+
+```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 OPENAI_BASE_BODY =
+  '{"model": "{{ model }}", "messages": [{"role": "user", "content": [{"type": "text", "text": "{{ rendered_prompt | json_escape }}"}{% for img in images %}, {"type": "image_url", "image_url": {"url": "data:{{ img.content_type }};base64,{{ img.data }}"}}{% endfor %}]}], "response_format": {"type": "json_schema", "json_schema": {"name": "output", "strict": true, "schema": {{ schema | to_json }}}}}'
+
+const OPENAI_EXTRACTOR =
+  '{"output_json": "{{ msg.choices[0].message.content | json_escape }}", "explanation": "{{ msg.choices[0].message.reasoning_content | json_escape }}", "input_tokens": {{ msg.usage.prompt_tokens | default: 0 }}, "output_tokens": {{ msg.usage.completion_tokens | default: 0 }}, "total_tokens": {{ msg.usage.total_tokens | default: 0 }}}'
+
+const { data: tool } = await api.tools.create(tenantSlug, datalakeSlug, {
+  name: `Legal-Entity Extraction Tool ${runSuffix}`,
+  description: 'Multimodal LLM-enrichment adapter for legal_entity extraction.',
+  intent: 'llm_enrichment',
+  status: 'active',
+  datalake_id: ctx.datalakeId,
+  response_extractor: { type: 'custom', body: OPENAI_EXTRACTOR, output_schema: ENRICHMENT_OUTPUT_SCHEMA },
+  body: {
+    tool_body_type: 'rest_api',
+    base_url: 'http://localhost:8080/openai',
+    base_path: { type: 'custom', body: '/v1/chat/completions' },
+    auth_method: 'api_key',
+    api_key: 'stub-key',
+    api_key_name: 'Authorization',
+    api_key_location: 'header',
+    request_type: 'json',
+    response_type: 'json',
+    timeout_ms: 300_000,
+    base_body: { type: 'custom', body: OPENAI_BASE_BODY },
+  },
+})
+toolId = tool.id!
+```
+
+## 003 — register the extraction agent
+
+The agent points at the tool and is constrained by two schemas: `input_schema`
+(what `invoke` must pass — here `instructions`) and `llm_response_schema` (the
+shape the model must return — load-bearing, the platform constrains the model to
+it). `data_access: 'unregulated'` is the compliance gate for what the agent may
+read.
+
+```typescript
+const LEGAL_ENTITY_RESPONSE_SCHEMA = {
+  type: 'object',
+  properties: {
+    company_name: { type: 'string', nullable: true, maxLength: 200 },
+    registered_address: { type: 'string', nullable: true, maxLength: 300 },
+    date_of_formation: { type: 'string', nullable: true, maxLength: 40 },
+    capital_amount: { type: 'number', nullable: true },
+    capital_currency: { type: 'string', nullable: true, maxLength: 20 },
+  },
+  required: ['company_name'],
+  additionalProperties: false,
+}
+
+const { data: agent } = await api.aiAgents.create(tenantSlug, datalakeSlug, {
+  name: `Legal Entity Extraction Agent ${runSuffix}`,
+  description: 'Extracts legal_entity-shaped fields from corporate documents.',
+  tool_id: toolId,
+  model: 'gpt-4o',
+  data_access: 'unregulated',
+  temperature: 0.0,
+  max_tokens: 8_192,
+  enabled: true,
+  input_schema: { type: 'object', properties: { instructions: { type: 'string' } }, required: ['instructions'] },
+  llm_response_schema: LEGAL_ENTITY_RESPONSE_SCHEMA,
+  prompt_config: {
+    type: 'custom',
+    body: 'You are a legal-entity data extraction specialist.\nExtract structured corporate information from the provided content and return a JSON object aligned to the legal_entity schema.\n\n{{ instructions }}',
+  },
+})
+aiAgentId = agent.id!
+```
+
+## 004 — invoke the agent with the files
+
+`invoke` runs the agent against the uploaded files: `input` satisfies the
+`input_schema`, and `files` lists the storage keys + content types to attach. The
+result is the parsed JSON (`output`, matching `llm_response_schema`), an
+`explanation`, and token `usage`.
+
+```typescript
+const { data: result } = await api.aiAgents.invoke(tenantSlug, datalakeSlug, aiAgentId, {
+  input: { instructions: 'Extract the company name and any visible registration details from the attached documents.' },
+  files: [
+    { key: ctx.pdfKey, content_type: 'application/pdf' },
+    { key: ctx.imageKey, content_type: 'image/png' },
+  ],
+})
+
+if (!result.output || typeof result.output !== 'object') {
+  throw new Error('invoke did not return a structured output object')
+}
+if (!(result.output as Record<string, unknown>).company_name) {
+  throw new Error('expected a company_name in the extracted output')
+}
+if (!result.usage || (result.usage as { input_tokens?: number }).input_tokens === undefined) {
+  throw new Error('expected token usage on the invoke result')
+}
+```
+
+## 005 — a malformed input is rejected
+
+`invoke` validates `input` against the agent's `input_schema` before calling the
+model. Omitting the required `instructions` returns a 422 — caught here so the
+walk proves the gate without aborting.
+
+```typescript
+let rejected = false
+try {
+  await api.aiAgents.invoke(tenantSlug, datalakeSlug, aiAgentId, {
+    input: { wrong_field: 'no instructions here' },
+    files: [],
+  })
+} catch (err) {
+  const status = (err as { _httpStatus?: number })._httpStatus
+  if (status !== 422) throw err
+  rejected = true
+}
+if (!rejected) {
+  throw new Error('expected a 422 for input that violates the agent input_schema')
+}
+```
+
+# Gotchas
+
+- **Uploading a file is not ingesting it.** The upload + `invoke` here makes the
+  agent *read* the file. To turn a file into dataset rows, use
+  `dataActivationClients.ingestFile` (`bulk-ingest.md`). Don't reach for an agent
+  to "ingest" a document — agents enrich, the DAC ingests.
+- **`llm_response_schema` is load-bearing.** It is what constrains the model's
+  output; the tool's `response_extractor.output_schema` is required too (a
+  missing one is a 422 at `/response_extractor/output_schema`).
+- **The model lives on the agent, not the tool.** The tool is the provider
+  adapter (URL + request/response shape); the agent sets the `model`. Swapping
+  providers means a new tool adapter + the agent's `model`.
+- **The file PUT is raw HTTP.** `createUploadLink` is an SDK call; the upload is a
+  plain `fetch` PUT to the presigned URL, exactly like bulk ingest.
+- **`data_access` gates what the agent may read.** `unregulated` here; a stricter
+  setting changes what content the agent is allowed to see.
+
+# See also
+
+- `ai_agents.md` — agent wire shape, `input_schema` / `llm_response_schema`, invoke
+- `interoperability_contracts.md` §6 — nesting an agent on a contract for per-row
+  enrichment during ingestion (the file→row path stays the DAC's)
+- `bulk-ingest.md` — the correct path for turning a file into dataset rows
+- `_setup/healthcare.md` — the bootstrap this walk starts from
+- `_fixtures/healthcare/` — the vendored PDF + image
+- `integration-tests/tests/healthcare/ai-agent-invoke.test.ts` — the green test
+  these calls are lifted from