@alvera-ai/platform-sdk 0.17.0 → 0.18.0

package/.agent/cookbook/system-templates.md

@@ -1,165 +0,0 @@
----
-title: "Capability: discover the platform's built-in row-mapping templates"
-summary: A capability walk for system-template discovery. List the Liquid templates the platform ships for your datalake's data domain (`api.templates.systemTemplates`), read the human-readable catalog (`api.templates.metadata`), and pull one template's detail (`api.templates.metadataDetails`) — so you can start an interoperability contract from a platform template instead of hand-writing Liquid. Read-only; creates nothing.
-industry: subscription
-slug: system-templates
-vitest_source:
-  - integration-tests/tests/subscription/system-templates.test.ts
-  - integration-tests/tests/subscription/bootstrap.test.ts
-status: green
----
-
-# Capability
-
-**What you get:** the list of row-mapping Liquid templates the platform already
-ships for your datalake's data domain, so an interoperability contract can start
-from a vetted template instead of hand-written Liquid.
-
-`api.templates.*` is read-only discovery. Three calls:
-
-- `systemTemplates(tenantSlug, datalakeSlug)` — the machine-readable list:
-  `{ data: [{ path, content, output_schema }] }`. The list is **filtered to your
-  datalake's data domain** plus globals — a payments or healthcare template
-  never appears in an subscription datalake.
-- `metadata(tenantSlug, datalakeSlug)` — the same catalog as a markdown summary.
-- `metadataDetails(tenantSlug, datalakeSlug, basename, intent)` — one template's
-  detail by basename + intent.
-
-This is **global** to every data domain — only the anchor template paths below
-differ by domain. See `templates.md` for the reference, and
-`interoperability_contracts.md` for how a template becomes a contract.
-
-# Walkthrough
-
-The `_setup/subscription.md` bootstrap already provisioned the tenant +
-datalake and left `api`, `tenantSlug`, and `datalakeSlug` populated. This walk
-starts from there.
-
-## 001 — list the system templates in scope for this datalake
-
-`systemTemplates` returns every platform-shipped Liquid template visible to this
-datalake: the templates for its data domain (here, `subscription`) plus
-domain-agnostic globals (e.g. the SNS delivery-status poller). Each entry has a
-`path`, the Liquid `content`, and an `output_schema` (`null` when the template
-has no companion schema). The list is domain-scoped — templates for other data
-domains (`healthcare`, `payments`, `foundation`, …) are filtered out, so you
-only see what is usable here.
-
-```typescript
-const { data: templates } = await api.templates.systemTemplates(tenantSlug, datalakeSlug)
-
-const paths = (templates.data ?? []).map((t) => t.path)
-if (paths.length === 0) {
-  throw new Error('expected the platform to ship at least one system template')
-}
-
-// The subscription anchor template is present...
-const arAnchor = 'data_activation/interoperability/subscription/stripe/customers_subscription_customer'
-if (!paths.some((p) => p.includes(arAnchor))) {
-  throw new Error(`expected the AR customer template (${arAnchor}) in the list`)
-}
-
-// ...and templates for other data domains are filtered out of an AR datalake.
-const otherDomains = ['healthcare', 'payments', 'foundation', 'core_banking', 'service_commerce', 'trading']
-const leaked = paths.filter((p) => otherDomains.some((d) => p.split('/').includes(d)))
-if (leaked.length > 0) {
-  throw new Error(`cross-domain templates leaked into an AR datalake: ${leaked.join(', ')}`)
-}
-```
-
-## 002 — read the catalog as markdown
-
-`metadata` returns the same catalog as a markdown document — the form an agent
-reads to decide which template to start from. It names the in-scope templates,
-including the AR customer template by basename.
-
-```typescript
-const { data: catalog } = await api.templates.metadata(tenantSlug, datalakeSlug)
-if (typeof catalog !== 'string' || catalog.length === 0) {
-  throw new Error('expected a non-empty markdown template catalog')
-}
-if (!catalog.includes('customers_subscription_customer')) {
-  throw new Error('expected the AR customer template named in the catalog markdown')
-}
-```
-
-## 003 — read one template's detail by basename + intent
-
-`metadataDetails` pulls a single template's detail. Address it by its
-**basename** (the template name without the path) and its **intent** (the path
-prefix joined with underscores — here `data_activation_interoperability`). The
-result is a markdown body you can show an operator or feed an agent before it
-copies the template into a contract's `template_config`.
-
-```typescript
-const { data: detail } = await api.templates.metadataDetails(
-  tenantSlug,
-  datalakeSlug,
-  'customers_subscription_customer',
-  'data_activation_interoperability',
-)
-if (typeof detail !== 'string' || detail.length === 0) {
-  throw new Error('expected a non-empty markdown detail for the AR customer template')
-}
-```
-
-## 004 — write the integration test
-
-End the walk with a test you keep: anything that references a system
-template by path (`template_config: { type: 'system', path: … }`) depends
-on that path staying in this datalake's scope — so the durable test
-re-asserts the anchor is listed, the domain filter holds, and the detail
-surface renders. This block runs live under `make validate-cookbook`.
-
-```typescript
-const { data: tplList } = await api.templates.systemTemplates(tenantSlug, datalakeSlug)
-const tplPaths = (tplList.data ?? []).map((t) => t.path)
-const anchor = 'data_activation/interoperability/subscription/stripe/customers_subscription_customer'
-if (!tplPaths.some((p) => p.includes(anchor))) {
-  throw new Error(`anchor template ${anchor} vanished from the domain-scoped list`)
-}
-const foreign = ['healthcare', 'payments', 'foundation', 'core_banking', 'service_commerce', 'trading']
-const leakedPaths = tplPaths.filter((p) => foreign.some((d) => p.split('/').includes(d)))
-if (leakedPaths.length > 0) {
-  throw new Error(`cross-domain templates leaked: ${leakedPaths.join(', ')}`)
-}
-// Behavioural probe — the detail surface must render for the anchor.
-const { data: anchorDetail } = await api.templates.metadataDetails(
-  tenantSlug,
-  datalakeSlug,
-  'customers_subscription_customer',
-  'data_activation_interoperability',
-)
-if (typeof anchorDetail !== 'string' || anchorDetail.length === 0) {
-  throw new Error('anchor template metadataDetails came back empty')
-}
-```
-
-If the anchor disappears in production, escalate with the listing
-evidence — a `type: system` reference that stops resolving is a platform
-regression, not something to paper over by inlining the template body.
-
-# Gotchas
-
-- **The list is domain-scoped, not global.** `systemTemplates` only returns
-  templates for this datalake's data domain plus globals. Calling it on a
-  healthcare datalake returns the healthcare templates, never the AR ones —
-  there is no "all templates" view.
-- **`output_schema` is often `null`.** A template carries a non-null
-  `output_schema` only when it ships a companion schema; most interop templates
-  return `null`. Don't treat `null` as an error.
-- **`metadataDetails` keys on basename + intent, not the full path.** Pass the
-  bare template name and the underscore-joined path prefix (the "intent"), not
-  the slash path from `systemTemplates`.
-- **Discovery only.** None of these calls create or mutate anything — they read
-  what the platform ships. To turn a template into a live mapping, copy its
-  `content` into an `interoperabilityContracts.create(...)` `template_config`
-  (see `interoperability_contracts.md`).
-
-# See also
-
-- `templates.md` — the `api.templates.*` reference (wire shapes, intents)
-- `interoperability_contracts.md` — how a template becomes a live row mapping
-- `_setup/subscription.md` — the bootstrap this walk starts from
-- `integration-tests/tests/subscription/system-templates.test.ts` — the
-  green test these calls are lifted from

