@acentric/llm 0.0.0-stage → 0.1.0

package/dist/convert/responses.js

@@ -0,0 +1,197 @@
+// The Responses format's side of conversion (OpenAI, Fireworks).
+import { isArray, isObject } from '../json.js';
+function texts(value) {
+    return isArray(value)
+        ? value.flatMap((part) => isObject(part) && typeof part['text'] === 'string' ? [part['text']] : [])
+        : [];
+}
+/** A reasoning item's readable text: its summary, or else its reasoning text. */
+function reasoningText(item) {
+    const summary = texts(item['summary']);
+    return (summary.length > 0 ? summary : texts(item['content'])).join('\n\n');
+}
+function message(content) {
+    return { type: 'message', role: 'assistant', content };
+}
+function outputText(text) {
+    return { type: 'output_text', text, annotations: [] };
+}
+/** Reasoning the target cannot use as it is: dropped, or kept as text. */
+function carryReasoning(text, context) {
+    if (context.reasoning === 'drop' || text === '') {
+        context.change('dropped', 'reasoning', text === '' ? 'no readable text' : 'bound to its model');
+        return undefined;
+    }
+    if (context.target.plainReasoning) {
+        context.change('rewritten', 'reasoning', 'as a plain reasoning item');
+        return { type: 'reasoning', summary: [{ type: 'summary_text', text }] };
+    }
+    context.change('rewritten', 'reasoning', 'as assistant text');
+    return message([outputText(text)]);
+}
+/** An item without the IDs and status its provider gave it. */
+function withoutIds(item) {
+    const { id: _id, status: _status, ...rest } = item;
+    return rest;
+}
+function string(value, otherwise) {
+    return typeof value === 'string' ? value : otherwise;
+}
+export const responsesConverter = {
+    sameFormat(items, sameProvider, context) {
+        const out = [];
+        for (const item of items) {
+            switch (item['type']) {
+                case 'message':
+                    out.push(sameProvider ? item : withoutIds(item));
+                    break;
+                case 'reasoning': {
+                    // A provider's own plain reasoning reads the same on any of its models.
+                    const encrypted = item['encrypted_content'];
+                    if (sameProvider && context.target.plainReasoning && !encrypted) {
+                        out.push(item);
+                        break;
+                    }
+                    const carried = carryReasoning(reasoningText(item), context);
+                    if (carried !== undefined)
+                        out.push(carried);
+                    break;
+                }
+                case 'function_call':
+                    out.push(sameProvider
+                        ? item
+                        : {
+                            type: 'function_call',
+                            call_id: string(item['call_id'], ''),
+                            name: string(item['name'], ''),
+                            arguments: string(item['arguments'], '{}'),
+                        });
+                    break;
+                case 'custom_tool_call':
+                    if (context.target.customTools) {
+                        out.push(sameProvider ? item : withoutIds(item));
+                    }
+                    else {
+                        const callId = item['call_id'];
+                        if (typeof callId === 'string')
+                            context.droppedCalls.add(callId);
+                        context.change('dropped', 'tool_call', `custom tool ${string(item['name'], '')}`);
+                    }
+                    break;
+                default:
+                    if (sameProvider)
+                        out.push(item);
+                    else
+                        context.change('dropped', 'provider_item', string(item['type'], 'unknown'));
+            }
+        }
+        return out;
+    },
+    read(items, context) {
+        const common = [];
+        for (const item of items) {
+            switch (item['type']) {
+                case 'message': {
+                    const content = item['content'];
+                    for (const part of isArray(content) ? content : []) {
+                        if (!isObject(part))
+                            continue;
+                        const text = part['text'];
+                        const refusal = part['refusal'];
+                        if (part['type'] === 'output_text' && typeof text === 'string') {
+                            const annotations = part['annotations'];
+                            if (isArray(annotations) && annotations.length > 0) {
+                                context.change('dropped', 'citations', `${annotations.length} annotations`);
+                            }
+                            common.push({ kind: 'text', text });
+                        }
+                        else if (part['type'] === 'refusal' && typeof refusal === 'string') {
+                            common.push({ kind: 'refusal', text: refusal });
+                        }
+                        else {
+                            common.push({ kind: 'other', type: `message ${string(part['type'], 'part')}` });
+                        }
+                    }
+                    break;
+                }
+                case 'reasoning':
+                    common.push({ kind: 'reasoning', text: reasoningText(item) });
+                    break;
+                case 'function_call':
+                    common.push({
+                        kind: 'call',
+                        id: string(item['call_id'], ''),
+                        name: string(item['name'], ''),
+                        arguments: string(item['arguments'], '{}'),
+                    });
+                    break;
+                case 'custom_tool_call':
+                    common.push({
+                        kind: 'custom_call',
+                        id: string(item['call_id'], ''),
+                        name: string(item['name'], ''),
+                        input: string(item['input'], ''),
+                    });
+                    break;
+                default:
+                    common.push({ kind: 'other', type: string(item['type'], 'unknown') });
+            }
+        }
+        return common;
+    },
+    write(items, context) {
+        const out = [];
+        let open = [];
+        const close = () => {
+            if (open.length > 0)
+                out.push(message(open));
+            open = [];
+        };
+        for (const item of items) {
+            switch (item.kind) {
+                case 'text':
+                    open.push(outputText(item.text));
+                    break;
+                case 'refusal':
+                    open.push({ type: 'refusal', refusal: item.text });
+                    break;
+                case 'reasoning': {
+                    close();
+                    const carried = carryReasoning(item.text, context);
+                    if (carried !== undefined)
+                        out.push(carried);
+                    break;
+                }
+                case 'call':
+                    close();
+                    out.push({
+                        type: 'function_call',
+                        call_id: context.callId(item.id),
+                        name: item.name,
+                        arguments: item.arguments,
+                    });
+                    break;
+                case 'custom_call':
+                    close();
+                    if (context.target.customTools) {
+                        out.push({
+                            type: 'custom_tool_call',
+                            call_id: context.callId(item.id),
+                            name: item.name,
+                            input: item.input,
+                        });
+                    }
+                    else {
+                        context.droppedCalls.add(item.id);
+                        context.change('dropped', 'tool_call', `custom tool ${item.name}`);
+                    }
+                    break;
+                case 'other':
+                    context.change('dropped', 'provider_item', item.type);
+            }
+        }
+        close();
+        return out;
+    },
+};
+//# sourceMappingURL=responses.js.map

