@jxburros/ai-nugget 0.3.1

package/dist/adapters/engines/openaiChat.js

@@ -0,0 +1,228 @@
+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 { health, listOpenModels, streamError, streamTimeout } from './base.js';
+export class OpenAIChatAdapter {
+    profile;
+    provider;
+    constructor(provider, profile) {
+        this.profile = profile;
+        this.provider = provider;
+    }
+    async chat(conn, req) {
+        let final;
+        for await (const event of this.stream(conn, req)) {
+            if (event.type === 'done')
+                final = event.result;
+            if (event.type === 'error')
+                throw event.error;
+        }
+        if (!final)
+            throw new AIError('Provider stream ended without a result', { kind: 'invalid_response', provider: conn.provider });
+        return final;
+    }
+    async *stream(conn, req) {
+        const started = Date.now();
+        let firstTokenMs = null;
+        let text = '';
+        let toolCalls = [];
+        let inputTokens;
+        let outputTokens;
+        let finish;
+        let sawTerminal = false;
+        const timeout = streamTimeout(conn, req.signal);
+        yield { type: 'start', callId: '', provider: conn.provider, model: req.model };
+        try {
+            const res = await postResponse(urlFor(conn, this.profile, req.model), openAiBody(req, this.profile), conn.headers, timeout.signal, conn.provider);
+            const contentType = res.headers.get('content-type') ?? '';
+            if (!contentType.includes('text/event-stream')) {
+                // Server ignored stream:true (or is a buffered gateway) — recover the whole body.
+                const rawText = await res.text().catch(() => '');
+                const raw = safeParse(rawText) ?? { text: rawText };
+                const parsed = parseOpenAiResponse(raw);
+                text = parsed.text;
+                toolCalls = parsed.toolCalls;
+                inputTokens = parsed.inputTokens;
+                outputTokens = parsed.outputTokens;
+                finish = parsed.finish;
+                sawTerminal = true;
+                if (text)
+                    yield { type: 'delta', text };
+                for (const call of toolCalls)
+                    yield { type: 'tool_call', call };
+            }
+            else {
+                const partialTools = new Map();
+                for await (const line of sseLines(res)) {
+                    const chunk = safeParse(line);
+                    const record = asRecord(chunk);
+                    if (!record)
+                        continue;
+                    const usage = asRecord(record.usage);
+                    inputTokens = asNumber(usage?.prompt_tokens) ?? inputTokens;
+                    outputTokens = asNumber(usage?.completion_tokens) ?? outputTokens;
+                    const choices = Array.isArray(record.choices) ? record.choices : [];
+                    const choice = asRecord(choices[0]);
+                    finish = asString(choice?.finish_reason) ?? finish;
+                    if (choice?.finish_reason)
+                        sawTerminal = true;
+                    const delta = asRecord(choice?.delta);
+                    const piece = asString(delta?.content);
+                    if (piece) {
+                        if (firstTokenMs === null)
+                            firstTokenMs = Date.now() - started;
+                        text += piece;
+                        yield { type: 'delta', text: piece };
+                    }
+                    const calls = Array.isArray(delta?.tool_calls) ? delta.tool_calls : [];
+                    for (const callValue of calls) {
+                        const call = asRecord(callValue);
+                        const index = asNumber(call?.index) ?? 0;
+                        const current = partialTools.get(index) ?? { raw: '' };
+                        current.id = asString(call?.id) ?? current.id;
+                        const fn = asRecord(call?.function);
+                        current.name = asString(fn?.name) ?? current.name;
+                        current.raw += asString(fn?.arguments) ?? '';
+                        partialTools.set(index, current);
+                    }
+                }
+                toolCalls = [...partialTools.values()].filter((call) => call.name).map((call) => ({
+                    id: call.id ?? randomId(),
+                    name: call.name,
+                    raw: call.raw,
+                    arguments: parseArgs(call.raw),
+                }));
+                for (const call of toolCalls)
+                    yield { type: 'tool_call', call };
+            }
+            if (!sawTerminal) {
+                yield { type: 'context', kind: 'stream_anomaly', data: { reason: 'stream ended without a finish_reason' } };
+            }
+            const result = makeResult(conn, req, text, toolCalls, finish, started, firstTokenMs, inputTokens, outputTokens);
+            yield { type: 'done', result };
+        }
+        catch (error) {
+            throw streamError(error, timeout, conn.provider);
+        }
+        finally {
+            timeout.done();
+        }
+    }
+    listModels(conn) {
+        return listOpenModels(conn, this.profile);
+    }
+    health(conn) {
+        return health(conn, this.profile);
+    }
+}
+function openAiBody(req, profile) {
+    const body = {
+        model: req.model,
+        messages: req.messages.map(toOpenAiMessage),
+        temperature: req.temperature,
+        top_p: req.topP,
+        stop: req.stopSequences,
+        response_format: responseFormatFor(req, profile),
+        tools: req.tools?.map((tool) => ({ type: 'function', function: tool })),
+        tool_choice: typeof req.toolChoice === 'object' ? { type: 'function', function: { name: req.toolChoice.name } } : req.toolChoice,
+        stream: true,
+        // Many OpenAI-compatible local servers (llama.cpp, LM Studio, vLLM) choke
+        // on or ignore stream_options — only send it where the profile confirms
+        // the server understands it.
+        stream_options: profile.quirks?.supportsUsageInStream ? { include_usage: true } : undefined,
+    };
+    if (req.maxTokens !== undefined)
+        body[profile.quirks?.maxTokensParam ?? 'max_tokens'] = req.maxTokens;
+    return body;
+}
+function responseFormatFor(req, profile) {
+    if (req.responseFormat?.type !== 'json')
+        return undefined;
+    if (req.responseFormat.schema && profile.quirks?.supportsJsonSchema) {
+        return { type: 'json_schema', json_schema: { name: 'response', schema: req.responseFormat.schema } };
+    }
+    return { type: 'json_object' };
+}
+function toOpenAiMessage(message) {
+    return {
+        role: message.role,
+        content: typeof message.content === 'string'
+            ? message.content
+            : message.content.map((part) => part.type === 'image'
+                ? { type: 'image_url', image_url: { url: `data:${part.mimeType ?? 'image/png'};base64,${part.imageBase64 ?? ''}` } }
+                : { type: 'text', text: part.text ?? '' }),
+        name: message.role === 'tool' ? message.name : undefined,
+        tool_call_id: message.toolCallId,
+        tool_calls: message.toolCalls?.map((call) => ({ id: call.id, type: 'function', function: { name: call.name, arguments: call.raw ?? JSON.stringify(call.arguments) } })),
+    };
+}
+function urlFor(conn, profile, model) {
+    if (profile.quirks?.urlTemplate) {
+        return profile.quirks.urlTemplate.replace('{baseUrl}', conn.baseUrl).replace('{model}', encodeURIComponent(model));
+    }
+    return `${conn.baseUrl}/chat/completions`;
+}
+function parseOpenAiResponse(raw) {
+    const record = asRecord(raw);
+    const usage = asRecord(record?.usage);
+    const choice = asRecord(Array.isArray(record?.choices) ? record.choices[0] : undefined);
+    const message = asRecord(choice?.message);
+    const text = asString(message?.content) ?? asString(record?.text) ?? '';
+    const calls = Array.isArray(message?.tool_calls) ? message.tool_calls : [];
+    return {
+        text,
+        finish: asString(choice?.finish_reason),
+        toolCalls: calls.map((value) => {
+            const call = asRecord(value);
+            const fn = asRecord(call?.function);
+            const rawArgs = asString(fn?.arguments) ?? '{}';
+            return { id: asString(call?.id) ?? randomId(), name: asString(fn?.name) ?? 'unknown', raw: rawArgs, arguments: parseArgs(rawArgs) };
+        }),
+        inputTokens: asNumber(usage?.prompt_tokens),
+        outputTokens: asNumber(usage?.completion_tokens),
+    };
+}
+function makeResult(conn, req, text, toolCalls, finish, started, firstTokenMs, inputTokens, outputTokens) {
+    const usage = inputTokens !== undefined || outputTokens !== undefined
+        ? { inputTokens, outputTokens, estimated: false }
+        : estimatedUsage(textFromMessages(req.messages), text);
+    return {
+        text,
+        toolCalls: toolCalls.length ? toolCalls : undefined,
+        finishReason: mapFinish(finish, toolCalls.length > 0),
+        usage,
+        timing: { firstTokenMs, totalMs: Date.now() - started },
+        model: req.model,
+        source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl },
+    };
+}
+function mapFinish(finish, hasToolCalls) {
+    if (hasToolCalls || finish === 'tool_calls' || finish === 'function_call')
+        return 'tool';
+    if (finish === 'length')
+        return 'length';
+    if (finish === 'content_filter')
+        return 'content_filter';
+    return 'stop';
+}
+function parseArgs(raw) {
+    try {
+        return raw ? JSON.parse(raw) : {};
+    }
+    catch {
+        return {};
+    }
+}
+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=openaiChat.js.map

