@jxburros/ai-nugget 0.3.1

package/dist/adapters/engines/base.js

@@ -0,0 +1,93 @@
+import { AIError, fromUnknown } from '../../errors.js';
+import { fetchJson, withTimeout } from '../../transport.js';
+import { asRecord, asString } from '../../util.js';
+export const DEFAULT_TIMEOUT_MS = 120_000;
+/**
+ * Maps a raw streaming failure onto a typed {@link AIError}. A fired timeout is
+ * reported as `timeout` regardless of how the underlying `fetch` surfaced the
+ * abort; anything else is normalized through {@link fromUnknown} (which passes
+ * an existing {@link AIError} through untouched, preserving retryability).
+ */
+export function streamError(error, timeout, provider) {
+    if (timeout.timedOut())
+        return new AIError('Request timed out', { kind: 'timeout', provider });
+    return fromUnknown(error, provider);
+}
+/** Create a timeout/abort scope covering the full stream lifetime. */
+export function streamTimeout(conn, signal) {
+    return withTimeout(conn.timeoutMs ?? DEFAULT_TIMEOUT_MS, signal);
+}
+export async function listOpenModels(conn, profile) {
+    if (!profile.listModelsPath)
+        return [];
+    const { data } = await fetchJson(`${conn.baseUrl}${profile.listModelsPath}`, {
+        method: 'GET',
+        headers: conn.headers,
+        timeoutMs: conn.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        provider: conn.provider,
+    });
+    const record = asRecord(data);
+    const items = Array.isArray(record?.data) ? record.data : Array.isArray(record?.models) ? record.models : [];
+    const models = [];
+    for (const item of items) {
+        const row = asRecord(item);
+        const id = asString(row?.id) ?? asString(row?.name);
+        if (!id)
+            continue;
+        const contextWindow = asContextWindow(row);
+        const capabilities = asCapabilities(row);
+        const model = {
+            id,
+            source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl },
+        };
+        if (contextWindow !== undefined)
+            model.contextWindow = contextWindow;
+        if (capabilities)
+            model.capabilities = capabilities;
+        models.push(model);
+    }
+    return models;
+}
+export async function health(conn, profile) {
+    const path = profile.healthPath ?? profile.listModelsPath;
+    if (!path)
+        return { ok: true };
+    try {
+        await fetchJson(`${conn.baseUrl}${path}`, {
+            method: 'GET',
+            headers: conn.headers,
+            timeoutMs: Math.min(conn.timeoutMs ?? DEFAULT_TIMEOUT_MS, 10_000),
+            provider: conn.provider,
+        });
+        return { ok: true };
+    }
+    catch (error) {
+        return { ok: false, detail: error instanceof Error ? error.message : 'Health check failed' };
+    }
+}
+export function requireResponse(condition, message) {
+    if (!condition)
+        throw new AIError(message, { kind: 'invalid_response' });
+}
+/**
+ * Pulls a context-window figure out of the many shapes providers use for it
+ * (OpenRouter `context_length`, OpenAI-style `context_window`, Ollama
+ * `/api/show` `model_info` entries surfaced as `contextWindow`).
+ */
+function asContextWindow(row) {
+    if (!row)
+        return undefined;
+    const direct = row['context_length'] ?? row['context_window'] ?? row['contextWindow'];
+    return typeof direct === 'number' && Number.isFinite(direct) ? direct : undefined;
+}
+function asCapabilities(row) {
+    if (!row)
+        return undefined;
+    const value = row['capabilities'] ?? asRecord(row['architecture'])?.['modality'];
+    if (Array.isArray(value) && value.every((entry) => typeof entry === 'string'))
+        return value;
+    if (typeof value === 'string')
+        return [value];
+    return undefined;
+}
+//# sourceMappingURL=base.js.map

package/dist/adapters/engines/google.d.ts

@@ -0,0 +1,8 @@
+import type { ChatRequest, ChatResult, ProviderAdapter, ResolvedConnection, StreamEvent } from '../../types.js';
+export declare class GoogleAdapter implements ProviderAdapter {
+    readonly provider: string;
+    constructor(provider: string);
+    chat(conn: ResolvedConnection, req: ChatRequest): Promise<ChatResult>;
+    stream(conn: ResolvedConnection, req: ChatRequest): AsyncIterable<StreamEvent>;
+}
+//# sourceMappingURL=google.d.ts.map

