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

package/.agent/mdm.md

@@ -0,0 +1,293 @@
+# MDM — entity resolution + identity verification
+
+Master Data Management is the platform's entity-resolution layer.
+It binds every inbound row to a canonical **subject** record (the
+domain's primary entity — e.g. `patient` for healthcare-domain
+datalakes, `legal_entity` for foundation-domain datalakes) so
+that downstream datasets, workflows, and agent prompts reference
+a single, deduplicated identity rather than the raw inbound
+identifiers each upstream system carries.
+
+SDK namespace: `api.mdm`. Today the wire exposes a single verb:
+
+```
+   api.mdm.verify(tenantSlug, datalakeSlug, body)
+```
+
+Other MDM operations (subject resolution during ingestion,
+record merging, conflict reconciliation) run inside the platform
+on consumer-supplied inputs but are not directly SDK-callable —
+see §5 Lifecycle.
+
+MDM is **Datalake-DB-resident** — the parent datalake must be
+`status: 'ready'` before any MDM verb is called, since
+resolution / verification both look up against the datalake's
+regulated master records.
+
+## 1. Wire shape — `.verify`
+
+Verify that a person on the other end of a workflow action or a
+connected-app form submission matches an existing subject in the
+datalake. Used at action time (workflows confirming an SMS
+recipient) and at runtime (connected apps confirming the form
+submitter before posting tracking updates).
+
+```typescript
+import type {
+  MDMVerifyRequest,
+  MDMVerifyResponse,
+} from '@alvera-ai/platform-sdk'
+
+const { data: result } = await api.mdm.verify(
+  tenantSlug,
+  datalakeSlug,
+  {
+    subject_id: subjectUuid,                          // required
+    family_name: 'Garcia',                            // optional
+    given_name:  'Maria',                             // optional
+    birth_date:  '1978-11-03',                        // optional; ISO 8601 date
+    identifiers: [                                    // optional
+      { system: 'http://hospital.org/mrn', value: 'MRN12345' },
+    ],
+  },
+)
+// result.status        === 'verified' | 'not_verified'
+// result.subject_id    === body.subject_id
+// result.verified_at   — ISO 8601 timestamp
+// when status === 'not_verified':
+//   result.errors      — { <field_name>: [reason, ...] } per-field failure detail
+```
+
+The response is **polymorphic on `status`**:
+
+```
+status === 'verified'       → { subject_id, verified_at }
+status === 'not_verified'   → { subject_id, verified_at, errors }
+```
+
+A `not_verified` response is NOT an error — it's a successful
+identity check that returned a negative result. Distinguish from
+402-level rejections (404 for missing subject, 401 for missing
+auth, 422 for malformed body).
+
+### Subject per data domain
+
+Every datalake has a single canonical **subject entity** — the
+domain's primary identity that all other rows attribute to. The
+verify call resolves against that subject. The subject's wire
+name follows the dataset's `resource_type` (see
+`interoperability_contracts.md` §2 `resource_type`):
+
+```
+   data_domain                  subject resource_type
+   ───────────                  ─────────────────────
+   healthcare                   patient
+   core_banking                 party
+   payment_risk                 legal_entity
+   accounts_receivable          customer
+   service_commerce             consumer
+   trading                      trading_account
+   foundation                   legal_entity
+```
+
+(`legal_entity` is the subject for both `payment_risk` and
+`foundation` — different domain context, same canonical entity
+shape.)
+
+Generic tables in a datalake automatically carry a foreign-key
+column to their subject (e.g. `patient_id` in a healthcare-
+domain generic table). Querying that column scopes any custom
+dataset to subjects the verify call has confirmed.
+
+## 2. Rules the type cannot encode
+
+### `subject_id` is required; the identity fields are not
+
+`subject_id` (the master record to verify against) is the only
+required field. The identity fields (`family_name`, `given_name`,
+`birth_date`, `identifiers`) are individually optional, but the
+platform requires **at least one** identity field to be supplied
+at runtime — a body carrying only `subject_id` returns a 422.
+
+The runtime check is a "must have something to match against"
+rule that the schema can't express in TypeScript / JSON Schema.
+
+### Verification is per-field, with field-specific match rules
+
+Each supplied identity field is checked independently against
+the subject record. The platform uses fuzzy matching for the
+string fields and exact matching for the structured ones:
+
+```
+family_name      Jaro distance ≥ 0.85
+given_name       Jaro distance ≥ 0.80
+birth_date       component-wise fuzzy match ≥ 0.80
+identifiers      exact (system, value) match
+```
+
+All supplied fields must pass for the overall result to be
+`'verified'`. A single failing field flips the result to
+`'not_verified'` and surfaces the field name in `errors`.
+
+The exact thresholds and field set are **domain-scoped** —
+healthcare-domain datalakes use the FHIR-shaped demographics
+listed above; future domains may extend the field set with
+additional verification predicates. The verify endpoint accepts
+the union of fields the parent datalake's domain knows how to
+match against; unknown fields are rejected as a 422.
+
+### `subject_id` must exist in the datalake's regulated schema
+
+If the supplied `subject_id` doesn't resolve to a master record
+in the datalake's regulated schema, the response is a 404, not
+a `'not_verified'`. The distinction matters:
+
+- `'not_verified'` → "subject exists, identity fields didn't match"
+- 404               → "subject doesn't exist at all"
+
+A consumer that conflates the two will mis-route an identity
+challenge as a missing-record error.
+
+## 3. Field ownership
+
+**Server-derived (Response-only).**
+
+```
+status         enum   — 'verified' | 'not_verified'
+verified_at    string — ISO 8601 timestamp of the verification attempt
+errors         object — present only when status === 'not_verified';
+                         maps field name to an array of failure reasons
+```
+
+**Caller-supplied (round-trip on the verified branch).**
+
+```
+subject_id     required UUID  — the master record to verify against
+family_name    optional string — fuzzy-matched (string distance)
+given_name     optional string — fuzzy-matched (string distance)
+birth_date     optional date   — fuzzy-matched component-wise
+identifiers    optional array  — [{ system, value }] exact-matched
+```
+
+**Write-only (Request-only).** None.
+
+## 4. Error envelopes
+
+Standard JSON:API envelopes per `errors.md`. Common rejections:
+
+| `source.pointer`              | Cause                                                  |
+|-------------------------------|--------------------------------------------------------|
+| `/subject_id`                 | missing, or the subject doesn't exist in the datalake  |
+| `errors.base`                 | no identity fields supplied (subject_id alone) — 422 response with `status: "not_verified"` in the body |
+| `/family_name` etc.           | field structurally invalid (wrong type, malformed)     |
+| `/identifiers/0/system`       | missing system on an identifier entry                  |
+| `/identifiers/0/value`        | missing value on an identifier entry                   |
+
+The `not_verified` outcome surfaces in two response shapes:
+
+- **Identity mismatch (most common)** — 200 response with
+  `status: 'not_verified'` and a field-keyed `errors` map naming
+  the demographics that failed (e.g. `errors.family_name`). The
+  subject exists; the supplied identity didn't match.
+- **No identity fields supplied** — 422 response with
+  `status: 'not_verified'` in the body and `errors.base` set to
+  `["at least one verification field is required"]`. Verification
+  was structurally impossible.
+
+Pattern-match on `status` first, then on the HTTP status code to
+distinguish the two not_verified shapes. The 404 case (subject
+doesn't exist) is a separate envelope — see §6 gotcha 2.
+
+## 5. Lifecycle
+
+### `.verify` is synchronous
+
+The verify call returns the resolution outcome in the response —
+no async polling, no job id. The platform performs the fuzzy
+match against the regulated master record inline.
+
+### Other MDM operations are platform-internal
+
+Beyond `.verify`, MDM also runs at two points without a direct
+SDK surface:
+
+- **During data activation ingestion.** Each inbound row that
+  carries an `mdm_input_config` on its bound interoperability
+  contract gets routed through the platform's resolution
+  pipeline before the dataset upsert. The pipeline matches the
+  rendered MDM input against existing subjects (or creates one
+  if no match) and produces an `mdm_output` carried forward to
+  the regulated upsert. Consumers configure this implicitly via
+  the contract's `mdm_input_config` — see
+  `interoperability_contracts.md` §2 and `data_activation_clients.md`
+  §6.
+
+- **Conflict reconciliation.** When two master records turn out
+  to represent the same subject (e.g. an MRN-only record and a
+  demographics-only record that operators later confirm are the
+  same person), the platform supports merge / unmerge operations.
+  These are administrative actions surfaced in the admin console,
+  not SDK-exposed verbs.
+
+### Read shapes
+
+```
+.verify(tenantSlug, datalakeSlug, body)    Single round-trip; see §1
+```
+
+Today there is no `.list`, `.get`, or `.metadata` on the MDM
+namespace — subjects themselves are queried through the dataset
+search surface (see `data_activation_clients.md` §6.5), not
+through `api.mdm`.
+
+## 6. Gotchas
+
+1. **`'not_verified'` is usually a successful 200 response, not
+   an error — but the "no fields supplied" case is a 422 with a
+   `not_verified` body.** Pattern-match on `result.status === 'verified'`
+   to gate the downstream "act on this person" path. Throwing on
+   `'not_verified'` collapses two distinct outcomes (subject
+   verified vs identity mismatch) into one branch and loses the
+   `errors` payload that explains which fields failed. The 422
+   sub-case (no identity fields, just `subject_id`) needs HTTP-status
+   handling on top of body-status handling — see §4 above.
+
+2. **`subject_id` missing → 404, identity mismatch → 200.** A
+   verify call against a deleted or never-existed subject id
+   returns a 404 envelope, NOT a `'not_verified'` response.
+   Consumers that handle only the polymorphic 200 response will
+   surface the 404 as an unexpected exception. Wrap the verify
+   call in standard 4xx handling per `errors.md`.
+
+3. **At least one identity field is required.** A body with
+   only `subject_id` and no identity fields returns a 422 with
+   `errors.base` set to `["at least one verification field is
+   required"]` and `status: "not_verified"` in the response
+   body. The platform cannot verify identity against zero
+   attributes; this is enforced at runtime rather than in the
+   request schema, so the TypeScript type permits the
+   no-identity-field body but the wire rejects it.
+
+4. **The verification field set is domain-scoped.** Today the
+   healthcare-domain verifier accepts FHIR-shaped demographics
+   (family_name, given_name, birth_date, identifiers). Other
+   domains will expose verifier-appropriate field sets as they
+   land. Querying `api.mdm.verify` against a datalake whose
+   domain doesn't support a supplied field returns a 422 on
+   that field's pointer — don't assume the full healthcare
+   field set works on every domain.
+
+5. **MDM also runs at ingestion — and you don't call it
+   directly.** The `mdm_input_config` on each interoperability
+   contract feeds the platform's resolution pipeline at
+   ingestion time, producing the `mdm_output` carried into the
+   dataset upsert. There is no `api.mdm.resolve` SDK verb; you
+   configure resolution by shaping the contract's
+   `mdm_input_config`. See `interoperability_contracts.md` §2.
+
+6. **`identifiers` matches are exact, not fuzzy.** Whitespace,
+   case, and trailing slashes in `system` URIs all matter.
+   Compare with the master record's identifier system strings
+   character-for-character; a `'http://hospital.org/mrn'` vs
+   `'http://hospital.org/mrn/'` mismatch will flip the verifier
+   to `'not_verified'` even when the value is correct.

package/.agent/mutations.md

@@ -0,0 +1,126 @@
+# Mutations
+
+Every resource exposes the same three mutation methods on the typed client:
+`create(body)`, `update(id, body)`, and `delete(id)`. Two rules cover almost
+everything:
+
+1. **`update()` replaces the whole resource.** There is no partial update —
+   resupply the full body with your change applied. A tiny, explicitly-listed
+   set of methods are the exception (below).
+2. **`create()` returns the full record**, including server-derived fields
+   (`id`, `slug`, `status`, timestamps). Use that returned record for
+   downstream references — never pre-compute a server-derived field yourself.
+
+Non-CRUD methods are out of scope for this page — RESTful sub-actions
+(`.syncRoutes`, `.resolvePage`, `.testInvocation`), artifact issuers
+(`.createUploadLink`, `.createDownloadLink`), and async triggers (`.run`,
+`.execute`, `.ingest`) each document their own semantics in their resource's MD.
+
+## `create()` — make a new record
+
+`create(body)` returns the full `<Resource>Response`, including every
+server-derived field (see `type_naming.md` "Server-derived fields"). Read the
+ids and slugs you need off that response.
+
+## `update()` — replace the whole record
+
+`update(id, body)` replaces the resource wholesale — it is **not** a partial
+update. To change one field, read the current record, change the field in
+memory, and send the entire body back:
+
+```typescript
+// 1. read current
+const { data: current } = await api.tools.get(
+  tenantSlug, datalakeSlug, toolId,
+)
+
+// 2. change in memory
+const next = { ...current, status: 'inactive' }
+
+// 3. send the whole body back
+const { data: updated } = await api.tools.update(
+  tenantSlug, datalakeSlug, toolId, next,
+)
+```
+
+Omitting a required field on `update()` is rejected with a `422 AlveraApiError`
+on that field — even when its value is unchanged from the stored row — because
+the call replaces the whole resource (see `errors.md`).
+
+## Partial-update exceptions
+
+A small set of methods accept a narrow partial body instead of replacing the
+whole resource. Each is named here and documents its partial-body contract in
+its TypeScript method's JSDoc and its per-resource MD §5 (Lifecycle):
+
+| SDK method                                  | Resource MD          |
+|---------------------------------------------|----------------------|
+| `api.connectedApps.updateMessageTracking`   | `connected_apps.md`  |
+
+For every other method, the default holds: `update()` replaces the whole
+resource.
+
+> This is the canonical index of partial-update methods. If a future method
+> joins, it lands here. If you find a method whose JSDoc claims partial-body
+> behavior but it isn't listed here, this index is stale and needs a refresh.
+
+## The discriminator can't change on update
+
+For polymorphic resources (tools, a datalake's cloud storage, …), the body's
+discriminator value must match the stored record's on `update()`. The platform
+rejects a discriminator change with a `422` on the discriminator field. To
+change body type, `delete()` and `create()` fresh — you cannot morph it in
+place.
+
+## Polymorphic discriminator naming
+
+Resources with polymorphic bodies carry an explicit discriminator field. Its
+**wire name** is what the SDK type expects:
+
+| Resource                       | Discriminator (wire)     |
+|--------------------------------|--------------------------|
+| Tool body                      | `tool_body_type`         |
+| Datalake cloud-storage embed   | `cloud_storage_type`     |
+
+The wire name is what appears in your request body's JSON and in the
+`<Resource>RequestWritable` TypeScript types. Each resource's MD §1 (Wire
+shape) names its discriminator and lists every branch's TypeScript type.
+
+## `delete()` — usually synchronous
+
+`delete(id)` removes the record. A few resources have semantic guards (e.g. you
+cannot delete a default-flagged data activation client, or a datalake that
+still has dependents) that surface as `422`s with `source.pointer` naming the
+field that's blocking the delete.
+
+For asynchronous deletes (e.g. AWS Lambda tools' out-of-band cleanup), poll the
+resource's status until it's gone — see `async.md`.
+
+## The parent scope comes from the method arguments, not the body
+
+Every resource method takes its parent scope as leading arguments —
+`tenantSlug` and `datalakeSlug` — which become the URL path:
+
+```
+/api/v1/tenants/{tenant_slug}/datalakes/{datalake_slug}/<resource>[/{id}]
+```
+
+A body often also carries a `datalake_id` (and sometimes `tenant_id`) naming
+the same parent. **The method arguments win.** If the body names a different
+parent than the arguments, the body field is silently ignored and the record
+lands under the argument-named parent. The practical consequences:
+
+- **You can't "redirect" a write with a body field.** To target a different
+  datalake, change the `datalakeSlug` argument.
+- **Reusing a body across datalakes is safe.** A `datalake_id` you captured
+  from an earlier call can ride along on a write under any scope — the
+  arguments govern where it lands.
+- **A `datalake_id` mismatch never 422s** — the platform just ignores the body
+  value.
+
+## No bulk mutations on standard CRUD
+
+Each `create()` / `update()` / `delete()` touches exactly one resource — there
+are no batch creates or updates on the standard methods. Some ingestion paths
+(data-activation-client bulk runs and file uploads) ARE batch by design; those
+are documented in `data_activation_clients.md`.

package/.agent/templates.md

@@ -0,0 +1,98 @@
+# Templates
+
+Templates are an **INFRASTRUCTURE** building block: the platform
+ships a library of Liquid templates that other infrastructure
+resources consume — interoperability contracts, AI agent prompts,
+workflow definitions, status poller bodies. Templates are
+**read-only** from the SDK; the platform composes them
+per-industry, and each datalake's `data_domain` selects which
+surface in its catalog.
+
+SDK namespace: `api.templates`.
+
+For the safety contract that bounds every template body the
+platform accepts — the consumer-author trust boundary, the 11
+custom Liquid filters, the SQL-fragment boundary, and the
+compliance gates that compose with them — see `ai_sandbox.md`.
+
+## 1. Wire shape
+
+Three discovery methods, two complementary response shapes —
+structured (for code) and markdown (for agents):
+
+```typescript
+import type { SystemTemplate } from '@alvera-ai/platform-sdk'
+
+// Structured catalog
+const { data: catalog } = await api.templates.systemTemplates(
+  tenantSlug,
+  datalakeSlug,
+)
+// catalog.data: SystemTemplate[]
+//   { path, content, output_schema }
+//     path           category/sub-category/name segment string
+//     content        Liquid template body
+//     output_schema  null | object — rendered output's expected shape
+
+// Markdown catalog
+const { data: catalogMd } = await api.templates.metadata(
+  tenantSlug,
+  datalakeSlug,
+)
+// catalogMd: string — agent-facing markdown listing in-scope templates
+
+// Markdown body for one template
+const { data: templateMd } = await api.templates.metadataDetails(
+  tenantSlug,
+  datalakeSlug,
+  basename,  // e.g. 'delivery_status' or 'contact_message_categorizer'
+  intent,    // e.g. 'status_poller' or 'ai_agent' — note: intent
+             //                                     != path segment;
+             //                                     see §4 Gotcha 1
+)
+// templateMd: string — agent-facing markdown describing the template
+```
+
+## 2. Path structure
+
+Template paths follow `<category>/<sub-category>/<name>`.
+Categories the SDK exposes include
+`data_activation/interoperability/`, `ai_agents/`, `workflows/`,
+`status_poller/`. Categories with an industry segment (e.g.
+`ai_agents/<industry>/*`) filter to the datalake's `data_domain`;
+categories without (e.g. `status_poller/*/*`) are globals
+present in every catalog.
+
+## 3. Lifecycle
+
+Templates are static — they ship with the platform, not created
+via SDK. New templates arrive via platform releases. If you need
+a custom template, supply it inline (e.g. an interop contract's
+`template_config: { type: 'custom', body: '...' }`) rather than
+trying to add to the catalog.
+
+## 4. Gotchas
+
+1. **`basename` + `intent` is the composite key.** The `intent`
+   value is a fixed set of category identifiers — it does NOT
+   map cleanly to path segments. Some intents match (e.g.
+   `status_poller/...` → `'status_poller'`); some are
+   singularizations (e.g. `ai_agents/<industry>/<name>` →
+   `'ai_agent'`); some collapse multiple path segments (e.g.
+   `data_activation/interoperability/<industry>/...` →
+   `'data_activation_interoperability'`). Check the typed
+   parameter for the valid set; multiple templates can share a
+   basename across intents.
+
+2. **`output_schema` may be `null`.** Some templates render plain
+   strings without structured output. Test for null before
+   treating it as an object.
+
+3. **Templates from other industries never appear.** The
+   platform filters per-datalake. Walking the catalog gives only
+   in-scope entries; no need to filter by industry in your code.
+
+4. **Read-only from SDK.** For custom template content, use
+   inline `template_config` on the consuming resource (interop
+   contracts, AI agents, etc.) rather than seeking a catalog
+   addition.

package/.agent/tool-call-configs.md

@@ -0,0 +1,90 @@
+<!-- alvera:doc kind="tool-call-configs" generated-by="mix alvera.dump.static_metadata" -->
+
+# Tool Call Configurations
+
+Per-invocation invocation-side schemas for Alvera tools. Each section
+documents one variant of `Platform.Tools.ToolCallConfig`, identified
+by its atom and rendered by `ToolCallConfig.metadata_details/2`.
+
+<!-- alvera:section kind="tool-call-config" atom="restapi_request" module="Platform.Tools.ToolCallConfig.RESTAPIRequest" -->
+
+## Tool Call Configuration (restapi_request)
+
+Fetches data via REST API with pagination support.
+
+- **method** (enum: head, get, put, post, delete, patch) — HTTP method
+- **path** (TemplateConfig) — API endpoint path, rendered as Liquid template
+- **body** (TemplateConfig, nullable) — Request body, rendered as Liquid template
+- **params** (TemplateConfig, nullable) — Query parameters, rendered as Liquid template
+- **pagination_context_template** (TemplateConfig) — Pagination control template, must render to JSON with `has_next` boolean field
+
+<!-- alvera:section kind="tool-call-config" atom="sql_query" module="Platform.Tools.ToolCallConfig.SQLQuery" -->
+
+## Tool Call Configuration (sql_query)
+
+Fetches data via SQL query with Liquid template variables for pagination.
+
+- **query** (TemplateConfig) — SQL query template with pagination variables
+
+<!-- alvera:section kind="tool-call-config" atom="sftp_request" module="Platform.Tools.ToolCallConfig.SFTPRequest" -->
+
+## Tool Call Configuration (sftp_request)
+
+Fetches data from a remote SFTP server.
+
+- **path** (string) — Remote file path on SFTP server
+- **content_type** (string) — MIME type of the file
+
+<!-- alvera:section kind="tool-call-config" atom="microsoft_share_point_excel_request" module="Platform.Tools.ToolCallConfig.MicrosoftSharePointExcelRequest" -->
+
+## Tool Call Configuration (microsoft_share_point_excel_request)
+
+Fetches data from a Microsoft SharePoint drive (Excel files).
+
+- **drive_url** (string) — SharePoint drive URL
+- **azure_tenant_id** (string) — Microsoft Azure tenant identifier
+- **sheet_number** (integer) — 0-indexed Excel sheet number
+- **search_params** (string) — Search parameters for locating files
+
+<!-- alvera:section kind="tool-call-config" atom="aws_lambda_request" module="Platform.Tools.ToolCallConfig.AWSLambdaRequest" -->
+
+## Tool Call Configuration (aws_lambda_request)
+
+Invokes an AWS Lambda function to fetch data.
+
+- **payload** (TemplateConfig) — Lambda JSON payload, rendered as Liquid template
+- **timeout_ms** (integer, default: 600000, max: 900000) — Invocation timeout in milliseconds
+
+<!-- alvera:section kind="tool-call-config" atom="s3_request" module="Platform.Tools.ToolCallConfig.S3Request" -->
+
+## Tool Call Configuration (s3_request)
+
+Fetches data from an S3 bucket.
+
+- **file_path** (string) — S3 object key (no `s3://` prefix)
+
+<!-- alvera:section kind="tool-call-config" atom="manual_upload" module="Platform.Tools.ToolCallConfig.ManualUpload" -->
+
+## Tool Call Configuration (manual_upload)
+
+Manual file upload — data is uploaded directly by the user. No additional configuration fields.
+
+<!-- alvera:section kind="tool-call-config" atom="sms_request" module="Platform.Tools.ToolCallConfig.SMSRequest" -->
+
+## Tool Call Configuration (sms_request)
+
+Sends an SMS message via the configured SMS provider.
+
+- **to** (TemplateConfig) — Recipient phone number in E.164 format, rendered as Liquid template
+- **body** (TemplateConfig) — Message body, rendered as Liquid template
+- **sms_type** (enum: transactional, promotional) — Message classification; defaults to `transactional`
+
+<!-- alvera:section kind="tool-call-config" atom="email_request" module="Platform.Tools.ToolCallConfig.EmailRequest" -->
+
+## Tool Call Configuration (email_request)
+
+Sends an email message via the configured email provider.
+
+- **to** (TemplateConfig) — Recipient email address (RFC 5322), rendered as Liquid template
+- **subject** (TemplateConfig) — Email subject line, rendered as Liquid template
+- **body** (TemplateConfig) — Email body, rendered as Liquid template