package/dist/adapters/index.d.ts

@@ -0,0 +1,5 @@
+import type { ProviderAdapter } from '../types.js';
+export declare function adapterFor(provider: string, baseUrl?: string): ProviderAdapter;
+export { PROVIDER_PROFILES, profileFor } from './profiles.js';
+export type { ProviderProfile, EngineName, AuthMode } from './profiles.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.js

@@ -0,0 +1,17 @@
+import { AnthropicAdapter } from './engines/anthropic.js';
+import { GoogleAdapter } from './engines/google.js';
+import { OllamaAdapter } from './engines/ollama.js';
+import { OpenAIChatAdapter } from './engines/openaiChat.js';
+import { profileFor } from './profiles.js';
+export function adapterFor(provider, baseUrl) {
+    const profile = profileFor(provider, baseUrl);
+    if (profile.engine === 'anthropic')
+        return new AnthropicAdapter(provider);
+    if (profile.engine === 'google')
+        return new GoogleAdapter(provider);
+    if (profile.engine === 'ollama')
+        return new OllamaAdapter(provider);
+    return new OpenAIChatAdapter(provider, profile);
+}
+export { PROVIDER_PROFILES, profileFor } from './profiles.js';
+//# sourceMappingURL=index.js.map

package/dist/adapters/profiles.d.ts

