@vfarcic/dot-ai/dist/core/ai-provider.interface.d.ts

AI-powered development productivity platform that enhances software development workflows through intelligent automation and AI-driven assistance

/**
 * AI Provider Interface
 *
 * Provider-agnostic abstraction for AI services supporting multiple providers
 * through Vercel AI SDK (19+ providers supported).
 *
 * This interface is extracted from actual ClaudeIntegration usage patterns
 * across the codebase, ensuring backward compatibility and minimal migration effort.
 *
 * Phase 1 Implementation (PRD 73): Anthropic, OpenAI, Google
 * Additional: AWS Bedrock, xAI Grok, OpenRouter, Custom endpoints
 */
/**
 * Standard AI response structure
 */
export interface AIResponse {
    content: string;
    usage: {
        input_tokens: number;
        output_tokens: number;
        cache_creation_input_tokens?: number;
        cache_read_input_tokens?: number;
    };
}
/**
 * AI Provider configuration
 */
export interface AIProviderConfig {
    /** API key for the provider */
    apiKey: string;
    /** Provider type (extensible string - supports any Vercel AI SDK provider) */
    provider: string;
    /** Optional model override (defaults to provider-specific default) */
    model?: string;
    /** Enable debug mode for logging AI interactions */
    debugMode?: boolean;
    /** Custom endpoint URL for OpenAI-compatible APIs (PRD #194)
     *
     * Enables connection to:
     * - Self-hosted LLMs (Ollama, vLLM, LocalAI)
     * - Alternative SaaS providers (Azure OpenAI, LiteLLM, OpenRouter)
     * - Internal inference services
     *
     * Example values:
     * - Ollama: "http://ollama-service:11434/v1"
     * - vLLM: "http://vllm-service:8000/v1"
     * - Azure OpenAI: "https://YOUR_RESOURCE.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT"
     *
     * Note: Models must support 8K+ output tokens. Custom endpoint will receive
     * maxOutputTokens=8192 in API requests.
     */
    baseURL?: string;
    /** Custom HTTP headers to pass to the AI provider SDK (PRD #443)
     *
     * Parsed from CUSTOM_LLM_HEADERS environment variable (JSON string).
     * Merged with provider-specific default headers (e.g., Anthropic beta header),
     * with custom headers taking precedence.
     *
     * Example: { "version": "2026-02-20", "x-custom-auth": "token123" }
     */
    customHeaders?: Record<string, string>;
}
/**
 * Tool definition for AI providers
 * Defines a tool that the AI can call during agentic loops
 */
export interface AITool {
    /** Unique tool name (e.g., 'kubectl_get', 'search_capabilities') */
    name: string;
    /** Human-readable description of what the tool does and when to use it */
    description: string;
    /** JSON schema for tool input parameters */
    inputSchema: {
        type: 'object';
        properties: Record<string, unknown>;
        required?: string[];
    };
}
/**
 * Tool executor function type
 * Called by the provider when AI requests a tool execution
 */
export type ToolExecutor = (toolName: string, input: unknown) => Promise<unknown>;
/**
 * Record of a tool call execution
 */
export interface ToolCallRecord {
    tool: string;
    input: unknown;
    output: unknown;
}
/**
 * Configuration for agentic tool loop
 */
export interface ToolLoopConfig {
    /** System prompt with context and strategic guidance */
    systemPrompt: string;
    /** User message/query to respond to */
    userMessage: string;
    /** Available tools for this workflow (scoped to workflow needs) */
    tools: AITool[];
    /** Function to execute tool calls */
    toolExecutor: ToolExecutor;
    /** Maximum number of AI iterations (default: 20) */
    maxIterations?: number;
    /** Optional callback invoked after each iteration */
    onIteration?: (iteration: number, toolCalls: ToolCallRecord[]) => void;
    /** Optional operation identifier for metrics and debugging */
    operation?: string;
    /** PRD #154: Evaluation context for dataset generation */
    evaluationContext?: {
        user_intent?: string;
    };
    /** PRD #154: Interaction ID for dataset generation pairing */
    interaction_id?: string;
}
/**
 * Result from agentic tool loop
 */
export interface AgenticResult {
    /** Final text response from AI after completing tool loop */
    finalMessage: string;
    /** Number of iterations executed */
    iterations: number;
    /** All tool calls executed during the loop */
    toolCallsExecuted: ToolCallRecord[];
    /** Token usage statistics including cache metrics */
    totalTokens: {
        input: number;
        output: number;
        cacheCreation?: number;
        cacheRead?: number;
    };
    /** Execution status (PRD #143 Decision 5) */
    status?: 'success' | 'failed' | 'timeout' | 'parse_error';
    /** Reason for loop completion (PRD #143 Decision 5) */
    completionReason?: 'investigation_complete' | 'max_iterations' | 'parse_failure' | 'model_stopped' | 'error';
    /** Specific model version used (PRD #143 Decision 5) */
    modelVersion?: string;
    /** Debug files created during toolLoop execution (PRD #154) */
    debugFiles?: {
        full_prompt: string;
        full_response: string;
    };
}
/**
 * AI Provider Interface
 *
 * Minimal interface based on actual usage across 10 dependent files.
 * Only includes methods that are currently called in production code.
 */
export interface AIProvider {
    /**
     * Send a message to the AI service
     *
     * Primary method for all AI interactions. Supports streaming for long operations.
     * Used in: recommend.ts, answer-question.ts, generate-manifests.ts, remediate.ts,
     *          schema.ts, unified-creation-session.ts, platform-operations.ts
     *
     * @param message The message/prompt to send
     * @param operation Optional operation identifier for debugging (e.g., 'deployment', 'intent-analysis')
     * @param evaluationContext Optional evaluation context for dataset generation (PRD #154)
     * @returns AI response with content and usage statistics
     */
    sendMessage(message: string, operation?: string, evaluationContext?: {
        user_intent?: string;
        interaction_id?: string;
    }): Promise<AIResponse>;
    /**
     * Check if the provider is properly initialized
     *
     * Used in: schema.ts (pre-flight check before AI calls)
     *
     * @returns true if provider is ready to use, false otherwise
     */
    isInitialized(): boolean;
    /**
     * Get the default model for this provider
     *
     * NEW: Required to replace hardcoded model at claude.ts:181
     * Each provider has different model naming conventions.
     *
     * @returns Model identifier (e.g., 'claude-sonnet-4-6', 'gpt-5.4', 'gemini-3.1-pro-preview')
     */
    getDefaultModel(): string;
    /**
     * Get the provider type
     *
     * NEW: Useful for debugging and logging
     *
     * @returns Provider identifier (e.g., 'anthropic', 'openai', 'google')
     */
    getProviderType(): string;
    /**
     * Get the current model name being used
     *
     * @returns Model name (e.g., 'grok-4', 'claude-sonnet-4-6')
     */
    getModelName(): string;
    /**
     * Execute agentic loop with tool calling (PRD #136)
     *
     * AI autonomously decides which tools to call and when to stop.
     * Supports multi-turn conversations with tool execution.
     * Used by remediate and operate tools for AI-driven investigations.
     *
     * @param config Tool loop configuration with system prompt, tools, and executor
     * @returns Agentic result with final message, iterations, tool calls, and token usage
     */
    toolLoop(config: ToolLoopConfig): Promise<AgenticResult>;
}
//# sourceMappingURL=ai-provider.interface.d.ts.map