package/dist/adapters/engines/google.js

@@ -0,0 +1,217 @@
+import { AIError } from '../../errors.js';
+import { estimatedUsage } from '../../tokens.js';
+import { postResponse, sseLines } from '../../transport.js';
+import { asNumber, asRecord, asString, textFromMessages } from '../../util.js';
+import { streamError, streamTimeout } from './base.js';
+export class GoogleAdapter {
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+    }
+    async chat(conn, req) {
+        let result;
+        for await (const event of this.stream(conn, req)) {
+            if (event.type === 'done')
+                result = event.result;
+            if (event.type === 'error')
+                throw event.error;
+        }
+        if (!result)
+            throw new AIError('Google stream ended without a result', { kind: 'invalid_response', provider: conn.provider });
+        return result;
+    }
+    async *stream(conn, req) {
+        const started = Date.now();
+        let firstTokenMs = null;
+        let text = '';
+        let inputTokens;
+        let outputTokens;
+        let finish;
+        const toolCalls = [];
+        const timeout = streamTimeout(conn, req.signal);
+        yield { type: 'start', callId: '', provider: conn.provider, model: req.model };
+        try {
+            const streamUrl = `${conn.baseUrl}/v1beta/models/${encodeURIComponent(req.model)}:streamGenerateContent?alt=sse`;
+            const res = await postResponse(streamUrl, body(req), conn.headers, timeout.signal, conn.provider);
+            const contentType = res.headers.get('content-type') ?? '';
+            const chunks = contentType.includes('text/event-stream') ? sseLines(res) : singleJsonLine(res);
+            for await (const line of chunks) {
+                const parsed = safeParse(line);
+                const record = asRecord(parsed);
+                const promptFeedback = asRecord(record?.promptFeedback);
+                if (!firstCandidate(record) && promptFeedback?.blockReason)
+                    finish = 'SAFETY';
+                for (const part of candidateParts(record)) {
+                    const partText = asString(asRecord(part)?.text);
+                    if (partText) {
+                        if (firstTokenMs === null)
+                            firstTokenMs = Date.now() - started;
+                        text += partText;
+                        yield { type: 'delta', text: partText };
+                    }
+                    const fnCall = asRecord(asRecord(part)?.functionCall);
+                    if (fnCall) {
+                        const call = {
+                            id: randomId(),
+                            name: asString(fnCall.name) ?? 'unknown',
+                            arguments: fnCall.args ?? {},
+                            raw: JSON.stringify(fnCall.args ?? {}),
+                        };
+                        toolCalls.push(call);
+                        yield { type: 'tool_call', call };
+                    }
+                }
+                finish = asString(asRecord(firstCandidate(record))?.finishReason) ?? finish;
+                const usage = asRecord(record?.usageMetadata);
+                inputTokens = asNumber(usage?.promptTokenCount) ?? inputTokens;
+                outputTokens = asNumber(usage?.candidatesTokenCount) ?? outputTokens;
+            }
+            const hasTools = toolCalls.length > 0;
+            yield { type: 'done', result: {
+                    text,
+                    toolCalls: hasTools ? toolCalls : undefined,
+                    finishReason: mapFinish(finish, hasTools),
+                    usage: inputTokens !== undefined || outputTokens !== undefined ? { inputTokens, outputTokens, estimated: false } : estimatedUsage(textFromMessages(req.messages), text),
+                    timing: { firstTokenMs, totalMs: Date.now() - started },
+                    model: req.model,
+                    source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl },
+                } };
+        }
+        catch (error) {
+            throw streamError(error, timeout, conn.provider);
+        }
+        finally {
+            timeout.done();
+        }
+    }
+}
+function body(req) {
+    const systemText = req.messages.filter((m) => m.role === 'system').map((m) => textContent(m.content)).join('\n\n');
+    const jsonMode = req.responseFormat?.type === 'json' && !req.tools?.length;
+    const responseSchema = req.responseFormat?.type === 'json' ? req.responseFormat.schema : undefined;
+    const payload = {
+        contents: toGoogleContents(req.messages.filter((m) => m.role !== 'system')),
+        generationConfig: {
+            temperature: req.temperature,
+            topP: req.topP,
+            maxOutputTokens: req.maxTokens,
+            stopSequences: req.stopSequences,
+            responseMimeType: jsonMode ? 'application/json' : undefined,
+            responseSchema: jsonMode ? responseSchema : undefined,
+        },
+    };
+    if (systemText)
+        payload.systemInstruction = { parts: [{ text: systemText }] };
+    if (req.tools?.length) {
+        payload.tools = [{ functionDeclarations: req.tools.map((tool) => ({ name: tool.name, description: tool.description, parameters: tool.parameters })) }];
+        const mode = req.toolChoice === 'none' ? 'NONE' : typeof req.toolChoice === 'object' ? 'ANY' : 'AUTO';
+        const config = { mode };
+        if (typeof req.toolChoice === 'object')
+            config.allowedFunctionNames = [req.toolChoice.name];
+        payload.toolConfig = { functionCallingConfig: config };
+    }
+    return payload;
+}
+function toGoogleContents(messages) {
+    const contents = [];
+    for (let index = 0; index < messages.length; index += 1) {
+        const message = messages[index];
+        if (message.role !== 'tool') {
+            contents.push(toGoogleContent(message));
+            continue;
+        }
+        const parts = [];
+        while (index < messages.length && messages[index]?.role === 'tool') {
+            const toolMessage = messages[index];
+            parts.push({ functionResponse: { name: toolMessage.name ?? 'unknown', response: toolResponseObject(toolMessage) } });
+            index += 1;
+        }
+        index -= 1;
+        contents.push({ role: 'user', parts });
+    }
+    return contents;
+}
+function toGoogleContent(m) {
+    if (m.role === 'tool') {
+        return {
+            role: 'user',
+            parts: [{ functionResponse: { name: m.name ?? 'unknown', response: toolResponseObject(m) } }],
+        };
+    }
+    if (m.role === 'assistant' && m.toolCalls?.length) {
+        const parts = [];
+        if (typeof m.content === 'string' && m.content)
+            parts.push({ text: m.content });
+        for (const call of m.toolCalls)
+            parts.push({ functionCall: { name: call.name, args: call.arguments ?? {} } });
+        return { role: 'model', parts };
+    }
+    return {
+        role: m.role === 'assistant' ? 'model' : 'user',
+        parts: typeof m.content === 'string'
+            ? [{ text: m.content }]
+            : m.content.map((part) => part.type === 'image'
+                ? { inlineData: { mimeType: part.mimeType ?? 'image/png', data: part.imageBase64 ?? '' } }
+                : { text: part.text ?? '' }),
+    };
+}
+function textContent(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!content)
+        return '';
+    return content.filter((part) => part.type === 'text').map((part) => part.text ?? '').join('\n');
+}
+function toolResponseObject(message) {
+    if (typeof message.content !== 'string')
+        return { content: textContent(message.content) };
+    try {
+        const parsed = JSON.parse(message.content);
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed))
+            return parsed;
+    }
+    catch {
+        // keep string fallback
+    }
+    return { content: message.content };
+}
+async function* singleJsonLine(res) {
+    const data = await res.json();
+    // Non-SSE responses may be a single object or an array of streamed chunks.
+    if (Array.isArray(data)) {
+        for (const item of data)
+            yield JSON.stringify(item);
+    }
+    else {
+        yield JSON.stringify(data);
+    }
+}
+function firstCandidate(record) {
+    const candidates = Array.isArray(record?.candidates) ? record.candidates : [];
+    return candidates[0];
+}
+function candidateParts(record) {
+    const content = asRecord(asRecord(firstCandidate(record))?.content);
+    return Array.isArray(content?.parts) ? content.parts : [];
+}
+function mapFinish(finish, hasTools) {
+    if (hasTools)
+        return 'tool';
+    if (finish === 'MAX_TOKENS')
+        return 'length';
+    if (finish === 'SAFETY' || finish === 'RECITATION' || finish === 'BLOCKLIST' || finish === 'PROHIBITED_CONTENT')
+        return 'content_filter';
+    return 'stop';
+}
+function safeParse(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+}
+function randomId() {
+    return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+//# sourceMappingURL=google.js.map

package/dist/adapters/engines/ollama.d.ts

@@ -0,0 +1,10 @@
+import type { ChatRequest, ChatResult, ModelInfo, ProviderAdapter, ResolvedConnection, StreamEvent } from '../../types.js';
+export declare class OllamaAdapter implements ProviderAdapter {
+    readonly provider: string;
+    constructor(provider: string);
+    chat(conn: ResolvedConnection, req: ChatRequest): Promise<ChatResult>;
+    stream(conn: ResolvedConnection, req: ChatRequest): AsyncIterable<StreamEvent>;
+    listModels(conn: ResolvedConnection): Promise<ModelInfo[]>;
+    private showModel;
+}
+//# sourceMappingURL=ollama.d.ts.map

package/dist/adapters/engines/ollama.js

@@ -0,0 +1,160 @@
+import { AIError } from '../../errors.js';
+import { estimatedUsage } from '../../tokens.js';
+import { fetchJson, ndjsonLines, postResponse } from '../../transport.js';
+import { asNumber, asRecord, asString, textFromMessages } from '../../util.js';
+import { DEFAULT_TIMEOUT_MS, streamError, streamTimeout } from './base.js';
+export class OllamaAdapter {
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+    }
+    async chat(conn, req) {
+        let result;
+        for await (const event of this.stream(conn, req)) {
+            if (event.type === 'done')
+                result = event.result;
+            if (event.type === 'error')
+                throw event.error;
+        }
+        if (!result)
+            throw new AIError('Ollama stream ended without a result', { kind: 'invalid_response', provider: conn.provider });
+        return result;
+    }
+    async *stream(conn, req) {
+        const started = Date.now();
+        let firstTokenMs = null;
+        let text = '';
+        let inputTokens;
+        let outputTokens;
+        let doneReason;
+        const toolCalls = [];
+        const timeout = streamTimeout(conn, req.signal);
+        yield { type: 'start', callId: '', provider: conn.provider, model: req.model };
+        try {
+            const res = await postResponse(`${conn.baseUrl}/api/chat`, body(req), conn.headers, timeout.signal, conn.provider);
+            for await (const value of ndjsonLines(res)) {
+                const record = asRecord(value);
+                const message = asRecord(record?.message);
+                const piece = asString(message?.content);
+                if (piece) {
+                    if (firstTokenMs === null)
+                        firstTokenMs = Date.now() - started;
+                    text += piece;
+                    yield { type: 'delta', text: piece };
+                }
+                inputTokens = asNumber(record?.prompt_eval_count) ?? inputTokens;
+                outputTokens = asNumber(record?.eval_count) ?? outputTokens;
+                doneReason = asString(record?.done_reason) ?? doneReason;
+                const calls = Array.isArray(message?.tool_calls) ? message.tool_calls : [];
+                for (const callValue of calls) {
+                    const fn = asRecord(asRecord(callValue)?.function);
+                    const args = fn?.arguments ?? {};
+                    const toolCall = {
+                        id: randomId(),
+                        name: asString(fn?.name) ?? 'unknown',
+                        arguments: args,
+                        raw: typeof args === 'string' ? args : JSON.stringify(args),
+                    };
+                    toolCalls.push(toolCall);
+                    yield { type: 'tool_call', call: toolCall };
+                }
+            }
+            const hasTools = toolCalls.length > 0;
+            yield { type: 'done', result: {
+                    text,
+                    toolCalls: hasTools ? toolCalls : undefined,
+                    finishReason: hasTools ? 'tool' : doneReason === 'length' ? 'length' : 'stop',
+                    usage: inputTokens !== undefined || outputTokens !== undefined ? { inputTokens, outputTokens, estimated: false } : estimatedUsage(textFromMessages(req.messages), text),
+                    timing: { firstTokenMs, totalMs: Date.now() - started },
+                    model: req.model,
+                    source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl },
+                } };
+        }
+        catch (error) {
+            throw streamError(error, timeout, conn.provider);
+        }
+        finally {
+            timeout.done();
+        }
+    }
+    async listModels(conn) {
+        const { data } = await fetchJson(`${conn.baseUrl}/api/tags`, {
+            method: 'GET',
+            headers: conn.headers,
+            timeoutMs: conn.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            provider: conn.provider,
+        });
+        const models = Array.isArray(asRecord(data)?.models) ? asRecord(data).models : [];
+        const ids = models.map((model) => asString(asRecord(model)?.name) ?? asString(asRecord(model)?.model) ?? '').filter(Boolean);
+        // Probe /api/show per model for context window + capabilities (best effort, sequential
+        // to avoid overwhelming a local Ollama instance).
+        const results = [];
+        for (const id of ids) {
+            const info = { id, source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl } };
+            const probed = await this.showModel(conn, id).catch(() => undefined);
+            if (probed?.contextWindow !== undefined)
+                info.contextWindow = probed.contextWindow;
+            if (probed?.capabilities)
+                info.capabilities = probed.capabilities;
+            results.push(info);
+        }
+        return results;
+    }
+    async showModel(conn, model) {
+        const { data } = await fetchJson(`${conn.baseUrl}/api/show`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...conn.headers },
+            body: JSON.stringify({ model }),
+            timeoutMs: Math.min(conn.timeoutMs ?? DEFAULT_TIMEOUT_MS, 15_000),
+            provider: conn.provider,
+        });
+        const record = asRecord(data);
+        const modelInfo = asRecord(record?.model_info);
+        let contextWindow;
+        if (modelInfo) {
+            for (const [key, value] of Object.entries(modelInfo)) {
+                if (key.endsWith('.context_length') && typeof value === 'number') {
+                    contextWindow = value;
+                    break;
+                }
+            }
+        }
+        const caps = record?.capabilities;
+        const capabilities = Array.isArray(caps) && caps.every((c) => typeof c === 'string') ? caps : undefined;
+        const result = {};
+        if (contextWindow !== undefined)
+            result.contextWindow = contextWindow;
+        if (capabilities)
+            result.capabilities = capabilities;
+        return result;
+    }
+}
+function body(req) {
+    return {
+        model: req.model,
+        messages: req.messages.map(toOllamaMessage),
+        stream: true,
+        options: { temperature: req.temperature, num_predict: req.maxTokens, top_p: req.topP, stop: req.stopSequences },
+        format: req.responseFormat?.type === 'json' ? (req.responseFormat.schema ?? 'json') : undefined,
+        tools: req.tools?.map((tool) => ({ type: 'function', function: { name: tool.name, description: tool.description, parameters: tool.parameters } })),
+    };
+}
+function toOllamaMessage(m) {
+    const images = typeof m.content === 'string' ? undefined : m.content.filter((part) => part.type === 'image').map((part) => part.imageBase64).filter(Boolean);
+    const message = {
+        role: m.role,
+        content: typeof m.content === 'string' ? m.content : m.content.filter((part) => part.type === 'text').map((part) => part.text ?? '').join('\n'),
+    };
+    if (images && images.length)
+        message.images = images;
+    if (m.role === 'tool' && m.name)
+        message.tool_name = m.name;
+    if (m.role === 'assistant' && m.toolCalls?.length) {
+        message.tool_calls = m.toolCalls.map((call) => ({ function: { name: call.name, arguments: call.arguments ?? {} } }));
+    }
+    return message;
+}
+function randomId() {
+    return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+//# sourceMappingURL=ollama.js.map

package/dist/adapters/engines/openaiChat.d.ts

@@ -0,0 +1,15 @@
+import type { ChatRequest, ChatResult, ProviderAdapter, ResolvedConnection, StreamEvent } from '../../types.js';
+import type { ProviderProfile } from '../profiles.js';
+export declare class OpenAIChatAdapter implements ProviderAdapter {
+    private profile;
+    readonly provider: string;
+    constructor(provider: string, profile: ProviderProfile);
+    chat(conn: ResolvedConnection, req: ChatRequest): Promise<ChatResult>;
+    stream(conn: ResolvedConnection, req: ChatRequest): AsyncIterable<StreamEvent>;
+    listModels(conn: ResolvedConnection): Promise<import("../../types.js").ModelInfo[]>;
+    health(conn: ResolvedConnection): Promise<{
+        ok: boolean;
+        detail?: string;
+    }>;
+}
+//# sourceMappingURL=openaiChat.d.ts.map