@alvera-ai/platform-sdk 0.17.0 → 0.18.0

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

@@ -1,279 +0,0 @@
----
-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')
-}
-```
-
-## 006 — write the integration test
-
-End the build with a test you keep: re-read the agent and probe the one
-behaviour that is provable deterministically — the input gate. A real
-extraction (§004) needs a live provider behind the tool; the schema gate
-does not, which is exactly what makes it the durable test. This block
-runs live under `make validate-cookbook`.
-
-```typescript
-// Re-GET — the agent must be enabled, or every invoke will refuse.
-const { data: agentRow } = await api.aiAgents.get(tenantSlug, datalakeSlug, aiAgentId)
-if (agentRow.enabled !== true) {
-  throw new Error('expected enabled=true on agent read-back')
-}
-// Behavioural probe — the input_schema gate fires BEFORE the model:
-// a malformed input must 422 even with no working provider.
-let gateFired = false
-try {
-  await api.aiAgents.invoke(tenantSlug, datalakeSlug, aiAgentId, {
-    input: { wrong_field: 'test — no instructions here' },
-    files: [],
-  })
-} catch (err) {
-  const status = (err as { _httpStatus?: number })._httpStatus
-  if (status !== 422) throw err
-  gateFired = true
-}
-if (!gateFired) {
-  throw new Error('agent accepted input that violates its input_schema (expected 422)')
-}
-```
-
-If the gate stops firing in production, escalate with the
-accepted-payload evidence — don't loosen the `input_schema` to make the
-error go away.
-
-# 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