@rce-mcp/retrieval-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,390 @@
+import type { EnhancePromptInput, EnhancePromptOutput, 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";
+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 interface RetrievalPathBiasConfig {
+    source_path_boost: number;
+    low_priority_prefix_penalty: number;
+    low_priority_substring_penalty: number;
+    low_priority_asset_penalty: number;
+    lockfile_penalty: number;
+    doc_intent_docs_boost: number;
+    doc_intent_markdown_boost: number;
+    docs_without_doc_intent_penalty: number;
+    non_doc_markdown_penalty: number;
+    code_intent_docs_penalty: number;
+    doc_intent_source_penalty: number;
+    workspace_manifest_root_boost: number;
+    workspace_manifest_nested_boost: number;
+    ui_component_tsx_boost: number;
+    ui_component_css_penalty: number;
+    docs_archive_penalty: number;
+    public_path_penalty: number;
+    test_path_penalty: number;
+    example_path_penalty: number;
+    declaration_file_penalty: number;
+    test_intent_test_boost: number;
+    example_intent_example_boost: number;
+    filename_token_match_boost: number;
+    negation_avoid_docs_penalty: number;
+    negation_avoid_tests_penalty: number;
+    negation_avoid_examples_penalty: number;
+    negation_avoid_archive_penalty: number;
+    min_total_bias: number;
+    max_total_bias: number;
+}
+export interface RetrievalRerankConfig {
+    low_information_penalty: number;
+    max_chunks_per_path_default: number;
+    max_chunks_per_path_file_lookup: number;
+    same_directory_penalty: number;
+    same_extension_penalty: number;
+}
+export interface RetrievalScoringConfig {
+    candidate_weights: CandidateScoreWeights;
+    path_bias: RetrievalPathBiasConfig;
+    rerank: RetrievalRerankConfig;
+}
+export interface RetrievalEnhancerConfig {
+    max_expansion_hints: number;
+    max_candidates_pre_rerank: number;
+    rerank_timeout_ms: number;
+}
+export interface RetrievalChunkingConfig {
+    strategy: ChunkingStrategy;
+    fallback_strategy: "sliding";
+    parse_timeout_ms: number;
+    enabled_languages: string[];
+}
+export type RetrievalScoringConfigInput = Partial<{
+    candidate_weights: Partial<CandidateScoreWeights>;
+    path_bias: Partial<RetrievalPathBiasConfig>;
+    rerank: Partial<RetrievalRerankConfig>;
+}>;
+export type RetrievalEnhancerConfigInput = Partial<RetrievalEnhancerConfig>;
+export type RetrievalChunkingConfigInput = Partial<{
+    strategy: ChunkingStrategy;
+    fallback_strategy: "sliding";
+    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_CHUNKING_CONFIG: RetrievalChunkingConfig;
+declare const BUILTIN_RETRIEVAL_SCORING_PROFILES: {
+    readonly baseline: RetrievalScoringConfig;
+    readonly conservative: RetrievalScoringConfig;
+};
+export type BuiltinRetrievalScoringProfileId = keyof typeof BUILTIN_RETRIEVAL_SCORING_PROFILES;
+export declare function resolveRetrievalScoringProfile(profile_id: string | undefined): {
+    profile_id: BuiltinRetrievalScoringProfileId;
+    config: RetrievalScoringConfig;
+};
+export declare function mergeRetrievalScoringConfig(base: RetrievalScoringConfig, overrides?: RetrievalScoringConfigInput): RetrievalScoringConfig;
+export declare function mergeRetrievalEnhancerConfig(base: RetrievalEnhancerConfig, overrides?: RetrievalEnhancerConfigInput): RetrievalEnhancerConfig;
+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"];
+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);
+}
+export interface RawFile {
+    path: string;
+    content: string;
+    language?: string;
+    updated_at?: string;
+    generated?: boolean;
+    binary?: boolean;
+}
+export interface IndexUploadArtifact {
+    tenant_id: string;
+    workspace_id: string;
+    index_version: string;
+    files: RawFile[];
+    manifest?: {
+        object_key: string;
+        checksum: string;
+    };
+}
+export interface IndexDeltaArtifact {
+    tenant_id: string;
+    workspace_id: string;
+    index_version: string;
+    base_index_version?: string;
+    upsert_files: RawFile[];
+    deleted_paths: string[];
+}
+interface ReadyIndex {
+    index_id: string;
+    tenant_id: string;
+    workspace_id: string;
+    index_version: string;
+    status: "indexing" | "ready" | "failed";
+    created_at: string;
+    updated_at: string;
+}
+interface PersistedFile {
+    file_id: string;
+    repo_path: string;
+    content_hash: string;
+    language?: string;
+}
+export interface IndexingWarning {
+    path: string;
+    reason: string;
+    category: "secret_exclusion" | "filter_exclusion";
+}
+export interface IndexingReport {
+    workspace_id: string;
+    index_version: string;
+    status: "ready";
+    counts: {
+        added: number;
+        modified: number;
+        deleted: number;
+        unchanged: number;
+        skipped: number;
+    };
+    skipped_files: Array<{
+        path: string;
+        reason: string;
+    }>;
+    warnings: IndexingWarning[];
+}
+export interface RetrievalCoreOptions {
+    cacheTtlSeconds?: number;
+    embeddingProvider?: EmbeddingProvider;
+    embeddingDescriptor?: EmbeddingDescriptor;
+    observability?: Observability;
+    scoringProfile?: BuiltinRetrievalScoringProfileId;
+    scoringProfileId?: string;
+    scoringConfig?: RetrievalScoringConfigInput;
+    enhancerConfig?: RetrievalEnhancerConfigInput;
+    chunkingConfig?: RetrievalChunkingConfigInput;
+    enhancerDecisionTraceEnabled?: boolean;
+}
+export interface EmbeddingDescriptor {
+    provider: string;
+    model?: string;
+    dimensions: number;
+    version?: string;
+}
+export type EmbeddingPurpose = "index" | "query";
+export interface EmbeddingProvider {
+    embed(input: {
+        texts: string[];
+        purpose: EmbeddingPurpose;
+    }): Promise<number[][]>;
+    describe?(): EmbeddingDescriptor;
+}
+export interface DeterministicEmbeddingProviderOptions {
+    dimensions?: number;
+    model?: string;
+    version?: string;
+}
+export interface OpenAICompatibleEmbeddingProviderOptions {
+    base_url: string;
+    api_key: string;
+    model?: string;
+    dimensions?: number;
+    timeout_ms?: number;
+    batch_size?: number;
+    max_retries?: number;
+    observability?: Observability;
+}
+export declare class DeterministicEmbeddingProvider implements EmbeddingProvider {
+    private readonly dimensions;
+    private readonly model;
+    private readonly version;
+    constructor(options?: DeterministicEmbeddingProviderOptions);
+    embed(input: {
+        texts: string[];
+        purpose: EmbeddingPurpose;
+    }): Promise<number[][]>;
+    describe(): EmbeddingDescriptor;
+}
+export declare class OpenAICompatibleEmbeddingProvider implements EmbeddingProvider {
+    private readonly baseUrl;
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly model;
+    private readonly dimensions;
+    private readonly timeoutMs;
+    private readonly batchSize;
+    private readonly maxRetries;
+    private readonly observability;
+    constructor(options: OpenAICompatibleEmbeddingProviderOptions);
+    describe(): EmbeddingDescriptor;
+    embed(input: {
+        texts: string[];
+        purpose: EmbeddingPurpose;
+    }): Promise<number[][]>;
+    private embedBatchWithRetries;
+    private embedBatchOnce;
+    private retryDelayMs;
+    private toProviderFailure;
+}
+export declare class InMemoryIndexStore implements IndexRepository {
+    private readonly workspaces;
+    private readonly workspacesByPath;
+    private readonly indexes;
+    private readonly workspaceIndexes;
+    private readonly filesByIndex;
+    private readonly chunksByFile;
+    private readonly indexMetadata;
+    migrate(): Promise<void>;
+    upsertWorkspace(input: WorkspaceRecord): Promise<void>;
+    resolveWorkspaceByProjectRoot(tenant_id: string, project_root_path: string): Promise<WorkspaceRecord | undefined>;
+    resolveWorkspaceByWorkspaceId(tenant_id: string, workspace_id: string): Promise<WorkspaceRecord | undefined>;
+    createIndexVersion(input: {
+        tenant_id: string;
+        workspace_id: string;
+        index_version: string;
+        status?: "indexing" | "ready" | "failed";
+    }): Promise<ReadyIndex>;
+    markIndexStatus(input: {
+        tenant_id: string;
+        workspace_id: string;
+        index_id: string;
+        status: "indexing" | "ready" | "failed";
+    }): Promise<void>;
+    getIndexByVersion(input: {
+        tenant_id: string;
+        workspace_id: string;
+        index_version: string;
+    }): Promise<ReadyIndex | undefined>;
+    resetIndexContent(input: {
+        tenant_id: string;
+        index_id: string;
+    }): Promise<void>;
+    getLatestReadyIndex(input: {
+        tenant_id: string;
+        workspace_id: string;
+    }): Promise<ReadyIndex | undefined>;
+    getFilesByIndex(input: {
+        tenant_id: string;
+        index_id: string;
+    }): Promise<PersistedFile[]>;
+    copyFileFromIndex(input: {
+        tenant_id: string;
+        source_index_id: string;
+        target_index_id: string;
+        repo_path: string;
+    }): Promise<void>;
+    upsertFile(input: {
+        tenant_id: string;
+        index_id: string;
+        repo_path: string;
+        content_hash: string;
+        size_bytes: number;
+        language?: string;
+    }): Promise<{
+        file_id: string;
+    }>;
+    replaceFileChunks(input: {
+        tenant_id: string;
+        file_id: string;
+        repo_path: string;
+        chunks: Array<{
+            start_line: number;
+            end_line: number;
+            snippet: string;
+            embedding: number[];
+            generated?: boolean;
+            updated_at?: string;
+        }>;
+    }): Promise<void>;
+    saveManifest(): Promise<void>;
+    saveIndexMetadata(input: {
+        tenant_id: string;
+        index_id: string;
+        embedding_provider: string;
+        embedding_model?: string;
+        embedding_dimensions: number;
+        embedding_version?: string;
+        chunking_strategy: "language_aware" | "sliding";
+        chunking_fallback_strategy: "sliding";
+    }): Promise<void>;
+    getIndexMetadata(input: {
+        tenant_id: string;
+        index_id: string;
+    }): Promise<{
+        embedding_provider: string;
+        embedding_model?: string;
+        embedding_dimensions: number;
+        embedding_version?: string;
+        chunking_strategy: "language_aware" | "sliding";
+        chunking_fallback_strategy: "sliding";
+        created_at: string;
+    } | undefined>;
+    listChunksByIndex(input: {
+        tenant_id: string;
+        index_id: string;
+        filters?: {
+            language?: string;
+            path_prefix?: string;
+            glob?: string;
+        };
+    }): Promise<Array<{
+        chunk_id: string;
+        file_id: string;
+        path: string;
+        start_line: number;
+        end_line: number;
+        snippet: string;
+        language?: string;
+        generated?: boolean;
+        updated_at: string;
+        embedding: number[];
+    }>>;
+}
+export declare class RetrievalCore {
+    private readonly store;
+    private readonly cache;
+    private readonly cacheTtlSeconds;
+    private readonly embeddingProvider;
+    private readonly embeddingDescriptor;
+    private readonly observability;
+    private readonly scoringConfig;
+    private readonly scoringProfileId;
+    private readonly scoringConfigChecksum;
+    private readonly enhancerConfig;
+    private readonly chunkingConfig;
+    private readonly enhancerDecisionTraceEnabled;
+    private cacheHits;
+    private cacheMisses;
+    constructor(store: IndexRepository, cache: QueryCache, options?: RetrievalCoreOptions);
+    indexArtifact(artifact: IndexUploadArtifact): Promise<IndexingReport>;
+    indexArtifactDelta(artifact: IndexDeltaArtifact): Promise<IndexingReport>;
+    getIndexVersion(input: {
+        tenant_id: string;
+        workspace_id: string;
+        index_version: string;
+    }): Promise<{
+        index_id: string;
+        status: "indexing" | "ready" | "failed";
+    } | undefined>;
+    searchContext(input: {
+        trace_id: string;
+        tenant_id: string;
+        workspace_id: string;
+        request: SearchContextInput;
+    }): Promise<SearchContextOutput>;
+    enhancePrompt(input: {
+        trace_id: string;
+        tenant_id: string;
+        workspace_id?: string;
+        request: EnhancePromptInput;
+    }): Promise<EnhancePromptOutput>;
+}
+export declare function createDefaultRetrievalCore(): RetrievalCore;
+export declare function seedWorkspaceIndex(core: RetrievalCore, artifact: IndexUploadArtifact): Promise<IndexingReport>;
+export * from "./remote-sync.js";