package/.agent/cookbook/talk-to-data.md

@@ -1,178 +0,0 @@
----
-title: "Capability: talk to your datalake — natural language → SQL → rows"
-summary: A capability walk for datalake text-to-SQL. Generate a read-only SQL statement from a natural-language prompt (`api.datalakes.textToSql`) — only the prompt + schema cross the LLM boundary, never rows — then run it read-only and read back the page (`api.datalakes.executeSql`), with both the JSON `{ data, meta }` envelope and a CSV export. The BI surface on a datalake.
-industry: foundation
-slug: talk-to-data
-vitest_source:
-  - integration-tests/tests/foundation/text-to-sql.test.ts
-status: green
----
-
-# Capability
-
-**What you get:** a two-call BI surface on a datalake — describe what you want in
-plain language, get back reviewable SQL, then run it read-only and read the rows.
-
-The split is deliberate: `textToSql` *generates*, `executeSql` *runs*. A UI or
-agent can show the SQL, let a human edit it, and re-run — and the generate step
-is **data-free by construction** (only the prompt + the datalake schema reach the
-LLM, never rows), so it is safe in both `regulated` and `unregulated` mode.
-
-1. `datalakes.textToSql(...)` — natural language → `{ sql, model, provider, explanation }`.
-2. `datalakes.executeSql(...)` — read-only execution → `{ data, meta }` (data is an
-   array-of-arrays row page aligned to `meta.columns`), or a CSV string with
-   `{ format: 'csv' }`.
-
-See `datalakes.md` "Talk to data" for the wire reference and `ai_sandbox.md`
-Layer 3 for why the boundary holds.
-
-# Walkthrough
-
-The `_setup/foundation.md` bootstrap left `api`, `tenantSlug`, and `datalakeSlug`
-populated, pointing at a freshly-migrated foundation datalake.
-
-## 001 — generate SQL from a natural-language prompt
-
-`textToSql` runs ordered multi-provider LLM failover and returns the generated
-`sql` plus the winning `model` / `provider` and a best-effort `explanation`
-(`null` when the explainer is unavailable). It does **not** execute the SQL — it
-hands it back for review. Nothing but the prompt and the datalake schema is sent
-to the model, so no datalake rows leave the trust boundary.
-
-```typescript
-const { data: gen } = await api.datalakes.textToSql(tenantSlug, datalakeSlug, {
-  prompt: 'how many legal entities are there?',
-  mode: 'unregulated',
-})
-if (typeof gen.sql !== 'string' || gen.sql.trim() === '') {
-  throw new Error(`textToSql returned no SQL (got: ${JSON.stringify(gen.sql)})`)
-}
-if (typeof gen.model !== 'string' || typeof gen.provider !== 'string') {
-  throw new Error('textToSql response missing model/provider attribution')
-}
-// gen.explanation is best-effort plain-language prose, or null.
-```
-
-## 002 — run a read-only query and read back the page
-
-`executeSql` runs the SQL **read-only** (INSERT/UPDATE/DELETE/DDL are rejected)
-and returns `{ data, meta }`. `data` is an **array-of-arrays** row page — positional,
-aligned to `meta.columns`, because arbitrary SQL can have duplicate / expression
-column names. `meta` carries the structural + pagination fields. A deterministic
-`SELECT 1 AS n` keeps this step independent of the generated SQL and seeded data.
-
-The curated return is `ExecuteSqlResponse | string` (the CSV branch is a string),
-so narrow with a `typeof` guard before reading the JSON envelope.
-
-```typescript
-const jsonResult = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
-  sql: 'SELECT 1 AS n',
-  mode: 'unregulated',
-})
-if (typeof jsonResult.data === 'string') {
-  throw new Error('expected the JSON envelope, got a CSV string')
-}
-const page = jsonResult.data
-if (!Array.isArray(page.data) || !Array.isArray(page.data[0])) {
-  throw new Error('executeSql data is not an array-of-arrays')
-}
-if (page.meta.columns[0] !== 'n' || page.data[0][0] !== 1 || page.meta.num_rows !== 1) {
-  throw new Error(`unexpected SELECT 1 result: ${JSON.stringify(page)}`)
-}
-// page.meta also carries total_count, page, page_size, total_pages, duration_ms, command.
-```
-
-## 003 — export the same page as CSV
-
-Pass `{ format: 'csv' }` to get the page as a CSV **string** instead of the JSON
-envelope — the same read, content-negotiated for download.
-
-```typescript
-const csvResult = await api.datalakes.executeSql(
-  tenantSlug,
-  datalakeSlug,
-  { sql: 'SELECT 1 AS n', mode: 'unregulated' },
-  { format: 'csv' },
-)
-if (typeof csvResult.data !== 'string') {
-  throw new Error('expected a CSV string for { format: "csv" }')
-}
-const csv = csvResult.data
-if (!/\bn\b/.test(csv) || !csv.includes('1')) {
-  throw new Error(`unexpected CSV body: ${JSON.stringify(csv)}`)
-}
-```
-
-## 004 — write the integration test
-
-End the walk with a test you keep: both surfaces are read-only, so the
-durable test is the pair of deterministic boundary probes — the
-round-trip works, and the read-only wall holds. Neither depends on an
-LLM provider or seeded data, which is what makes the test durable. This
-block runs live under `make validate-cookbook`.
-
-```typescript
-// Round-trip probe — deterministic, data-independent.
-const probe = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
-  sql: 'SELECT 1 AS ok',
-  mode: 'unregulated',
-})
-if (typeof probe.data === 'string' || probe.data.data[0]?.[0] !== 1) {
-  throw new Error('executeSql round-trip probe failed')
-}
-// Boundary probe — write SQL must be rejected with a 422; the
-// read-only wall is the security property this capability rests on.
-let walled = false
-try {
-  await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
-    sql: "INSERT INTO legal_entities (legal_name) VALUES ('test-should-never-land')",
-    mode: 'unregulated',
-  })
-} catch (err) {
-  const status = (err as { _httpStatus?: number })._httpStatus
-  if (status !== 422) throw err
-  walled = true
-}
-if (!walled) {
-  throw new Error('executeSql accepted a write statement — the read-only wall is down')
-}
-```
-
-If the write probe ever lands in production, stop and escalate
-immediately with the accepted statement as evidence — a read-only
-boundary failure is a security regression, never a config problem.
-
-# Branches
-
-- **Generation failure.** If every configured LLM provider fails, `textToSql`
-  returns `422` (`AlveraApiError`) — `Text-to-SQL generation failed for all
-  providers (...)`. Surface it; do not retry blindly.
-- **Write SQL rejected.** `executeSql` with a non-read-only statement
-  (`INSERT`/`UPDATE`/`DELETE`/DDL) is rejected `422` — the read-only boundary is
-  enforced at the app `@deny` regex, a read-only DB transaction, and an EXPLAIN
-  preflight.
-- **Pagination.** Pass `page` / `page_size` to window large result sets;
-  `meta.total_count` / `meta.total_pages` describe the full set (`page_size` is
-  capped server-side).
-
-# Rollback
-
-Nothing to tear down — both calls are read-only (or generate-only). The
-`_setup/foundation.md` tenant + datalake are reset with `mix ecto.reset` on the
-platform; per-run `runSuffix` names avoid collisions across reruns.
-
-# Outcome
-
-A datalake becomes conversational: a prompt yields reviewable SQL with provider
-attribution and a plain-language explanation, that SQL runs read-only, and the
-page comes back either as a structured `{ data, meta }` envelope or a CSV export
-— all without any datalake row ever reaching the LLM.
-
-# See also
-
-- `.agent/datalakes.md` — "Talk to data" (`textToSql` / `executeSql` wire shape)
-  and §6 gotcha on the array-of-arrays `data`.
-- `.agent/ai_sandbox.md` — Layer 3 SQL boundary: how generation stays data-free
-  and execution stays read-only + mode-routed.
-- `integration-tests/tests/foundation/text-to-sql.test.ts` — the green vitest
-  these snippets are lifted from.