@@ -0,0 +1,42 @@
+export type EngineName = 'openaiChat' | 'anthropic' | 'google' | 'ollama';
+export type AuthMode = 'bearer' | 'x-api-key' | 'x-goog-api-key' | 'api-key-header' | 'none';
+/**
+ * Answers the capability questions apps need before choosing behavior —
+ * distinct from `quirks`, which are wire-format details an adapter consults
+ * to build a request. These are per-provider defaults, not per-model: a
+ * specific model behind a `true` profile can still lack a capability (a tiny
+ * Ollama model ignoring `tools`), and callers that know better should pass an
+ * explicit `toolMode` rather than rely on `auto`.
+ */
+export interface ProviderCapabilities {
+    /** Native tool/function-calling is reliable for this provider's protocol, not just model-dependent. Drives `toolMode: 'auto'` in the agent loop. */
+    nativeTools: boolean;
+    /** A provider-enforced structured-output mode exists (not just prompt-and-hope JSON). */
+    jsonMode: boolean;
+    /** Runs on localhost / user-controlled infrastructure rather than a hosted cloud API. */
+    local: boolean;
+    /** Meant to run embedded alongside the app (a local sidecar process) rather than accessed as a standalone hosted service. */
+    embeddable: boolean;
+}
+export interface ProviderProfile {
+    engine: EngineName;
+    defaultBaseUrl?: string;
+    auth: AuthMode;
+    defaultHeaders?: Record<string, string>;
+    capabilities: ProviderCapabilities;
+    quirks?: {
+        keyOptional?: boolean;
+        modelOptional?: boolean;
+        urlTemplate?: string;
+        supportsUsageInStream?: boolean;
+        maxTokensRequired?: boolean;
+        maxTokensParam?: 'max_tokens' | 'max_completion_tokens';
+        supportsJsonSchema?: boolean;
+    };
+    listModelsPath?: string;
+    healthPath?: string;
+}
+export declare const PROVIDER_PROFILES: Record<string, ProviderProfile>;
+export declare function profileFor(provider: string, baseUrl?: string): ProviderProfile;
+export declare function applyAuth(profile: ProviderProfile, apiKey: string | null, headers: Record<string, string>): Record<string, string>;
+//# sourceMappingURL=profiles.d.ts.map

