@pellux/goodvibes-sdk 0.18.14 → 0.18.16

package/dist/_internal/platform/providers/openai.js

@@ -0,0 +1,199 @@
+import OpenAI from 'openai';
+import { ProviderError } from '@pellux/goodvibes-sdk/platform/types/errors';
+import { withRetry } from '@pellux/goodvibes-sdk/platform/utils/retry';
+import { toOpenAITools, toOpenAIMessages, fromOpenAIToolCalls, extractTextToolCalls, } from './tool-formats.js';
+import { extractOpenAIStreamTextDelta } from '@pellux/goodvibes-sdk/platform/providers/openai-stream-delta';
+import { summarizeError, toProviderError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+const NOOP_CACHE_HIT_TRACKER = {
+    recordTurn: () => { },
+};
+/**
+ * OpenAIProvider — wraps the official `openai` npm package.
+ * Supports GPT-5 family models with full function/tool calling.
+ */
+export class OpenAIProvider {
+    name = 'openai';
+    models = [];
+    client;
+    embeddingModel = 'text-embedding-3-small';
+    cacheHitTracker;
+    constructor(apiKey, cacheHitTracker = NOOP_CACHE_HIT_TRACKER) {
+        this.client = new OpenAI({ apiKey });
+        this.cacheHitTracker = cacheHitTracker;
+    }
+    async chat(params) {
+        const { messages, tools, model, maxTokens, signal, systemPrompt, onDelta, reasoningEffort: _reasoningEffort } = params;
+        // Note: OpenAI GPT-5 does not expose reasoning effort as a configurable API parameter
+        return withRetry(async () => {
+            let responseText = '';
+            let inputTokens = 0;
+            let outputTokens = 0;
+            let cacheReadTokens = 0;
+            let stopReason = 'end';
+            let rawToolCalls = [];
+            const openaiMessages = toOpenAIMessages(messages, systemPrompt);
+            const openaiTools = tools && tools.length > 0 ? toOpenAITools(tools) : undefined;
+            try {
+                const stream = await this.client.chat.completions.create({
+                    model,
+                    messages: openaiMessages,
+                    ...(openaiTools ? { tools: openaiTools } : {}),
+                    ...(maxTokens ? { max_tokens: maxTokens } : {}),
+                    stream: true,
+                    stream_options: { include_usage: true },
+                }, { signal });
+                const accToolCalls = new Map();
+                for await (const chunk of stream) {
+                    const delta = chunk.choices[0]?.delta;
+                    const textDelta = extractOpenAIStreamTextDelta(chunk);
+                    for (const contentDelta of textDelta.content) {
+                        responseText += contentDelta;
+                        if (onDelta)
+                            onDelta({ content: contentDelta });
+                    }
+                    for (const reasoningDelta of textDelta.reasoning) {
+                        if (onDelta)
+                            onDelta({ reasoning: reasoningDelta });
+                    }
+                    // Accumulate streaming tool_calls deltas
+                    if (delta?.tool_calls) {
+                        for (const tc of delta.tool_calls) {
+                            const idx = tc.index;
+                            if (!accToolCalls.has(idx)) {
+                                accToolCalls.set(idx, { id: tc.id ?? '', name: tc.function?.name ?? '', args: '' });
+                            }
+                            const entry = accToolCalls.get(idx);
+                            if (tc.id)
+                                entry.id = tc.id;
+                            if (tc.function?.name)
+                                entry.name = tc.function.name;
+                            if (tc.function?.arguments)
+                                entry.args += tc.function.arguments;
+                            if (onDelta) {
+                                onDelta({ toolCalls: [{ index: idx, id: tc.id, name: tc.function?.name, arguments: tc.function?.arguments }] });
+                            }
+                        }
+                    }
+                    const finishReason = chunk.choices[0]?.finish_reason;
+                    if (finishReason === 'tool_calls')
+                        stopReason = 'tool_use';
+                    else if (finishReason === 'length')
+                        stopReason = 'max_tokens';
+                    const usage = chunk.usage;
+                    if (usage) {
+                        inputTokens = usage.prompt_tokens ?? 0;
+                        outputTokens = usage.completion_tokens ?? 0;
+                        cacheReadTokens = usage.prompt_tokens_details?.cached_tokens ?? cacheReadTokens;
+                    }
+                }
+                // Finalise accumulated tool calls
+                for (const [, tc] of [...accToolCalls.entries()].sort(([a], [b]) => a - b)) {
+                    rawToolCalls.push({
+                        id: tc.id,
+                        type: 'function',
+                        function: { name: tc.name, arguments: tc.args },
+                    });
+                }
+            }
+            catch (err) {
+                const { hasStatus } = await import('@pellux/goodvibes-sdk/platform/utils/retry');
+                const status = hasStatus(err) ? err.status : undefined;
+                throw toProviderError(err, {
+                    ...(status !== undefined ? { statusCode: status } : {}),
+                    provider: this.name,
+                    operation: 'chat',
+                    phase: 'stream',
+                });
+            }
+            // Some models may emit tool calls as raw text tokens instead of the
+            // OpenAI function-calling wire format. Fall back to text extraction.
+            let toolCalls = rawToolCalls.length > 0 ? fromOpenAIToolCalls(rawToolCalls) : [];
+            if (toolCalls.length === 0 && (responseText.includes('<|toolcallbegin|>') || responseText.includes('<|tool_call_begin|>'))) {
+                const extracted = extractTextToolCalls(responseText);
+                if (extracted.toolCalls.length > 0) {
+                    toolCalls = extracted.toolCalls;
+                    responseText = extracted.cleanedContent;
+                    stopReason = 'tool_use';
+                }
+            }
+            this.cacheHitTracker.recordTurn({
+                inputTokens,
+                cacheReadTokens,
+            });
+            return {
+                content: responseText,
+                toolCalls,
+                usage: {
+                    inputTokens,
+                    outputTokens,
+                    ...(cacheReadTokens > 0 ? { cacheReadTokens } : {}),
+                },
+                stopReason,
+            };
+        });
+    }
+    async embed(request) {
+        let response;
+        try {
+            response = await this.client.embeddings.create({
+                model: request.model ?? this.embeddingModel,
+                input: request.text,
+                ...(request.dimensions ? { dimensions: request.dimensions } : {}),
+            }, request.signal ? { signal: request.signal } : undefined);
+        }
+        catch (error) {
+            throw toProviderError(error, {
+                provider: this.name,
+                operation: 'embed',
+                phase: 'request',
+            });
+        }
+        const embedding = response.data[0]?.embedding ?? [];
+        return {
+            vector: Float32Array.from(embedding),
+            dimensions: embedding.length,
+            modelId: response.model,
+            metadata: {
+                usage: request.usage,
+                provider: this.name,
+            },
+        };
+    }
+    async describeRuntime(deps) {
+        const configured = Boolean(process.env.OPENAI_API_KEY || process.env.OPENAI_KEY);
+        const { buildStandardProviderAuthRoutes } = await import('./runtime-metadata.js');
+        const authRoutes = await buildStandardProviderAuthRoutes({
+            providerId: 'openai',
+            apiKeyEnvVars: ['OPENAI_API_KEY', 'OPENAI_KEY'],
+            serviceNames: ['openai'],
+            subscriptionProviderId: 'openai',
+        }, deps);
+        return {
+            auth: {
+                mode: 'api-key',
+                configured,
+                detail: configured ? 'OpenAI API key available' : 'OPENAI_API_KEY or OPENAI_KEY not set',
+                envVars: ['OPENAI_API_KEY', 'OPENAI_KEY'],
+                routes: authRoutes,
+            },
+            models: {
+                models: this.models,
+                embeddingModel: this.embeddingModel,
+                embeddingDimensions: 384,
+            },
+            usage: {
+                streaming: true,
+                toolCalling: true,
+                parallelTools: true,
+                notes: ['Embeddings use the OpenAI embeddings API.'],
+            },
+            policy: {
+                local: false,
+                streamProtocol: 'openai-chat-completions',
+                reasoningMode: 'provider-default',
+                cacheStrategy: 'implicit-openai-cache-observation',
+                notes: ['OpenAI embedding usage is subject to OpenAI API terms.'],
+            },
+        };
+    }
+}

package/dist/_internal/platform/providers/optimizer.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Provider Optimizer
+ *
+ * Lives above provider implementations. Routes requests based on capability
+ * contracts from ProviderCapabilityRegistry. Supports auto/manual/pinned
+ * routing modes with deterministic, fully-explainable decisions.
+ *
+ * Optimizer off → zero behavior change (selectRoute returns null).
+ * Optimizer on  → deterministic route explanation for every request profile.
+ */
+import { ProviderCapabilityRegistry, type RequestProfile, type RouteExplanation } from './capabilities.js';
+import type { ProviderRegistry } from './registry.js';
+import type { ProviderHealthRecord } from '@pellux/goodvibes-sdk/platform/runtime/store/domains/provider-health';
+/** Optimizer routing mode. */
+export type OptimizerMode = 'auto' | 'manual' | 'pinned';
+/** A single fallback transition log entry. */
+export interface FallbackTransition {
+    /** Epoch ms when the transition occurred. */
+    readonly ts: number;
+    /** Provider/model that failed or was skipped. */
+    readonly from: string;
+    /** Provider/model selected as fallback. */
+    readonly to: string;
+    /** Human-readable reason for the transition. */
+    readonly reason: string;
+}
+/** Result of a route selection decision. */
+export interface RouteDecision {
+    /** Provider ID selected. */
+    readonly providerId: string;
+    /** Model ID selected. */
+    readonly modelId: string;
+    /** Full route explanation from the capability registry. */
+    readonly explanation: RouteExplanation;
+    /** All candidates considered (accepted and rejected). */
+    readonly allCandidates: readonly RouteExplanation[];
+    /** Epoch ms when this decision was made. */
+    readonly decidedAt: number;
+    /** Whether this decision was constrained by a pin. */
+    readonly pinned: boolean;
+}
+/** Result of a fallback chain test. */
+export interface FallbackTestResult {
+    /** Ordered nodes in the simulated fallback chain. */
+    readonly chain: ReadonlyArray<{
+        readonly position: number;
+        readonly providerId: string;
+        readonly modelId: string;
+        readonly capable: boolean;
+        readonly explanation: RouteExplanation;
+    }>;
+    /** Number of nodes that satisfy the empty request profile. */
+    readonly viableCount: number;
+    /** Total nodes tested. */
+    readonly totalCount: number;
+    /** Epoch ms when the test was run. */
+    readonly testedAt: number;
+}
+/**
+ * Optimizer that selects the best provider/model for a given request profile.
+ *
+ * When disabled (`enabled = false`) every method returns null/empty — the
+ * optimizer has zero effect on normal request flow.
+ *
+ * When enabled, routing decisions are driven entirely by `ProviderCapabilityRegistry`
+ * capability contracts. The selection algorithm is deterministic: candidates are
+ * evaluated in registry order (custom → synthetic → catalog → discovered), and
+ * the first capable model wins. Ties are never broken by opaque scoring.
+ */
+export declare class ProviderOptimizer {
+    private _mode;
+    private _enabled;
+    private _pinnedProvider;
+    private _pinnedModel;
+    private readonly _fallbackLog;
+    private static readonly MAX_LOG_ENTRIES;
+    private readonly _clock;
+    private readonly registry;
+    private readonly capabilityRegistry;
+    constructor(registry: Pick<ProviderRegistry, 'getCurrentModel' | 'getSelectableModels' | 'explainRoute'>, capabilityRegistry: ProviderCapabilityRegistry, enabled?: boolean, clock?: () => number);
+    /** Current routing mode. */
+    get mode(): OptimizerMode;
+    /** Whether the optimizer is active. When false, selectRoute always returns null. */
+    get enabled(): boolean;
+    /** Enable or disable the optimizer. */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Set the routing mode.
+     * - `auto`   — optimizer selects the best capable provider for each request profile.
+     * - `manual` — optimizer is advisory only; caller drives provider selection.
+     * - `pinned` — optimizer always returns the pinned provider/model (if capable).
+     */
+    setMode(mode: OptimizerMode): void;
+    /**
+     * Pin routing to a specific provider and model.
+     * Automatically switches mode to `pinned`.
+     *
+     * @param providerId - Provider name (e.g. `'anthropic'`).
+     * @param modelId    - Model ID (e.g. `'claude-opus-4-5'`).
+     */
+    pin(providerId: string, modelId: string): void;
+    /** Remove the current pin and return to `manual` mode. */
+    unpin(): void;
+    /** Current pin target, or null if not pinned. */
+    get pinnedTarget(): {
+        providerId: string;
+        modelId: string;
+    } | null;
+    /**
+     * Select the best route for the given request profile.
+     *
+     * Returns `null` when the optimizer is disabled — callers must handle null
+     * and fall through to their own provider selection logic.
+     *
+     * @param profile        - Capability requirements for the request.
+     * @param healthSnapshot - Optional map of provider health records for filtering
+     *                         unhealthy providers in `auto` mode.
+     * @returns A `RouteDecision` or `null` when optimizer is off.
+     *
+     * @remarks
+     * `selectRoute` is wired by the orchestrator when the `provider-optimizer`
+     * feature flag is enabled. This follows the same deferred-integration pattern
+     * as session emitters — the method is fully functional but called externally
+     * only when the feature is active. Until then it is a no-op (returns `null`).
+     */
+    selectRoute(profile: RequestProfile, healthSnapshot?: ReadonlyMap<string, ProviderHealthRecord>): RouteDecision | null;
+    /**
+     * Explain the current routing decision for the active model without changing it.
+     * Always returns a full explanation even when the optimizer is in manual mode.
+     *
+     * @param profile - Optional request profile; defaults to empty (no requirements).
+     */
+    explainCurrentRoute(profile?: RequestProfile): RouteExplanation;
+    /** Returns a fully-typed rejection explanation when no candidates are available. */
+    private _emptyExplanation;
+    /**
+     * Simulate the fallback chain by evaluating all selectable models against
+     * the given profile. Returns an ordered list of results (capable first,
+     * then incapable) so operators can visualize the full fallback topology.
+     *
+     * @param profile - Capability requirements to test against.
+     */
+    testFallback(profile?: RequestProfile): FallbackTestResult;
+    /**
+     * Record a fallback transition. Called by orchestration layers when a
+     * provider fails and routing switches to a fallback.
+     *
+     * Transitions are always recorded regardless of optimizer enabled state
+     * so that manual fallbacks are also visible in the log.
+     */
+    recordFallbackTransition(from: string, to: string, reason: string): void;
+    /** All recorded fallback transitions (oldest first). */
+    get fallbackLog(): readonly FallbackTransition[];
+    /** Clear the fallback transition log. */
+    clearFallbackLog(): void;
+}
+//# sourceMappingURL=optimizer.d.ts.map

package/dist/_internal/platform/providers/optimizer.d.ts.map

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

package/dist/_internal/platform/providers/optimizer.js

@@ -0,0 +1,265 @@
+/**
+ * Provider Optimizer
+ *
+ * Lives above provider implementations. Routes requests based on capability
+ * contracts from ProviderCapabilityRegistry. Supports auto/manual/pinned
+ * routing modes with deterministic, fully-explainable decisions.
+ *
+ * Optimizer off → zero behavior change (selectRoute returns null).
+ * Optimizer on  → deterministic route explanation for every request profile.
+ */
+import { ProviderCapabilityRegistry, } from './capabilities.js';
+// ---------------------------------------------------------------------------
+// ProviderOptimizer
+// ---------------------------------------------------------------------------
+/**
+ * Optimizer that selects the best provider/model for a given request profile.
+ *
+ * When disabled (`enabled = false`) every method returns null/empty — the
+ * optimizer has zero effect on normal request flow.
+ *
+ * When enabled, routing decisions are driven entirely by `ProviderCapabilityRegistry`
+ * capability contracts. The selection algorithm is deterministic: candidates are
+ * evaluated in registry order (custom → synthetic → catalog → discovered), and
+ * the first capable model wins. Ties are never broken by opaque scoring.
+ */
+export class ProviderOptimizer {
+    _mode = 'manual';
+    _enabled;
+    _pinnedProvider = null;
+    _pinnedModel = null;
+    _fallbackLog = [];
+    static MAX_LOG_ENTRIES = 200;
+    _clock;
+    registry;
+    capabilityRegistry;
+    constructor(registry, capabilityRegistry, enabled = false, clock = Date.now) {
+        this.registry = registry;
+        this.capabilityRegistry = capabilityRegistry;
+        this._enabled = enabled;
+        this._clock = clock;
+    }
+    // -------------------------------------------------------------------------
+    // Mode control
+    // -------------------------------------------------------------------------
+    /** Current routing mode. */
+    get mode() {
+        return this._mode;
+    }
+    /** Whether the optimizer is active. When false, selectRoute always returns null. */
+    get enabled() {
+        return this._enabled;
+    }
+    /** Enable or disable the optimizer. */
+    setEnabled(enabled) {
+        this._enabled = enabled;
+    }
+    /**
+     * Set the routing mode.
+     * - `auto`   — optimizer selects the best capable provider for each request profile.
+     * - `manual` — optimizer is advisory only; caller drives provider selection.
+     * - `pinned` — optimizer always returns the pinned provider/model (if capable).
+     */
+    setMode(mode) {
+        this._mode = mode;
+        if (mode !== 'pinned') {
+            this._pinnedProvider = null;
+            this._pinnedModel = null;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Pinning
+    // -------------------------------------------------------------------------
+    /**
+     * Pin routing to a specific provider and model.
+     * Automatically switches mode to `pinned`.
+     *
+     * @param providerId - Provider name (e.g. `'anthropic'`).
+     * @param modelId    - Model ID (e.g. `'claude-opus-4-5'`).
+     */
+    pin(providerId, modelId) {
+        this._pinnedProvider = providerId;
+        this._pinnedModel = modelId;
+        this._mode = 'pinned';
+    }
+    /** Remove the current pin and return to `manual` mode. */
+    unpin() {
+        this._pinnedProvider = null;
+        this._pinnedModel = null;
+        this._mode = 'manual';
+    }
+    /** Current pin target, or null if not pinned. */
+    get pinnedTarget() {
+        if (this._pinnedProvider && this._pinnedModel) {
+            return { providerId: this._pinnedProvider, modelId: this._pinnedModel };
+        }
+        return null;
+    }
+    // -------------------------------------------------------------------------
+    // Route selection
+    // -------------------------------------------------------------------------
+    /**
+     * Select the best route for the given request profile.
+     *
+     * Returns `null` when the optimizer is disabled — callers must handle null
+     * and fall through to their own provider selection logic.
+     *
+     * @param profile        - Capability requirements for the request.
+     * @param healthSnapshot - Optional map of provider health records for filtering
+     *                         unhealthy providers in `auto` mode.
+     * @returns A `RouteDecision` or `null` when optimizer is off.
+     *
+     * @remarks
+     * `selectRoute` is wired by the orchestrator when the `provider-optimizer`
+     * feature flag is enabled. This follows the same deferred-integration pattern
+     * as session emitters — the method is fully functional but called externally
+     * only when the feature is active. Until then it is a no-op (returns `null`).
+     */
+    selectRoute(profile, healthSnapshot) {
+        if (!this._enabled)
+            return null;
+        const candidates = this.registry.getSelectableModels();
+        const allCandidates = [];
+        // Pinned mode — evaluate only the pinned target
+        if (this._mode === 'pinned' && this._pinnedProvider && this._pinnedModel) {
+            const explanation = this.capabilityRegistry.getRouteExplanation(this._pinnedProvider, this._pinnedModel, profile);
+            allCandidates.push(explanation);
+            return {
+                providerId: this._pinnedProvider,
+                modelId: this._pinnedModel,
+                explanation,
+                allCandidates,
+                decidedAt: this._clock(),
+                pinned: true,
+            };
+        }
+        // Auto mode — evaluate all selectable models; pick first capable
+        // Manual mode — same evaluation but result is advisory (caller may ignore)
+        let selected = null;
+        let selectedExplanation = null;
+        for (const model of candidates) {
+            // Skip unhealthy providers in auto mode when health data is available
+            if (this._mode === 'auto' && healthSnapshot) {
+                const health = healthSnapshot.get(model.provider);
+                if (health && (health.status === 'unavailable' || health.status === 'auth_error')) {
+                    continue;
+                }
+            }
+            const explanation = this.capabilityRegistry.getRouteExplanation(model.provider, model.id, profile);
+            allCandidates.push(explanation);
+            if (explanation.accepted && !selected) {
+                selected = model;
+                selectedExplanation = explanation;
+            }
+        }
+        if (!selected || !selectedExplanation) {
+            // No capable provider found — return first candidate's explanation as the decision
+            // so callers get a fully-populated rejection explanation
+            const fallbackExpl = allCandidates[0] ?? this._emptyExplanation();
+            return {
+                providerId: fallbackExpl.providerId,
+                modelId: fallbackExpl.modelId,
+                explanation: fallbackExpl,
+                allCandidates,
+                decidedAt: this._clock(),
+                pinned: false,
+            };
+        }
+        return {
+            providerId: selected.provider,
+            modelId: selected.id,
+            explanation: selectedExplanation,
+            allCandidates,
+            decidedAt: this._clock(),
+            pinned: false,
+        };
+    }
+    /**
+     * Explain the current routing decision for the active model without changing it.
+     * Always returns a full explanation even when the optimizer is in manual mode.
+     *
+     * @param profile - Optional request profile; defaults to empty (no requirements).
+     */
+    explainCurrentRoute(profile = {}) {
+        const current = this.registry.getCurrentModel();
+        return this.registry.explainRoute(current.registryKey ?? `${current.provider}:${current.id}`, profile);
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /** Returns a fully-typed rejection explanation when no candidates are available. */
+    _emptyExplanation() {
+        return {
+            accepted: false,
+            providerId: 'none',
+            modelId: 'none',
+            summary: 'No selectable models available in registry.',
+            rejections: [],
+            capability: this.capabilityRegistry.getCapability('unknown', 'unknown'),
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Fallback test
+    // -------------------------------------------------------------------------
+    /**
+     * Simulate the fallback chain by evaluating all selectable models against
+     * the given profile. Returns an ordered list of results (capable first,
+     * then incapable) so operators can visualize the full fallback topology.
+     *
+     * @param profile - Capability requirements to test against.
+     */
+    testFallback(profile = {}) {
+        const candidates = this.registry.getSelectableModels();
+        const chain = [];
+        let position = 0;
+        for (const model of candidates) {
+            const explanation = this.capabilityRegistry.getRouteExplanation(model.provider, model.id, profile);
+            chain.push({
+                position,
+                providerId: model.provider,
+                modelId: model.id,
+                capable: explanation.accepted,
+                explanation,
+            });
+            position++;
+        }
+        const viableCount = chain.filter((n) => n.capable).length;
+        return {
+            chain,
+            viableCount,
+            totalCount: chain.length,
+            testedAt: this._clock(),
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Fallback transition log
+    // -------------------------------------------------------------------------
+    /**
+     * Record a fallback transition. Called by orchestration layers when a
+     * provider fails and routing switches to a fallback.
+     *
+     * Transitions are always recorded regardless of optimizer enabled state
+     * so that manual fallbacks are also visible in the log.
+     */
+    recordFallbackTransition(from, to, reason) {
+        const entry = {
+            ts: this._clock(),
+            from,
+            to,
+            reason,
+        };
+        this._fallbackLog.push(entry);
+        // Trim to bounded size
+        if (this._fallbackLog.length > ProviderOptimizer.MAX_LOG_ENTRIES) {
+            this._fallbackLog.splice(0, this._fallbackLog.length - ProviderOptimizer.MAX_LOG_ENTRIES);
+        }
+    }
+    /** All recorded fallback transitions (oldest first). */
+    get fallbackLog() {
+        return this._fallbackLog;
+    }
+    /** Clear the fallback transition log. */
+    clearFallbackLog() {
+        this._fallbackLog.splice(0);
+    }
+}