@thinwrap/llm 1.0.0

package/dist/esm/providers/anthropic/anthropic.connector.js

@@ -0,0 +1,423 @@
+import { appendPassthroughQuery, BaseConnector, parseSSEStream } from '../../base/base.connector.js';
+import { ConnectorError } from '../../types/index.js';
+const DEFAULT_BASE_URL = 'https://api.anthropic.com/v1';
+const DEFAULT_VERSION = '2023-06-01';
+const DEFAULT_MAX_TOKENS = 4096;
+/**
+ * Native adapter for the Anthropic **Messages API** (`POST /v1/messages`).
+ * Anthropic is structurally different from OpenAI Chat Completions — different
+ * auth, a top-level `system`, typed content blocks, tool results carried inside
+ * a user turn, `stop_sequences`, and Anthropic-shaped SSE events — so this is a
+ * full translation layer, not an OpenAI passthrough. It emits the identical
+ * normalized `ChatResult` / `ChatStreamDelta` / `ConnectorError` as every other
+ * connector, so it is drop-in swappable via the `Chat` facade.
+ *
+ * Not normalized here (per D2/D4, surfaced via `raw` or `_passthrough`, never
+ * emulated): `responseFormat` (Anthropic has no `response_format` — use
+ * tool-based structured output via `_passthrough`); reasoning CoT output
+ * (`thinking` blocks land in `raw`); prompt caching (`cache_control` via
+ * `_passthrough`, cached-token counts in `raw`).
+ */
+export class AnthropicConnector extends BaseConnector {
+    constructor(config) {
+        super(config.fetch);
+        this.id = 'anthropic';
+        this.config = config;
+        this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    }
+    async complete(input) {
+        const body = this.buildRequest(input, false);
+        const response = await this.sendPostJson(appendPassthroughQuery(`${this.baseUrl}/messages`, input._passthrough?.query), body, this.authHeaders(input), input.signal);
+        if (!response.ok) {
+            const errBody = await response.json().catch(() => null);
+            throw this.mapVendorError(response.status, errBody, response.headers);
+        }
+        const json = this.requireDecodedBody((await response.json().catch(() => null)), response.status);
+        return this.parseResult(json, input.model);
+    }
+    async *stream(input) {
+        const body = this.buildRequest(input, true);
+        const response = await this.invokeFetch(appendPassthroughQuery(`${this.baseUrl}/messages`, input._passthrough?.query), {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Accept: 'text/event-stream',
+                ...this.authHeaders(input),
+            },
+            body: JSON.stringify(body),
+            signal: input.signal,
+        });
+        if (!response.ok) {
+            const errBody = await response.json().catch(() => null);
+            throw this.mapVendorError(response.status, errBody, response.headers);
+        }
+        let inputTokens = 0;
+        // Anthropic indexes content blocks (text + tool_use interleaved), so the
+        // first tool call can arrive at block index 1. Normalize to a 0-based
+        // tool-call-relative index to match OpenAI-compat's emitted surface.
+        let nextToolIndex = 0;
+        const toolIndexByBlock = new Map();
+        for await (const raw of parseSSEStream(response)) {
+            const evt = raw;
+            switch (evt.type) {
+                case 'error':
+                    // A provider error emitted mid-stream (e.g. `overloaded_error`) — throw
+                    // instead of silently ending the stream with no finishReason.
+                    throw this.mapVendorError(errorEventStatus(evt.error?.type), evt, new Headers());
+                case 'message_start':
+                    inputTokens = evt.message?.usage?.input_tokens ?? 0;
+                    break;
+                case 'content_block_start': {
+                    const cb = evt.content_block;
+                    if (cb?.type === 'tool_use') {
+                        const toolIndex = nextToolIndex++;
+                        toolIndexByBlock.set(evt.index ?? 0, toolIndex);
+                        yield {
+                            toolCallDelta: {
+                                index: toolIndex,
+                                ...(cb.id ? { id: cb.id } : {}),
+                                ...(cb.name ? { functionName: cb.name } : {}),
+                            },
+                            raw: evt,
+                        };
+                    }
+                    break;
+                }
+                case 'content_block_delta': {
+                    const d = evt.delta;
+                    if (d?.type === 'text_delta' && typeof d.text === 'string' && d.text.length > 0) {
+                        yield { contentDelta: d.text, raw: evt };
+                    }
+                    else if (d?.type === 'input_json_delta' && typeof d.partial_json === 'string') {
+                        const toolIndex = toolIndexByBlock.get(evt.index ?? 0) ?? 0;
+                        yield { toolCallDelta: { index: toolIndex, argumentsDelta: d.partial_json }, raw: evt };
+                    }
+                    // thinking_delta → CoT output not normalized (D2); available only via raw event stream
+                    break;
+                }
+                case 'message_delta': {
+                    const out = { raw: evt };
+                    if (evt.delta?.stop_reason)
+                        out.finishReason = mapStopReason(evt.delta.stop_reason);
+                    const outputTokens = evt.usage?.output_tokens ?? 0;
+                    out.usage = { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens };
+                    yield out;
+                    break;
+                }
+                // message_stop / content_block_stop / ping → ignored
+            }
+        }
+    }
+    authHeaders(input) {
+        return {
+            'x-api-key': this.config.apiKey,
+            'anthropic-version': this.config.anthropicVersion ?? DEFAULT_VERSION,
+            ...this.config.headers,
+            ...input._passthrough?.headers,
+        };
+    }
+    buildRequest(input, stream) {
+        const { system, messages } = splitMessages(input.messages);
+        const thinking = input.reasoning
+            ? { type: 'enabled', budget_tokens: effortBudget(input.reasoning.effort) }
+            : undefined;
+        const budget = thinking ? thinking.budget_tokens : 0;
+        const callerSetMax = input.maxOutputTokens !== undefined;
+        let maxTokens = input.maxOutputTokens ?? this.config.defaultMaxTokens ?? DEFAULT_MAX_TOKENS;
+        if (thinking && maxTokens <= budget) {
+            // Anthropic requires max_tokens > thinking.budget_tokens (max_tokens is the
+            // TOTAL, thinking included). If the CALLER set an explicit maxOutputTokens
+            // below the budget, silently inflating it would spend past their cap — throw
+            // so they lower reasoning.effort or raise the cap. Only a non-explicit default
+            // is inflated to keep the request valid.
+            if (callerSetMax) {
+                throw new ConnectorError({
+                    message: `maxOutputTokens (${maxTokens}) must be greater than the reasoning budget (${budget}) for extended thinking — raise maxOutputTokens or lower reasoning.effort`,
+                    statusCode: null,
+                    providerCode: 'invalid_request',
+                });
+            }
+            maxTokens = budget + DEFAULT_MAX_TOKENS;
+        }
+        const body = {
+            model: input.model,
+            max_tokens: maxTokens,
+            messages,
+        };
+        if (system)
+            body.system = system;
+        if (input.tools && input.tools.length > 0) {
+            body.tools = input.tools.map((t) => ({
+                name: t.function.name,
+                ...(t.function.description ? { description: t.function.description } : {}),
+                input_schema: t.function.parameters ?? { type: 'object', properties: {} },
+            }));
+        }
+        if (input.toolChoice !== undefined) {
+            const tc = mapToolChoice(input.toolChoice);
+            if (tc)
+                body.tool_choice = tc;
+        }
+        if (thinking) {
+            // Extended thinking requires temperature=1 and disallows top_p/top_k — omit sampling.
+            body.thinking = thinking;
+        }
+        else {
+            if (input.temperature !== undefined)
+                body.temperature = input.temperature;
+            if (input.topP !== undefined)
+                body.top_p = input.topP;
+        }
+        if (input.stop !== undefined) {
+            body.stop_sequences = Array.isArray(input.stop) ? input.stop : [input.stop];
+        }
+        // NOTE: `responseFormat` is intentionally NOT mapped — Anthropic has no
+        // `response_format`; structured output is via tools / `_passthrough`.
+        if (stream)
+            body.stream = true;
+        if (input._passthrough?.body)
+            Object.assign(body, input._passthrough.body);
+        return body;
+    }
+    parseResult(json, requestedModel) {
+        const blocks = json?.content ?? [];
+        let text = '';
+        const toolCalls = [];
+        for (const b of blocks) {
+            if (b.type === 'text' && typeof b.text === 'string') {
+                text += b.text;
+            }
+            else if (b.type === 'tool_use') {
+                toolCalls.push({
+                    id: b.id ?? '',
+                    type: 'function',
+                    function: { name: b.name ?? '', arguments: JSON.stringify(b.input ?? {}) },
+                });
+            }
+            // thinking blocks → raw only (D2)
+        }
+        const inputTokens = json?.usage?.input_tokens ?? 0;
+        const outputTokens = json?.usage?.output_tokens ?? 0;
+        return {
+            message: {
+                role: 'assistant',
+                content: text.length > 0 ? text : null,
+                ...(toolCalls.length > 0 ? { toolCalls } : {}),
+            },
+            finishReason: mapStopReason(json?.stop_reason),
+            usage: { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens },
+            model: json?.model ?? requestedModel,
+            raw: json,
+        };
+    }
+    mapVendorError(status, body, headers) {
+        const message = extractAnthropicError(body) ?? `HTTP ${status}`;
+        const providerCode = mapStatusToProviderCode(status, message);
+        const retryAfter = headers.get('retry-after');
+        const cause = { raw: body ?? null };
+        if (retryAfter != null) {
+            cause.retryAfter = retryAfter;
+            const secs = parseRetryAfterSeconds(retryAfter);
+            if (secs != null)
+                cause.retryAfterSeconds = secs;
+        }
+        return new ConnectorError({
+            message,
+            statusCode: status,
+            providerCode,
+            providerMessage: message,
+            cause,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Module-private mappers
+// ---------------------------------------------------------------------------
+function splitMessages(messages) {
+    let system;
+    const out = [];
+    for (const m of messages) {
+        if (m.role === 'system') {
+            const text = contentToText(m.content);
+            system = system ? `${system}\n\n${text}` : text;
+            continue;
+        }
+        if (m.role === 'tool') {
+            const block = {
+                type: 'tool_result',
+                tool_use_id: m.toolCallId ?? '',
+                content: contentToText(m.content),
+            };
+            const last = out[out.length - 1];
+            if (last && last.role === 'user' && isToolResultContent(last.content)) {
+                last.content.push(block);
+            }
+            else {
+                out.push({ role: 'user', content: [block] });
+            }
+            continue;
+        }
+        out.push({ role: m.role, content: mapContentBlocks(m) });
+    }
+    return { system, messages: out };
+}
+function contentToText(content) {
+    if (content === null)
+        return '';
+    if (typeof content === 'string')
+        return content;
+    return content
+        .filter((p) => p.type === 'text')
+        .map((p) => p.text)
+        .join('');
+}
+function mapContentBlocks(m) {
+    const blocks = [];
+    if (typeof m.content === 'string') {
+        if (m.content.length > 0)
+            blocks.push({ type: 'text', text: m.content });
+    }
+    else if (Array.isArray(m.content)) {
+        for (const p of m.content) {
+            if (p.type === 'text') {
+                blocks.push({ type: 'text', text: p.text });
+            }
+            else {
+                blocks.push({
+                    type: 'image',
+                    source: { type: 'base64', media_type: p.mediaType, data: p.base64 },
+                });
+            }
+        }
+    }
+    if (m.role === 'assistant' && m.toolCalls) {
+        for (const tc of m.toolCalls) {
+            blocks.push({
+                type: 'tool_use',
+                id: tc.id,
+                name: tc.function.name,
+                input: safeJsonParse(tc.function.arguments),
+            });
+        }
+    }
+    if (blocks.length === 0)
+        blocks.push({ type: 'text', text: '' });
+    return blocks;
+}
+function isToolResultContent(content) {
+    return (Array.isArray(content) &&
+        content.length > 0 &&
+        typeof content[0] === 'object' &&
+        content[0] !== null &&
+        content[0].type === 'tool_result');
+}
+function mapToolChoice(tc) {
+    if (tc === 'auto')
+        return { type: 'auto' };
+    if (tc === 'required')
+        return { type: 'any' };
+    if (tc === 'none')
+        return { type: 'none' };
+    if (typeof tc === 'object' && tc.type === 'function') {
+        return { type: 'tool', name: tc.function.name };
+    }
+    return null;
+}
+function mapStopReason(sr) {
+    switch (sr) {
+        case 'end_turn':
+        case 'stop_sequence':
+            return 'stop';
+        case 'max_tokens':
+            return 'length';
+        case 'tool_use':
+            return 'tool_calls';
+        case 'refusal':
+            return 'content_filter';
+        default:
+            return 'unknown';
+    }
+}
+function effortBudget(effort) {
+    switch (effort) {
+        case 'low':
+            return 1024;
+        case 'medium':
+            return 4096;
+        case 'high':
+            return 12288;
+    }
+}
+function safeJsonParse(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return {};
+    }
+}
+function extractAnthropicError(body) {
+    if (typeof body === 'string')
+        return body;
+    if (!body || typeof body !== 'object')
+        return null;
+    const b = body;
+    if (b.error && typeof b.error === 'object') {
+        const em = b.error.message;
+        if (typeof em === 'string')
+            return em;
+    }
+    if (typeof b.message === 'string')
+        return b.message;
+    return null;
+}
+/** Map an Anthropic SSE `error` event's `type` to the HTTP status its non-stream path would carry. */
+function errorEventStatus(type) {
+    switch (type) {
+        case 'authentication_error':
+            return 401;
+        case 'permission_error':
+            return 403;
+        case 'not_found_error':
+            return 404;
+        case 'rate_limit_error':
+            return 429;
+        case 'invalid_request_error':
+            return 400;
+        case 'overloaded_error':
+            return 529;
+        default:
+            return 500;
+    }
+}
+function mapStatusToProviderCode(status, message) {
+    if (status === 401 || status === 403)
+        return 'auth_failed';
+    if (status === 429)
+        return 'rate_limited';
+    // Any 5xx is a provider-side failure. A fixed {500,502,503,529} whitelist
+    // dropped 504/520/522/524 (gateway / Cloudflare-origin) to unknown, so a
+    // consumer's retry policy wouldn't fire on them.
+    if (status >= 500) {
+        return 'provider_unavailable';
+    }
+    if (status === 400 || status === 404 || status === 413 || status === 422) {
+        const msg = message.toLowerCase();
+        if (msg.includes('too long') || msg.includes('context') || msg.includes('max_tokens')) {
+            return 'context_length_exceeded';
+        }
+        return 'invalid_request';
+    }
+    return 'unknown';
+}
+function parseRetryAfterSeconds(header) {
+    const asNum = Number(header);
+    if (Number.isFinite(asNum))
+        return asNum;
+    const asDate = Date.parse(header);
+    if (!Number.isNaN(asDate)) {
+        const secs = Math.round((asDate - Date.now()) / 1000);
+        return secs >= 0 ? secs : 0;
+    }
+    return null;
+}

package/dist/esm/providers/anthropic/index.d.ts

@@ -0,0 +1,2 @@
+export { AnthropicConnector } from './anthropic.connector.js';
+export type { AnthropicConfig } from './anthropic.config.js';

package/dist/esm/providers/anthropic/index.js

@@ -0,0 +1 @@
+export { AnthropicConnector } from './anthropic.connector.js';

package/dist/esm/providers/bedrock/bedrock.config.d.ts

@@ -0,0 +1,18 @@
+export interface BedrockConfig {
+    /** AWS region, e.g. `us-east-1`. No environment inference. */
+    region: string;
+    /** AWS access key id. */
+    accessKeyId: string;
+    /** AWS secret access key. */
+    secretAccessKey: string;
+    /** Optional STS session token (temporary credentials). */
+    sessionToken?: string;
+    /** Override origin. Default `https://bedrock-runtime.<region>.amazonaws.com`. */
+    baseUrl?: string;
+    /** Converse `inferenceConfig.maxTokens` used when `ChatInput.maxOutputTokens` is omitted. Default 4096. */
+    defaultMaxTokens?: number;
+    /** Bring-your-own fetch. Defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /** Extra headers merged onto every request (participate in the SigV4 signature). */
+    headers?: Record<string, string>;
+}

package/dist/esm/providers/bedrock/bedrock.config.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/providers/bedrock/bedrock.connector.d.ts

@@ -0,0 +1,61 @@
+import { BaseConnector } from '../../base/base.connector.js';
+import type { ChatInput, ChatResult, ChatStreamDelta, IChatConnector } from '../../types/index.js';
+import type { BedrockConfig } from './bedrock.config.js';
+/**
+ * Native adapter for AWS Bedrock's unified **Converse API**
+ * (`POST /model/{modelId}/converse`). Requests are signed with hand-rolled AWS
+ * SigV4 on `node:crypto` (zero third-party deps — same approach as the
+ * notifications SES/SNS connectors). Converse is structurally different from
+ * OpenAI (top-level `system[]`, typed content blocks, `inferenceConfig`,
+ * `toolConfig`, tool results in a user turn), so this is a full translation
+ * layer emitting the identical normalized `ChatResult` / `ChatStreamDelta` /
+ * `ConnectorError`.
+ *
+ * v1 streaming NOTE: Bedrock's `converse-stream` uses AWS's binary
+ * event-stream framing (`application/vnd.amazon.eventstream`), not SSE. v1 does
+ * NOT parse that binary protocol — `stream()` falls back to a single
+ * non-incremental Converse call and yields the full result as deltas. True
+ * incremental streaming (a binary event-stream parser) is a documented
+ * follow-up.
+ *
+ * Not normalized here (passthrough/raw, never emulated): reasoning control
+ * (model-dependent on Bedrock — pass `additionalModelRequestFields` via
+ * `_passthrough.body`), `responseFormat`, prompt caching (`cachePoint` blocks
+ * via `_passthrough`), and `top_k`.
+ */
+export declare class BedrockConnector extends BaseConnector implements IChatConnector {
+    readonly id = "bedrock";
+    private readonly config;
+    private readonly origin;
+    private readonly host;
+    constructor(config: BedrockConfig);
+    complete(input: ChatInput): Promise<ChatResult>;
+    /**
+     * v1 fallback: non-incremental. See the class NOTE — Bedrock streaming is a
+     * binary event-stream, not SSE; v1 issues one Converse call and yields the
+     * result as a content delta + tool-call deltas + a terminal finish/usage delta.
+     */
+    stream(input: ChatInput): AsyncGenerator<ChatStreamDelta>;
+    private buildSignedHeaders;
+    private buildRequest;
+    private parseResult;
+    private mapVendorError;
+}
+/**
+ * Hand-rolled AWS SigV4 signer (exported for white-box testing of the
+ * canonical-path encoding; NOT re-exported from the package barrel).
+ */
+export declare function signAwsRequest(opts: {
+    method: string;
+    path: string;
+    service: string;
+    region: string;
+    host: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+    serializedBody: string;
+    additionalSignedHeaders: Record<string, string>;
+    isoTimestamp: string;
+    canonicalQuery?: string;
+}): Record<string, string>;