TypeScript SDK: Ai: analysis and transformation

ctx.ai() runs through the platform and consumes the workspace AI budget unless extract() has a verified cache hit. Every method is asynchronous. The platform selects the model; the script selects tier and effort.

Each example is a separate fragment inside async function run(ctx: Akmelo.Context): Promise<void>. Use await only for methods whose signature returns a Promise.

Before the first call

• A run can make up to eight AI calls. Send no more than 48 KB per call. For a large page, select the relevant fragment with the regular SDK methods first.
• Calls use the workspace AI budget. Actual usage appears in limits and the operation log; script execution time is accounted for separately. A verified extract() cache hit reuses a recipe without a new AI call.
• Do not include passwords, tokens, or personal data. Never send the result of ctx.credential() to AI.
• An offline agent cannot make an AI call without the platform. Keep the verified rules in code if collection must work autonomously.

Tier and effort

Defaults are small and medium; repair() defaults to large and high. The platform chooses the model, so a script does not specify its name.

Methods

• analyze()
• transform()
• find()
• repair()
• documentRows()
• extract()

analyze

ctx.ai().analyze(content, question, tier, effort) → Promise<string>

Answers a question about the supplied content as text. It may be wrong; verify facts before saving records.

const result = await ctx.ai().analyze('sku,price\nA-1,1250', 'Where is the price?');

transform

ctx.ai().transform(data, shape, instruction, tier, effort) → Promise<object>

Transforms an object into the requested shape and returns the transformed object itself. Validate required fields before ctx.emit().

const result = await ctx.ai().transform({ title: 'Product', price: '1 250 RUB' }, { title: 'string', price: 'number' });

find

ctx.ai().find(html, description, tier, effort) → Promise<{ selector: string, reason: string }>

Suggests a CSS selector for an element using HTML and a description. Returns selector and reason; verify the selector on the page.

const result = await ctx.ai().find('<button class="next">Next</button>', 'Next page button');

repair

ctx.ai().repair(source, error, goal, tier, effort) → Promise<string>

Returns a proposed fix for the supplied TypeScript source. It does not save or publish a new version. Review the result and run a trial.

const result = await ctx.ai().repair('async function run(ctx: Akmelo.Context): Promise<void> {}', 'Element not found', 'Collect the product title');

documentRows

ctx.ai().documentRows(document, sheet) → Promise<object>

Plans table rows and header from cell shapes without revealing values to an external model. Returns ready, needs_range, or incomplete; select the range manually for the latter two.

const document = await ctx.documents().fromUrl(ctx.param<string>('file_url'), 'prices.csv');
const result = await ctx.ai().documentRows(document, 0);
if (result.status === 'ready') {
  for (const row of result.records) ctx.emit(row);
}

extract

ctx.ai().extract(input, schema, options) → Promise<object>

Extract fresh records using a validated, cached table recipe. Supported inputs: a single HTML table without merged cells, a JSON record array, rows, or one complete document worksheet. Read CSV bytes with documents().fromBytes() first. Select multiple worksheets and ambiguous columns explicitly. Arbitrary page cards and unstructured PDF text require preprocessing.

const result = await ctx.ai().extract(
  [['SKU', 'Price'], ['A-1', '1,250.50']],
  { sku: { type: 'string', unique: true }, price: { type: 'decimal', min: 0 } },
  { key: 'supplier-prices', expected_rows: 1 },
);
for (const record of result.records) ctx.emit(record, String(record.sku));

records contains fresh values from this run even when the recipe came from cache. cache_hit and ai_used show whether the model was called. To map columns explicitly, set column on fields and header_row in options; indices start at zero. Check ambiguous column mappings manually.

If the service is unavailable or returns an invalid response, the SDK throws an error. Check a suggested selector, transformation, or code fix in a trial run before publishing the script.

Lifecycle · Limits and balance