@uluops/core 0.5.0

package/dist/ai/AIProvider.d.ts

@@ -0,0 +1,198 @@
+import { Output, type ToolSet } from 'ai';
+import type { ProviderOptions } from '@ai-sdk/provider-utils';
+import type { UsageMetrics } from '../types/ai.js';
+import type { ResolvedConfig } from '../types/config.js';
+import type { ModelCatalog, ResolvedModel } from './ModelCatalog.js';
+import { TokenBudgetTracker } from './TokenBudgetTracker.js';
+import type { ModelCapabilities } from '@uluops/registry-sdk';
+import type { Logger } from '@uluops/sdk-core';
+/**
+ * Result from AI provider generation
+ */
+export interface AIGenerateResult {
+    /** Final text content after tool loop completion */
+    text: string;
+    /** Total usage across all steps */
+    usage: UsageMetrics;
+    /** Number of tool calls made */
+    toolCallCount: number;
+    /** Resolved provider:modelId that was used */
+    model: string;
+    /** Provider name (e.g., 'anthropic', 'openai') */
+    provider: string;
+    /** Number of steps (LLM calls) in the tool loop */
+    steps: number;
+    /** Finish reason */
+    finishReason: string;
+    /** Structured output object, if output schema was provided and model supports it.
+     *  When present, this is already validated against the schema — no extraction needed. */
+    structuredOutput?: unknown;
+}
+/**
+ * Options for generation
+ */
+export interface AIGenerateOptions {
+    /** Model alias (e.g., 'sonnet'), tier (e.g., 'premium'), or full provider:modelId */
+    model: string;
+    /** System prompt */
+    system: string;
+    /** Initial user message */
+    prompt: string;
+    /** Available tools (AI SDK ToolSet format) */
+    tools?: ToolSet;
+    /** Maximum response tokens per step */
+    maxTokens?: number;
+    /** Maximum tool loop iterations */
+    maxSteps?: number;
+    /** Timeout in milliseconds */
+    timeoutMs?: number;
+    /** Temperature (0-1) */
+    temperature?: number;
+    /** Required capabilities (validated before execution) */
+    requiredCapabilities?: Array<keyof ModelCapabilities>;
+    /** Provider-specific options (thinking, effort, etc.) passed through to generateText */
+    providerOptions?: ProviderOptions;
+    /** Token budget for context window management. When set, forces wrap-up at 80% usage. */
+    contextBudget?: number;
+    /** Optional budget tracker for sharing state with tools (e.g., get_token_budget) */
+    budgetTracker?: TokenBudgetTracker;
+    /** Structured output schema. When provided and the model supports it,
+     *  constrains the final response to match this schema exactly. */
+    output?: Parameters<typeof Output.object>[0];
+}
+/**
+ * Multi-provider AI SDK wrapper with registry-backed model resolution.
+ *
+ * Wraps Vercel AI SDK v6 to provide:
+ * - Registry-backed model alias resolution (sonnet → anthropic:claude-sonnet-4-5-20250929)
+ * - Multi-provider support (Anthropic + OpenAI + Google bundled, others via dynamic import)
+ * - Capability pre-flight checks (tools, vision, streaming, extendedThinking)
+ * - Unified generation with automatic tool loops
+ * - Automatic prompt caching for Anthropic system messages
+ * - Extended thinking auto-enabled for capable Anthropic models
+ * - Reasoning effort auto-set for capable OpenAI models
+ * - Provider-defined tool support (Anthropic bash, OpenAI shell)
+ * - Error mapping to UluOps error types
+ * - Usage metrics in UluOps format (including OpenAI reasoning + Google thinking tokens)
+ */
+export declare class AIProvider {
+    private config;
+    private catalog;
+    private logger;
+    /** Factory name overrides for providers that don't follow the `create<Name>` convention */
+    private static readonly FACTORY_NAME_OVERRIDES;
+    /**
+     * Allowlist of valid provider names for dynamic import.
+     * Prevents path traversal via crafted provider strings (CWE-829).
+     */
+    private static readonly VALID_DYNAMIC_PROVIDERS;
+    /** Initialized AI SDK provider factories, keyed by provider name */
+    private providers;
+    /** Anthropic provider instance for accessing provider-defined tools */
+    private anthropicInstance?;
+    /** OpenAI provider instance for accessing provider-defined tools */
+    private openaiInstance?;
+    /** Google provider instance for future provider-defined tools (googleSearch, codeExecution) */
+    private googleInstance?;
+    constructor(config: ResolvedConfig, catalog: ModelCatalog, logger: Logger);
+    /**
+     * Generate text with automatic tool loop handling.
+     *
+     * Resolution flow:
+     * 1. Resolve model alias → provider:modelId via ModelCatalog
+     * 2. Validate required capabilities (if specified)
+     * 3. Get AI SDK LanguageModel from provider factory
+     * 4. Build provider options (cache control, thinking, etc.)
+     * 5. Call generateText with maxSteps for automatic tool loop
+     */
+    generate(options: AIGenerateOptions): Promise<AIGenerateResult>;
+    /**
+     * Resolve model alias and ensure provider is loaded.
+     * @internal Used by AgentExecutor for early provider detection.
+     */
+    resolveModel(input: string, opts?: {
+        requiredCapabilities?: Array<keyof ModelCapabilities>;
+    }): Promise<ResolvedModel>;
+    /**
+     * Create provider-defined shell tool for the resolved model's provider.
+     *
+     * - Anthropic: bash_20250124 (Claude's built-in bash knowledge) — returns string
+     * - OpenAI: openai.tools.shell() with local execution — returns structured output
+     *
+     * Returns undefined if the model's provider has no shell tool support or
+     * the provider instance is not available.
+     */
+    createProviderShellTool(provider: string, targetDir: string, timeoutMs?: number): ToolSet | undefined;
+    /**
+     * Build system message with provider-specific cache control.
+     *
+     * For Anthropic: wraps system text in a SystemModelMessage with
+     * ephemeral cache control. The API ignores cache hints if the
+     * prompt is below the minimum cacheable length (1024 tokens for Sonnet).
+     *
+     * For other providers: passes through as plain string.
+     * OpenAI caching is automatic for prompts ≥1024 tokens — no markup needed.
+     */
+    private buildSystemMessage;
+    /**
+     * Build top-level providerOptions for generateText().
+     * Dispatches to provider-specific builders.
+     */
+    private buildProviderOptions;
+    /**
+     * Anthropic-specific provider options.
+     * - Auto-enables extended thinking when model has extendedThinking capability
+     * - Auto-injects context management (clear old tool uses at 100K tokens)
+     */
+    private buildAnthropicOptions;
+    /**
+     * OpenAI-specific provider options.
+     * - Auto-sets reasoningEffort for reasoning-capable models (o1, o3, o4-mini)
+     * - No context management equivalent — budget wrap-up via prepareStep is the only guard
+     * - systemMessageMode auto-handled by @ai-sdk/openai (system → developer for reasoning)
+     */
+    private buildOpenAIOptions;
+    /**
+     * Google-specific provider options.
+     * - Auto-enables thinkingConfig with thinkingBudget for thinking-capable models (Gemini 2.5+)
+     * - No context management equivalent — budget wrap-up via prepareStep is the only guard
+     * - No system message wrapping — Gemini caching is implicit for 2.5+ models
+     */
+    private buildGoogleOptions;
+    /**
+     * Build a prepareStep callback that forces wrap-up when budget is 80% consumed.
+     *
+     * Each step's `inputTokens` is the TOTAL input for that API call (the full
+     * conversation including cached tokens). The last step's value represents the
+     * current context window size. We check that against the budget.
+     */
+    private buildBudgetPrepareStep;
+    /**
+     * Initialize AI SDK provider factories from config.
+     * @ai-sdk/anthropic, @ai-sdk/openai, and @ai-sdk/google are bundled and eagerly initialized.
+     */
+    private initializeProviders;
+    /**
+     * Ensure a provider is loaded. Dynamically imports non-bundled providers.
+     */
+    ensureProvider(providerName: string): Promise<void>;
+    /**
+     * Get provider factory, throwing if not configured.
+     */
+    private getProviderFactory;
+    private missingProviderError;
+    /**
+     * Convert AI SDK usage to UluOps format
+     */
+    private mapUsage;
+    private extractAnthropicUsage;
+    private extractOpenAIUsage;
+    private extractGoogleUsage;
+    private extractGenericUsage;
+    /**
+     * Map AI SDK errors to sdk-core error types.
+     * AI SDK normalizes all provider errors to APICallError with statusCode.
+     */
+    private mapError;
+}
+//# sourceMappingURL=AIProvider.d.ts.map

package/dist/ai/AIProvider.d.ts.map

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