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

package/.agent/action_status_updaters.md

@@ -0,0 +1,262 @@
+# Action status updaters
+
+An **action status updater** is a scheduled job that polls an
+external system (e.g. a cloud-provider log group, a delivery
+provider's API) for status updates on actions the platform
+previously fired, and writes those updates back onto the
+matching message rows.
+
+The typical use case: a workflow's SMS action fires through a
+provider (a sender tool), and a status updater periodically
+polls the provider's log group to mark each message as
+`delivered` / `failed` / `bounced` on its tracked record.
+
+SDK namespace: `api.actionStatusUpdaters`.
+
+Action status updaters are **Datalake-DB-resident** — the
+parent datalake must be `status: 'ready'` and every
+referenced tool must exist before POST.
+
+## 1. Wire shape
+
+```typescript
+import type {
+  ActionStatusUpdaterRequestWritable,
+  ActionStatusUpdaterResponse,
+} from '@alvera-ai/platform-sdk'
+
+const { data: created } = await api.actionStatusUpdaters.create(
+  tenantSlug,
+  datalakeSlug,
+  {
+    name: 'SMS Delivery Updater',
+    cron_expression: '*/30 * * * *',                  // every 30 minutes
+    updater_type: 'cloud_watch',                      // polling source family
+    updater_tool_id: cloudWatchToolId,                // the tool that issues the poll
+    sender_tool_ids: [smsToolId],                     // tools whose sent messages this updater tracks
+    datalake_id: datalakeId,
+
+    // Polymorphic — discriminator: updater_body_type
+    updater_body: {
+      updater_body_type: 'cloud_watch_request',
+      log_group_name: 'sns/us-east-1/...',
+      start_time: '{{ now | minutes_ago: 45 }}',     // Liquid window
+      end_time:   '{{ now }}',
+    },
+
+    // Liquid template emitting JSON that maps poll events to message updates
+    message_config: {
+      type: 'custom',
+      body:
+        '{% for event in events %}' +
+        '{"external_id": "{{ event.message_id }}", "set_params": {"status": "{{ event.status }}"}}' +
+        '{% endfor %}',
+    },
+  },
+)
+```
+
+## 2. Rules the type cannot encode
+
+### `updater_body` is polymorphic on `updater_body_type`
+
+The body's discriminator selects the polling shape. Each
+variant declares the fields the platform needs to construct
+the poll request:
+
+```
+updater_body_type: 'cloud_watch_request'
+  log_group_name   string — the log group to scan
+  start_time       string — Liquid template producing a timestamp
+  end_time         string — Liquid template producing a timestamp
+```
+
+(See the SDK type for the full set of body types — others
+follow the same `<verb>_request` naming and carry the fields
+their target API requires.)
+
+`start_time` / `end_time` accept Liquid expressions using the
+`now` variable plus relative-time filters (`minutes_ago: N`,
+`hours_ago: N`, ...). A literal ISO 8601 string also works for
+fixed windows.
+
+### `message_config.body` emits a JSON event stream
+
+The template runs against an `events` array — the parsed
+response from the polling tool. Each iteration must render
+one JSON object with two required fields:
+
+```
+external_id  string — the message identifier to update (typically
+                       the provider's id, matching the recipient
+                       record's external_id column)
+set_params   object — fields to update on the matching message row
+                       (e.g. { status, delivered_at, error_code })
+```
+
+The platform parses the rendered output, joins each event to a
+message row by `external_id`, and applies `set_params` as the
+update. Events that don't match any message are silently
+discarded.
+
+### `cron_expression` is a standard 5-field cron string
+
+```
+*/30 * * * *      — every 30 minutes
+0 * * * *         — every hour on the minute
+0 9 * * 1-5       — 9am Mon-Fri
+```
+
+Sub-minute cadences are NOT supported. The minimum interval
+the scheduler honors depends on platform-level configuration;
+default minimum is 5 minutes.
+
+### `updater_type` and `updater_body.updater_body_type` must correspond
+
+The body carries TWO discriminator fields that name the same
+choice from different angles:
+
+```
+   updater_type                  outer field on the request body
+                                  (top-level)
+   updater_body.updater_body_type   inner field on the polymorphic
+                                  body embed
+```
+
+They must agree according to a fixed mapping:
+
+```
+   updater_type: "cloud_watch"   ↔   updater_body_type: "cloud_watch_request"
+   updater_type: "restapi"       ↔   updater_body_type: "restapi_request"
+```
+
+A mismatched pair (e.g. `updater_type: "cloud_watch"` +
+`updater_body_type: "restapi_request"`) returns 422 — typically
+on `/updater_type` with a "type / body type mismatch" message.
+The full mapping is exported by the SDK; the `updater_type` enum
+and the `updater_body_type` enum are kept in lockstep by the
+generated types.
+
+### `updater_tool_id` and `sender_tool_ids` serve different roles
+
+- `updater_tool_id` (single) — the tool the updater uses to
+  ISSUE the poll. Must be a tool whose `intent` is
+  `status_poller` (e.g. a `cloud_watch_log_group` body type).
+- `sender_tool_ids` (array) — the tools whose sent messages
+  this updater is responsible for tracking. The match logic
+  joins each polled event back to a message row that was
+  sent through one of these tools.
+
+A single status updater can track messages from multiple
+sender tools (e.g. an SMS tool plus a voice tool routed
+through the same provider).
+
+## 3. Field ownership
+
+**Server-derived (Response-only).** Universal set from
+`type_naming.md`.
+
+**Caller-supplied (round-trip).**
+
+```
+name                  required string
+cron_expression       required string — standard cron
+updater_type          required enum   — e.g. 'cloud_watch'
+updater_tool_id       required UUID   — the polling tool
+sender_tool_ids       required UUID[] — tools whose messages this updater tracks
+datalake_id           required UUID
+updater_body          required embed  — { updater_body_type, ... }
+message_config        required embed  — { type, body }
+```
+
+**Write-only (Request-only).** None.
+
+## 4. Error envelopes
+
+Standard JSON:API envelopes per `errors.md`. Common rejections:
+
+| `source.pointer`                    | Cause                                              |
+|-------------------------------------|----------------------------------------------------|
+| `/cron_expression`                  | invalid cron syntax or below minimum interval      |
+| `/updater_tool_id`                  | tool's intent isn't `status_poller`                |
+| `/sender_tool_ids/0`                | tool id doesn't exist or wrong datalake            |
+| `/updater_body/updater_body_type`   | enum mismatch                                      |
+| `/updater_type`                     | mismatch with `updater_body.updater_body_type`     |
+| `/message_config/body`              | empty when `type: 'custom'`                        |
+| `/base`                             | `cron_management_failed` — body validated and saved but scheduler registration failed; the row is rolled back |
+
+## 5. Lifecycle
+
+### Create
+
+Synchronous. A successful create registers a scheduled poll
+under the supplied `cron_expression`; the first run fires at
+the next cron slot at-or-after create time.
+
+The cron registration is part of the create transaction — if
+the body validates but scheduler registration fails, the
+platform rolls the row back and returns 422 with
+`cron_management_failed` on `/base` (see §4). Conversely, a
+body that fails structural validation never reaches the
+scheduler; cron-job registration only happens on the success
+branch.
+
+### Read shapes
+
+```
+.list(tenantSlug, datalakeSlug)              Paged: { data, meta }
+.get(tenantSlug, datalakeSlug, idOrSlug)     One row
+.metadata(tenantSlug, datalakeSlug)          Markdown — catalog
+.metadataDetails(tenantSlug, datalakeSlug,   Markdown — one updater
+                  idOrSlug)
+```
+
+### Update
+
+`PUT` replays the full body. The polymorphic `updater_body`
+must keep the same `updater_body_type` on update — changing
+the discriminator requires delete + recreate.
+
+### Delete
+
+`DELETE` removes the row and cancels future scheduled polls.
+In-flight polls complete; their writebacks land normally.
+
+The delete is **graceful** with respect to scheduler state: if
+the row exists but its cron-job entry is somehow missing or
+the scheduler raises during cancellation, the row is still
+deleted and the DELETE returns 204. Consumers do not need to
+check or retry for partial-delete states.
+
+## 6. Gotchas
+
+1. **The polling tool's `intent` must be `status_poller`.**
+   A tool with `intent: 'sms'` or any other non-poller intent
+   is rejected at create time. The poller intent gates the
+   tool's eligibility as an `updater_tool_id`.
+
+2. **`message_config.body` must emit valid JSON.** The
+   template is rendered against the polling tool's parsed
+   response and the output is then JSON-parsed. A render that
+   produces malformed JSON (e.g. trailing comma, unquoted
+   string) makes the entire poll cycle silently no-op for
+   that updater — events stay unprocessed.
+
+3. **`external_id` join is exact-match.** Events whose
+   `external_id` doesn't match a message row are discarded
+   silently. If your provider returns a prefixed id (e.g.
+   `provider-prefix/12345`) but your message rows carry
+   the bare id, transform inside the Liquid template (string
+   filters) so the rendered `external_id` matches.
+
+4. **`set_params` keys must be writable columns on the
+   message row.** Unknown keys are silently dropped during
+   the update. Refer to the message dataset's schema to
+   confirm which columns are writable from updater output.
+
+5. **Cron windows + polling-window overlap.** Choose
+   `start_time` / `end_time` to overlap consecutive cron
+   intervals (e.g. cron every 30 min, window of 45 min) so
+   transient delivery delays don't fall between two polls.
+   The defaults in the wire-shape example illustrate this
+   pattern: 30-minute cron, 45-minute window.

package/.agent/ai_agents.md

@@ -0,0 +1,423 @@
+# AI agents
+
+An **AI agent** is a registered LLM caller — a configured pairing
+of a chat-completion tool, a model identifier, a system prompt
+template, and JSON Schemas declaring the agent's input shape and
+the LLM's required output shape. Workflows attach agents at
+their enrichment stage; the agent's structured output then feeds
+the workflow's decision template.
+
+SDK namespace: `api.aiAgents`.
+
+AI agents are **Datalake-DB-resident** — the parent datalake
+must be `status: 'ready'` and the bound tool must exist before
+POST.
+
+## 1. Wire shape
+
+```typescript
+import type {
+  AiAgentRequestWritable,
+  AiAgentResponse,
+} from '@alvera-ai/platform-sdk'
+
+const { data: created } = await api.aiAgents.create(
+  tenantSlug,
+  datalakeSlug,
+  {
+    name: 'Contact Us Triage Categorizer',
+    description: 'Triages inbound submissions into appointment / job / spam',
+
+    tool_id: chatCompletionToolId,                  // see §2 — must be a tool with intent: 'llm_enrichment'
+
+    model: 'llama3.2:3b',                            // provider-specific model identifier
+    data_access: 'unregulated',                      // 'unregulated' | 'regulated' (compliance gate)
+    temperature: 0.0,
+    max_tokens: 2048,
+    enabled: true,
+
+    input_schema: {                                  // JSON Schema — fields the prompt receives
+      type: 'object',
+      properties: {
+        msg:           { type: 'string' },
+        submission_id: { type: 'string' },
+      },
+      required: ['msg', 'submission_id'],
+    },
+
+    llm_response_schema: {                           // JSON Schema — what the LLM MUST return
+      type: 'object',
+      properties: {
+        category: {
+          type: 'string',
+          enum: ['appointment_request', 'job_inquiry', 'flag_spam'],
+        },
+      },
+      required: ['category'],
+      additionalProperties: false,
+    },
+
+    prompt_config: {
+      type: 'custom',
+      body: `You are a triage assistant. Categorize this submission ...
+
+Submission ID: {{ submission_id }}
+Message: {{ msg }}
+
+Respond with JSON: {"category": "..."}`,
+    },
+  },
+)
+// created.id, created.slug    — server-derived
+// created.name === body.name
+```
+
+## 2. Rules the type cannot encode
+
+### `tool_id` must point to a chat-completion tool
+
+The bound tool's `intent` MUST be `llm_enrichment`. Tools with
+any other intent (`sms`, `data_exchange`, `status_poller`, …)
+are rejected at create time as a 422 on `/tool_id`.
+
+The chat-completion tool is typically a `tool_body_type:
+'rest_api'` configured against an OpenAI-compatible endpoint
+(OpenAI itself, Ollama, vLLM, etc.). The platform appends
+`/chat/completions` to the tool's `base_url`, so:
+
+```
+   tool.base_url = 'http://localhost:11434/v1'
+   →   actual request URL = 'http://localhost:11434/v1/chat/completions'
+```
+
+A tool whose `base_url` already contains `/chat/completions`
+will produce a doubled path and 404.
+
+### `llm_response_schema` is REQUIRED and load-bearing
+
+The schema is mandatory at create time — a body omitting it
+returns a 422 on `/llm_response_schema`. The schema serves two
+roles:
+
+1. **Provider-side decoding constraint**: the platform forwards
+   the schema in the chat-completion request as
+   `response_format: json_schema`, instructing the provider to
+   constrain decoding so the LLM cannot return prose, markdown
+   code fences, or chat preamble around the JSON. Without this
+   constraint, small models often wrap output in fences and the
+   platform's JSON parse step fails with `json_decode_failed`.
+2. **Output binding**: the parsed LLM output is exposed in the
+   workflow's `additional_context` under the agent's slug, with
+   property paths matching the schema (see §3 below).
+
+### Prompt receives Liquid-rendered fields from `input_schema`
+
+The agent's `prompt_config.body` is a Liquid template that
+references the agent's `input_schema` fields via `{{ <field> }}`.
+At workflow runtime, the workflow's `context_mapping_config`
+populates these fields from the inbound dataset row (see §3).
+
+The platform validates at create time that every `{{ <field> }}`
+referenced by the prompt body resolves to a property declared in
+`input_schema`. Drift between the two surfaces as a 422 on
+`/prompt_config/body`.
+
+### `data_access` is the compliance gate
+
+```
+data_access: 'unregulated'   — the LLM call receives tokenized,
+                                redacted data; safe for any LLM
+                                (third-party, on-prem, …).
+                                Default for triage / categorization
+                                / lead-scoring workflows.
+data_access: 'regulated'     — the LLM call receives raw values;
+                                MUST be paired with an LLM the
+                                operator trusts with this tier
+                                (typically an on-prem deployment).
+                                Use for compliance workflows that
+                                need raw values — sanctions
+                                screening, manual review, KYC.
+```
+
+The setting is **immutable post-create**. Flipping the access
+tier requires recreating the agent (delete + create).
+
+### `enabled` gates whether workflows can invoke the agent
+
+A workflow that references a `disabled` agent fails at run time
+with `error_code: 'ai_agent_disabled'` on the workflow execution
+log. `enabled: false` is the operator's kill switch for an agent
+without removing it from the workflow's `ai_agents` array.
+
+### Numeric clamps on `temperature` and `max_tokens`
+
+The platform validates the numeric ranges at create / update time
+— BEFORE any chat-completion call to the bound tool. Out-of-range
+values surface as field-level rejections, not as runtime
+provider errors:
+
+```
+   temperature   required number ∈ [0.0, 2.0]    inclusive on both ends
+   max_tokens    required integer ∈ [1, 100_000]  inclusive on both ends
+```
+
+These bounds are the platform's, not the provider's. Picking a
+value the provider doesn't support (e.g. `temperature: 1.5` on
+a model that caps at 1.0) surfaces later as a provider error in
+the workflow execution log, not at create.
+
+### Name uniqueness is per-tenant, not per-datalake
+
+The agent's `name` (and the server-derived `slug`) must be
+unique within the tenant — collisions across **different
+datalakes of the same tenant** are rejected with a 422 on
+`/name` or `/slug`. This is unusual: most other resources scoped
+under a datalake (tools, data sources, interoperability
+contracts) carry per-datalake uniqueness. AI agents are the
+exception because their `slug` is the workflow-template
+reference key (`additional_context.<slug>`) and the platform
+needs a stable cross-datalake namespace for it.
+
+Practical consequence: if you want the same logical agent in
+two datalakes (e.g. dev + prod inside one tenant), give them
+distinct names. A naming convention like `"<purpose>-<env>"` or
+including the datalake slug in the agent name keeps the
+namespace clean.
+
+## 3. Workflow attachment
+
+A workflow attaches an AI agent at its **enrichment** stage via
+the inline `ai_agents` array on the workflow body (see
+`workflows.md` §3):
+
+```typescript
+{
+  // ... other workflow fields ...
+  ai_agents: [
+    {
+      ai_agent_id: createdAgentId,
+      position: 0,                                  // ordering when multiple agents fire
+      context_mapping_config: {
+        type: 'custom',
+        // Liquid renders to a JSON object whose keys match the
+        // agent's input_schema. The values reference the inbound
+        // dataset row via `event_dataset.<field>`.
+        body: JSON.stringify({
+          msg:           '{{ event_dataset.message }}',
+          submission_id: '{{ event_dataset.submission_id }}',
+        }),
+        output_schema: '{"type":"object"}',
+      },
+    },
+  ],
+  decision_config: {
+    type: 'custom',
+    // The agent's parsed output is exposed at
+    // `additional_context.<agent_slug>.<field>`. Property paths
+    // match the agent's llm_response_schema.
+    body: '["{{ additional_context.contact-us-triage-categorizer.category }}"]',
+    output_schema: '{"type":"array","items":{"type":"string"}}',
+  },
+}
+```
+
+The flow at run time:
+
+```
+   inbound row
+       │
+       ▼
+   workflow filter
+       │
+       ▼
+   for each ai_agents[i] (ordered by position):
+     • render context_mapping_config.body with Liquid (event_dataset.*, etc.)
+     • parse rendered output as JSON
+     • check it conforms to agent.input_schema
+     • forward to the bound tool as a chat completion
+     • parse the LLM response per agent.llm_response_schema
+     • merge under additional_context[agent.slug]
+       │
+       ▼
+   workflow decision (reads additional_context.<agent_slug>.<field>)
+       │
+       ▼
+   workflow action(s)
+```
+
+## 4. Field ownership
+
+**Server-derived (Response-only).** Universal set from
+`type_naming.md`. The `slug` is what workflow templates
+reference via `additional_context.<slug>`.
+
+**Caller-supplied (round-trip).**
+
+```
+name                  required string
+description           optional string
+tool_id               required UUID  — must be intent: llm_enrichment
+model                 required string — provider-specific identifier
+data_access           required enum  — 'unregulated' | 'regulated'
+temperature           required number
+max_tokens            required number
+enabled               required bool
+input_schema          required JSON Schema object
+llm_response_schema   required JSON Schema object  — see §2
+prompt_config         required embed — { type, body }
+```
+
+**Write-only (Request-only).** None.
+
+## 5. Error envelopes
+
+Standard JSON:API envelopes per `errors.md`. Common rejections:
+
+| `source.pointer`                | Cause                                              |
+|---------------------------------|----------------------------------------------------|
+| `/tool_id`                      | tool's intent isn't `llm_enrichment`              |
+| `/llm_response_schema`          | missing or not a valid JSON Schema object          |
+| `/input_schema`                 | missing or not a valid JSON Schema object          |
+| `/prompt_config/body`           | references a field absent from `input_schema`      |
+| `/data_access`                  | value not in enum                                  |
+| `/temperature`                  | outside the inclusive range [0.0, 2.0]             |
+| `/max_tokens`                   | outside the inclusive range [1, 100_000]           |
+| `/name` or `/slug`               | uniqueness collision — scope is per-tenant         |
+
+## 6. Lifecycle
+
+### Create
+
+Synchronous. The agent is immediately invocable by workflows
+once `enabled: true`.
+
+### Read shapes
+
+```
+.list(tenantSlug, datalakeSlug)              Paged: { data, meta }
+.get(tenantSlug, datalakeSlug, id)           One row, BY ID (UUID — not slug)
+.metadata(tenantSlug, datalakeSlug)          Markdown catalog
+.metadataDetails(tenantSlug, datalakeSlug,   Markdown for one agent;
+                  id)                         section headings: Model,
+                                              Bound tool, Prompt config
+```
+
+`.get` and `.metadataDetails` accept the agent's UUID `id` as
+the path key — NOT the slug. The slug is only used as a
+runtime reference key (`additional_context.<slug>` in workflow
+templates).
+
+### Update
+
+`PUT` replays the full body — no PATCH. Replace-on-PUT means
+all required fields must be re-supplied verbatim, including
+`input_schema`, `llm_response_schema`, and `prompt_config`.
+Omitting any returns a 422.
+
+### Delete
+
+`DELETE` removes the row. Workflows that still reference the
+agent in their `ai_agents` array fail at run time with
+`error_code: 'ai_agent_not_found'`; clean up workflow
+references first.
+
+## 7. Run-time failure modes
+
+When a workflow run's enrichment stage fails, the per-execution
+`error.json` artifact carries a structured failure record (see
+`workflows.md` §6 for the artifact convention). The
+agent-specific codes:
+
+```
+tool_execution_failed        — the bound chat-completion tool's
+                                HTTP call failed (404, refused,
+                                timeout). error.json carries the
+                                rich detail (URL, status); the
+                                workflow execution log carries
+                                a coarse error_message of the
+                                form "AI enrichment failed: <agent_name>"
+json_decode_failed           — provider returned a response that
+                                didn't parse as JSON (typically
+                                when llm_response_schema wasn't
+                                wired through to the provider's
+                                structured-output mode)
+context_mapping_failed       — context_mapping_config.body
+                                rendered output that didn't
+                                validate against the agent's
+                                input_schema
+ai_agent_disabled            — agent's enabled flag is false
+ai_agent_not_found           — agent was deleted but workflow
+                                still references it
+```
+
+The `error.json` shape:
+
+```
+{
+  error_code:    string  — one of the codes above
+  stage:         string  — 'enrichment' for agent-related failures
+  ai_agent_slug: string  — slug of the failing agent
+  error_message: string  — coarse copy of the workflow execution log's message
+  detail:        string  — rich provider context (URL, HTTP status, etc.);
+                            ONLY present in error.json, NOT mirrored to the
+                            workflow execution log row
+}
+```
+
+The `enrichment.json` artifact (success branch) carries the
+parsed agent outputs:
+
+```
+{
+  status: 'completed' | 'failed' | 'skipped',
+  <agent_slug_1>: {
+    status: 'completed',
+    output: { /* matches llm_response_schema */ },
+  },
+  <agent_slug_2>: { /* ... */ },
+}
+```
+
+For workflows without any `ai_agents`, `enrichment.json` lands
+with `{ status: 'skipped' }` and no per-agent entries.
+
+## 8. Gotchas
+
+1. **`llm_response_schema` is REQUIRED**, not optional. Omitting
+   it returns 422 on `/llm_response_schema`. The platform uses
+   it both as a provider-side decoding constraint and as the
+   output-binding shape for `additional_context.<slug>`. Missing
+   the schema means no structured output and downstream decision
+   templates can't reference the agent's fields.
+
+2. **`tool_id` must reference an `intent: 'llm_enrichment'`
+   tool.** Other intents are rejected at create. The chat
+   completion tool is typically `tool_body_type: 'rest_api'`
+   against an OpenAI-compatible endpoint; the platform appends
+   `/chat/completions` to its `base_url`.
+
+3. **`additional_context.<slug>` is the workflow accessor.**
+   The agent's `slug` (server-derived from `name`) is what
+   workflow decision and action templates reference. Capture it
+   from the create response — don't pre-compute.
+
+4. **`.get` takes UUID `id`, not slug.** The SHOW route is
+   `/ai-agents/:id`. The slug is only a runtime template key.
+
+5. **Replace-on-PUT.** Update bodies must re-supply
+   `input_schema`, `llm_response_schema`, `prompt_config`
+   verbatim. Partial PUT silently drops fields and returns
+   422 on the missing required field.
+
+6. **`data_access` is immutable post-create.** Flipping the
+   compliance tier requires delete + recreate.
+
+7. **`prompt_config.body` field references must resolve in
+   `input_schema`.** A `{{ field }}` that isn't declared in
+   `input_schema` returns 422 on `/prompt_config/body` at
+   create time.
+
+8. **The chat-completion tool's `base_url` should NOT include
+   `/chat/completions`.** The platform appends the path; a
+   doubled path 404s. Use the API root (e.g. `/v1` for OpenAI
+   or Ollama).