mdorigin 0.3.2 → 0.4.1

package/dist/adapters/cloudflare.js

@@ -27,7 +27,7 @@ export function createCloudflareWorker(manifest, options = {}) {
         };
     }));
     const inlineSearchApi = manifest.searchEntries && manifest.searchEntries.length > 0
-        ? createSearchApiFromBundle(manifest.searchEntries)
+        ? createSearchApiFromBundle(manifest.searchEntries, manifest.siteConfig?.search)
         : undefined;
     const externalSearchApis = new WeakMap();
     let defaultExternalSearchApi;
@@ -88,13 +88,13 @@ function getExternalSearchApi(manifest, env, cache, defaultApi) {
     }
     if (!env) {
         return (defaultApi ??
-            createSearchApiFromExternalBundle(manifest.externalSearchEntries, async (entry) => loadExternalSearchEntryResponse(entry, undefined, manifest.runtime?.r2Binding)));
+            createSearchApiFromExternalBundle(manifest.externalSearchEntries, async (entry) => loadExternalSearchEntryResponse(entry, undefined, manifest.runtime?.r2Binding), manifest.siteConfig?.search));
     }
     const cached = cache.get(env);
     if (cached) {
         return cached;
     }
-    const searchApi = createSearchApiFromExternalBundle(manifest.externalSearchEntries, async (entry) => loadExternalSearchEntryResponse(entry, env, manifest.runtime?.r2Binding));
+    const searchApi = createSearchApiFromExternalBundle(manifest.externalSearchEntries, async (entry) => loadExternalSearchEntryResponse(entry, env, manifest.runtime?.r2Binding), manifest.siteConfig?.search);
     cache.set(env, searchApi);
     return searchApi;
 }

package/dist/cli/dev.js

@@ -27,7 +27,7 @@ export async function runDevCommand(argv) {
         draftMode: 'include',
         siteConfig,
         searchApi: args.search
-            ? await createSearchApiFromDirectory(path.resolve(args.search))
+            ? await createSearchApiFromDirectory(path.resolve(args.search), siteConfig.search)
             : undefined,
         plugins: loadedConfig.plugins,
     });

package/dist/core/api.js

@@ -12,7 +12,9 @@ export async function handleApiRoute(pathname, searchParams, options) {
                 error: 'missing required query parameter: q',
             });
         }