package/dist/convert/responses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.js","sourceRoot":"","sources":["../../src/convert/responses.ts"],"names":[],"mappings":"AAAA,iEAAiE;AAIjE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG/C,SAAS,KAAK,CAAC,KAAuB;IACpC,OAAO,OAAO,CAAC,KAAK,CAAC;QACnB,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CACrB,QAAQ,CAAC,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CACzE;QACH,CAAC,CAAC,EAAE,CAAC;AACT,CAAC;AAED,iFAAiF;AACjF,SAAS,aAAa,CAAC,IAAgB;IACrC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IACvC,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,OAAO,CAAC,OAAqB;IACpC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;AACzD,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;AACxD,CAAC;AAED,0EAA0E;AAC1E,SAAS,cAAc,CAAC,IAAY,EAAE,OAAgB;IACpD,IAAI,OAAO,CAAC,SAAS,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QAChD,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,WAAW,EAAE,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC;QAChG,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;QAClC,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,WAAW,EAAE,2BAA2B,CAAC,CAAC;QACtE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAC1E,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,WAAW,EAAE,mBAAmB,CAAC,CAAC;IAC9D,OAAO,OAAO,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAED,+DAA+D;AAC/D,SAAS,UAAU,CAAC,IAAgB;IAClC,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IACnD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,MAAM,CAAC,KAAuB,EAAE,SAAiB;IACxD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAoB;IACjD,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO;QACrC,MAAM,GAAG,GAAiB,EAAE,CAAC;QAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,QAAQ,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;gBACrB,KAAK,SAAS;oBACZ,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;oBACjD,MAAM;gBACR,KAAK,WAAW,CAAC,CAAC,CAAC;oBACjB,wEAAwE;oBACxE,MAAM,SAAS,GAAG,IAAI,CAAC,mBAAmB,CAAC,CAAC;oBAC5C,IAAI,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,cAAc,IAAI,CAAC,SAAS,EAAE,CAAC;wBAChE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;wBACf,MAAM;oBACR,CAAC;oBACD,MAAM,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;oBAC7D,IAAI,OAAO,KAAK,SAAS;wBAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;oBAC7C,MAAM;gBACR,CAAC;gBACD,KAAK,eAAe;oBAClB,GAAG,CAAC,IAAI,CACN,YAAY;wBACV,CAAC,CAAC,IAAI;wBACN,CAAC,CAAC;4BACE,IAAI,EAAE,eAAe;4BACrB,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;4BACpC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;4BAC9B,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC;yBAC3C,CACN,CAAC;oBACF,MAAM;gBACR,KAAK,kBAAkB;oBACrB,IAAI,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;wBAC/B,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;oBACnD,CAAC;yBAAM,CAAC;wBACN,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;wBAC/B,IAAI,OAAO,MAAM,KAAK,QAAQ;4BAAE,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;wBACjE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,WAAW,EAAE,eAAe,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;oBACpF,CAAC;oBACD,MAAM;gBACR;oBACE,IAAI,YAAY;wBAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;;wBAC5B,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,eAAe,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;YACrF,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,IAAI,CAAC,KAAK,EAAE,OAAO;QACjB,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,QAAQ,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;gBACrB,KAAK,SAAS,CAAC,CAAC,CAAC;oBACf,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;oBAChC,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;wBACnD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;4BAAE,SAAS;wBAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;wBAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;wBAChC,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,aAAa,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;4BAC/D,MAAM,WAAW,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;4BACxC,IAAI,OAAO,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gCACnD,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,WAAW,EAAE,GAAG,WAAW,CAAC,MAAM,cAAc,CAAC,CAAC;4BAC9E,CAAC;4BACD,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;wBACtC,CAAC;6BAAM,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,SAAS,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;4BACrE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;wBAClD,CAAC;6BAAM,CAAC;4BACN,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;wBAClF,CAAC;oBACH,CAAC;oBACD,MAAM;gBACR,CAAC;gBACD,KAAK,WAAW;oBACd,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;oBAC9D,MAAM;gBACR,KAAK,eAAe;oBAClB,MAAM,CAAC,IAAI,CAAC;wBACV,IAAI,EAAE,MAAM;wBACZ,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;wBAC/B,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;wBAC9B,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC;qBAC3C,CAAC,CAAC;oBACH,MAAM;gBACR,KAAK,kBAAkB;oBACrB,MAAM,CAAC,IAAI,CAAC;wBACV,IAAI,EAAE,aAAa;wBACnB,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;wBAC/B,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;wBAC9B,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;qBACjC,CAAC,CAAC;oBACH,MAAM;gBACR;oBACE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC;YAC1E,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,KAAK,EAAE,OAAO;QAClB,MAAM,GAAG,GAAiB,EAAE,CAAC;QAC7B,IAAI,IAAI,GAAiB,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,GAAG,EAAE;YACjB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;gBAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;YAC7C,IAAI,GAAG,EAAE,CAAC;QACZ,CAAC,CAAC;QACF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;gBAClB,KAAK,MAAM;oBACT,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;oBACjC,MAAM;gBACR,KAAK,SAAS;oBACZ,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;oBACnD,MAAM;gBACR,KAAK,WAAW,CAAC,CAAC,CAAC;oBACjB,KAAK,EAAE,CAAC;oBACR,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;oBACnD,IAAI,OAAO,KAAK,SAAS;wBAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;oBAC7C,MAAM;gBACR,CAAC;gBACD,KAAK,MAAM;oBACT,KAAK,EAAE,CAAC;oBACR,GAAG,CAAC,IAAI,CAAC;wBACP,IAAI,EAAE,eAAe;wBACrB,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;wBAChC,IAAI,EAAE,IAAI,CAAC,IAAI;wBACf,SAAS,EAAE,IAAI,CAAC,SAAS;qBAC1B,CAAC,CAAC;oBACH,MAAM;gBACR,KAAK,aAAa;oBAChB,KAAK,EAAE,CAAC;oBACR,IAAI,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;wBAC/B,GAAG,CAAC,IAAI,CAAC;4BACP,IAAI,EAAE,kBAAkB;4BACxB,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;4BAChC,IAAI,EAAE,IAAI,CAAC,IAAI;4BACf,KAAK,EAAE,IAAI,CAAC,KAAK;yBAClB,CAAC,CAAC;oBACL,CAAC;yBAAM,CAAC;wBACN,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;wBAClC,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,WAAW,EAAE,eAAe,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;oBACrE,CAAC;oBACD,MAAM;gBACR,KAAK,OAAO;oBACV,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,eAAe,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;YAC1D,CAAC;QACH,CAAC;QACD,KAAK,EAAE,CAAC;QACR,OAAO,GAAG,CAAC;IACb,CAAC;CACF,CAAC"}

