@lacneu/openclaw-knowledge 3.1.2 → 3.2.0

package/dist/jina/classifier.js

@@ -0,0 +1,170 @@
+// Jina Classifier client.
+//
+// Wraps POST /v1/classify in both modes:
+//
+//   - **zero-shot**  — caller supplies `labels`; Jina embeds them on the fly
+//                       and matches against the input. Up to 256 classes.
+//                       Stateless.
+//
+//   - **few-shot**   — caller supplies a `classifier_id` from a prior
+//                       training run. The plugin does NOT implement training
+//                       (/v1/train) — that is an explicit out-of-band step
+//                       performed via the Jina Playground or a one-off
+//                       script. Rationale: training is a rare, deliberate
+//                       act; baking it into the plugin would invite
+//                       accidental retraining on every plugin reload.
+//
+// Defensive response parsing:
+// Jina has historically used several field names for the predicted label
+// across docs revisions: `predictions[0].label`, `predictions[0].prediction`,
+// `label`, `prediction`. The parser tries each known path in turn and falls
+// back to `null` if none matches (callers treat `null` like a Jina outage
+// → fail-open route).
+import { postJson } from "./client.js";
+const CLASSIFY_URL = "https://api.jina.ai/v1/classify";
+/** Defaults aligned with the plugin's "no-config" mode. */
+const DEFAULT_CLASSIFIER_MODEL = "jina-embeddings-v3";
+/**
+ * Classify `text` against a list of semantic labels.
+ *
+ * Returns `null` when:
+ *   - the response shape is unexpected (Jina rev mismatch),
+ *   - the predicted label does not exactly match any provided label (we
+ *     refuse to invent a class — the router should treat this as "unknown").
+ *
+ * Throws on network / API errors so the caller's circuit breaker can react.
+ */
+export async function classifyZeroShot({ apiKey, text, labels, model = DEFAULT_CLASSIFIER_MODEL, timeoutMs, signal, }) {
+    if (labels.length < 2) {
+        // Jina rejects requests with fewer than 2 labels; surface a clearer
+        // error than the upstream's generic 400.
+        throw new Error("classifyZeroShot: at least 2 labels are required");
+    }
+    const body = {
+        model,
+        input: [{ text }],
+        labels,
+    };
+    const raw = await postJson({
+        url: CLASSIFY_URL,
+        body,
+        apiKey,
+        timeoutMs,
+        signal,
+    });
+    return parseClassificationResponse(raw, labels);
+}
+/**
+ * Classify `text` using a pre-trained few-shot classifier identified by
+ * `classifierId`. Same `null`-vs-throw contract as `classifyZeroShot`.
+ */
+export async function classifyFewShot({ apiKey, text, classifierId, expectedLabels, timeoutMs, signal, }) {
+    if (!classifierId) {
+        throw new Error("classifyFewShot: classifierId is required");
+    }
+    const body = {
+        classifier_id: classifierId,
+        input: [{ text }],
+    };
+    const raw = await postJson({
+        url: CLASSIFY_URL,
+        body,
+        apiKey,
+        timeoutMs,
+        signal,
+    });
+    return parseClassificationResponse(raw, expectedLabels);
+}
+// ---------------------------------------------------------------------------
+// Defensive response parser
+// ---------------------------------------------------------------------------
+/**
+ * Extract the predicted label + optional score from a Classifier response.
+ *
+ * Known shapes (in order tried):
+ *   1. `{ data: [ { predictions: [ { label, score } ] } ] }`
+ *   2. `{ results: [ { label, score } ] }`
+ *   3. `{ data: [ { label, score } ] }`
+ *   4. `{ data: [ { prediction, confidence } ] }`
+ *
+ * The first match wins. When `allowedLabels` is provided, the picked label
+ * MUST be an exact (case-sensitive) member — otherwise we return `null` and
+ * the caller falls back to its safe default (the router treats `null` like
+ * an outage).
+ *
+ * @internal exported only for unit testing
+ */
+export function parseClassificationResponse(raw, allowedLabels) {
+    const candidates = extractCandidates(raw);
+    for (const candidate of candidates) {
+        const label = candidate.label;
+        if (typeof label !== "string" || label.length === 0)
+            continue;
+        if (allowedLabels && allowedLabels.length > 0 && !allowedLabels.includes(label)) {
+            // Silent skip — Jina occasionally hallucinates a "best" label that
+            // is not in the input set. We never invent a class.
+            continue;
+        }
+        return {
+            label,
+            score: typeof candidate.score === "number" ? candidate.score : null,
+        };
+    }
+    return null;
+}
+function extractCandidates(raw) {
+    if (!isRecord(raw))
+        return [];
+    const candidates = [];
+    // Shape #1: data[].predictions[] — newer Jina docs. Falls through when
+    // `predictions` is empty so the same payload can still be parsed via
+    // shape #3 (data[] flat) below.
+    if (Array.isArray(raw.data) && raw.data.length > 0) {
+        const first = raw.data[0];
+        if (isRecord(first) && Array.isArray(first.predictions)) {
+            for (const p of first.predictions) {
+                if (!isRecord(p))
+                    continue;
+                candidates.push({
+                    label: p.label ?? p.prediction,
+                    score: p.score ?? p.confidence,
+                });
+            }
+        }
+    }
+    // Shape #2: results[] — older docs / few-shot path.
+    if (Array.isArray(raw.results)) {
+        for (const r of raw.results) {
+            if (!isRecord(r))
+                continue;
+            candidates.push({
+                label: r.label ?? r.prediction,
+                score: r.score ?? r.confidence,
+            });
+        }
+    }
+    // Shape #3 & #4: data[] flat — `{label, score}` or `{prediction, confidence}`.
+    if (Array.isArray(raw.data)) {
+        for (const d of raw.data) {
+            if (!isRecord(d))
+                continue;
+            // Only push if at least one of the recognized keys is present, to
+            // avoid duplicating the predictions[] entries already captured above
+            // when both shapes are present on the same record.
+            if (d.label !== undefined ||
+                d.prediction !== undefined ||
+                d.score !== undefined ||
+                d.confidence !== undefined) {
+                candidates.push({
+                    label: d.label ?? d.prediction,
+                    score: d.score ?? d.confidence,
+                });
+            }
+        }
+    }
+    return candidates;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=classifier.js.map

package/dist/jina/classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifier.js","sourceRoot":"","sources":["../../src/jina/classifier.ts"],"names":[],"mappings":"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"}

package/dist/jina/client.d.ts

@@ -0,0 +1,30 @@
+/** Options accepted by every Jina request helper. */
+export interface JinaRequestOptions {
+    /** Bearer token sent in `Authorization`. Required. */
+    apiKey: string;
+    /** Override the default 8 s timeout. */
+    timeoutMs?: number;
+    /**
+     * Optional AbortSignal from the caller. Composed with the internal timeout
+     * signal so either source can cancel the request.
+     */
+    signal?: AbortSignal;
+}
+interface PostJsonParams<Req> extends JinaRequestOptions {
+    url: string;
+    body: Req;
+}
+/**
+ * POST `body` to `url` as JSON, return the parsed JSON response as `unknown`.
+ *
+ * The response is `unknown` on purpose: callers MUST narrow it with their
+ * own defensive parser (Jina occasionally changes response shapes).
+ *
+ * @throws {JinaAuthError}      on 401/403
+ * @throws {JinaRateLimitError} on 429
+ * @throws {JinaApiError}       on any other non-OK status (incl. HTML
+ *                              bodies from upstream CDNs/LBs)
+ * @throws {JinaNetworkError}   on fetch failure, abort, or timeout
+ */
+export declare function postJson<Req>({ url, body, apiKey, timeoutMs, signal: callerSignal, }: PostJsonParams<Req>): Promise<unknown>;
+export {};

package/dist/jina/client.js

@@ -0,0 +1,131 @@
+// HTTP client for the Jina AI cloud API.
+//
+// Centralized so every endpoint wrapper (classifier, reranker) shares the
+// same auth, timeout, and error handling. The client is intentionally tiny
+// and dependency-free — `fetch` + `AbortController` only.
+//
+// Design choices:
+//
+// 1. **Bearer-only auth.** The API key is sent in the `Authorization` header,
+//    never in the URL or in error messages. Operators copy the key from the
+//    Jina console into the plugin config (with `${JINA_API_KEY}` env
+//    substitution) and that's the only place it touches.
+//
+// 2. **Hard timeout via AbortController, covering BOTH the connection AND
+//    the body read.** A stalled connection — or, worse, an endpoint that
+//    sends headers immediately but never finishes streaming the body —
+//    would otherwise hold the agent turn open until the SDK's outer
+//    timeout kicks in (usually too long). The internal `controller`
+//    remains armed until JSON.parse completes, so `resp.text()` is
+//    cancelled by the same `controller.abort()` call as the underlying
+//    fetch. Default 8 s — comfortable for cross-Atlantic Jina latency but
+//    short enough to keep `before_prompt_build` snappy.
+//
+// 3. **Defensive JSON parsing.** Some upstream errors (502 from a CDN, 503
+//    from a load balancer in front of Jina) return HTML, not JSON. Treating
+//    the body as JSON without try/catch would crash the plugin with a
+//    SyntaxError. We always read as text first, then try to parse; failures
+//    become `JinaApiError` with a 200-char body preview.
+//
+// 4. **No automatic retry on 5xx.** The plugin's outer circuit breaker
+//    already handles repeated failures (3 errors → 5 min cooldown). Retrying
+//    here would just consume more tokens during an outage. Callers that want
+//    retries should layer them above this client.
+import { errorForStatus, JinaApiError, JinaNetworkError, previewBody, } from "./errors.js";
+const DEFAULT_TIMEOUT_MS = 8_000;
+/**
+ * POST `body` to `url` as JSON, return the parsed JSON response as `unknown`.
+ *
+ * The response is `unknown` on purpose: callers MUST narrow it with their
+ * own defensive parser (Jina occasionally changes response shapes).
+ *
+ * @throws {JinaAuthError}      on 401/403
+ * @throws {JinaRateLimitError} on 429
+ * @throws {JinaApiError}       on any other non-OK status (incl. HTML
+ *                              bodies from upstream CDNs/LBs)
+ * @throws {JinaNetworkError}   on fetch failure, abort, or timeout
+ */
+export async function postJson({ url, body, apiKey, timeoutMs = DEFAULT_TIMEOUT_MS, signal: callerSignal, }) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    // If the caller supplied a signal, abort the local controller when it
+    // fires so both signals merge into one.
+    const onCallerAbort = () => controller.abort();
+    if (callerSignal) {
+        if (callerSignal.aborted)
+            controller.abort();
+        else
+            callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+    }
+    try {
+        let resp;
+        try {
+            resp = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
+                    Authorization: `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            throw new JinaNetworkError(networkErrorReason(controller, timeoutMs), err);
+        }
+        // IMPORTANT: the body read happens BEFORE the timeout is cleared. If
+        // the upstream server sends headers immediately but stalls or slowly
+        // streams the body, `controller.abort()` (still armed) will reject
+        // `resp.text()` with the underlying fetch's abort reason. Without
+        // this, the hook could hang for the SDK's outer timeout window.
+        const rawBody = await safeReadText(resp, controller, timeoutMs);
+        if (!resp.ok) {
+            throw errorForStatus(resp.status, previewBody(rawBody));
+        }
+        try {
+            return JSON.parse(rawBody);
+        }
+        catch {
+            // Upstream sometimes returns HTML on partial failures even with HTTP 200.
+            throw new JinaApiError(resp.status, previewBody(rawBody));
+        }
+    }
+    finally {
+        clearTimeout(timeoutId);
+        if (callerSignal)
+            callerSignal.removeEventListener("abort", onCallerAbort);
+    }
+}
+/**
+ * Read the response body as text under the same abort controller as the
+ * underlying fetch. A connection that delivered headers but stalls on the
+ * body is the failure mode this guards against: when `controller.abort()`
+ * fires (timeout OR caller-initiated), the WHATWG fetch spec rejects the
+ * pending `resp.text()` promise with the abort reason.
+ *
+ * Errors during read are mapped:
+ *   - aborted by timeout/caller → re-throw as `JinaNetworkError`
+ *   - any other I/O failure     → empty string (we still want to attempt
+ *                                  error mapping based on the HTTP status)
+ */
+async function safeReadText(resp, controller, timeoutMs) {
+    try {
+        return await resp.text();
+    }
+    catch (err) {
+        if (controller.signal.aborted) {
+            throw new JinaNetworkError(networkErrorReason(controller, timeoutMs), err);
+        }
+        return "";
+    }
+}
+/**
+ * Format a consistent reason string for a network-level failure.
+ * The two distinct cases (timeout vs. raw fetch error) need different
+ * wording for log readability.
+ */
+function networkErrorReason(controller, timeoutMs) {
+    return controller.signal.aborted ? `timed out after ${timeoutMs}ms` : "fetch failed";
+}
+//# sourceMappingURL=client.js.map

package/dist/jina/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/jina/client.ts"],"names":[],"mappings":"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"}

package/dist/jina/errors.d.ts

@@ -0,0 +1,42 @@
+/** Truncate an upstream error body to a safe length for logging. */
+export declare function previewBody(body: string): string;
+/** Base class for any Jina-related error. */
+export declare class JinaError extends Error {
+    constructor(message: string);
+}
+/** 401/403 — operator must rotate or refill the API key. */
+export declare class JinaAuthError extends JinaError {
+    constructor(status: number, bodyPreview: string);
+}
+/** 429 — Jina backed off; transient. */
+export declare class JinaRateLimitError extends JinaError {
+    constructor(bodyPreview: string);
+}
+/** Any other non-OK HTTP response. */
+export declare class JinaApiError extends JinaError {
+    readonly status: number;
+    constructor(status: number, bodyPreview: string);
+}
+/** Network failure, abort, timeout. `cause` carries the original error. */
+export declare class JinaNetworkError extends JinaError {
+    constructor(reason: string, cause?: unknown);
+}
+/**
+ * Classify an HTTP status code into the appropriate Jina error class.
+ * Centralized so every endpoint wrapper produces consistent errors.
+ */
+export declare function errorForStatus(status: number, bodyPreview: string): JinaError;
+/**
+ * Build a privacy-safe one-line description of any thrown value, suitable
+ * for `logger.error(...)` in the hook handler.
+ *
+ * IMPORTANT: this MUST NOT include the upstream body preview that
+ * `JinaError.message` carries — that preview can echo the user query or
+ * document chunks if Jina's error path mirrors the request. We expose
+ * only the error CLASS and (when applicable) the HTTP status code.
+ *
+ * Non-Jina errors fall through to `error.name`, which is safe by design
+ * (it's a class name, not a message). The raw message of an unknown
+ * error is NEVER logged here.
+ */
+export declare function summarizeJinaError(err: unknown): string;

package/dist/jina/errors.js

@@ -0,0 +1,113 @@
+// Typed errors for Jina API calls.
+//
+// We distinguish three failure modes the caller may want to react to
+// differently:
+//
+//   - `JinaAuthError`      → API key invalid/expired. Permanent until the
+//                            operator fixes the config; no point retrying.
+//   - `JinaRateLimitError` → 429 from Jina. Transient; the circuit breaker
+//                            should back off but the plugin remains usable
+//                            on the next turn.
+//   - `JinaApiError`       → generic non-OK response. Catches every 4xx/5xx
+//                            that isn't auth or rate-limit.
+//   - `JinaNetworkError`   → fetch threw / aborted before we got a response.
+//                            Includes timeouts.
+//
+// All concrete classes extend `JinaError` so callers can `catch (e instanceof
+// JinaError)` to handle them uniformly when they don't care about the
+// subtype.
+//
+// IMPORTANT: error messages NEVER include the API key, the full request body,
+// or the user query verbatim. Bodies are truncated to 200 chars to match the
+// existing pattern in `embeddings.ts` and `lightrag.ts`.
+const ERROR_BODY_PREVIEW_CHARS = 200;
+/** Truncate an upstream error body to a safe length for logging. */
+export function previewBody(body) {
+    if (body.length <= ERROR_BODY_PREVIEW_CHARS)
+        return body;
+    return body.slice(0, ERROR_BODY_PREVIEW_CHARS);
+}
+/** Base class for any Jina-related error. */
+export class JinaError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "JinaError";
+    }
+}
+/** 401/403 — operator must rotate or refill the API key. */
+export class JinaAuthError extends JinaError {
+    constructor(status, bodyPreview) {
+        super(`Jina auth failed (${status}): ${bodyPreview}`);
+        this.name = "JinaAuthError";
+    }
+}
+/** 429 — Jina backed off; transient. */
+export class JinaRateLimitError extends JinaError {
+    constructor(bodyPreview) {
+        super(`Jina rate-limited (429): ${bodyPreview}`);
+        this.name = "JinaRateLimitError";
+    }
+}
+/** Any other non-OK HTTP response. */
+export class JinaApiError extends JinaError {
+    status;
+    constructor(status, bodyPreview) {
+        super(`Jina request failed (${status}): ${bodyPreview}`);
+        this.status = status;
+        this.name = "JinaApiError";
+    }
+}
+/** Network failure, abort, timeout. `cause` carries the original error. */
+export class JinaNetworkError extends JinaError {
+    constructor(reason, cause) {
+        super(`Jina network error: ${reason}`);
+        this.name = "JinaNetworkError";
+        if (cause !== undefined) {
+            // `Error.cause` is standard since ES2022; keep it readable in stack
+            // traces without leaking sensitive context.
+            this.cause = cause;
+        }
+    }
+}
+/**
+ * Classify an HTTP status code into the appropriate Jina error class.
+ * Centralized so every endpoint wrapper produces consistent errors.
+ */
+export function errorForStatus(status, bodyPreview) {
+    if (status === 401 || status === 403) {
+        return new JinaAuthError(status, bodyPreview);
+    }
+    if (status === 429) {
+        return new JinaRateLimitError(bodyPreview);
+    }
+    return new JinaApiError(status, bodyPreview);
+}
+/**
+ * Build a privacy-safe one-line description of any thrown value, suitable
+ * for `logger.error(...)` in the hook handler.
+ *
+ * IMPORTANT: this MUST NOT include the upstream body preview that
+ * `JinaError.message` carries — that preview can echo the user query or
+ * document chunks if Jina's error path mirrors the request. We expose
+ * only the error CLASS and (when applicable) the HTTP status code.
+ *
+ * Non-Jina errors fall through to `error.name`, which is safe by design
+ * (it's a class name, not a message). The raw message of an unknown
+ * error is NEVER logged here.
+ */
+export function summarizeJinaError(err) {
+    if (err instanceof JinaApiError)
+        return `JinaApiError(status=${err.status})`;
+    if (err instanceof JinaAuthError)
+        return "JinaAuthError";
+    if (err instanceof JinaRateLimitError)
+        return "JinaRateLimitError";
+    if (err instanceof JinaNetworkError)
+        return "JinaNetworkError";
+    if (err instanceof JinaError)
+        return err.name;
+    if (err instanceof Error)
+        return err.name;
+    return "unknown-error";
+}
+//# sourceMappingURL=errors.js.map

package/dist/jina/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/jina/errors.ts"],"names":[],"mappings":"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"}

package/dist/jina/reranker.d.ts

@@ -0,0 +1,34 @@
+import type { RerankedItem, RerankerModel } from "./types.js";
+export interface RerankParams {
+    apiKey: string;
+    query: string;
+    /** Document texts to rerank. Order MUST match the caller's source array. */
+    documents: string[];
+    /** Override the default model. */
+    model?: RerankerModel;
+    /**
+     * Keep only the top-N results. When omitted, Jina returns all reranked
+     * items (still useful when the caller wants to keep full ordering).
+     */
+    topN?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Rerank `documents` against `query` and return the new ordering.
+ *
+ * Each item carries the ORIGINAL index from the input array plus the new
+ * relevance score. Callers should use the `index` to look up their own
+ * data structures rather than relying on document text.
+ *
+ * @returns `[]` for an empty input (no API call) or when the response
+ *          shape is unrecognized (fail-open semantics).
+ * @throws  on network / auth / API errors so the cooldown breaker can react.
+ */
+export declare function rerank({ apiKey, query, documents, model, topN, timeoutMs, signal, }: RerankParams): Promise<RerankedItem[]>;
+/**
+ * Defensive parser for the /v1/rerank response.
+ *
+ * @internal exported for unit testing
+ */
+export declare function parseRerankResponse(raw: unknown, inputCount: number): RerankedItem[];

package/dist/jina/reranker.js

@@ -0,0 +1,95 @@
+// Jina Reranker client.
+//
+// Wraps POST /v1/rerank for use after a pgvector cosine-similarity pass:
+// vector search returns N coarse candidates, then a cross-encoder rerank
+// promotes the ones that actually answer the query.
+//
+// Implementation choices:
+//
+// 1. **`return_documents: false` is hardcoded.** The caller (pgvector source)
+//    already owns the `PgvectorResult` objects and only needs the new
+//    ordering. Asking Jina to echo the documents back would multiply the
+//    response payload by ~10× for nothing.
+//
+// 2. **`truncate: true` by default.** Lets Jina silently shrink each document
+//    to the model's per-doc cap rather than failing the whole batch. The
+//    LightRAG-side reranker uses the same setting (`RERANK_ENABLE_CHUNKING`).
+//
+// 3. **Defensive response parsing.** We validate the structural shape
+//    (`results: [{index, score}]`) and silently skip malformed entries
+//    rather than crashing. An empty or unrecognized response yields an
+//    empty array — the caller falls back to the original cosine order.
+import { postJson } from "./client.js";
+const RERANK_URL = "https://api.jina.ai/v1/rerank";
+/**
+ * Default reranker model. v2-base-multilingual is the best-balanced choice
+ * for French-heavy corpora (LightRAG-side tuning notes from 2026-05-14 show
+ * v3 plateauing at 0.05-0.15 on short French queries vs dense chunks).
+ */
+const DEFAULT_RERANKER_MODEL = "jina-reranker-v2-base-multilingual";
+/**
+ * Rerank `documents` against `query` and return the new ordering.
+ *
+ * Each item carries the ORIGINAL index from the input array plus the new
+ * relevance score. Callers should use the `index` to look up their own
+ * data structures rather than relying on document text.
+ *
+ * @returns `[]` for an empty input (no API call) or when the response
+ *          shape is unrecognized (fail-open semantics).
+ * @throws  on network / auth / API errors so the cooldown breaker can react.
+ */
+export async function rerank({ apiKey, query, documents, model = DEFAULT_RERANKER_MODEL, topN, timeoutMs, signal, }) {
+    if (documents.length === 0)
+        return [];
+    const body = {
+        model,
+        query,
+        documents,
+        return_documents: false,
+        truncate: true,
+    };
+    if (typeof topN === "number" && topN > 0) {
+        body.top_n = topN;
+    }
+    const raw = await postJson({
+        url: RERANK_URL,
+        body,
+        apiKey,
+        timeoutMs,
+        signal,
+    });
+    return parseRerankResponse(raw, documents.length);
+}
+/**
+ * Defensive parser for the /v1/rerank response.
+ *
+ * @internal exported for unit testing
+ */
+export function parseRerankResponse(raw, inputCount) {
+    if (!isRecord(raw))
+        return [];
+    const results = raw.results;
+    if (!Array.isArray(results))
+        return [];
+    const out = [];
+    for (const item of results) {
+        if (!isRecord(item))
+            continue;
+        const index = item.index;
+        const score = item.relevance_score ?? item.score;
+        if (typeof index !== "number" ||
+            !Number.isInteger(index) ||
+            index < 0 ||
+            index >= inputCount ||
+            typeof score !== "number" ||
+            !Number.isFinite(score)) {
+            continue;
+        }
+        out.push({ index, score });
+    }
+    return out;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=reranker.js.map

package/dist/jina/reranker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranker.js","sourceRoot":"","sources":["../../src/jina/reranker.ts"],"names":[],"mappings":"AAAA,wBAAwB;AACxB,EAAE;AACF,yEAAyE;AACzE,yEAAyE;AACzE,oDAAoD;AACpD,EAAE;AACF,0BAA0B;AAC1B,EAAE;AACF,8EAA8E;AAC9E,sEAAsE;AACtE,yEAAyE;AACzE,2CAA2C;AAC3C,EAAE;AACF,8EAA8E;AAC9E,yEAAyE;AACzE,8EAA8E;AAC9E,EAAE;AACF,sEAAsE;AACtE,uEAAuE;AACvE,uEAAuE;AACvE,uEAAuE;AAEvE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAOvC,MAAM,UAAU,GAAG,+BAA+B,CAAC;AAEnD;;;;GAIG;AACH,MAAM,sBAAsB,GAAkB,oCAAoC,CAAC;AAkBnF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,EAC3B,MAAM,EACN,KAAK,EACL,SAAS,EACT,KAAK,GAAG,sBAAsB,EAC9B,IAAI,EACJ,SAAS,EACT,MAAM,GACO;IACb,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEtC,MAAM,IAAI,GAAsB;QAC9B,KAAK;QACL,KAAK;QACL,SAAS;QACT,gBAAgB,EAAE,KAAK;QACvB,QAAQ,EAAE,IAAI;KACf,CAAC;IACF,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAoB;QAC5C,GAAG,EAAE,UAAU;QACf,IAAI;QACJ,MAAM;QACN,SAAS;QACT,MAAM;KACP,CAAC,CAAC;IAEH,OAAO,mBAAmB,CAAC,GAAG,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAAY,EACZ,UAAkB;IAElB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAE9B,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAC5B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC;IAEvC,MAAM,GAAG,GAAmB,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,SAAS;QAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,MAAM,KAAK,GAAG,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,KAAK,CAAC;QACjD,IACE,OAAO,KAAK,KAAK,QAAQ;YACzB,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC;YACxB,KAAK,GAAG,CAAC;YACT,KAAK,IAAI,UAAU;YACnB,OAAO,KAAK,KAAK,QAAQ;YACzB,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EACvB,CAAC;YACD,SAAS;QACX,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}