-        const topK = normalizePositiveInteger(searchParams?.get('topK')) ?? 10;
+        const topK = normalizePositiveInteger(searchParams?.get('topK')) ??
+            options.siteConfig.search?.topK ??
+            10;
         const metadata = readSearchMetadataFilters(searchParams);
         const hits = await options.searchApi.search(query, {
             topK,
@@ -66,7 +68,7 @@ function buildOpenApiDocument(options) {
                             in: 'query',
                             required: false,
                             schema: { type: 'string' },
-                            description: 'Exact-match metadata filter. Use query parameters such as meta.type=post or meta.section=guides.',
+                            description: 'Exact-match metadata filter. Use query parameters such as meta.type=post or meta.section=guides. Retrieval mode and reranking stay under site configuration.',
                         },
                     ],
                     responses: {

package/dist/core/site-config.d.ts

@@ -17,6 +17,37 @@ export interface SiteSocialLink {
 export interface EditLinkConfig {
     baseUrl: string;
 }
+export interface SiteSearchRerankerConfig {
+    kind?: 'embedding-v1' | 'heuristic-v1';
+    candidatePoolSize?: number;
+}
+export interface SiteSearchScoreAdjustmentConfig {
+    metadataNumericMultiplier?: string;
+}
+export interface SiteSearchPolicyOverrideConfig {
+    mode?: 'hybrid' | 'vector' | null;
+    minScore?: number | null;
+    reranker?: SiteSearchRerankerConfig | null;
+    scoreAdjustment?: SiteSearchScoreAdjustmentConfig | null;
+}
+export interface SiteSearchShortQueryPolicyConfig extends SiteSearchPolicyOverrideConfig {
+    maxChars: number;
+}
+export interface SiteSearchLongQueryPolicyConfig extends SiteSearchPolicyOverrideConfig {
+    minChars: number;
+}
+export interface SiteSearchPolicyConfig {
+    shortQuery?: SiteSearchShortQueryPolicyConfig;
+    longQuery?: SiteSearchLongQueryPolicyConfig;
+}
+export interface SiteSearchConfig {
+    topK?: number;
+    mode?: 'hybrid' | 'vector';
+    minScore?: number;
+    reranker?: SiteSearchRerankerConfig;
+    scoreAdjustment?: SiteSearchScoreAdjustmentConfig;
+    policy?: SiteSearchPolicyConfig;
+}
 export interface SiteConfig {
     siteTitle?: string;
     siteDescription?: string;
@@ -35,6 +66,7 @@ export interface SiteConfig {
     showHomeIndex?: boolean;
     listingInitialPostCount?: number;
     listingLoadMoreStep?: number;
+    search?: SiteSearchConfig;
 }
 export interface UserSiteConfig extends SiteConfig {
     plugins?: MdoPlugin[];
@@ -56,6 +88,7 @@ export interface ResolvedSiteConfig {
     showHomeIndex: boolean;
     listingInitialPostCount: number;
     listingLoadMoreStep: number;
+    search?: SiteSearchConfig;
     stylesheetContent?: string;
     siteTitleConfigured: boolean;
     siteDescriptionConfigured: boolean;

package/dist/core/site-config.js

@@ -47,6 +47,7 @@ export async function loadUserSiteConfig(options = {}) {
             : normalizeTopNav(parsedConfig.topNav).length === 0,
         listingInitialPostCount: normalizePositiveInteger(parsedConfig.listingInitialPostCount ?? legacyConfig.catalogInitialPostCount, 10),
         listingLoadMoreStep: normalizePositiveInteger(parsedConfig.listingLoadMoreStep ?? legacyConfig.catalogLoadMoreStep, 10),
+        search: normalizeSearchConfig(parsedConfig.search, configFilePath),
         stylesheetContent,
         siteTitleConfigured: typeof parsedConfig.siteTitle === 'string' && parsedConfig.siteTitle !== '',
         siteDescriptionConfigured: typeof parsedConfig.siteDescription === 'string' &&
@@ -197,6 +198,171 @@ function normalizePositiveInteger(value, fallback) {
     }
     return fallback;
 }
+function normalizeOptionalPositiveInteger(value) {
+    if (typeof value === 'number' && Number.isInteger(value) && value > 0) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number.parseInt(value, 10);
+        if (Number.isInteger(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return undefined;
+}
+function normalizeOptionalNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number.parseFloat(value);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+    return undefined;
+}
+function normalizeSearchConfig(value, configFilePath) {
+    if (typeof value !== 'object' || value === null) {
+        return undefined;
+    }
+    if ('hybrid' in value) {
+        throw new Error(`[mdorigin] ${configFilePath}: "search.hybrid" has been removed. Use "search.mode" with "hybrid" or "vector" instead.`);
+    }
+    const searchConfig = value;
+    const reranker = typeof searchConfig.reranker === 'object' && searchConfig.reranker !== null
+        ? normalizeSearchReranker(searchConfig.reranker)
+        : undefined;
+    const scoreAdjustment = typeof searchConfig.scoreAdjustment === 'object' &&
+        searchConfig.scoreAdjustment !== null
+        ? normalizeSearchScoreAdjustment(searchConfig.scoreAdjustment)
+        : undefined;
+    const policy = typeof searchConfig.policy === 'object' && searchConfig.policy !== null
+        ? normalizeSearchPolicy(searchConfig.policy)
+        : undefined;
+    const normalized = {
+        topK: normalizeOptionalPositiveInteger(searchConfig.topK),
+        mode: searchConfig.mode === 'hybrid' || searchConfig.mode === 'vector'
+            ? searchConfig.mode
+            : undefined,
+        minScore: normalizeOptionalNumber(searchConfig.minScore),
+        reranker,
+        scoreAdjustment,
+        policy,
+    };
+    return Object.values(normalized).some((entry) => entry !== undefined)
+        ? normalized
+        : undefined;
+}
+function normalizeSearchReranker(value) {
+    if (typeof value !== 'object' || value === null) {
+        return undefined;
+    }
+    const reranker = value;
+    const normalized = {
+        kind: reranker.kind === 'embedding-v1' || reranker.kind === 'heuristic-v1'
+            ? reranker.kind
+            : undefined,
+        candidatePoolSize: normalizeOptionalPositiveInteger(reranker.candidatePoolSize),
+    };
+    return Object.values(normalized).some((entry) => entry !== undefined)
+        ? normalized
+        : undefined;
+}
+function normalizeSearchScoreAdjustment(value) {
+    if (typeof value !== 'object' || value === null) {
+        return undefined;
+    }
+    const scoreAdjustment = value;
+    const normalized = {
+        metadataNumericMultiplier: typeof scoreAdjustment.metadataNumericMultiplier === 'string' &&
+            scoreAdjustment.metadataNumericMultiplier !== ''
+            ? scoreAdjustment.metadataNumericMultiplier
+            : undefined,
+    };
+    return Object.values(normalized).some((entry) => entry !== undefined)
+        ? normalized
+        : undefined;
+}
+function normalizeSearchPolicy(value) {
+    if (typeof value !== 'object' || value === null) {
+        return undefined;
+    }
+    const policy = value;
+    const normalized = {
+        shortQuery: normalizeSearchShortQueryPolicy(policy.shortQuery),
+        longQuery: normalizeSearchLongQueryPolicy(policy.longQuery),
+    };
+    return Object.values(normalized).some((entry) => entry !== undefined)
+        ? normalized
+        : undefined;
+}
+function normalizeSearchShortQueryPolicy(value) {
+    if (typeof value !== 'object' || value === null) {
+        return undefined;
+    }
+    const policy = value;
+    const maxChars = normalizeOptionalPositiveInteger(policy.maxChars);
+    if (maxChars === undefined) {
+        return undefined;
+    }
+    return {
+        maxChars,
+        ...normalizeSearchPolicyOverride(policy),
+    };
+}
+function normalizeSearchLongQueryPolicy(value) {
+    if (typeof value !== 'object' || value === null) {
+        return undefined;
+    }
+    const policy = value;
+    const minChars = normalizeOptionalPositiveInteger(policy.minChars);
+    if (minChars === undefined) {
+        return undefined;
+    }
+    return {
+        minChars,
+        ...normalizeSearchPolicyOverride(policy),
+    };
+}
+function normalizeSearchPolicyOverride(value) {
+    const normalized = {};
+    if (value.mode === null) {
+        normalized.mode = null;
+    }
+    else if (value.mode === 'hybrid' || value.mode === 'vector') {
+        normalized.mode = value.mode;
+    }
+    if (value.minScore === null) {
+        normalized.minScore = null;
+    }
+    else {
+        const minScore = normalizeOptionalNumber(value.minScore);
+        if (minScore !== undefined) {
+            normalized.minScore = minScore;
+        }
+    }
+    if (value.reranker === null) {
+        normalized.reranker = null;
+    }
+    else if (typeof value.reranker === 'object' && value.reranker !== null) {
+        const reranker = normalizeSearchReranker(value.reranker);
+        if (reranker !== undefined) {
+            normalized.reranker = reranker;
+        }
+    }
+    if (value.scoreAdjustment === null) {
+        normalized.scoreAdjustment = null;
+    }
+    else if (typeof value.scoreAdjustment === 'object' &&
+        value.scoreAdjustment !== null) {
+        const scoreAdjustment = normalizeSearchScoreAdjustment(value.scoreAdjustment);
+        if (scoreAdjustment !== undefined) {
+            normalized.scoreAdjustment = scoreAdjustment;
+        }
+    }
+    return normalized;
+}
 function normalizeLogo(value) {
     if (typeof value !== 'object' ||
         value === null ||

package/dist/search.d.ts

@@ -1,4 +1,4 @@
-import type { ResolvedSiteConfig } from './core/site-config.js';
+import type { ResolvedSiteConfig, SiteSearchConfig, SiteSearchRerankerConfig, SiteSearchScoreAdjustmentConfig } from './core/site-config.js';
 type JsonValue = null | boolean | number | string | JsonValue[] | {
     [key: string]: JsonValue;
 };
@@ -21,8 +21,12 @@ export interface SearchHit {
 }
 export interface SearchQueryOptions {
     topK?: number;
+    mode?: 'hybrid' | 'vector';
+    minScore?: number;
+    reranker?: SiteSearchRerankerConfig;
     relativePathPrefix?: string;
     metadata?: Record<string, string>;
+    scoreAdjustment?: SiteSearchScoreAdjustmentConfig;
 }
 export interface SearchApi {
     search(query: string, options?: SearchQueryOptions): Promise<SearchHit[]>;
@@ -71,12 +75,16 @@ export interface SearchBundleOptions {
     indexDir: string;
     query: string;
     topK?: number;
+    mode?: 'hybrid' | 'vector';
+    minScore?: number;
+    reranker?: SiteSearchRerankerConfig;
     relativePathPrefix?: string;
     metadata?: Record<string, string>;
+    scoreAdjustment?: SiteSearchScoreAdjustmentConfig;
 }
 export declare function buildSearchBundle(options: BuildSearchBundleOptions): Promise<BuildSearchBundleResult>;
 export declare function searchBundle(options: SearchBundleOptions): Promise<SearchHit[]>;
-export declare function createSearchApiFromDirectory(indexDir: string): Promise<SearchApi>;
-export declare function createSearchApiFromBundle(bundleEntries: SearchBundleEntry[]): SearchApi;
-export declare function createSearchApiFromExternalBundle(bundleEntries: ExternalSearchBundleEntry[], loadResponse: (entry: ExternalSearchBundleEntry) => Promise<Response>): SearchApi;
+export declare function createSearchApiFromDirectory(indexDir: string, defaults?: SiteSearchConfig): Promise<SearchApi>;
+export declare function createSearchApiFromBundle(bundleEntries: SearchBundleEntry[], defaults?: SiteSearchConfig): SearchApi;
+export declare function createSearchApiFromExternalBundle(bundleEntries: ExternalSearchBundleEntry[], loadResponse: (entry: ExternalSearchBundleEntry) => Promise<Response>, defaults?: SiteSearchConfig): SearchApi;
 export {};

package/dist/search.js

@@ -46,23 +46,24 @@ export async function searchBundle(options) {
     const searchContext = await openSearchContextFromDirectory(path.resolve(options.indexDir));
     return rerankSearchHits(hydrateSearchHits(await searchContext.index.search(options.query, buildIndexbindSearchOptions({
         topK: options.topK ?? 10,
+        mode: options.mode,
+        minScore: options.minScore,
+        reranker: options.reranker,
         relativePathPrefix: options.relativePathPrefix,
         metadata: options.metadata,
+        scoreAdjustment: options.scoreAdjustment,
     })), searchContext.documentsById));
 }
-export async function createSearchApiFromDirectory(indexDir) {
+export async function createSearchApiFromDirectory(indexDir, defaults) {
     const searchContext = await openSearchContextFromDirectory(path.resolve(indexDir));
     return {
         async search(query, options) {
-            return rerankSearchHits(hydrateSearchHits(await searchContext.index.search(query, buildIndexbindSearchOptions({
-                topK: options?.topK,
-                relativePathPrefix: options?.relativePathPrefix,
-                metadata: options?.metadata,
-            })), searchContext.documentsById));
+            const searchOptions = resolveSearchQueryOptions(query, defaults, options);
+            return rerankSearchHits(hydrateSearchHits(await searchContext.index.search(query, buildIndexbindSearchOptions(searchOptions)), searchContext.documentsById));
         },
     };
 }
-export function createSearchApiFromBundle(bundleEntries) {
+export function createSearchApiFromBundle(bundleEntries, defaults) {
     let searchContextPromise = null;
     return {
         async search(query, options) {
@@ -70,15 +71,12 @@ export function createSearchApiFromBundle(bundleEntries) {
                 searchContextPromise = openSearchContextFromBundle(bundleEntries, async (entry) => createInlineSearchBundleResponse(entry));
             }
             const searchContext = await searchContextPromise;
-            return rerankSearchHits(hydrateSearchHits(await searchContext.index.search(query, buildIndexbindSearchOptions({
-                topK: options?.topK,
-                relativePathPrefix: options?.relativePathPrefix,
-                metadata: options?.metadata,
-            })), searchContext.documentsById));
+            const searchOptions = resolveSearchQueryOptions(query, defaults, options);
+            return rerankSearchHits(hydrateSearchHits(await searchContext.index.search(query, buildIndexbindSearchOptions(searchOptions)), searchContext.documentsById));
         },
     };
 }
-export function createSearchApiFromExternalBundle(bundleEntries, loadResponse) {
+export function createSearchApiFromExternalBundle(bundleEntries, loadResponse, defaults) {
     let searchContextPromise = null;
     return {
         async search(query, options) {
@@ -86,11 +84,8 @@ export function createSearchApiFromExternalBundle(bundleEntries, loadResponse) {
                 searchContextPromise = openSearchContextFromBundle(bundleEntries, loadResponse);
             }
             const searchContext = await searchContextPromise;
-            return rerankSearchHits(hydrateSearchHits(await searchContext.index.search(query, buildIndexbindSearchOptions({
-                topK: options?.topK,
-                relativePathPrefix: options?.relativePathPrefix,
-                metadata: options?.metadata,
-            })), searchContext.documentsById));
+            const searchOptions = resolveSearchQueryOptions(query, defaults, options);
+            return rerankSearchHits(hydrateSearchHits(await searchContext.index.search(query, buildIndexbindSearchOptions(searchOptions)), searchContext.documentsById));
         },
     };
 }
@@ -447,6 +442,94 @@ function decodeBase64(value) {
     const decoded = atob(value);
     return Uint8Array.from(decoded, (character) => character.charCodeAt(0));
 }
+function resolveSearchQueryOptions(query, defaults, overrides) {
+    const policyOverride = resolveSearchPolicyOverride(query, defaults?.policy);
+    return mergeSearchQueryOptions(mergePolicySearchOptions(defaults, policyOverride), overrides);
+}
+function resolveSearchPolicyOverride(query, policy) {
+    if (!policy) {
+        return undefined;
+    }
+    const queryCharCount = Array.from(query.trim()).length;
+    if (queryCharCount === 0) {
+        return undefined;
+    }
+    if (policy.shortQuery &&
+        queryCharCount <= policy.shortQuery.maxChars) {
+        return policy.shortQuery;
+    }
+    if (policy.longQuery &&
+        queryCharCount >= policy.longQuery.minChars) {
+        return policy.longQuery;
+    }
+    return undefined;
+}
+function mergePolicySearchOptions(defaults, policyOverride) {
+    const normalized = {
+        topK: defaults?.topK,
+        mode: defaults?.mode,
+        minScore: defaults?.minScore,
+        reranker: defaults?.reranker ? { ...defaults.reranker } : undefined,
+        scoreAdjustment: defaults?.scoreAdjustment
+            ? { ...defaults.scoreAdjustment }
+            : undefined,
+    };
+    if (!policyOverride) {
+        return normalized;
+    }
+    if (policyOverride.mode === null) {
+        normalized.mode = undefined;
+    }
+    else if (policyOverride.mode !== undefined) {
+        normalized.mode = policyOverride.mode;
+    }
+    if (policyOverride.minScore === null) {
+        normalized.minScore = undefined;
+    }
+    else if (policyOverride.minScore !== undefined) {
+        normalized.minScore = policyOverride.minScore;
+    }
+    if (policyOverride.reranker === null) {
+        normalized.reranker = undefined;
+    }
+    else if (policyOverride.reranker) {
+        normalized.reranker = {
+            ...(normalized.reranker ?? {}),
+            ...policyOverride.reranker,
+        };
+    }
+    if (policyOverride.scoreAdjustment === null) {
+        normalized.scoreAdjustment = undefined;
+    }
+    else if (policyOverride.scoreAdjustment) {
+        normalized.scoreAdjustment = {
+            ...(normalized.scoreAdjustment ?? {}),
+            ...policyOverride.scoreAdjustment,
+        };
+    }
+    return normalized;
+}
+function mergeSearchQueryOptions(defaults, overrides) {
+    return {
+        topK: overrides?.topK ?? defaults?.topK,
+        mode: overrides?.mode ?? defaults?.mode,
+        minScore: overrides?.minScore ?? defaults?.minScore,
+        reranker: overrides?.reranker || defaults?.reranker
+            ? {
+                ...(defaults?.reranker ?? {}),
+                ...(overrides?.reranker ?? {}),
+            }
+            : undefined,
+        relativePathPrefix: overrides?.relativePathPrefix ?? defaults?.relativePathPrefix,
+        metadata: overrides?.metadata ?? defaults?.metadata,
+        scoreAdjustment: overrides?.scoreAdjustment || defaults?.scoreAdjustment
+            ? {
+                ...(defaults?.scoreAdjustment ?? {}),
+                ...(overrides?.scoreAdjustment ?? {}),
+            }
+            : undefined,
+    };
+}
 function buildIndexbindSearchOptions(options) {
     const normalized = {};
     if (typeof options.topK === 'number' &&
@@ -455,12 +538,45 @@ function buildIndexbindSearchOptions(options) {
         options.topK > 0) {
         normalized.topK = options.topK;
     }
+    if (options.mode === 'hybrid' || options.mode === 'vector') {
+        normalized.mode = options.mode;
+    }
+    if (typeof options.minScore === 'number' && Number.isFinite(options.minScore)) {
+        normalized.minScore = options.minScore;
+    }
+    if (options.reranker) {
+        const reranker = {};
+        if (options.reranker.kind === 'embedding-v1' ||
+            options.reranker.kind === 'heuristic-v1') {
+            reranker.kind = options.reranker.kind;
+        }
+        if (typeof options.reranker.candidatePoolSize === 'number' &&
+            Number.isFinite(options.reranker.candidatePoolSize) &&
+            Number.isInteger(options.reranker.candidatePoolSize) &&
+            options.reranker.candidatePoolSize > 0) {
+            reranker.candidatePoolSize = options.reranker.candidatePoolSize;
+        }
+        if (Object.keys(reranker).length > 0) {
+            normalized.reranker = reranker;
+        }
+    }
     if (typeof options.relativePathPrefix === 'string' && options.relativePathPrefix !== '') {
         normalized.relativePathPrefix = options.relativePathPrefix;
     }
     if (options.metadata && Object.keys(options.metadata).length > 0) {
         normalized.metadata = options.metadata;
     }
+    if (options.scoreAdjustment) {
+        const scoreAdjustment = {};
+        if (typeof options.scoreAdjustment.metadataNumericMultiplier === 'string' &&
+            options.scoreAdjustment.metadataNumericMultiplier !== '') {
+            scoreAdjustment.metadataNumericMultiplier =
+                options.scoreAdjustment.metadataNumericMultiplier;
+        }
+        if (Object.keys(scoreAdjustment).length > 0) {
+            normalized.scoreAdjustment = scoreAdjustment;
+        }
+    }
     return Object.keys(normalized).length > 0 ? normalized : undefined;
 }
 function hydrateSearchHits(hits, documentsById) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdorigin",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "type": "module",
   "description": "Markdown-first publishing for humans and agents.",
   "repository": {
@@ -78,6 +78,6 @@
     "typescript": "^5.9.2"
   },
   "optionalDependencies": {
-    "indexbind": "^0.3.3"
+    "indexbind": "^0.6.1"
   }
 }