import type { Memory, Fact, FactCategory, EntityProfile, Scopes, Tier, StructuredStore, VectorStore, EmbeddingProvider, RerankerProvider, Logger, QueryResult } from '@kybernesis/arcana-contracts';
export interface HybridSearchInput {
    query: string;
    scopes?: Scopes;
    tier?: Tier;
    topK?: number;
    /**
     * @deprecated Since v0.4.0 (ADR 011 — port-first principle). Accepted for
     * shape stability but silently ignored at runtime; the graph-BFS retrieval
     * channel will return as v2 hybridSearch after parity is proven.
     */
    graphHops?: number;
    rerank?: boolean;
}
/**
 * Result shape — KyberBot-faithful (v0.4.0 rebase per ADR 011). Three channels
 * collapse onto two exposed score fields: `semanticScore` carries the semantic
 * channel's RRF contribution; `keywordScore` collapses the keyword (FTS),
 * temporal, and entity-name-filter channels' contributions. `matchType` is
 * `'semantic' | 'keyword' | 'both'` mirroring KyberBot's vocabulary.
 *
 * `graphScore` is retained as a deprecated zero-emitting field for shape
 * stability — graph-BFS retrieval returns in a future v2 hybridSearch.
 */
export interface HybridSearchResult {
    memory: Memory;
    /** Fused RRF score across all channels this memory appears in. */
    score: number;
    /** Semantic channel RRF contribution. 0 when absent from this channel. */
    semanticScore: number;
    /** Collapsed RRF contribution from keyword + temporal + entity channels. 0 when absent. */
    keywordScore: number;
    /** @deprecated Since v0.4.0. Always 0; graph-BFS retrieval returns in v2. */
    graphScore: number;
    matchType: 'semantic' | 'keyword' | 'both';
    why?: string;
}
export interface FactRetrievalInput {
    query: string;
    depth?: number;
    scopes?: Scopes;
    tokenBudget?: number;
    /** v1.0.0 — filter Layer 0 fact-FTS to a single category. */
    category?: FactCategory;
}
/**
 * v1.0.0 — fact bundle from KB `fact-retrieval.ts:31-59` (`FactSearchResult`).
 * Per ADR 013.
 */
export interface ScoredFact {
    fact: Fact;
    score: number;
    /** Which retrieval layer surfaced this fact. */
    source: 'direct_facts' | 'entity_expansion' | 'graph_expansion' | 'bridge';
}
export interface FactRetrievalResult {
    /** Direct fact hits — Layer 0 (fact-FTS) + entity-derived facts. */
    facts: ScoredFact[];
    /** Memory-shaped results from the 4 memory layers. */
    supportingMemories: HybridSearchResult[];
    /** Token-budgeted concatenation of facts + supporting memories, prompt-ready. */
    assembledContext: string;
    /** Rough token count — `Math.ceil(assembledContext.length / 4)` (KB convention). */
    tokenEstimate: number;
    stats: {
        perLayerCounts: Record<string, number>;
        totalCandidates: number;
        deduplicatedCount: number;
    };
}
export interface RetrieveDeps {
    structured: StructuredStore;
    vector: VectorStore;
    embed: EmbeddingProvider;
    reranker?: RerankerProvider;
    logger: Logger;
}
export interface RetrieveApi {
    /** Hybrid retrieval: semantic + keyword + graph-expansion, fused via RRF. */
    hybridSearch(input: HybridSearchInput): Promise<QueryResult<HybridSearchResult[]>>;
    /**
     * Multi-stage fact-aware retrieval. v1.0.0: 5-layer flow per ADR 013 —
     * Layer 0 direct fact-FTS, then memory layers 1-4 (direct memory FTS,
     * entity-name expansion, 1-hop graph, bridge). Returns a rich
     * `FactRetrievalResult` bundle ported from KyberBot's empirical shape.
     */
    factRetrieval(input: FactRetrievalInput): Promise<QueryResult<FactRetrievalResult>>;
    /** Compiled dossier for an entity. */
    getEntityProfile(entityId: string): Promise<QueryResult<EntityProfile | null>>;
}
export declare function createRetrieve(deps: RetrieveDeps): RetrieveApi;
//# sourceMappingURL=index.d.ts.map