@ninjaxtools/slopdex 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -3,6 +3,7 @@ declare class CodeIndex {
     readonly rootDir: string;
     readonly indexPath: string;
     readonly provider: EmbeddingProvider;
+    readonly reranker: Reranker | undefined;
     readonly descriptionProvider: DescriptionProvider;
     constructor(options: CodeIndexOptions);
     close(): void;
@@ -105,6 +106,24 @@ interface EmbeddingProvider {
         signal?: AbortSignal;
     }): Promise<number[]>;
 }
+interface RerankerProfile {
+    provider: string;
+    model: string;
+}
+interface Reranker {
+    readonly profile: RerankerProfile;
+    /** Preferred embedding-ranked candidate pool size for this reranker. */
+    readonly candidateCount?: number;
+    /** Maximum candidate/result count accepted by this reranker. */
+    readonly maximumCandidateCount?: number;
+    rerank(query: string, documents: readonly string[], options?: {
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<Array<{
+        index: number;
+        score: number;
+    }>>;
+}
 interface DescriptionProfile {
     provider: string;
     model: string;
@@ -149,12 +168,16 @@ interface CodeIndexOptions {
     rootDir: string;
     indexPath?: string;
     provider: EmbeddingProvider;
+    /** Optional second-stage ranker for natural-language query searches. */
+    reranker?: Reranker;
     descriptionProvider?: DescriptionProvider;
     onWarning?: (message: string) => void;
     include?: readonly string[];
     exclude?: readonly string[];
     maxFileSize?: number;
     embeddingBatchSize?: number;
+    /** Emit a stderr notice for every call made by the default description provider. */
+    verbose?: boolean;
     readOnly?: boolean;
 }
 interface UpdateFilesOptions {
@@ -218,6 +241,8 @@ interface AnalysisSimilarity {
 }
 interface SimilarityResult extends SimilarityScores {
     function: IndexedFunction;
+    /** Provider relevance score when a second-stage reranker ordered this result. */
+    rerankScore?: number;
 }
 type CrossSearchSourceFilter = ({
     type: "all";
@@ -243,6 +268,8 @@ interface CrossSearchOptions {
     maxSimilarity?: number;
     includeSymmetricDuplicates?: boolean;
     crossFileOnly?: boolean;
+    /** Re-rank each source's semantic matches from greatest to least physical path distance. */
+    cohesion?: boolean;
     minLines?: number;
     nameRegex?: string;
     signal?: AbortSignal;
@@ -251,9 +278,13 @@ interface CrossSearchOptions {
         total: number;
     }) => void;
 }
+interface CrossSearchMatch extends SimilarityResult {
+    /** Present when cohesion re-ranking is enabled. */
+    physicalDistance?: number;
+}
 interface CrossSearchResult {
     source: IndexedFunction;
-    matches: SimilarityResult[];
+    matches: CrossSearchMatch[];
     scoring?: AnalysisSimilarity & {
         sourceDescriptionProfile: DescriptionProfile | null;
         targetDescriptionProfile: DescriptionProfile | null;
@@ -389,6 +420,7 @@ interface OpenAIEmbeddingProviderOptions {
     model?: string;
     dimensions?: number;
     baseUrl?: string;
+    verbose?: boolean;
 }
 declare class OpenAIEmbeddingProvider implements EmbeddingProvider {
     #private;
@@ -412,6 +444,7 @@ interface OpenAIDescriptionProviderOptions {
     model?: string;
     baseUrl?: string;
     provider?: DescriptionProviderName;
+    verbose?: boolean;
 }
 declare const DESCRIPTION_PROVIDER_NAMES: readonly ["openai", "opencode", "opencode-go"];
 type DescriptionProviderName = typeof DESCRIPTION_PROVIDER_NAMES[number];
@@ -437,6 +470,7 @@ interface JinaEmbeddingProviderOptions {
     model?: string;
     dimensions?: number;
     baseUrl?: string;
+    verbose?: boolean;
 }
 declare class JinaEmbeddingProvider implements EmbeddingProvider {
     #private;
@@ -455,6 +489,68 @@ declare class JinaEmbeddingProvider implements EmbeddingProvider {
     }): Promise<number[]>;
 }
 
+interface HostedRerankerOptions {
+    apiKey?: string;
+    model?: string;
+    baseUrl?: string;
+    verbose?: boolean;
+}
+interface HostedRerankerSettings {
+    provider: "cohere" | "jina";
+    apiKeyName: "COHERE_API_KEY" | "JINA_API_KEY";
+    defaultModel: string;
+    defaultUrl: string;
+    returnDocuments?: boolean;
+}
+declare abstract class HostedReranker implements Reranker {
+    #private;
+    readonly profile: {
+        readonly provider: "jina" | "cohere";
+        readonly model: string;
+    };
+    protected constructor(options: HostedRerankerOptions, settings: HostedRerankerSettings);
+    rerank(query: string, documents: readonly string[], options?: {
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<Array<{
+        index: number;
+        score: number;
+    }>>;
+}
+type CohereRerankerOptions = HostedRerankerOptions;
+declare class CohereReranker extends HostedReranker {
+    constructor(options?: CohereRerankerOptions);
+}
+type JinaRerankerOptions = HostedRerankerOptions;
+declare class JinaReranker extends HostedReranker {
+    constructor(options?: JinaRerankerOptions);
+}
+
+interface OpenAILLMRerankerOptions {
+    apiKey?: string;
+    model?: string;
+    baseUrl?: string;
+    candidateCount?: number;
+    verbose?: boolean;
+}
+declare class OpenAILLMReranker implements Reranker {
+    #private;
+    readonly profile: {
+        readonly provider: "openai";
+        readonly model: string;
+    };
+    readonly candidateCount: number;
+    readonly maximumCandidateCount = 100;
+    constructor(options?: OpenAILLMRerankerOptions);
+    rerank(query: string, documents: readonly string[], options?: {
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<Array<{
+        index: number;
+        score: number;
+    }>>;
+}
+
 declare class CodeIndexError extends Error {
     constructor(message: string, options?: ErrorOptions);
 }
@@ -482,4 +578,4 @@ declare function searchDescription(index: CodeIndex, options: SimilaritySearchOp
 declare function crossSearchFunctions(options: CrossSearchOptions): AsyncGenerator<CrossSearchResult, any, any>;
 declare function analyzeCodeCohesion(options: CohesionAnalysisOptions): Promise<CohesionReport<IndexedFunction>>;
 
-export { type AnalysisSimilarity, type CallableKind, CodeIndex, CodeIndexError, type CodeIndexOptions, type CohesionAnalysisOptions, type CohesionFileReport, type CohesionFunctionReference, type CohesionGroup, type CohesionJsonReport, type CohesionLocation, type CohesionLocationCategory, type CohesionMetrics, type CohesionPair, type CohesionReport, type CrossSearchOptions, type CrossSearchResult, type CrossSearchSourceFilter, type DescriptionFileInput, type DescriptionFileSession, type DescriptionInput, type DescriptionProfile, type DescriptionProvider, type DescriptionProviderName, type DescriptionStats, type EmbeddingProfile, type EmbeddingProvider, GitDivergenceError, GitUnavailableError, IncompatibleIndexError, type IndexStatus, type IndexedFunction, type IndexingError, type IndexingIssue, JinaEmbeddingProvider, type JinaEmbeddingProviderOptions, OpenAIDescriptionProvider, type OpenAIDescriptionProviderOptions, OpenAIEmbeddingProvider, type OpenAIEmbeddingProviderOptions, type ParsedCallable, type ReindexFilesOptions, type ReindexFilesStats, type SimilarityResult, type SimilarityScores, type SimilaritySearchOptions, type SourceMode, type SupportedLanguage, type UpdateFilesOptions, type UpdateFromGitOptions, type UpdateFromWorkingTreeOptions, type UpdateStats, analyzeCodeCohesion, analyzeCohesion, cohesionLocation, crossSearch, crossSearchFunctions, disableDescriptions, openCodeIndex, readIndexErrors, reindexFiles, searchDescription, similaritySearch, updateFiles, updateFromGit, updateFromWorkingTree, useDescriptions };
+export { type AnalysisSimilarity, type CallableKind, CodeIndex, CodeIndexError, type CodeIndexOptions, CohereReranker, type CohereRerankerOptions, type CohesionAnalysisOptions, type CohesionFileReport, type CohesionFunctionReference, type CohesionGroup, type CohesionJsonReport, type CohesionLocation, type CohesionLocationCategory, type CohesionMetrics, type CohesionPair, type CohesionReport, type CrossSearchMatch, type CrossSearchOptions, type CrossSearchResult, type CrossSearchSourceFilter, type DescriptionFileInput, type DescriptionFileSession, type DescriptionInput, type DescriptionProfile, type DescriptionProvider, type DescriptionProviderName, type DescriptionStats, type EmbeddingProfile, type EmbeddingProvider, GitDivergenceError, GitUnavailableError, IncompatibleIndexError, type IndexStatus, type IndexedFunction, type IndexingError, type IndexingIssue, JinaEmbeddingProvider, type JinaEmbeddingProviderOptions, JinaReranker, type JinaRerankerOptions, OpenAIDescriptionProvider, type OpenAIDescriptionProviderOptions, OpenAIEmbeddingProvider, type OpenAIEmbeddingProviderOptions, OpenAILLMReranker, type OpenAILLMRerankerOptions, type ParsedCallable, type ReindexFilesOptions, type ReindexFilesStats, type Reranker, type RerankerProfile, type SimilarityResult, type SimilarityScores, type SimilaritySearchOptions, type SourceMode, type SupportedLanguage, type UpdateFilesOptions, type UpdateFromGitOptions, type UpdateFromWorkingTreeOptions, type UpdateStats, analyzeCodeCohesion, analyzeCohesion, cohesionLocation, crossSearch, crossSearchFunctions, disableDescriptions, openCodeIndex, readIndexErrors, reindexFiles, searchDescription, similaritySearch, updateFiles, updateFromGit, updateFromWorkingTree, useDescriptions };