@pellux/goodvibes-sdk 0.18.14 → 0.18.16

package/dist/_internal/platform/providers/cache-planner.js

@@ -0,0 +1,203 @@
+/**
+ * Cache Strategy Planner — uses the helper model (or main model) to optimize
+ * cache breakpoint placement for explicit-caching providers.
+ *
+ * Two modes:
+ *   1. Heuristic (default): Uses getDefaultStrategy() from cache-strategy.ts
+ *   2. LLM-assisted: Sends context to the helper model for optimized strategy
+ *
+ * The planner runs:
+ *   - Once at session start (first turn)
+ *   - Every N turns (configurable, default 10)
+ *   - When cache hit rate drops below threshold
+ */
+import { getDefaultStrategy } from '@pellux/goodvibes-sdk/platform/providers/cache-strategy';
+import { getCacheCapability } from '@pellux/goodvibes-sdk/platform/providers/cache-capability';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+/**
+ * CachePlanner — manages cache strategy lifecycle.
+ *
+ * Caches the current strategy and refreshes it based on
+ * turn count and hit rate thresholds.
+ */
+export class CachePlanner {
+    configManager;
+    helperModel;
+    currentStrategy = null;
+    lastPlanTurn = 0;
+    turnsSinceLastPlan = 0;
+    cacheHitTracker;
+    constructor(configManager, helperModel, cacheHitTracker) {
+        this.configManager = configManager;
+        this.helperModel = helperModel;
+        this.cacheHitTracker = cacheHitTracker;
+    }
+    /**
+     * Get the current cache strategy, planning a new one if needed.
+     *
+     * Triggers re-planning when:
+     *   - No strategy exists yet (first call)
+     *   - refreshAfterTurns threshold reached
+     *   - Cache hit rate dropped below warning threshold
+     */
+    async getStrategy(context) {
+        const startMs = Date.now();
+        this.turnsSinceLastPlan++;
+        // Check if we need to refresh
+        const needsRefresh = this.shouldRefresh(context);
+        if (this.currentStrategy && !needsRefresh) {
+            return {
+                strategy: this.currentStrategy,
+                source: 'cached',
+                planTimeMs: Date.now() - startMs,
+            };
+        }
+        // Try LLM-assisted planning first (if helper enabled)
+        const helperEnabled = this.configManager.get('helper.enabled');
+        const cap = getCacheCapability(context.providerName);
+        if (helperEnabled && cap.type === 'explicit') {
+            try {
+                const helperStrategy = await this.planWithHelper(context, cap);
+                if (helperStrategy) {
+                    this.currentStrategy = helperStrategy;
+                    this.lastPlanTurn = this.turnsSinceLastPlan;
+                    this.turnsSinceLastPlan = 0;
+                    return {
+                        strategy: helperStrategy,
+                        source: 'helper',
+                        planTimeMs: Date.now() - startMs,
+                    };
+                }
+            }
+            catch (err) {
+                logger.debug('[CachePlanner] Helper planning failed, falling back to heuristic', {
+                    error: summarizeError(err),
+                });
+            }
+        }
+        // Fallback: heuristic strategy
+        const heuristicStrategy = getDefaultStrategy(context);
+        this.currentStrategy = heuristicStrategy;
+        this.lastPlanTurn = this.turnsSinceLastPlan;
+        this.turnsSinceLastPlan = 0;
+        return {
+            strategy: heuristicStrategy,
+            source: 'heuristic',
+            planTimeMs: Date.now() - startMs,
+        };
+    }
+    /** Check if strategy needs refresh. */
+    shouldRefresh(context) {
+        // No strategy yet
+        if (!this.currentStrategy)
+            return true;
+        // Refresh interval reached
+        if (this.currentStrategy.refreshAfterTurns > 0 &&
+            this.turnsSinceLastPlan >= this.currentStrategy.refreshAfterTurns) {
+            return true;
+        }
+        // Hit rate dropped below threshold
+        const hitRateThreshold = this.configManager.get('cache.hitRateWarningThreshold');
+        if (context.recentCacheHitRate !== undefined &&
+            context.recentCacheHitRate < hitRateThreshold &&
+            this.cacheHitTracker.getMetrics().turns >= 3 // Need enough data
+        ) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Use the helper model to plan an optimized cache strategy.
+     * Returns null if the helper can't produce a valid strategy.
+     */
+    async planWithHelper(context, cap) {
+        const prompt = this.buildHelperPrompt(context, cap);
+        const response = await this.helperModel.chat('cache_strategy', prompt, {
+            maxTokens: 1024,
+            systemPrompt: 'You are a cache optimization assistant. Respond ONLY with valid JSON matching the requested schema. No markdown, no explanation.',
+        });
+        if (!response)
+            return null;
+        try {
+            // Extract JSON from response (handle potential markdown wrapping)
+            let jsonStr = response.trim();
+            if (jsonStr.startsWith('```')) {
+                jsonStr = jsonStr.replace(/^```(?:json)?\s*/, '').replace(/\s*```$/, '');
+            }
+            const parsed = JSON.parse(jsonStr);
+            if (!parsed.breakpoints || !Array.isArray(parsed.breakpoints)) {
+                logger.debug('[CachePlanner] Helper returned invalid structure');
+                return null;
+            }
+            // Validate and sanitize breakpoints
+            const validPositions = new Set(['system_and_tools', 'conversation_prefix', 'last_tool_result', 'dynamic']);
+            const validTtls = new Set(['5m', '1h']);
+            const breakpoints = parsed.breakpoints
+                .filter(bp => bp.position && validPositions.has(bp.position) && bp.ttl && validTtls.has(bp.ttl))
+                .map(bp => ({
+                position: bp.position,
+                ttl: bp.ttl,
+                ttlSeconds: bp.ttl === '1h' ? 3600 : 300,
+                reason: bp.reason ?? 'Helper-planned breakpoint',
+            }));
+            // Enforce TTL ordering constraint: longer TTLs must come first
+            breakpoints.sort((a, b) => b.ttlSeconds - a.ttlSeconds);
+            // Enforce max breakpoints
+            if (cap.type === 'explicit') {
+                breakpoints.splice(cap.maxBreakpoints);
+            }
+            if (breakpoints.length === 0) {
+                logger.debug('[CachePlanner] Helper produced no valid breakpoints');
+                return null;
+            }
+            return {
+                breakpoints,
+                prefixStable: true,
+                refreshAfterTurns: parsed.refreshAfterTurns ?? 10,
+            };
+        }
+        catch (err) {
+            logger.debug('[CachePlanner] Failed to parse helper response', {
+                error: summarizeError(err),
+                response: response.slice(0, 200),
+            });
+            return null;
+        }
+    }
+    /** Build the prompt for the helper model. */
+    buildHelperPrompt(context, cap) {
+        return `Optimize cache breakpoint placement for an LLM API request.
+
+Provider: ${context.providerName}
+Cache type: ${cap.type}
+Max breakpoints: ${cap.type === 'explicit' ? cap.maxBreakpoints : 'N/A'}
+Available TTLs: ${cap.type === 'explicit' ? cap.ttlOptions.map(t => `${t.label} (${t.writeCostMultiplier}x write)`).join(', ') : 'N/A'}
+Read discount: ${cap.type === 'explicit' || cap.type === 'automatic' ? `${((1 - cap.readDiscount) * 100).toFixed(0)}% off` : 'N/A'}
+Min cacheable tokens: ${cap.type === 'explicit' ? cap.minCacheableTokens : 'N/A'}
+
+Current request context:
+- System prompt: ~${context.systemPromptTokens} tokens
+- Tools: ${context.toolCount} tools, ~${context.toolTokens} tokens
+- Conversation: ${context.conversationTurns} turns, ~${context.conversationTokens} tokens
+- Recent cache hit rate: ${context.recentCacheHitRate !== undefined ? `${(context.recentCacheHitRate * 100).toFixed(0)}%` : 'unknown'}
+
+Rules:
+- system_and_tools content NEVER changes during a session \u2192 prefer longest TTL
+- conversation_prefix grows each turn but old turns are stable \u2192 5m TTL (refreshes on read)
+- Longer TTL breakpoints MUST come before shorter TTL in content order
+- Only place breakpoints if content exceeds ${cap.type === 'explicit' ? cap.minCacheableTokens : 1024} token minimum
+
+Respond with JSON only:
+{
+  "breakpoints": [
+    { "position": "system_and_tools|conversation_prefix|last_tool_result|dynamic", "ttl": "5m|1h", "reason": "brief explanation" }
+  ],
+  "refreshAfterTurns": 10
+}`;
+    }
+    /** Force a strategy refresh on the next getStrategy() call. */
+    invalidate() {
+        this.currentStrategy = null;
+    }
+}

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

@@ -0,0 +1,154 @@
+/**
+ * Provider Capability Registry
+ *
+ * Unified capability contracts per provider/model for routing decisions.
+ * Routing choices are fully explainable from capability records.
+ */
+import { type CacheType } from '@pellux/goodvibes-sdk/platform/providers/cache-capability';
+import type { LLMProvider } from './interface.js';
+/**
+ * Unified capability contract describing what a provider/model can do.
+ * All fields are required — use `getCapability()` which always returns a
+ * fully-resolved record derived from provider defaults and model overrides.
+ */
+export interface ProviderCapability {
+    /** Whether the provider streams responses incrementally. */
+    streaming: boolean;
+    /** Whether the model accepts tool/function definitions in requests. */
+    toolCalling: boolean;
+    /** Whether the model can execute multiple tool calls in one turn. */
+    parallelTools: boolean;
+    /** Whether the provider supports JSON mode / structured output. */
+    jsonMode: boolean;
+    /** Whether the model exposes reasoning effort / budget controls. */
+    reasoningControls: boolean;
+    /** Maximum tokens the model can receive (context window). */
+    maxContextTokens: number;
+    /** Maximum tokens the model can generate in one response. */
+    maxOutputTokens: number;
+    /** Provider-level request timeout in milliseconds. */
+    timeoutMs: number;
+    /** Prompt-caching strategy supported by this provider. */
+    caching: CacheType;
+}
+/**
+ * A request profile describing what capabilities are needed to handle a
+ * particular task. All fields are optional — omitted means "no requirement".
+ */
+export interface RequestProfile {
+    /** Whether the request requires streaming output. */
+    requiresStreaming?: boolean;
+    /** Whether the request submits tool definitions. */
+    requiresToolCalling?: boolean;
+    /** Whether the request expects parallel tool execution. */
+    requiresParallelTools?: boolean;
+    /** Whether the request expects a JSON-mode / structured output response. */
+    requiresJsonMode?: boolean;
+    /** Whether the request tunes reasoning effort (budget, effort label). */
+    requiresReasoningControls?: boolean;
+    /** Minimum context window size the request needs (in tokens). */
+    minContextTokens?: number;
+    /** Minimum output capacity the request needs (in tokens). */
+    minOutputTokens?: number;
+}
+/**
+ * Typed reason codes for routing rejections.
+ * Use these instead of free-form strings so callers can branch on them.
+ */
+export declare const RouteRejectionCode: {
+    readonly NO_STREAMING: "NO_STREAMING";
+    readonly NO_TOOL_CALLING: "NO_TOOL_CALLING";
+    readonly NO_PARALLEL_TOOLS: "NO_PARALLEL_TOOLS";
+    readonly NO_JSON_MODE: "NO_JSON_MODE";
+    readonly NO_REASONING_CONTROLS: "NO_REASONING_CONTROLS";
+    readonly CONTEXT_TOO_SMALL: "CONTEXT_TOO_SMALL";
+    readonly OUTPUT_TOO_SMALL: "OUTPUT_TOO_SMALL";
+};
+export type RouteRejectionCode = (typeof RouteRejectionCode)[keyof typeof RouteRejectionCode];
+/** A single capability requirement that was not met. */
+export interface RouteRejectionDetail {
+    /** Machine-readable rejection code. */
+    code: RouteRejectionCode;
+    /** Human-readable description of why this requirement failed. */
+    reason: string;
+    /** Actual capability value on the provider. */
+    actual: boolean | number | string;
+    /** Required value from the request profile. */
+    required: boolean | number | string;
+}
+/** Structured result of a routing decision for a provider/model/request triple. */
+export type RouteExplanation = {
+    accepted: true;
+    providerId: string;
+    modelId: string;
+    /** Human-readable summary of why this route was chosen. */
+    summary: string;
+    /** The resolved capability record used for this decision. */
+    capability: ProviderCapability;
+} | {
+    accepted: false;
+    providerId: string;
+    modelId: string;
+    /** Human-readable summary of why this route was rejected. */
+    summary: string;
+    /** Ordered list of unmet requirements (non-empty when accepted=false). */
+    rejections: RouteRejectionDetail[];
+    /** The resolved capability record used for this decision. */
+    capability: ProviderCapability;
+};
+/**
+ * Registry that resolves and caches capability records per provider/model,
+ * and provides explainable routing decisions.
+ *
+ * Merge order (lowest to highest priority):
+ * 1. `GLOBAL_DEFAULTS` — conservative baseline
+ * 2. `PROVIDER_DEFAULTS[providerId]` — provider-level defaults
+ * 3. `LLMProvider.capabilities` — self-declared by the provider instance
+ * 4. `MODEL_OVERRIDES` — static per-model overrides
+ *
+ * Exception: the `caching` field is always sourced from `getCacheCapability(providerId)`
+ * (falling back to `MODEL_OVERRIDES.caching` if present), so self-declared caching
+ * from `LLMProvider.capabilities` is intentionally ignored.
+ *
+ * The cache key is `${providerId}::${modelId}`. Call `invalidate()` after dynamic
+ * provider registration to avoid stale entries.
+ */
+export declare class ProviderCapabilityRegistry {
+    private readonly cache;
+    /**
+     * Resolve the full capability record for a provider/model pair.
+     *
+     * @param providerId - The registered provider name (e.g. `'anthropic'`).
+     * @param modelId    - The model ID (e.g. `'claude-opus-4-5'`).
+     * @param provider   - Optional provider instance for self-declared capabilities.
+     * @returns A fully-resolved, immutable `ProviderCapability`.
+     */
+    getCapability(providerId: string, modelId: string, provider?: Pick<LLMProvider, 'capabilities'>): ProviderCapability;
+    /**
+     * Invalidate all cached capability records.
+     * Call after dynamic provider registration or model discovery.
+     */
+    invalidate(): void;
+    /**
+     * Check whether a resolved capability record satisfies a request profile.
+     *
+     * @param capability - Resolved capability from `getCapability()`.
+     * @param request    - The request profile describing requirements.
+     * @returns `true` if every requirement in the profile is satisfied.
+     */
+    canHandle(capability: ProviderCapability, request: RequestProfile): boolean;
+    /**
+     * Produce a structured routing explanation for a provider/model/request triple.
+     * Always returns a complete `RouteExplanation` — never throws.
+     *
+     * @param providerId - The registered provider name.
+     * @param modelId    - The model ID.
+     * @param request    - The request profile.
+     * @param provider   - Optional provider instance for self-declared capabilities.
+     * @returns A `RouteExplanation` with `accepted` flag, rejections, and capability.
+     */
+    getRouteExplanation(providerId: string, modelId: string, request: RequestProfile, provider?: Pick<LLMProvider, 'capabilities'>): RouteExplanation;
+    private _resolve;
+    private _collectRejections;
+}
+//# sourceMappingURL=capabilities.d.ts.map

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

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