package/dist/convert/types.d.ts

@@ -0,0 +1,88 @@
+import type { JsonObject } from '@acentric/types';
+import type { ApiFormat, Provider } from '../providers.js';
+/** The provider and model a conversation is converted for. */
+export type ConvertTarget<P extends Provider = Provider> = {
+    readonly provider: P;
+    readonly model: string;
+};
+export type ConvertOptions = {
+    /**
+     * Reasoning the target cannot use as it is: another model's signed or
+     * encrypted reasoning, and any reasoning sent to another provider. `drop`,
+     * the default, leaves it out. `text` keeps its readable text: as a plain
+     * reasoning item where the target reads one (Fireworks), otherwise as
+     * assistant text. Reasoning with no readable text is dropped either way.
+     */
+    readonly reasoning?: 'drop' | 'text';
+};
+/** One thing `convert` dropped or rewrote. */
+export type ConversionChange = {
+    /** The message's index in the input. */
+    readonly index: number;
+    readonly action: 'dropped' | 'rewritten';
+    readonly what: 'message' | 'reasoning' | 'tool_call' | 'tool_result' | 'tool_call_id' | 'tool_arguments' | 'provider_item' | 'citations' | 'refusal' | 'part' | 'part_option';
+    /** What exactly, for logs, such as `web_search_call` or `cache_control`. */
+    readonly detail: string;
+};
+/** The converted messages, and every change made to get them. */
+export type Conversion<M> = {
+    readonly messages: M[];
+    readonly changes: readonly ConversionChange[];
+};
+/** What a target provider takes, as far as conversion cares. */
+export type Capabilities = {
+    readonly api: ApiFormat;
+    /** Free-form custom tools and their calls. */
+    readonly customTools: boolean;
+    /** File parts. */
+    readonly files: boolean;
+    /** Images and files by a provider's file ID. */
+    readonly fileIds: boolean;
+    /** Reads reasoning items that hold only text. */
+    readonly plainReasoning: boolean;
+};
+export type Target = Capabilities & ConvertTarget;
+/** One assistant item read without its format, on its way to another format. Never stored. */
+export type Common = {
+    readonly kind: 'text';
+    readonly text: string;
+} | {
+    readonly kind: 'refusal';
+    readonly text: string;
+} | {
+    readonly kind: 'reasoning';
+    readonly text: string;
+} | {
+    readonly kind: 'call';
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: string;
+} | {
+    readonly kind: 'custom_call';
+    readonly id: string;
+    readonly name: string;
+    readonly input: string;
+} | {
+    readonly kind: 'other';
+    readonly type: string;
+};
+/** What a conversation's conversion shares from message to message. */
+export type Context = {
+    readonly target: Target;
+    readonly reasoning: 'drop' | 'text';
+    /** Call IDs whose calls were dropped; their results are dropped too. */
+    readonly droppedCalls: Set<string>;
+    change(action: ConversionChange['action'], what: ConversionChange['what'], detail: string): void;
+    /** A call ID as the target takes it. Results are mapped the same way. */
+    callId(id: string): string;
+};
+/** One API format's side of conversion. */
+export type FormatConverter = {
+    /** The items of a message from another provider or model in this same format. */
+    sameFormat(items: readonly JsonObject[], sameProvider: boolean, context: Context): JsonObject[];
+    /** The items of a message in this format, read for another format. */
+    read(items: readonly JsonObject[], context: Context): Common[];
+    /** Common items written as this format's. */
+    write(items: readonly Common[], context: Context): JsonObject[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/convert/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/convert/types.ts"],"names":[],"mappings":"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"}

package/dist/convert/types.js

@@ -0,0 +1,3 @@
+// The shapes conversion works with.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/convert/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/convert/types.ts"],"names":[],"mappings":"AAAA,oCAAoC"}

package/dist/cost.d.ts

@@ -0,0 +1,18 @@
+import type { ModelPricing } from './model.js';
+import type { Usage, UsageCost } from './usage.js';
+export type CostOptions = {
+    /**
+     * Scales every price, for where and how the request ran, such as 0.5 for a
+     * batch or 1.1 for inference kept in the US. Defaults to 1.
+     */
+    readonly multiplier?: number;
+    /** The part of `usage.cacheWrite` written for an hour, priced at `cacheWrite1h`. */
+    readonly cacheWrite1h?: number;
+};
+/**
+ * The estimated cost, or undefined when it cannot be known: no prices, a count
+ * that is missing, or tokens in a part the prices do not cover. The prices for
+ * the whole request are those of the highest tier its prompt is over.
+ */
+export declare function estimateCost(usage: Usage, pricing: ModelPricing | undefined, { multiplier, cacheWrite1h }?: CostOptions): UsageCost | undefined;
+//# sourceMappingURL=cost.d.ts.map

package/dist/cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../src/cost.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,MAAM,WAAW,GAAG;IACxB;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,YAAY,GAAG,SAAS,EACjC,EAAE,UAAc,EAAE,YAAgB,EAAE,GAAE,WAAgB,GACrD,SAAS,GAAG,SAAS,CA+BvB"}

package/dist/cost.js

@@ -0,0 +1,49 @@
+// What a completion cost, estimated from its tokens and the model's prices,
+// for providers that do not say what they charged.
+/**
+ * The estimated cost, or undefined when it cannot be known: no prices, a count
+ * that is missing, or tokens in a part the prices do not cover. The prices for
+ * the whole request are those of the highest tier its prompt is over.
+ */
+export function estimateCost(usage, pricing, { multiplier = 1, cacheWrite1h = 0 } = {}) {
+    const { totalInput, input, output, cacheRead, cacheWrite } = usage;
+    if (pricing === undefined || totalInput === undefined || input === undefined)
+        return undefined;
+    if (output === undefined)
+        return undefined;
+    if (cacheWrite1h > (cacheWrite ?? 0))
+        return undefined;
+    let prices = pricing.base;
+    for (const tier of pricing.tiers ?? []) {
+        if (totalInput > tier.aboveInputTokens)
+            prices = tier.cost;
+    }
+    const read = part(cacheRead, prices.cacheRead);
+    const shortWrite = part(cacheWrite === undefined ? undefined : cacheWrite - cacheWrite1h, prices.cacheWrite);
+    const hourWrite = part(cacheWrite1h, prices.cacheWrite1h);
+    if (read === null || shortWrite === null || hourWrite === null)
+        return undefined;
+    const written = shortWrite === undefined && hourWrite === undefined
+        ? undefined
+        : (shortWrite ?? 0) + (hourWrite ?? 0);
+    const parts = {
+        input: price(input, prices.input) * multiplier,
+        output: price(output, prices.output) * multiplier,
+        ...(read === undefined ? {} : { cacheRead: read * multiplier }),
+        ...(written === undefined ? {} : { cacheWrite: written * multiplier }),
+    };
+    const total = parts.input + parts.output + (parts.cacheRead ?? 0) + (parts.cacheWrite ?? 0);
+    return { source: 'estimated', ...parts, total };
+}
+/** The price of some tokens: undefined when there are none to price, null when they have no price. */
+function part(tokens, perMillion) {
+    if (tokens === undefined)
+        return undefined;
+    if (tokens === 0)
+        return perMillion === undefined ? undefined : 0;
+    return perMillion === undefined ? null : price(tokens, perMillion);
+}
+function price(tokens, perMillion) {
+    return (tokens * perMillion) / 1_000_000;
+}
+//# sourceMappingURL=cost.js.map

package/dist/cost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.js","sourceRoot":"","sources":["../src/cost.ts"],"names":[],"mappings":"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"}

package/dist/failure.d.ts

@@ -0,0 +1,90 @@
+import type { Json, Outcome } from '@acentric/types';
+import type { Usage } from './usage.js';
+/** Whether each kind is worth retrying when the error does not say otherwise. */
+declare const RETRYABLE: {
+    /** The client, the gateway or the provider refused the request. */
+    readonly invalid_request: false;
+    /** Credentials missing, not valid or not allowed. */
+    readonly auth: false;
+    /** Throttled; see `retryAfterMs`. */
+    readonly rate_limited: true;
+    /** Out of credits or over a billing limit. */
+    readonly quota_exceeded: false;
+    /** The prompt is too long for the model. */
+    readonly context_overflow: false;
+    /** A provider's safety policy refused it; sending it again as it is will not help. */
+    readonly policy_violation: false;
+    /** An unknown model, or a previous response that expired or is not valid; see `providerParam`. */
+    readonly not_found: false;
+    /** The provider is out of capacity. */
+    readonly overloaded: true;
+    /** Any other failure at the provider. */
+    readonly provider_error: true;
+    /** The provider answered with something that cannot be read. */
+    readonly invalid_response: false;
+    /** The provider or the gateway could not be reached. */
+    readonly network_error: true;
+    /** The call took longer than allowed. */
+    readonly timeout: true;
+    /** The handler's signal fired: the effect was cancelled, aborted or timed out. */
+    readonly cancelled: false;
+    /** A bug in the gateway. */
+    readonly internal_error: false;
+};
+export type LlmFailureKind = keyof typeof RETRYABLE;
+export declare const LLM_FAILURE_KINDS: readonly LlmFailureKind[];
+/** A failed completion as Json: what an LlmError's toJSON() returns, and what step reads. */
+export type LlmFailure = {
+    /** Always `LlmError`, which tells an LLM failure from other thrown values. */
+    readonly name: 'LlmError';
+    readonly message: string;
+    readonly kind: LlmFailureKind;
+    /** Whether sending the same request again may succeed. */
+    readonly retryable: boolean;
+    /** Left out for a failure before a provider was chosen. */
+    readonly provider?: string;
+    readonly providerCode?: string;
+    readonly providerType?: string;
+    /** The request field the provider blamed, such as `previous_response_id`. */
+    readonly providerParam?: string;
+    /** The provider's error as it answered, cut short when long. */
+    readonly providerError?: Json;
+    /** The provider's HTTP status, not the gateway's. */
+    readonly httpStatus?: number;
+    /** How long the provider asked to wait before trying again, in milliseconds. */
+    readonly retryAfterMs?: number;
+    /** The provider's request ID, for its support. */
+    readonly requestId?: string;
+    /** The provider's response ID, when a response was created before it failed. */
+    readonly responseId?: string;
+    /** Tokens the provider reported, and may bill, for a failed generation. */
+    readonly usage?: Usage;
+};
+type Detail = Omit<LlmFailure, 'name' | 'message' | 'kind' | 'retryable'>;
+/** What an LlmError is made from. `retryable` defaults by kind. */
+export type LlmErrorOptions = Detail & {
+    readonly kind: LlmFailureKind;
+    readonly retryable?: boolean;
+};
+/** A failed completion. The client throws it; a runner reports its toJSON() to step. */
+export declare class LlmError extends Error {
+    readonly name = "LlmError";
+    readonly failure: LlmFailure;
+    constructor(message: string, options: LlmErrorOptions);
+    get kind(): LlmFailureKind;
+    get retryable(): boolean;
+    /** The failure as Json, which a runner reports as the effect's error. */
+    toJSON(): LlmFailure;
+    /** An LlmError from its Json, such as a gateway's answer. */
+    static fromJSON({ message, kind, retryable, ...detail }: LlmFailure): LlmError;
+}
+/** Whether a value is an LlmFailure, such as a failed effect's error. */
+export declare function isLlmFailure(value: Json | undefined): value is LlmFailure;
+/**
+ * The LLM failure in an effect's outcome, or null: for a result, for a
+ * failure the runner reported itself (a timeout, a crash) and for one thrown
+ * by something other than this package.
+ */
+export declare function llmFailure(outcome: Outcome): LlmFailure | null;
+export {};
+//# sourceMappingURL=failure.d.ts.map

package/dist/failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure.d.ts","sourceRoot":"","sources":["../src/failure.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAGrD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,iFAAiF;AACjF,QAAA,MAAM,SAAS;IACb,mEAAmE;;IAEnE,qDAAqD;;IAErD,qCAAqC;;IAErC,8CAA8C;;IAE9C,4CAA4C;;IAE5C,sFAAsF;;IAEtF,kGAAkG;;IAElG,uCAAuC;;IAEvC,yCAAyC;;IAEzC,gEAAgE;;IAEhE,wDAAwD;;IAExD,yCAAyC;;IAEzC,kFAAkF;;IAElF,4BAA4B;;CAE2B,CAAC;AAE1D,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,SAAS,CAAC;AAEpD,eAAO,MAAM,iBAAiB,EAAE,SAAS,cAAc,EAEtD,CAAC;AAEF,6FAA6F;AAC7F,MAAM,MAAM,UAAU,GAAG;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,gEAAgE;IAChE,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,CAAC;IAC9B,qDAAqD;IACrD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,gFAAgF;IAChF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB,CAAC;AAEF,KAAK,MAAM,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAE1E,mEAAmE;AACnE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG;IACrC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAeF,wFAAwF;AACxF,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAkB,IAAI,cAAc;IACpC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe;IAcrD,IAAI,IAAI,IAAI,cAAc,CAEzB;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,yEAAyE;IACzE,MAAM,IAAI,UAAU;IAIpB,6DAA6D;IAC7D,MAAM,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,EAAE,UAAU,GAAG,QAAQ;CAI/E;AAOD,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,IAAI,GAAG,SAAS,GAAG,KAAK,IAAI,UAAU,CAUzE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAI9D"}

package/dist/failure.js

@@ -0,0 +1,111 @@
+// Every way a completion can fail, as an error the client throws and as the
+// Json a step reads. An LlmError's toJSON() is what a runner reports as the
+// failure's error (RUNNERS.md §8), so step learns its kind, whether a retry
+// may help and how long to wait. Retrying is the agent's decision.
+import { isObject } from './json.js';
+/** Whether each kind is worth retrying when the error does not say otherwise. */
+const RETRYABLE = {
+    /** The client, the gateway or the provider refused the request. */
+    invalid_request: false,
+    /** Credentials missing, not valid or not allowed. */
+    auth: false,
+    /** Throttled; see `retryAfterMs`. */
+    rate_limited: true,
+    /** Out of credits or over a billing limit. */
+    quota_exceeded: false,
+    /** The prompt is too long for the model. */
+    context_overflow: false,
+    /** A provider's safety policy refused it; sending it again as it is will not help. */
+    policy_violation: false,
+    /** An unknown model, or a previous response that expired or is not valid; see `providerParam`. */
+    not_found: false,
+    /** The provider is out of capacity. */
+    overloaded: true,
+    /** Any other failure at the provider. */
+    provider_error: true,
+    /** The provider answered with something that cannot be read. */
+    invalid_response: false,
+    /** The provider or the gateway could not be reached. */
+    network_error: true,
+    /** The call took longer than allowed. */
+    timeout: true,
+    /** The handler's signal fired: the effect was cancelled, aborted or timed out. */
+    cancelled: false,
+    /** A bug in the gateway. */
+    internal_error: false,
+};
+export const LLM_FAILURE_KINDS = Object.keys(RETRYABLE).filter((kind) => kind in RETRYABLE);
+const DETAIL = [
+    'provider',
+    'providerCode',
+    'providerType',
+    'providerParam',
+    'providerError',
+    'httpStatus',
+    'retryAfterMs',
+    'requestId',
+    'responseId',
+    'usage',
+];
+/** A failed completion. The client throws it; a runner reports its toJSON() to step. */
+export class LlmError extends Error {
+    name = 'LlmError';
+    failure;
+    constructor(message, options) {
+        super(message);
+        const { kind, retryable, ...detail } = options;
+        const failure = {
+            name: 'LlmError',
+            message,
+            kind,
+            retryable: retryable ?? RETRYABLE[kind],
+        };
+        for (const key of DETAIL)
+            if (detail[key] !== undefined)
+                failure[key] = detail[key];
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+        this.failure = failure;
+    }
+    get kind() {
+        return this.failure.kind;
+    }
+    get retryable() {
+        return this.failure.retryable;
+    }
+    /** The failure as Json, which a runner reports as the effect's error. */
+    toJSON() {
+        return this.failure;
+    }
+    /** An LlmError from its Json, such as a gateway's answer. */
+    static fromJSON({ message, kind, retryable, ...detail }) {
+        const options = { ...omitName(detail), kind, retryable };
+        return new LlmError(message, options);
+    }
+}
+function omitName(detail) {
+    const { name: _name, ...rest } = detail;
+    return rest;
+}
+/** Whether a value is an LlmFailure, such as a failed effect's error. */
+export function isLlmFailure(value) {
+    if (!isObject(value))
+        return false;
+    const { name, message, kind, retryable } = value;
+    return (name === 'LlmError' &&
+        typeof message === 'string' &&
+        typeof kind === 'string' &&
+        kind in RETRYABLE &&
+        typeof retryable === 'boolean');
+}
+/**
+ * The LLM failure in an effect's outcome, or null: for a result, for a
+ * failure the runner reported itself (a timeout, a crash) and for one thrown
+ * by something other than this package.
+ */
+export function llmFailure(outcome) {
+    if (!('failed' in outcome))
+        return null;
+    const { error } = outcome.failed;
+    return isLlmFailure(error) ? error : null;
+}
+//# sourceMappingURL=failure.js.map

package/dist/failure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure.js","sourceRoot":"","sources":["../src/failure.ts"],"names":[],"mappings":"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"}

package/dist/fields.d.ts

@@ -0,0 +1,14 @@
+import type { Json } from '@acentric/types';
+/**
+ * Fields merged as they are into the provider's own block for a shared shape,
+ * such as Anthropic's `cache_control` on a content part or OpenAI's `detail`
+ * on an image. The client never interprets them.
+ */
+export type ProviderFields = {
+    readonly [key: string]: Json;
+};
+/** The application's own attributes on a part or message. Never sent to a provider. */
+export type Metadata = {
+    readonly [key: string]: Json;
+};
+//# sourceMappingURL=fields.d.ts.map

package/dist/fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../src/fields.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE9D,uFAAuF;AACvF,MAAM,MAAM,QAAQ,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC"}

package/dist/fields.js

@@ -0,0 +1,3 @@
+// Open records of Json: fields a shape passes through without interpreting.
+export {};
+//# sourceMappingURL=fields.js.map

package/dist/fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.js","sourceRoot":"","sources":["../src/fields.ts"],"names":[],"mappings":"AAAA,4EAA4E"}