package/dist/adapters/profiles.js

@@ -0,0 +1,111 @@
+const HOSTED_CLOUD = { nativeTools: true, jsonMode: true, local: false, embeddable: false };
+const LOCAL_RUNTIME = { nativeTools: false, jsonMode: false, local: true, embeddable: true };
+export const PROVIDER_PROFILES = {
+    openai: {
+        engine: 'openaiChat',
+        defaultBaseUrl: 'https://api.openai.com/v1',
+        auth: 'bearer',
+        listModelsPath: '/models',
+        capabilities: HOSTED_CLOUD,
+        quirks: { supportsUsageInStream: true, maxTokensParam: 'max_completion_tokens', supportsJsonSchema: true },
+    },
+    'azure-openai': {
+        engine: 'openaiChat',
+        auth: 'api-key-header',
+        capabilities: HOSTED_CLOUD,
+        quirks: { urlTemplate: '{baseUrl}/openai/deployments/{model}/chat/completions?api-version=2024-10-21', maxTokensParam: 'max_completion_tokens', supportsJsonSchema: true },
+    },
+    openrouter: {
+        engine: 'openaiChat',
+        defaultBaseUrl: 'https://openrouter.ai/api/v1',
+        auth: 'bearer',
+        defaultHeaders: { 'HTTP-Referer': 'https://github.com/jxburros/AI-Nugget', 'X-Title': 'ai-nugget' },
+        listModelsPath: '/models',
+        capabilities: HOSTED_CLOUD,
+        quirks: { supportsUsageInStream: true },
+    },
+    groq: { engine: 'openaiChat', defaultBaseUrl: 'https://api.groq.com/openai/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+    deepseek: { engine: 'openaiChat', defaultBaseUrl: 'https://api.deepseek.com/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+    mistral: { engine: 'openaiChat', defaultBaseUrl: 'https://api.mistral.ai/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+    together: { engine: 'openaiChat', defaultBaseUrl: 'https://api.together.xyz/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+    fireworks: { engine: 'openaiChat', defaultBaseUrl: 'https://api.fireworks.ai/inference/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+    lmstudio: {
+        engine: 'openaiChat',
+        defaultBaseUrl: 'http://localhost:1234/v1',
+        auth: 'none',
+        listModelsPath: '/models',
+        capabilities: LOCAL_RUNTIME,
+        quirks: { keyOptional: true },
+    },
+    llamacpp: {
+        engine: 'openaiChat',
+        defaultBaseUrl: 'http://localhost:8080/v1',
+        auth: 'none',
+        listModelsPath: '/models',
+        healthPath: '/health',
+        capabilities: LOCAL_RUNTIME,
+        quirks: { keyOptional: true, modelOptional: true },
+    },
+    vllm: {
+        engine: 'openaiChat',
+        defaultBaseUrl: 'http://localhost:8000/v1',
+        auth: 'none',
+        listModelsPath: '/models',
+        capabilities: LOCAL_RUNTIME,
+        quirks: { keyOptional: true },
+    },
+    ollama: {
+        engine: 'ollama',
+        defaultBaseUrl: 'http://localhost:11434',
+        auth: 'none',
+        listModelsPath: '/api/tags',
+        // Ollama's `format: 'json'` is engine-enforced (reliable regardless of
+        // model); its `tools` field is honored only by models trained for tool
+        // use, so nativeTools stays conservative like the other local runtimes.
+        capabilities: { ...LOCAL_RUNTIME, jsonMode: true },
+        quirks: { keyOptional: true },
+    },
+    anthropic: {
+        engine: 'anthropic',
+        defaultBaseUrl: 'https://api.anthropic.com',
+        auth: 'x-api-key',
+        defaultHeaders: { 'anthropic-version': '2023-06-01' },
+        capabilities: HOSTED_CLOUD,
+        quirks: { maxTokensRequired: true },
+    },
+    google: {
+        engine: 'google',
+        defaultBaseUrl: 'https://generativelanguage.googleapis.com',
+        auth: 'x-goog-api-key',
+        capabilities: HOSTED_CLOUD,
+    },
+    'openai-compat': {
+        engine: 'openaiChat',
+        auth: 'bearer',
+        listModelsPath: '/models',
+        // Unknown endpoint — usually pointed at a local/self-hosted server, so
+        // assume the conservative local-runtime defaults rather than the hosted-cloud ones.
+        capabilities: LOCAL_RUNTIME,
+    },
+};
+export function profileFor(provider, baseUrl) {
+    return PROVIDER_PROFILES[provider] ?? {
+        ...PROVIDER_PROFILES['openai-compat'],
+        defaultBaseUrl: baseUrl,
+    };
+}
+export function applyAuth(profile, apiKey, headers) {
+    const next = { ...profile.defaultHeaders, ...headers };
+    if (!apiKey)
+        return next;
+    if (profile.auth === 'bearer')
+        next.authorization = `Bearer ${apiKey}`;
+    else if (profile.auth === 'x-api-key')
+        next['x-api-key'] = apiKey;
+    else if (profile.auth === 'x-goog-api-key')
+        next['x-goog-api-key'] = apiKey;
+    else if (profile.auth === 'api-key-header')
+        next['api-key'] = apiKey;
+    return next;
+}
+//# sourceMappingURL=profiles.js.map

