/**
 * MoE Config Schema
 *
 * Configuration for Mixture of Experts routing and caching.
 * These are runtime settings that affect how MoE layers execute.
 *
 * @module config/schema/moe
 */

/** Supported data types for router computation */
export type RouterDtype = 'f16' | 'f32';

/** Expert execution scheduling policy after Top-K routing */
export type ActiveExpertSelection = 'all' | 'topk-readback' | 'topk-route';

/**
 * Configuration for MoE routing behavior.
 *
 * Controls how tokens are routed to experts during inference.
 */
export interface MoERoutingConfigSchema {
  /** Number of experts in the MoE layer */
  numExperts: number;

  /** Number of experts to activate per token (top-K routing) */
  topK: number;

  /** Normalize expert weights after routing */
  normalizeWeights: boolean;

  /** Data type for router computation */
  routerDtype: RouterDtype;

  /**
   * Max tokens per expert (0 = auto).
   * Used to size MoE gather/scatter buffers.
   */
  maxTokensPerExpert: number;

  /** Headroom multiplier for auto maxTokensPerExpert */
  maxTokensPerExpertHeadroom: number;

  /** Minimum maxTokensPerExpert when auto-tuning */
  maxTokensPerExpertMin: number;

  /**
   * Hard cap for maxTokensPerExpert (0 = no cap).
   * Useful to limit buffer sizes on constrained devices.
   */
  maxTokensPerExpertCap: number;

  /**
   * Expert execution scheduling policy.
   * "all" executes every expert with the configured row budget.
   * "topk-readback" reads the compact Top-K index buffer and executes only
   * experts selected by the current batch.
   * "topk-route" executes each Top-K route directly on GPU without CPU
   * scheduling readback when the model format supports route-wise kernels.
   */
  activeExpertSelection: ActiveExpertSelection;
}

/** Default MoE routing configuration */
export declare const DEFAULT_MOE_ROUTING_CONFIG: MoERoutingConfigSchema;

/**
 * Configuration for MoE dequantization caching.
 *
 * Controls the LRU cache for dequantized expert weights to avoid
 * redundant dequantization when experts are reused across tokens.
 */
export interface MoECacheConfigSchema {
  /** Maximum number of dequantized expert entries to cache */
  dequantCacheMaxEntries: number;
}

/** Default MoE cache configuration */
export declare const DEFAULT_MOE_CACHE_CONFIG: MoECacheConfigSchema;

/**
 * Complete MoE runtime configuration schema.
 *
 * Controls all aspects of MoE inference behavior.
 */
export interface MoERuntimeConfigSchema {
  routing: MoERoutingConfigSchema;
  cache: MoECacheConfigSchema;
}

/** Default MoE runtime configuration */
export declare const DEFAULT_MOE_RUNTIME_CONFIG: MoERuntimeConfigSchema;