@loams/client 0.1.0-preview.2 → 0.1.1

package/dist/builders/search.js

@@ -0,0 +1,307 @@
+// The search builder (SDKP §2.4): a `loams.collection.v1.SearchRequest`, one
+// verb at a time.
+//
+//   const request = Search.on('notes')
+//     .text('refund', { fields: ['body'] })
+//     .vector('embedding', [0.1, 0.2, 0.3, 0.4], { k: 10 })
+//     .fuse(rrf(60))
+//     .filter(Filter.eq('tags', 'policy'))
+//     .highlight('body')
+//     .select({ include: ['title'] })
+//     .limit(5);
+//   const answer = await loams.search.query(request.build());
+//
+// Each verb is pure: it returns a new builder and leaves the old one as it
+// was, so a base query can be shared and specialised. `toJson()` is the
+// request's proto3 JSON, which is how the builder corpus spells each case;
+// `build()` decodes it into the generated message, refusing the requests the
+// builder can tell are wrong (a weighted fusion with the wrong number of
+// weights) before any network call.
+var _a;
+import { fromJson, toJson } from '@bufbuild/protobuf';
+import { ValueSchema } from '@bufbuild/protobuf/wkt';
+import { Code } from '@connectrpc/connect';
+import { SearchRequestSchema } from '../vendor/proto/gen/loams/collection/v1/query_pb.js';
+import { ConsistencyToken } from '../runtime/consistency.js';
+import { InvalidArgumentError } from '../runtime/errors.js';
+import { Filter } from './filter.js';
+/** Reciprocal-rank fusion; `k` absent is the engine's 60. */
+export function rrf(k) {
+    return { rrf: k === undefined ? {} : { k } };
+}
+/** Distance-based score fusion, with the engine's parameters. */
+export function dbsf() {
+    return { dbsf: {} };
+}
+/** A weighted sum, one weight per retriever in the order they were added. */
+export function weighted(...weights) {
+    return { weightedSum: { weights } };
+}
+/** The fusions, as one namespace. */
+export const Fusion = { rrf, dbsf, weighted };
+const order = (value) => (value === 'asc' ? 'SORT_ORDER_ASC' : 'SORT_ORDER_DESC');
+/** The sort keys. The primary key ascending always breaks ties on the server,
+ * but `queryAll` needs it spelled out to page. */
+export const Sort = {
+    /** By score; descending unless told otherwise. */
+    score(direction) {
+        return { score: direction === undefined ? {} : { order: order(direction) } };
+    },
+    /** By primary key; ascending unless told otherwise. */
+    pk(direction) {
+        return { pk: direction === undefined ? {} : { order: order(direction) } };
+    },
+    /** By a fast field. `missing` puts documents without it first or last. */
+    field(name, direction, missing) {
+        const key = { field: name };
+        if (direction !== undefined) {
+            key.order = order(direction);
+        }
+        if (missing !== undefined) {
+            key.missing = missing === 'first' ? 'MISSING_ORDER_FIRST' : 'MISSING_ORDER_LAST';
+        }
+        return { field: key };
+    },
+};
+/** The proto3 JSON of a `loams.collection.v1.Consistency`. */
+export function consistencyJson(level) {
+    if (level === 'strong') {
+        return { freshness: 'FRESHNESS_STRONG' };
+    }
+    if (level === 'eventual') {
+        return { freshness: 'FRESHNESS_EVENTUAL' };
+    }
+    const token = typeof level === 'string' ? ConsistencyToken.parse(level) : level;
+    return { atLeast: token.toString() };
+}
+function sortValueJson(value) {
+    if (value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        value.$typeName === 'google.protobuf.Value') {
+        return toJson(ValueSchema, value);
+    }
+    return value;
+}
+function textQuery(text, fields) {
+    if (typeof text !== 'string') {
+        return text;
+    }
+    if (fields === undefined || fields.length === 0) {
+        return Filter.queryString(text);
+    }
+    if (fields.length === 1) {
+        return Filter.match(fields[0], text);
+    }
+    return Filter.multiMatch(fields, text);
+}
+/** The search builder. */
+export class Search {
+    #json;
+    constructor(json) {
+        this.#json = json;
+    }
+    /** A search of `collection` (a name or an alias). */
+    static on(collection, options = {}) {
+        return new _a({
+            ...(options.namespace === undefined ? {} : { namespace: options.namespace }),
+            collection,
+        });
+    }
+    /** A builder over an existing request's proto3 JSON. */
+    static fromJson(json) {
+        return new _a(structuredClone(json));
+    }
+    #with(patch) {
+        return new _a({ ...structuredClone(this.#json), ...patch });
+    }
+    #retrievers() {
+        return this.#json.retrievers ?? [];
+    }
+    /** The namespace, when it is not the client's default. */
+    namespace(namespace) {
+        return this.#with({ namespace });
+    }
+    /** A text retriever. A string is a `match`/`multi_match`/`query_string`
+     * by `fields`; a `Filter` (`match`, `multiMatch`, `phrase`…) is used as is. */
+    text(text, options = {}) {
+        const retriever = { query: textQuery(text, options.fields) };
+        if (options.k !== undefined) {
+            retriever.k = options.k;
+        }
+        return this.#with({ retrievers: [...this.#retrievers(), { text: retriever }] });
+    }
+    /** A dense-vector kNN retriever on `field`. */
+    vector(field, values, options = {}) {
+        const retriever = { field, query: [...values] };
+        if (options.k !== undefined) {
+            retriever.k = options.k;
+        }
+        const params = {};
+        for (const key of ['exact', 'nprobes', 'refineFactor', 'ef', 'oversampling', 'distance']) {
+            if (options[key] !== undefined) {
+                params[key] = options[key];
+            }
+        }
+        if (Object.keys(params).length > 0) {
+            retriever.params = params;
+        }
+        if (options.filter !== undefined) {
+            retriever.filter = options.filter;
+        }
+        return this.#with({ retrievers: [...this.#retrievers(), { vector: retriever }] });
+    }
+    /** A sparse-vector retriever: `{indices, values}`, or a term-to-weight map
+     * whose keys are the indices. */
+    sparse(field, terms, options = {}) {
+        const query = 'indices' in terms && Array.isArray(terms.indices)
+            ? { indices: [...terms.indices], values: [...terms.values] }
+            : (() => {
+                const entries = Object.entries(terms);
+                return { indices: entries.map(([index]) => Number(index)), values: entries.map(([, v]) => v) };
+            })();
+        const retriever = { field, query };
+        if (options.k !== undefined) {
+            retriever.k = options.k;
+        }
+        if (options.filter !== undefined) {
+            retriever.filter = options.filter;
+        }
+        return this.#with({ retrievers: [...this.#retrievers(), { sparse: retriever }] });
+    }
+    /** How the retrievers' ranked lists combine: `rrf()`, `dbsf()` or
+     * `weighted(…)`. */
+    fuse(fusion) {
+        return this.#with({ fusion });
+    }
+    /** The filter every candidate must match. */
+    filter(filter) {
+        return this.#with({ filter });
+    }
+    /** The sort, replacing any earlier one. */
+    sort(...keys) {
+        return this.#with({ sort: keys });
+    }
+    /** The window size; the engine's default is 10. */
+    limit(limit) {
+        return this.#with({ limit });
+    }
+    /** How many hits to skip before the window. */
+    offset(offset) {
+        return this.#with({ offset });
+    }
+    /** The page after the hit whose `sortValues` these are. */
+    after(sortValues) {
+        return this.#with({ searchAfter: sortValues.map(sortValueJson) });
+    }
+    /** Drops hits scoring below `score`. */
+    minScore(score) {
+        return this.#with({ scoreThreshold: score });
+    }
+    /** What to return of each hit. */
+    select(options) {
+        const select = {};
+        if (options.noSource === true) {
+            select.source = 'none';
+        }
+        else if (options.include !== undefined || options.exclude !== undefined) {
+            const source = {};
+            if (options.include !== undefined) {
+                source.include = [...options.include];
+            }
+            if (options.exclude !== undefined) {
+                source.exclude = [...options.exclude];
+            }
+            select.source = source;
+        }
+        if (options.vectors !== undefined) {
+            select.vectors = [...options.vectors];
+        }
+        if (options.fields !== undefined) {
+            select.fields = [...options.fields];
+        }
+        return this.#with({ select });
+    }
+    /** Highlights `field` in each hit; call once per field. */
+    highlight(field, options = {}) {
+        const entry = { field };
+        if (options.pre !== undefined) {
+            entry.preTag = options.pre;
+        }
+        if (options.post !== undefined) {
+            entry.postTag = options.post;
+        }
+        if (options.fragmentSize !== undefined) {
+            entry.fragmentSize = options.fragmentSize;
+        }
+        if (options.fragments !== undefined) {
+            entry.numberOfFragments = options.fragments;
+        }
+        const existing = this.#json.highlight?.fields ?? [];
+        return this.#with({ highlight: { fields: [...existing, entry] } });
+    }
+    /** Groups the hits by `field`: `size` hits per group, `limit` groups. */
+    groupBy(field, options = {}) {
+        const group = { field };
+        if (options.size !== undefined) {
+            group.groupSize = options.size;
+        }
+        if (options.limit !== undefined) {
+            group.limit = options.limit;
+        }
+        return this.#with({ groupBy: group });
+    }
+    /** Walks `graph` from the top hits and returns their neighbours. */
+    expand(graph, options = {}) {
+        const spec = { graph };
+        const copy = ['fromField', 'seedLabel', 'seeds', 'hops', 'limitPerSeed', 'limit'];
+        for (const key of copy) {
+            if (options[key] !== undefined) {
+                spec[key] = options[key];
+            }
+        }
+        if (options.direction !== undefined) {
+            spec.direction = `EXPAND_DIRECTION_${options.direction.toUpperCase()}`;
+        }
+        if (options.edgeTypes !== undefined) {
+            spec.edgeTypes = [...options.edgeTypes];
+        }
+        if (options.output !== undefined) {
+            spec.output = `EXPAND_OUTPUT_${options.output.toUpperCase()}`;
+        }
+        return this.#with({ expandSpec: spec });
+    }
+    /** How fresh the read must be. */
+    consistency(level) {
+        return this.#with({ consistency: consistencyJson(level) });
+    }
+    /** The collection searched. */
+    get collection() {
+        return this.#json.collection;
+    }
+    /** Whether the sort ends in a primary-key tiebreaker, which `queryAll`
+     * needs to page without skipping or repeating a hit. */
+    get hasTiebreak() {
+        const sort = this.#json.sort;
+        const last = sort?.[sort.length - 1];
+        return last !== undefined && 'pk' in last;
+    }
+    /** The request's proto3 JSON. */
+    toJson() {
+        return structuredClone(this.#json);
+    }
+    /** The request as the generated message, checked. */
+    build() {
+        const weights = this.#json.fusion?.weightedSum
+            ?.weights;
+        const retrievers = this.#retrievers().length;
+        if (weights !== undefined && weights.length !== retrievers) {
+            throw new InvalidArgumentError(`a weighted fusion needs one weight per retriever: ${weights.length} weights for ${retrievers} retrievers`, {
+                code: Code.InvalidArgument,
+                metadata: { field: 'fusion.weighted_sum.weights' },
+            });
+        }
+        return fromJson(SearchRequestSchema, this.#json);
+    }
+}
+_a = Search;