@functional-systems/lambdadb 0.5.1 → 0.7.0

package/src/models/operations/querycollection.ts

@@ -1,5 +1,5 @@
 /*
- * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * Maintained manually following docs/OPENAPI_UPDATE.md.
  */
 
 import * as z from "zod/v3";
@@ -8,6 +8,14 @@ import { nullToUndefined, safeParse } from "../../lib/schemas.js";
 import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 import * as models from "../index.js";
+import { hasRerankScoringQuery } from "../rerank.js";
+
+export type FacetRequest = {
+  /** Maximum buckets to return (1–100). Omitted or null uses the server default of 10. */
+  size?: number | null | undefined;
+};
+export type FacetBucket = { value: string; count: number };
+export type FacetResult = { buckets: Array<FacetBucket> };
 
 export type QueryCollectionRequestBody = {
   /**
@@ -17,7 +25,10 @@ export type QueryCollectionRequestBody = {
   /**
    * Query object. For managed embedding vector fields, use knn.queryText. For unmanaged vector fields, use knn.queryVector.
    */
-  query: { [k: string]: any };
+  query?: { [k: string]: any } | undefined;
+  facets?: Record<string, FacetRequest> | undefined;
+  /** Optional per-query managed reranking. Omitted or null preserves retrieval behavior. */
+  rerank?: models.RerankConfig | null | undefined;
   /**
    * Overlay eligible pending writes on a directly selected Branch. Tag and Alias reads reject true, pending bulk imports are excluded, and an oversized pending overlay can return HTTP 429.
    */
@@ -53,9 +64,11 @@ export type QueryCollectionDoc = {
    */
   collection: string;
   /**
-   * Document similarity score.
+   * Final ranking score: evaluation score in [0,1] when rerank is applied, otherwise retrieval score.
    */
   score?: number | undefined;
+  /** Original retrieval/fusion score, outside doc; present only when rerank is applied. */
+  retrievalScore?: number | undefined;
   doc: { [k: string]: any };
 };
 
@@ -63,12 +76,15 @@ export type QueryCollectionDoc = {
  * Documents selected by query.
  */
 export type QueryCollectionResponse = {
+  /** Present only for requests using reranking. */
+  rerank?: models.RerankResponse | undefined;
+  facets?: Record<string, FacetResult> | undefined;
   /**
    * Elapsed time in milliseconds.
    */
   took: number;
   /**
-   * Maximum score.
+   * Maximum final returned score, including zero; omitted for empty rerank results.
    */
   maxScore?: number | undefined;
   /**
@@ -92,7 +108,10 @@ export type QueryCollectionResponse = {
 /** @internal */
 export type QueryCollectionRequestBody$Outbound = {
   size?: number | undefined;
-  query: { [k: string]: any };
+  query?: { [k: string]: any } | undefined;
+  facets?: Record<string, FacetRequest> | undefined;
+  /** Optional per-query managed reranking. Omitted or null preserves retrieval behavior. */
+  rerank?: models.RerankConfig | null | undefined;
   consistentRead: boolean;
   includeVectors: boolean;
   sort?: Array<{ [k: string]: any }> | undefined;
@@ -108,7 +127,13 @@ export const QueryCollectionRequestBody$outboundSchema: z.ZodType<
   QueryCollectionRequestBody
 > = z.object({
   size: z.number().int().optional(),
-  query: z.record(z.any()),
+  query: z.record(z.any()).optional(),
+  facets: z.record(z.object({
+    size: z.number().int().min(1).max(100).nullable().optional(),
+  }).strict()).refine((facets) => Object.keys(facets).length <= 5, {
+    message: "At most five facet fields may be requested",
+  }).optional(),
+  rerank: models.RerankConfig$outboundSchema.nullable().optional(),
   consistentRead: z.boolean().default(false),
   includeVectors: z.boolean().default(false),
   sort: z.array(z.record(z.any())).optional(),
@@ -116,6 +141,38 @@ export const QueryCollectionRequestBody$outboundSchema: z.ZodType<
   partitionFilter: models.PartitionFilter$outboundSchema.optional(),
   ref: models.ReadRef$schema.optional(),
 }).strict().superRefine((value, context) => {
+  if (value.rerank != null) {
+    const size = value.size ?? 10;
+    const candidateSize = value.rerank.candidateSize ?? Math.max(50, size);
+    if (size < 1 || size > 100 || candidateSize < size) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "rerank requires 1 <= size <= candidateSize <= 100",
+        path: ["rerank", "candidateSize"],
+      });
+    }
+    if (value.sort !== undefined) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "rerank cannot be combined with sort",
+        path: ["sort"],
+      });
+    }
+    if (!hasRerankScoringQuery(value.query)) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "rerank requires a scoring retrieval query",
+        path: ["query"],
+      });
+    }
+  }
+  if (value.size === 0 && Object.keys(value.facets ?? {}).length === 0) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "size: 0 requires at least one facet",
+      path: ["facets"],
+    });
+  }
   if (value.consistentRead && value.ref != null && value.ref.kind !== "branch") {
     context.addIssue({
       code: z.ZodIssueCode.custom,
@@ -169,6 +226,7 @@ export const QueryCollectionDoc$inboundSchema: z.ZodType<
 > = z.object({
   collection: z.string(),
   score: nullToUndefined(z.number().optional()),
+  retrievalScore: nullToUndefined(z.number().optional()),
   doc: z.record(z.any()),
 });
 
@@ -188,12 +246,16 @@ export const QueryCollectionResponse$inboundSchema: z.ZodType<
   z.ZodTypeDef,
   unknown
 > = z.object({
+  rerank: nullToUndefined(models.RerankResponse$inboundSchema.optional()),
   took: z.number().int(),
   maxScore: nullToUndefined(z.number().optional()),
   total: z.number().int(),
   docs: z.array(z.lazy(() => QueryCollectionDoc$inboundSchema)),
   isDocsInline: z.boolean(),
   docsUrl: nullToUndefined(z.string().optional()),
+  facets: nullToUndefined(z.record(z.object({
+    buckets: z.array(z.object({ value: z.string(), count: z.number().int() })),
+  })).optional()),
 });
 
 export function queryCollectionResponseFromJSON(

package/src/models/rerank.ts

@@ -0,0 +1,89 @@
+/** Managed reranking DTOs, maintained manually following docs/OPENAPI_UPDATE.md. */
+import * as z from "zod/v3";
+import { nullToUndefined } from "../lib/schemas.js";
+
+/** Per-query fixed managed model; credentials are managed by the server. */
+export type RerankConfig = {
+  provider: "typesafe";
+  model: "jev-1.13.0";
+  /** Nonblank text, at most 8 KiB UTF-8; sent unchanged. */
+  queryText: string;
+  /** 1–8 unique stored scalar text paths, in model input order. */
+  fields: string[];
+  /** Defaults on the server to max(50, size); does not change knn.k. */
+  candidateSize?: number | null | undefined;
+  /** Server default: error. Only eligible provider failures can returnOriginal. */
+  onFailure?: "error" | "returnOriginal" | null | undefined;
+  /** 2–10 distinct nonblank descriptions, lowest to highest relevance; null uses defaults. */
+  criteria?: string[] | null | undefined;
+};
+
+export type RerankResponse = {
+  status: "applied" | "skipped" | "fallback";
+  provider: string;
+  model: string;
+  resolvedModel?: string | undefined;
+  candidateCount: number;
+  scoredCount: number;
+  /** Rerank stage duration in milliseconds. */
+  took: number;
+  /** Only applied results report this marker; custom is not a content identity. */
+  criteriaVersion?: "default-relevance-v1" | "custom" | undefined;
+  reason?: string | undefined;
+};
+
+// Match Java String.isBlank; do not trim or normalize caller text.
+// eslint-disable-next-line no-control-regex -- Java whitespace includes these control characters.
+const blank = /^[\u0009-\u000d\u001c-\u0020\u1680\u2000-\u2006\u2008-\u200a\u2028\u2029\u205f\u3000]*$/u;
+const nonblank = z.string().refine((text) => !blank.test(text), "Must be nonblank");
+const bytes = (text: string) => new TextEncoder().encode(text).length;
+
+/** @internal */
+export const RerankConfig$outboundSchema: z.ZodType<RerankConfig> = z.object({
+  provider: z.literal("typesafe"),
+  model: z.literal("jev-1.13.0"),
+  queryText: nonblank.refine((text) => bytes(text) <= 8192, "queryText exceeds 8 KiB UTF-8"),
+  fields: z.array(nonblank.refine(
+    (path) => path.split(".").every((part) => !blank.test(part)), "Invalid field path",
+  )).min(1).max(8).refine((paths) => new Set(paths).size === paths.length, "Fields must be unique"),
+  candidateSize: z.number().int().min(1).max(100).nullable().optional(),
+  onFailure: z.enum(["error", "returnOriginal"]).nullable().optional(),
+  criteria: z.array(nonblank.refine(
+    (text) => bytes(text) <= 2048, "Criterion exceeds 2 KiB UTF-8",
+  )).min(2).max(10).refine(
+    (texts) => new Set(texts).size === texts.length, "Criteria must be distinct",
+  ).refine(
+    (texts) => texts.reduce((total, text) => total + bytes(text), 0) <= 8192,
+    "Criteria exceed 8 KiB total UTF-8",
+  ).nullable().optional(),
+}).strict();
+
+/** @internal */
+export const RerankResponse$inboundSchema: z.ZodType<RerankResponse, z.ZodTypeDef, unknown> = z.object({
+  status: z.enum(["applied", "skipped", "fallback"]),
+  provider: z.string(),
+  model: z.string(),
+  resolvedModel: nullToUndefined(z.string().optional()),
+  candidateCount: z.number().int().nonnegative(),
+  scoredCount: z.number().int().nonnegative(),
+  took: z.number().int().nonnegative(),
+  criteriaVersion: nullToUndefined(z.enum(["default-relevance-v1", "custom"]).optional()),
+  reason: nullToUndefined(z.string().optional()),
+});
+
+/** @internal: mirrors ManagedRerankService.hasScoringQuery for the existing wire DSL. */
+export function hasRerankScoringQuery(query: unknown): boolean {
+  if (query == null || typeof query !== "object" || Array.isArray(query)) return false;
+  const node = query as Record<string, unknown>;
+  const occur = typeof node["occur"] === "string" ? node["occur"].toUpperCase() : undefined;
+  if (occur === "FILTER" || occur === "MUST_NOT") return false;
+  // Follow backend parser precedence for composite queries.
+  for (const key of ["bool", "rrf", "mm", "l2"]) {
+    // Undefined members are omitted by JSON serialization.
+    if (node[key] !== undefined) {
+      const children = node[key];
+      return Array.isArray(children) && children.some(hasRerankScoringQuery);
+    }
+  }
+  return ["queryString", "sparseVector", "knn"].some((key) => node[key] != null);
+}

package/src/types/public.ts

@@ -273,3 +273,7 @@ export function tagDetailsWithDates(details: TagDetailsModel): TagDetails {
 export function aliasDetailsWithDate(details: AliasDetailsModel): AliasDetails {
   return { ...details, createdAt: new Date(details.createdAt) };
 }
+
+export type { FacetRequest, FacetBucket, FacetResult } from "../models/operations/querycollection.js";
+
+export type { RerankConfig, RerankResponse } from "../models/rerank.js";