@rce-mcp/retrieval-core 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -1,13 +1,24 @@
-import type { EnhancePromptInput, EnhancePromptOutput, SearchContextInput, SearchContextOutput } from "@rce-mcp/contracts";
+import type { EnhancePromptInput, EnhancePromptOutput, EnhancePromptStyle, SearchContextInput, SearchContextOutput } from "@rce-mcp/contracts";
 import { type CandidateScoreWeights, type IndexRepository, type QueryCache, type WorkspaceRecord } from "@rce-mcp/data-plane";
 import { type Observability } from "@rce-mcp/observability";
 import { type ChunkingStrategy } from "./chunking.js";
+type ContextRef = EnhancePromptOutput["context_refs"][number];
 export declare const DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_BASE_URL = "https://router.tumuer.me/v1";
 export declare const DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-4B";
 export declare const DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_DIMENSIONS = 2560;
 export declare const DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_TIMEOUT_MS = 10000;
 export declare const DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_BATCH_SIZE = 64;
 export declare const DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_MAX_RETRIES = 2;
+export declare const DEFAULT_OPENAI_COMPATIBLE_EMBEDDING_TRANSIENT_403_MAX_RETRIES = 4;
+export declare const DEFAULT_OPENAI_COMPATIBLE_RERANKER_BASE_URL = "https://router.tumuer.me/v1";
+export declare const DEFAULT_OPENAI_COMPATIBLE_RERANKER_MODEL = "Qwen/Qwen3-Reranker-4B";
+export declare const DEFAULT_OPENAI_COMPATIBLE_RERANKER_TIMEOUT_MS = 2500;
+export declare const DEFAULT_SEARCH_RERANKER_TOP_N = 30;
+export declare const DEFAULT_PROVIDER_MAX_REQUESTS_PER_MINUTE = 90;
+export declare const DEFAULT_PROVIDER_LIMIT_INDEX_MAX_WAIT_MS = 120000;
+export declare const DEFAULT_PROVIDER_LIMIT_QUERY_MAX_WAIT_MS = 1000;
+export declare const DEFAULT_PROVIDER_LIMIT_RERANK_MAX_WAIT_MS = 500;
+export declare const DEFAULT_CLAUDE_ENHANCER_MODEL = "claude-3-5-sonnet-latest";
 export interface RetrievalPathBiasConfig {
     source_path_boost: number;
     low_priority_prefix_penalty: number;
@@ -36,6 +47,10 @@ export interface RetrievalPathBiasConfig {
     negation_avoid_tests_penalty: number;
     negation_avoid_examples_penalty: number;
     negation_avoid_archive_penalty: number;
+    security_trace_meta_penalty: number;
+    literal_path_boost: number;
+    literal_snippet_boost: number;
+    literal_max_boost: number;
     min_total_bias: number;
     max_total_bias: number;
 }
@@ -56,9 +71,18 @@ export interface RetrievalEnhancerConfig {
     max_candidates_pre_rerank: number;
     rerank_timeout_ms: number;
 }
+export type EnhancerToolMode = "none" | "read_only";
+export interface RetrievalEnhancerGenerationConfig {
+    timeout_ms: number;
+    max_retries: number;
+    tool_mode: EnhancerToolMode;
+    max_context_snippets: number;
+}
 export interface RetrievalChunkingConfig {
     strategy: ChunkingStrategy;
     fallback_strategy: "sliding";
+    target_chunk_tokens: number;
+    chunk_overlap_tokens: number;
     parse_timeout_ms: number;
     enabled_languages: string[];
 }
@@ -68,15 +92,19 @@ export type RetrievalScoringConfigInput = Partial<{
     rerank: Partial<RetrievalRerankConfig>;
 }>;
 export type RetrievalEnhancerConfigInput = Partial<RetrievalEnhancerConfig>;
+export type RetrievalEnhancerGenerationConfigInput = Partial<RetrievalEnhancerGenerationConfig>;
 export type RetrievalChunkingConfigInput = Partial<{
     strategy: ChunkingStrategy;
     fallback_strategy: "sliding";
+    target_chunk_tokens: number;
+    chunk_overlap_tokens: number;
     parse_timeout_ms: number;
     enabled_languages: string[];
 }>;
 export declare const BASELINE_RETRIEVAL_SCORING_CONFIG: RetrievalScoringConfig;
 export declare const CONSERVATIVE_RETRIEVAL_SCORING_CONFIG: RetrievalScoringConfig;
 export declare const DEFAULT_RETRIEVAL_ENHANCER_CONFIG: RetrievalEnhancerConfig;
+export declare const DEFAULT_RETRIEVAL_ENHANCER_GENERATION_CONFIG: RetrievalEnhancerGenerationConfig;
 export declare const DEFAULT_RETRIEVAL_CHUNKING_CONFIG: RetrievalChunkingConfig;
 declare const BUILTIN_RETRIEVAL_SCORING_PROFILES: {
     readonly baseline: RetrievalScoringConfig;
@@ -89,12 +117,13 @@ export declare function resolveRetrievalScoringProfile(profile_id: string | unde
 };
 export declare function mergeRetrievalScoringConfig(base: RetrievalScoringConfig, overrides?: RetrievalScoringConfigInput): RetrievalScoringConfig;
 export declare function mergeRetrievalEnhancerConfig(base: RetrievalEnhancerConfig, overrides?: RetrievalEnhancerConfigInput): RetrievalEnhancerConfig;
+export declare function mergeRetrievalEnhancerGenerationConfig(base: RetrievalEnhancerGenerationConfig, overrides?: RetrievalEnhancerGenerationConfigInput): RetrievalEnhancerGenerationConfig;
 export declare function mergeRetrievalChunkingConfig(base: RetrievalChunkingConfig, overrides?: RetrievalChunkingConfigInput): RetrievalChunkingConfig;
-declare const REASON_STRINGS: readonly ["semantic match", "exact symbol match", "path and token overlap", "recently modified relevant module"];
+declare const REASON_STRINGS: readonly ["semantic match", "exact literal match", "path token overlap", "recently modified relevant module"];
 export type RetrievalReason = (typeof REASON_STRINGS)[number];
 export declare class RetrievalError extends Error {
-    readonly code: "INVALID_ARGUMENT" | "NOT_FOUND" | "UPSTREAM_FAILURE";
-    constructor(code: "INVALID_ARGUMENT" | "NOT_FOUND" | "UPSTREAM_FAILURE", message: string);
+    readonly code: "INVALID_ARGUMENT" | "NOT_FOUND" | "RATE_LIMITED" | "UPSTREAM_FAILURE";
+    constructor(code: "INVALID_ARGUMENT" | "NOT_FOUND" | "RATE_LIMITED" | "UPSTREAM_FAILURE", message: string);
 }
 export interface RawFile {
     path: string;
@@ -161,13 +190,18 @@ export interface IndexingReport {
 }
 export interface RetrievalCoreOptions {
     cacheTtlSeconds?: number;
+    internalCandidateDepth?: number;
     embeddingProvider?: EmbeddingProvider;
     embeddingDescriptor?: EmbeddingDescriptor;
+    rerankerProvider?: RerankerProvider;
+    rerankerTopN?: number;
+    enhancerProvider?: EnhancerGenerationProvider;
     observability?: Observability;
     scoringProfile?: BuiltinRetrievalScoringProfileId;
     scoringProfileId?: string;
     scoringConfig?: RetrievalScoringConfigInput;
     enhancerConfig?: RetrievalEnhancerConfigInput;
+    enhancerGenerationConfig?: RetrievalEnhancerGenerationConfigInput;
     chunkingConfig?: RetrievalChunkingConfigInput;
     enhancerDecisionTraceEnabled?: boolean;
 }
@@ -185,6 +219,62 @@ export interface EmbeddingProvider {
     }): Promise<number[][]>;
     describe?(): EmbeddingDescriptor;
 }
+export interface RerankerDescriptor {
+    provider: string;
+    model?: string;
+}
+export interface RerankerResult {
+    index: number;
+    relevance_score: number;
+}
+export interface RerankerProvider {
+    rerank(input: {
+        query: string;
+        documents: string[];
+        top_n: number;
+    }): Promise<RerankerResult[]>;
+    describe?(): RerankerDescriptor;
+}
+export type EnhancerIntent = "bugfix" | "feature" | "refactor" | "docs" | "tests" | "unknown";
+export type EnhancerOutputLanguage = "en" | "es" | "zh";
+type ResolvedEnhancerPromptStyle = Exclude<EnhancePromptStyle, "auto">;
+export interface EnhancerContextSnippet {
+    path: string;
+    start_line: number;
+    end_line: number;
+    reason: string;
+    snippet: string;
+    score: number;
+}
+export interface EnhancerGenerationRequest {
+    trace_id: string;
+    tenant_id: string;
+    workspace_id?: string;
+    request: EnhancePromptInput;
+    style_requested: EnhancePromptStyle;
+    style_resolved: ResolvedEnhancerPromptStyle;
+    intent: EnhancerIntent;
+    query_intent: "symbol-heavy" | "impl-focused" | "conceptual";
+    language: EnhancerOutputLanguage;
+    context_refs: ContextRef[];
+    context_snippets: EnhancerContextSnippet[];
+    warnings: string[];
+    questions: string[];
+    tool_mode: EnhancerToolMode;
+    abort_signal?: AbortSignal;
+    on_progress?: () => void;
+}
+export interface EnhancerGenerationResult {
+    enhanced_prompt: string;
+}
+export interface EnhancerProviderDescriptor {
+    provider: string;
+    model?: string;
+}
+export interface EnhancerGenerationProvider {
+    generate(input: EnhancerGenerationRequest): Promise<EnhancerGenerationResult>;
+    describe?(): EnhancerProviderDescriptor;
+}
 export interface DeterministicEmbeddingProviderOptions {
     dimensions?: number;
     model?: string;
@@ -198,8 +288,82 @@ export interface OpenAICompatibleEmbeddingProviderOptions {
     timeout_ms?: number;
     batch_size?: number;
     max_retries?: number;
+    transient_forbidden_max_retries?: number;
+    request_limiter?: ProviderRequestLimiter;
+    request_limit_scope_id?: string;
+    max_requests_per_minute?: number;
+    index_max_wait_ms?: number;
+    query_max_wait_ms?: number;
+    observability?: Observability;
+}
+export interface OpenAICompatibleRerankerProviderOptions {
+    base_url: string;
+    api_key: string;
+    model?: string;
+    timeout_ms?: number;
+    request_limiter?: ProviderRequestLimiter;
+    request_limit_scope_id?: string;
+    max_requests_per_minute?: number;
+    rerank_max_wait_ms?: number;
     observability?: Observability;
 }
+export interface ClaudeAgentEnhancerProviderOptions {
+    api_key: string;
+    model?: string;
+    base_url?: string;
+    max_tokens?: number;
+    path_to_claude_code_executable?: string;
+    permission_mode?: ClaudeCodePermissionMode;
+}
+export type ClaudeCodePermissionMode = "default" | "acceptEdits" | "bypassPermissions" | "plan";
+export interface ProviderRateLimitAcquireInput {
+    scope: string;
+    max_requests_per_minute: number;
+    max_wait_ms: number;
+}
+export interface ProviderRateLimitAcquireResult {
+    wait_ms: number;
+}
+export interface ProviderRequestLimiter {
+    readonly mode?: "local" | "redis" | "custom";
+    acquire(input: ProviderRateLimitAcquireInput): Promise<ProviderRateLimitAcquireResult>;
+}
+export interface RedisProviderRequestLimiterClient {
+    eval(script: string, numKeys: number, ...args: Array<string | number>): Promise<unknown>;
+}
+export interface RedisProviderRequestLimiterOptions {
+    redis: RedisProviderRequestLimiterClient;
+    key_prefix?: string;
+    window_ms?: number;
+    now?: () => number;
+    sleeper?: (ms: number) => Promise<void>;
+}
+export declare class ProviderRateLimitExceededError extends Error {
+    readonly retry_after_ms: number;
+    constructor(message: string, retry_after_ms: number);
+}
+export declare class LocalProviderRequestLimiter implements ProviderRequestLimiter {
+    readonly mode: "local";
+    private readonly buckets;
+    private readonly now;
+    private readonly sleeper;
+    constructor(options?: {
+        now?: () => number;
+        sleeper?: (ms: number) => Promise<void>;
+    });
+    acquire(input: ProviderRateLimitAcquireInput): Promise<ProviderRateLimitAcquireResult>;
+}
+export declare class RedisProviderRequestLimiter implements ProviderRequestLimiter {
+    readonly mode: "redis";
+    private readonly redis;
+    private readonly keyPrefix;
+    private readonly windowMs;
+    private readonly now;
+    private readonly sleeper;
+    constructor(options: RedisProviderRequestLimiterOptions);
+    acquire(input: ProviderRateLimitAcquireInput): Promise<ProviderRateLimitAcquireResult>;
+    private reserveAttempt;
+}
 export declare class DeterministicEmbeddingProvider implements EmbeddingProvider {
     private readonly dimensions;
     private readonly model;
@@ -220,6 +384,12 @@ export declare class OpenAICompatibleEmbeddingProvider implements EmbeddingProvi
     private readonly timeoutMs;
     private readonly batchSize;
     private readonly maxRetries;
+    private readonly transientForbiddenMaxRetries;
+    private readonly requestLimiter?;
+    private readonly requestLimitScope;
+    private readonly maxRequestsPerMinute;
+    private readonly indexMaxWaitMs;
+    private readonly queryMaxWaitMs;
     private readonly observability;
     constructor(options: OpenAICompatibleEmbeddingProviderOptions);
     describe(): EmbeddingDescriptor;
@@ -228,10 +398,43 @@ export declare class OpenAICompatibleEmbeddingProvider implements EmbeddingProvi
         purpose: EmbeddingPurpose;
     }): Promise<number[][]>;
     private embedBatchWithRetries;
+    private enforceRequestLimit;
     private embedBatchOnce;
+    private maxRetriesForReason;
     private retryDelayMs;
+    private isTransientForbidden;
     private toProviderFailure;
 }
