import type { NeuroLink } from "../neurolink.js";
import type { AIProviderName } from "../constants/enums.js";
import type { AIProvider, NeurolinkCredentials, ProviderConstructor, ProviderDescriptor, ProviderRegistration } from "../types/index.js";
/**
 * Resolve a registered provider name (or alias) to its NeurolinkCredentials
 * key. Backed by ProviderFactory.getDescriptor() — PROVIDER_DESCRIPTORS is
 * the single source of truth for provider identity — instead of a
 * hand-maintained map, so this can no longer drift out of sync with the
 * descriptors, and it correctly resolves aliases (e.g. "hf") through
 * PROVIDER_ALIAS_INDEX, not just canonical names. Falls back to the
 * lowercased input when no descriptor is found, matching the retired
 * map's behavior for unknown provider names.
 *
 * Referencing ProviderFactory here (defined further down this file) is
 * safe: this function's body only runs when called, by which point the
 * module has finished evaluating and ProviderFactory is fully defined —
 * there is no temporal-dead-zone hazard from the declaration order.
 */
export declare function resolveCredentialKey(providerName: string): string;
/**
 * True Factory Pattern implementation for AI Providers
 * Uses registration-based approach to eliminate switch statements
 * and enable dynamic provider registration
 */
export declare class ProviderFactory {
    private static readonly providers;
    private static initialized;
    /**
     * Register a provider with the factory
     */
    static registerProvider(name: AIProviderName | string, constructor: ProviderConstructor, defaultModel?: string, // Optional - provider can read from env
    aliases?: string[], descriptor?: ProviderDescriptor): void;
    /**
     * Create a provider instance
     * @param providerName - Provider name (optional, uses NEUROLINK_PROVIDER env var or 'vertex' as default)
     * @param modelName - Model name (optional, uses provider-specific env var or registry default)
     */
    static createProvider(providerName?: AIProviderName | string, modelName?: string, sdk?: NeuroLink, region?: string, credentials?: NeurolinkCredentials): Promise<AIProvider>;
    /**
     * Check if a provider is registered
     */
    static hasProvider(providerName: string): boolean;
    /**
     * Get list of available providers
     */
    /**
     * Explain why a provider name did not resolve, usefully (#354).
     *
     * Three distinct situations used to share one generic message:
     *
     * - The registry is empty, because `ProviderRegistry.registerAllProviders()`
     *   has not run yet. Every name is unresolvable, and listing zero available
     *   providers tells the reader nothing about why.
     * - The name IS a known provider but has no registration — recognised,
     *   unavailable. Distinct from a typo and worth saying so.
     * - The name is not a provider at all, in which case a near-miss is almost
     *   always a typo and is worth naming: "opennai" -> "openai".
     *
     * Canonical names are offered as suggestions ahead of aliases, so a typo
     * resolves to the name the docs use.
     *
     * @param requested - The provider name as the caller supplied it
     * @returns A message naming the situation and what to do about it
     */
    private static describeUnresolvableProvider;
    static getAvailableProviders(): string[];
    /**
     * Get provider registration info
     */
    static getProviderInfo(providerName: string): ProviderRegistration | undefined;
    /**
     * Look up a provider's static descriptor. Checks the built-in
     * PROVIDER_DESCRIPTORS first (works even before registerAllProviders()
     * has run, and resolves aliases via PROVIDER_ALIAS_INDEX), then falls
     * back to whatever descriptor a live custom registration attached via
     * registerProvider()'s 5th parameter.
     */
    static getDescriptor(name: string): ProviderDescriptor | undefined;
    /** All built-in provider descriptors (does not include custom-registered providers that lack a descriptor). */
    static getAllDescriptors(): readonly ProviderDescriptor[];
    /**
     * Normalize provider names using aliases (PHASE 1: Factory Pattern)
     */
    static normalizeProviderName(providerName: string): string | null;
    /**
     * Clear all registrations (mainly for testing)
     */
    static clearRegistrations(): void;
    /**
     * Ensure providers are initialized
     */
    private static ensureInitialized;
    /**
     * Initialize default providers
     * NOTE: Providers are now registered by ProviderRegistry to avoid circular dependencies
     */
    private static initializeDefaultProviders;
    /**
     * Create the best available provider for the given name
     * Used by NeuroLink SDK for streaming and generation
     */
    static createBestProvider(providerName: AIProviderName | string, modelName?: string, enableMCP?: boolean, sdk?: NeuroLink, credentials?: NeurolinkCredentials): Promise<AIProvider>;
}
/**
 * Helper function to create providers with backward compatibility
 */
export declare function createAIProvider(providerName: AIProviderName | string, modelName?: string, credentials?: NeurolinkCredentials): Promise<AIProvider>;