import { type SkillContent } from '../common/interfaces';
import { type SkillMetadata } from '../common/metadata';
/**
 * Options for searching skills.
 */
export interface SkillSearchOptions {
    /**
     * Maximum number of results to return.
     * @default 10
     */
    topK?: number;
    /**
     * Filter by specific tags.
     */
    tags?: string[];
    /**
     * Minimum similarity score threshold (0-1).
     * @default 0.1
     */
    minScore?: number;
    /**
     * Only return skills where all referenced tools are available.
     * @default false
     */
    requireAllTools?: boolean;
    /**
     * Skill IDs to exclude from results.
     */
    excludeIds?: string[];
    /**
     * Filter by specific tools (skills must reference these tools).
     */
    tools?: string[];
    /**
     * Anti-query / negative search term(s). A skill's relevance score is reduced
     * by how strongly it matches these terms — surfacing what the user wants while
     * demoting what they explicitly do NOT want (e.g. query "rate limiting",
     * negativeQuery "enforcement" to prefer guidance over enforcement skills).
     * Honored when the installed `vectoriadb` supports it; ignored otherwise.
     */
    negativeQuery?: string | string[];
    /**
     * Weight applied to the negative-query penalty (higher = stronger demotion).
     * @default 1
     */
    negativeWeight?: number;
}
/**
 * Options for listing skills.
 */
export interface SkillListOptions {
    /**
     * Number of skills to skip (for pagination).
     * @default 0
     */
    offset?: number;
    /**
     * Maximum number of skills to return.
     * @default 50
     */
    limit?: number;
    /**
     * Filter by specific tags.
     */
    tags?: string[];
    /**
     * Field to sort by.
     * @default 'name'
     */
    sortBy?: 'name' | 'priority' | 'createdAt';
    /**
     * Sort order.
     * @default 'asc'
     */
    sortOrder?: 'asc' | 'desc';
    /**
     * Include hidden skills in results.
     * @default false
     */
    includeHidden?: boolean;
}
/**
 * Result from a skill search operation.
 */
export interface SkillSearchResult {
    /**
     * The skill metadata.
     */
    metadata: SkillMetadata;
    /**
     * Relevance score (0-1).
     */
    score: number;
    /**
     * Tools that are available in the current scope.
     */
    availableTools: string[];
    /**
     * Tools that are referenced but not available.
     */
    missingTools: string[];
    /**
     * Source of the skill ('local' or 'external').
     */
    source: 'local' | 'external';
}
/**
 * Result from loading a skill.
 */
export interface SkillLoadResult {
    /**
     * The loaded skill content.
     */
    skill: SkillContent;
    /**
     * Tools that are available in the current scope.
     */
    availableTools: string[];
    /**
     * Tools that are referenced but not available.
     */
    missingTools: string[];
    /**
     * True if all required tools are available.
     */
    isComplete: boolean;
    /**
     * Warning message if tools are missing.
     */
    warning?: string;
}
/**
 * Result from listing skills.
 */
export interface SkillListResult {
    /**
     * List of skill metadata.
     */
    skills: SkillMetadata[];
    /**
     * Total number of skills matching the filter.
     */
    total: number;
    /**
     * Whether there are more skills beyond this page.
     */
    hasMore: boolean;
}
/**
 * Provider type identifier.
 */
export type SkillStorageProviderType = 'memory' | 'vectordb' | 'postgres' | 'external' | 'custom';
/**
 * Interface for skill storage providers.
 *
 * Storage providers handle persistence and retrieval of skills,
 * enabling both local (in-memory) and external (database) storage.
 */
export interface SkillStorageProvider {
    /**
     * Provider type identifier.
     */
    readonly type: SkillStorageProviderType;
    /**
     * Initialize the storage provider.
     * Called once during startup.
     */
    initialize(): Promise<void>;
    /**
     * Search for skills matching a query.
     *
     * @param query - Search query string
     * @param options - Search options
     * @returns Array of matching skills with scores
     */
    search(query: string, options?: SkillSearchOptions): Promise<SkillSearchResult[]>;
    /**
     * Load a skill by ID.
     *
     * @param skillId - The skill identifier
     * @returns The loaded skill or null if not found
     */
    load(skillId: string): Promise<SkillLoadResult | null>;
    /**
     * List skills with optional filtering and pagination.
     *
     * @param options - List options
     * @returns Paginated list of skills
     */
    list(options?: SkillListOptions): Promise<SkillListResult>;
    /**
     * Check if a skill exists.
     *
     * @param skillId - The skill identifier
     * @returns True if the skill exists
     */
    exists(skillId: string): Promise<boolean>;
    /**
     * Count skills matching optional criteria.
     *
     * @param options - Filter options
     * @returns Number of matching skills
     */
    count(options?: {
        tags?: string[];
        includeHidden?: boolean;
    }): Promise<number>;
    /**
     * Dispose of resources.
     * Called during shutdown.
     */
    dispose(): Promise<void>;
}
/**
 * Interface for skill storage providers that support adding skills.
 * Used by providers that can dynamically add skills (e.g., file watchers).
 */
export interface MutableSkillStorageProvider extends SkillStorageProvider {
    /**
     * Add a skill to the storage.
     *
     * @param skill - The skill content to add
     */
    add(skill: SkillContent): Promise<void>;
    /**
     * Update an existing skill.
     *
     * @param skillId - The skill identifier
     * @param skill - The updated skill content
     */
    update(skillId: string, skill: SkillContent): Promise<void>;
    /**
     * Remove a skill from the storage.
     *
     * @param skillId - The skill identifier
     */
    remove(skillId: string): Promise<void>;
    /**
     * Clear all skills from the storage.
     */
    clear(): Promise<void>;
}
//# sourceMappingURL=skill-storage.interface.d.ts.map