package/dist/agent/index.d.ts

@@ -0,0 +1,3 @@
+export * from './tools.js';
+export * from './loop.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/agent/index.js

@@ -0,0 +1,3 @@
+export * from './tools.js';
+export * from './loop.js';
+//# sourceMappingURL=index.js.map

package/dist/agent/loop.d.ts

@@ -0,0 +1,70 @@
+import type { AIHandler } from '../handler.js';
+import type { ChatMessage, Connection, StreamEvent, ToolCall, Usage } from '../types.js';
+import type { ToolSpec } from './tools.js';
+export interface AgentOptions {
+    handler: AIHandler;
+    connection: Connection;
+    model: string;
+    tools: ToolSpec[];
+    messages: ChatMessage[];
+    /**
+     * `native` sends `tools` on the request; `promptJson` describes tools in a
+     * system message and parses a JSON directive back out of plain text.
+     * `auto` (the default) picks per-call from the connection's provider
+     * capability profile (`profileFor(provider).capabilities.nativeTools`) —
+     * hosted providers with reliable tool-calling get `native`, local runtimes
+     * (Ollama, llama.cpp, LM Studio, vLLM) and the `openai-compat` escape hatch
+     * default to `promptJson` since native tool support there is model-
+     * dependent, not protocol-guaranteed.
+     */
+    toolMode?: 'native' | 'promptJson' | 'auto';
+    budget?: {
+        maxSteps?: number;
+        maxTokens?: number;
+        deadlineMs?: number;
+    };
+    approval?: ApprovalGate;
+    onEvent?: (e: AgentEvent) => void;
+    signal?: AbortSignal;
+    metadata?: Record<string, unknown>;
+}
+export type ApprovalGate = (req: {
+    call: ToolCall;
+    tool: ToolSpec;
+    step: number;
+}) => Promise<'allow' | 'deny' | {
+    modifiedArguments: unknown;
+}>;
+export type AgentEvent = StreamEvent | {
+    type: 'step_start';
+    step: number;
+} | {
+    type: 'tool_start';
+    step: number;
+    call: ToolCall;
+} | {
+    type: 'tool_result';
+    step: number;
+    call: ToolCall;
+    result: unknown;
+    isError: boolean;
+} | {
+    type: 'tool_denied';
+    step: number;
+    call: ToolCall;
+    reason: string;
+} | {
+    type: 'agent_done';
+    result: AgentResult;
+};
+export interface AgentResult {
+    finalText: string;
+    messages: ChatMessage[];
+    usage: Usage;
+    steps: number;
+    stopReason: 'finished' | 'max_steps' | 'budget' | 'deadline' | 'canceled' | 'error';
+}
+export declare function runAgent(opts: AgentOptions): AsyncIterable<AgentEvent> & {
+    result: Promise<AgentResult>;
+};
+//# sourceMappingURL=loop.d.ts.map