+export declare class OpenAICompatibleRerankerProvider implements RerankerProvider {
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly model;
+    private readonly timeoutMs;
+    private readonly requestLimiter?;
+    private readonly requestLimitScope;
+    private readonly maxRequestsPerMinute;
+    private readonly rerankMaxWaitMs;
+    private readonly observability;
+    constructor(options: OpenAICompatibleRerankerProviderOptions);
+    describe(): RerankerDescriptor;
+    rerank(input: {
+        query: string;
+        documents: string[];
+        top_n: number;
+    }): Promise<RerankerResult[]>;
+    private enforceRequestLimit;
+}
+export declare class ClaudeAgentEnhancerProvider implements EnhancerGenerationProvider {
+    private readonly apiKey;
+    private readonly model;
+    private readonly maxTokens;
+    private readonly baseUrl?;
+    private readonly pathToClaudeCodeExecutable?;
+    private readonly permissionMode;
+    constructor(options: ClaudeAgentEnhancerProviderOptions);
+    describe(): EnhancerProviderDescriptor;
+    generate(input: EnhancerGenerationRequest): Promise<EnhancerGenerationResult>;
+}
 export declare class InMemoryIndexStore implements IndexRepository {
     private readonly workspaces;
     private readonly workspacesByPath;
@@ -350,13 +553,21 @@ export declare class RetrievalCore {
     private readonly store;
     private readonly cache;
     private readonly cacheTtlSeconds;
+    private readonly internalCandidateDepth;
     private readonly embeddingProvider;
     private readonly embeddingDescriptor;
+    private readonly rerankerProvider?;
+    private readonly rerankerDescriptor?;
+    private readonly rerankerTopN;
+    private readonly rerankerCacheVariant;
     private readonly observability;
     private readonly scoringConfig;
     private readonly scoringProfileId;
     private readonly scoringConfigChecksum;
+    private readonly enhancerProvider?;
+    private readonly enhancerProviderDescriptor?;
     private readonly enhancerConfig;
+    private readonly enhancerGenerationConfig;
     private readonly chunkingConfig;
     private readonly enhancerDecisionTraceEnabled;
     private cacheHits;
@@ -372,12 +583,16 @@ export declare class RetrievalCore {
         index_id: string;
         status: "indexing" | "ready" | "failed";
     } | undefined>;
+    private applyLearnedReranker;
     searchContext(input: {
         trace_id: string;
         tenant_id: string;
         workspace_id: string;
         request: SearchContextInput;
     }): Promise<SearchContextOutput>;
+    private enhancerProviderLabels;
+    private buildEnhancerContextSnippets;
+    private generateEnhancedPrompt;
     enhancePrompt(input: {
         trace_id: string;
         tenant_id: string;
@@ -388,3 +603,4 @@ export declare class RetrievalCore {
 export declare function createDefaultRetrievalCore(): RetrievalCore;
 export declare function seedWorkspaceIndex(core: RetrievalCore, artifact: IndexUploadArtifact): Promise<IndexingReport>;
 export * from "./remote-sync.js";
+export * from "./indexing-ignore.js";