@query-farm/vgi 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "TypeScript framework for extending DuckDB with user-defined functions via the Vector Gateway Interface (VGI) over Arrow IPC.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Query Farm LLC (https://query.farm)",

package/src/arguments/argument-spec.ts

@@ -14,7 +14,12 @@ import {
   VGI_CONST_KEY,
   VGI_CONST_TRUE,
   VGI_DOC_KEY,
+  VGI_DEFAULT_KEY,
+  VGI_CHOICES_KEY,
+  VGI_RANGE_KEY,
+  VGI_PATTERN_KEY,
 } from "../types.js";
+import { ArgumentValidationError } from "../errors.js";
 
 export interface ArgumentSpec {
   name: string;
@@ -25,6 +30,193 @@ export interface ArgumentSpec {
   isVarargs?: boolean;
   isConst?: boolean;
   doc?: string;
+  /**
+   * Discovery-facing constraint metadata, pre-encoded to their surfaced UTF-8
+   * forms (presence-only — `undefined` means the constraint is absent and the
+   * corresponding field-metadata key is omitted entirely). Mirrors Python's
+   * `ArgumentSpec.default_json` / `choices_json` / `range_notation` / `pattern`
+   * so `argumentSpecsToSchema`/`schemaToArgumentSpecs` round-trip symmetrically.
+   */
+  defaultJson?: string;
+  choicesJson?: string;
+  rangeNotation?: string;
+  pattern?: string;
+}
+
+/**
+ * Raw per-argument constraint declarations, as authored on a function's
+ * argument descriptor. Encoded into the pre-computed {@link ArgumentSpec}
+ * constraint fields via {@link constraintSpecFields}.
+ */
+export interface ArgumentConstraints {
+  /** Closed set of allowed values (JSON-encoded into `vgi_choices`). */
+  choices?: readonly unknown[];
+  /** Inclusive lower bound (`>=`). */
+  ge?: number;
+  /** Inclusive upper bound (`<=`). */
+  le?: number;
+  /** Exclusive lower bound (`>`). */
+  gt?: number;
+  /** Exclusive upper bound (`<`). */
+  lt?: number;
+  /** Regex the value must match (surfaced as `vgi_pattern`, as-is). */
+  pattern?: string;
+  /** Default value (JSON-encoded into `vgi_default`); optional args only. */
+  default?: unknown;
+}
+
+/** `JSON.stringify`, falling back to the value's string form when unserializable. */
+function safeJson(value: unknown): string {
+  try {
+    const encoded = JSON.stringify(value);
+    // JSON.stringify returns undefined for functions/symbols/undefined.
+    if (encoded === undefined) {
+      return JSON.stringify(String(value));
+    }
+    return encoded;
+  } catch {
+    return JSON.stringify(String(value));
+  }
+}
+
+/**
+ * Build interval notation from an argument's numeric bounds.
+ *
+ * Inclusive bounds (`ge`/`le`) render as square brackets, exclusive bounds
+ * (`gt`/`lt`) as parentheses, and an open side as `-inf`/`+inf`. Returns
+ * `undefined` when the argument has no numeric bound at all.
+ *
+ * Examples: `ge=0,le=10` -> `"[0, 10]"`; `gt=0` -> `"(0, +inf)"`;
+ * `ge=1,lt=10` -> `"[1, 10)"`.
+ */
+export function formatRange(
+  ge?: number,
+  le?: number,
+  gt?: number,
+  lt?: number,
+): string | undefined {
+  if (ge === undefined && le === undefined && gt === undefined && lt === undefined) {
+    return undefined;
+  }
+  let low: string;
+  if (gt !== undefined) {
+    low = `(${gt}`;
+  } else if (ge !== undefined) {
+    low = `[${ge}`;
+  } else {
+    low = "(-inf";
+  }
+  let high: string;
+  if (lt !== undefined) {
+    high = `${lt})`;
+  } else if (le !== undefined) {
+    high = `${le}]`;
+  } else {
+    high = "+inf)";
+  }
+  return `${low}, ${high}`;
+}
+
+/**
+ * Encode raw {@link ArgumentConstraints} into the pre-computed constraint
+ * fields of an {@link ArgumentSpec} (presence-only — absent constraints yield
+ * no field). Mirrors Python's `_constraint_kwargs`.
+ */
+export function constraintSpecFields(
+  constraints: ArgumentConstraints | undefined,
+): Pick<ArgumentSpec, "defaultJson" | "choicesJson" | "rangeNotation" | "pattern"> {
+  const fields: Pick<
+    ArgumentSpec,
+    "defaultJson" | "choicesJson" | "rangeNotation" | "pattern"
+  > = {};
+  if (constraints === undefined) return fields;
+
+  if ("default" in constraints && constraints.default !== undefined) {
+    fields.defaultJson = safeJson(constraints.default);
+  }
+  if (constraints.choices !== undefined) {
+    fields.choicesJson = safeJson([...constraints.choices]);
+  }
+  const range = formatRange(
+    constraints.ge,
+    constraints.le,
+    constraints.gt,
+    constraints.lt,
+  );
+  if (range !== undefined) {
+    fields.rangeNotation = range;
+  }
+  if (constraints.pattern !== undefined) {
+    fields.pattern = constraints.pattern;
+  }
+  return fields;
+}
+
+/** Coerce a numeric const value (number or int64 `bigint`) to `number`. */
+function toNumber(value: unknown): number | undefined {
+  if (typeof value === "number") return value;
+  if (typeof value === "bigint") return Number(value);
+  return undefined;
+}
+
+/** Equality for a choice comparison, coercing numeric/bigint operands. */
+function choiceEquals(choice: unknown, value: unknown): boolean {
+  const cn = toNumber(choice);
+  const vn = toNumber(value);
+  if (cn !== undefined && vn !== undefined) return cn === vn;
+  return choice === value;
+}
+
+/**
+ * Enforce a bind-time const value against its declared {@link ArgumentConstraints},
+ * throwing {@link ArgumentValidationError} on violation. Mirrors the Python SDK's
+ * `Arg._validate`: numeric range (`ge`/`le`/`gt`/`lt`), closed choice set, and
+ * regex `pattern`. A `null`/`undefined` value skips its value constraints.
+ */
+export function validateConstConstraints(
+  name: string,
+  constraints: ArgumentConstraints,
+  value: unknown,
+): void {
+  if (value === null || value === undefined) return;
+
+  const num = toNumber(value);
+  if (num !== undefined) {
+    if (constraints.ge !== undefined && num < constraints.ge) {
+      throw new ArgumentValidationError(`argument '${name}' must be >= ${constraints.ge}`);
+    }
+    if (constraints.le !== undefined && num > constraints.le) {
+      throw new ArgumentValidationError(`argument '${name}' must be <= ${constraints.le}`);
+    }
+    if (constraints.gt !== undefined && num <= constraints.gt) {
+      throw new ArgumentValidationError(`argument '${name}' must be > ${constraints.gt}`);
+    }
+    if (constraints.lt !== undefined && num >= constraints.lt) {
+      throw new ArgumentValidationError(`argument '${name}' must be < ${constraints.lt}`);
+    }
+  }
+
+  if (constraints.choices !== undefined && constraints.choices.length > 0) {
+    if (!constraints.choices.some((c) => choiceEquals(c, value))) {
+      throw new ArgumentValidationError(
+        `argument '${name}' must be one of ${JSON.stringify([...constraints.choices])}`,
+      );
+    }
+  }
+
+  if (constraints.pattern !== undefined && typeof value === "string") {
+    let re: RegExp | undefined;
+    try {
+      re = new RegExp(constraints.pattern);
+    } catch {
+      re = undefined; // an invalid declared regex must not reject the caller
+    }
+    if (re !== undefined && !re.test(value)) {
+      throw new ArgumentValidationError(
+        `argument '${name}' must match pattern ${JSON.stringify(constraints.pattern)}`,
+      );
+    }
+  }
 }
 
 function argumentSpecSortKey(spec: ArgumentSpec): [number, number | string] {
@@ -76,6 +268,20 @@ export function argumentSpecsToSchema(specs: ArgumentSpec[]): VgiSchema {
       metadata.set(VGI_DOC_KEY, spec.doc);
     }
 
+    // Per-argument constraint metadata (presence-only; already value-encoded).
+    if (spec.defaultJson !== undefined) {
+      metadata.set(VGI_DEFAULT_KEY, spec.defaultJson);
+    }
+    if (spec.choicesJson !== undefined) {
+      metadata.set(VGI_CHOICES_KEY, spec.choicesJson);
+    }
+    if (spec.rangeNotation !== undefined) {
+      metadata.set(VGI_RANGE_KEY, spec.rangeNotation);
+    }
+    if (spec.pattern !== undefined) {
+      metadata.set(VGI_PATTERN_KEY, spec.pattern);
+    }
+
     const field = field_(
       spec.name,
       spec.arrowType,
@@ -184,6 +390,12 @@ export function schemaToArgumentSpecs(schema: VgiSchema): ArgumentSpec[] {
     const isConst = metadata.get(VGI_CONST_KEY) === VGI_CONST_TRUE;
     const doc = metadata.get(VGI_DOC_KEY) ?? "";
 
+    // Per-argument constraint metadata (absent key -> undefined).
+    const defaultJson = metadata.get(VGI_DEFAULT_KEY);
+    const choicesJson = metadata.get(VGI_CHOICES_KEY);
+    const rangeNotation = metadata.get(VGI_RANGE_KEY);
+    const pattern = metadata.get(VGI_PATTERN_KEY);
+
     specs.push({
       name: field.name,
       position,
@@ -193,6 +405,10 @@ export function schemaToArgumentSpecs(schema: VgiSchema): ArgumentSpec[] {
       isVarargs,
       isConst,
       doc,
+      defaultJson,
+      choicesJson,
+      rangeNotation,
+      pattern,
     });
   }
 

package/src/functions/scalar.ts

@@ -37,7 +37,12 @@ import type {
   FunctionExample,
 } from "./types.js";
 import type { ArgumentSpec } from "../arguments/argument-spec.js";
-import { argumentSpecsToSchema } from "../arguments/argument-spec.js";
+import {
+  argumentSpecsToSchema,
+  constraintSpecFields,
+  validateConstConstraints,
+  type ArgumentConstraints,
+} from "../arguments/argument-spec.js";
 import { batchToScalarDict, batchToSecretDict, batchFromColumns, projectBatch, safeNumber } from "../util/arrow/index.js";
 
 // ============================================================================
@@ -71,6 +76,22 @@ export interface ScalarParameterDef {
   varargs?: boolean;
   /** Human-readable per-argument description (surfaced as `vgi_doc`). */
   doc?: string;
+  // Discovery-facing validation constraints (surfaced via
+  // `vgi_function_arguments()`). All optional; see `ArgumentConstraints`.
+  /** Closed set of allowed values (surfaced as `vgi_choices`). */
+  choices?: readonly unknown[];
+  /** Inclusive lower bound, `>=` (folded into `vgi_range`). */
+  ge?: number;
+  /** Inclusive upper bound, `<=` (folded into `vgi_range`). */
+  le?: number;
+  /** Exclusive lower bound, `>` (folded into `vgi_range`). */
+  gt?: number;
+  /** Exclusive upper bound, `<` (folded into `vgi_range`). */
+  lt?: number;
+  /** Regex the value must match (surfaced as `vgi_pattern`). */
+  pattern?: string;
+  /** Default value (surfaced as `vgi_default`, JSON-encoded). */
+  default?: unknown;
 }
 
 /**
@@ -183,6 +204,7 @@ export function defineScalarFunction<
         isConst: p.const,
         isVarargs: p.varargs,
         doc: p.doc,
+        ...constraintSpecFields(p),
       });
     }
   } else {
@@ -215,6 +237,26 @@ export function defineScalarFunction<
     }
   }
 
+  // Raw const-arg constraints for bind-time enforcement, keyed by arg name.
+  // Only the ordered `parameters` API carries constraints (the legacy
+  // params/constParams path does not), so only its const params appear here.
+  const constConstraints = new Map<string, ArgumentConstraints>();
+  if (config.parameters) {
+    for (const p of config.parameters) {
+      if (
+        p.const &&
+        (p.choices !== undefined ||
+          p.ge !== undefined ||
+          p.le !== undefined ||
+          p.gt !== undefined ||
+          p.lt !== undefined ||
+          p.pattern !== undefined)
+      ) {
+        constConstraints.set(p.name, p);
+      }
+    }
+  }
+
   const meta: FunctionMeta = {
     name: config.name,
     description: config.description,
@@ -253,7 +295,11 @@ export function defineScalarFunction<
         let constIdx = 0;
         for (const spec of specs) {
           if (spec.isConst) {
-            constArgs[spec.name] = request.arguments.get(constIdx, undefined);
+            const value = request.arguments.get(constIdx, undefined);
+            constArgs[spec.name] = value;
+            // Enforce declared const-arg constraints at bind (choices/range/pattern).
+            const constraints = constConstraints.get(spec.name);
+            if (constraints) validateConstConstraints(spec.name, constraints, value);
             constIdx++;
           }
         }

package/src/index.core.ts

@@ -75,7 +75,7 @@ export type {
 
 // Arguments
 export { Arguments } from "./arguments/arguments.js";
-export { type ArgumentSpec, argumentSpecsToSchema, schemaToArgumentSpecs, macroArgumentsSchema, macroParameterDocsFromSchema } from "./arguments/argument-spec.js";
+export { type ArgumentSpec, type ArgumentConstraints, argumentSpecsToSchema, schemaToArgumentSpecs, macroArgumentsSchema, macroParameterDocsFromSchema, formatRange, constraintSpecFields } from "./arguments/argument-spec.js";
 
 // Errors
 export {

package/src/types.ts

@@ -62,6 +62,20 @@ export const VGI_CONST_TRUE = "true";
 // Per-argument description (UTF-8; presence-only). `vgi_doc_*` prefix reserved.
 export const VGI_DOC_KEY = "vgi_doc";
 
+// Per-argument constraint metadata for agent discovery. All presence-only
+// (omitted when absent) and value-encoded as UTF-8 so the surfaced column type
+// stays uniform regardless of the arg's value type:
+//   vgi_default — JSON scalar (the arg's default value; optional args only)
+//   vgi_choices — JSON array (the closed set of allowed values)
+//   vgi_range   — interval notation built from ge/le/gt/lt (e.g. "[0, 100]",
+//                 "(0, +inf)", "[1, 10)"); a discovery surface, not raw bounds
+//   vgi_pattern — raw regex the value must match (open set)
+// Kept byte-for-byte in sync with the C++ reader and the Python/other SDKs.
+export const VGI_DEFAULT_KEY = "vgi_default";
+export const VGI_CHOICES_KEY = "vgi_choices";
+export const VGI_RANGE_KEY = "vgi_range";
+export const VGI_PATTERN_KEY = "vgi_pattern";
+
 export interface TableCardinality {
   estimate: number | null;
   max: number | null;