@query-farm/vgi 0.9.0 → 0.11.0

package/dist/arguments/argument-spec.d.ts

@@ -58,6 +58,13 @@ export declare function formatRange(ge?: number, le?: number, gt?: number, lt?:
  * no field). Mirrors Python's `_constraint_kwargs`.
  */
 export declare function constraintSpecFields(constraints: ArgumentConstraints | undefined): Pick<ArgumentSpec, "defaultJson" | "choicesJson" | "rangeNotation" | "pattern">;
+/**
+ * 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 declare function validateConstConstraints(name: string, constraints: ArgumentConstraints, value: unknown): void;
 /**
  * Convert ArgumentSpecs to an Arrow Schema with VGI metadata keys.
  * Positional arguments come first (in order), named arguments follow.

package/dist/functions/aggregate.d.ts

@@ -1,5 +1,6 @@
 import { type VgiSchema, type VgiBatch, type VgiDataType } from "../arrow/index.js";
 import type { Arguments } from "../arguments/arguments.js";
+import { type ArgumentConstraints } from "../arguments/argument-spec.js";
 import type { VgiFunction } from "./types.js";
 import type { FunctionExample } from "./types.js";
 export declare const GROUP_COLUMN_NAME = "__vgi_group_id";
@@ -70,6 +71,13 @@ export interface AggregateFunctionConfig<TArgs = Record<string, any>, TState = a
     onBind?: (params: AggregateBindParams<TArgs>) => VgiDataType | Promise<VgiDataType>;
     /** Optional per-arg default values (positional only here). */
     argDefaults?: Record<string, any>;
+    /**
+     * Per-argument discovery constraints (choices / ge / le / gt / lt / pattern),
+     * keyed by argument name. Surfaced via `vgi_function_arguments()` and enforced
+     * at aggregate_bind for const params: a value violating a declared constraint
+     * fails the bind with an ArgumentValidationError.
+     */
+    argConstraints?: Record<string, ArgumentConstraints>;
     initialState: (params: AggregateBindParams<TArgs>) => TState;
     /**
      * Fold a batch of input rows into the provided per-group state map.

package/dist/functions/table.d.ts

@@ -2,6 +2,7 @@ import { type VgiSchema, type VgiDataType } from "../arrow/index.js";
 import type { OutputCollector } from "@query-farm/vgi-rpc";
 import type { BindRequest, InitRequest, GlobalInitResponse, TableCardinality } from "../protocol/types.js";
 import type { VgiFunction, FunctionExample } from "./types.js";
+import { type ArgumentConstraints } from "../arguments/argument-spec.js";
 import { type PushdownFilters } from "../filter-pushdown/index.js";
 import type { ColumnStatistics } from "../util/statistics.js";
 import { FunctionStability, type NullHandling, type OrderPreservation, type OrderDependence, type DistinctDependence } from "../types.js";
@@ -41,6 +42,13 @@ export interface TableFunctionConfig<TArgs = Record<string, any>, TState = null>
     argDocs?: Record<string, string>;
     /** Argument defaults */
     argDefaults?: Record<string, any>;
+    /**
+     * Per-argument discovery constraints (choices / ge / le / gt / lt / pattern),
+     * keyed by argument name. Surfaced via `vgi_function_arguments()` for agent
+     * discovery AND enforced at bind: a value violating a declared constraint
+     * fails the bind with an ArgumentValidationError.
+     */
+    argConstraints?: Record<string, ArgumentConstraints>;
     /** Names of args that accept variable number of arguments */
     varargs?: string[];
     /** Bind: return output schema. May be async — handlers `await` the result. */

package/dist/index.js

@@ -2717,6 +2717,55 @@ function constraintSpecFields(constraints) {
   }
   return fields;
 }
+function toNumber(value) {
+  if (typeof value === "number")
+    return value;
+  if (typeof value === "bigint")
+    return Number(value);
+  return;
+}
+function choiceEquals(choice, value) {
+  const cn = toNumber(choice);
+  const vn = toNumber(value);
+  if (cn !== undefined && vn !== undefined)
+    return cn === vn;
+  return choice === value;
+}
+function validateConstConstraints(name, constraints, value) {
+  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;
+    try {
+      re = new RegExp(constraints.pattern);
+    } catch {
+      re = undefined;
+    }
+    if (re !== undefined && !re.test(value)) {
+      throw new ArgumentValidationError(`argument '${name}' must match pattern ${JSON.stringify(constraints.pattern)}`);
+    }
+  }
+}
 function argumentSpecSortKey(spec) {
   if (typeof spec.position === "number") {
     return [0, spec.position];
@@ -2884,6 +2933,14 @@ function defineScalarFunction(config) {
       }
     }
   }
+  const constConstraints = new Map;
+  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 = {
     name: config.name,
     description: config.description,
@@ -2910,7 +2967,11 @@ function defineScalarFunction(config) {
         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;
+            const constraints = constConstraints.get(spec.name);
+            if (constraints)
+              validateConstConstraints(spec.name, constraints, value);
             constIdx++;
           }
         }
@@ -3803,7 +3864,8 @@ function defineTableFunction(config) {
         arrowType: isAny ? nullType2() : type,
         isAnyType: isAny,
         isVarargs: varargsSet.has(name),
-        doc: config.argDocs?.[name]
+        doc: config.argDocs?.[name],
+        ...constraintSpecFields(config.argConstraints?.[name])
       });
     }
   }
@@ -3842,6 +3904,9 @@ function defineTableFunction(config) {
       }
       if (typeof val === "bigint")
         val = safeNumber(val);
+      const constraints = config.argConstraints?.[spec.name];
+      if (constraints)
+        validateConstConstraints(spec.name, constraints, val);
       args[spec.name] = val;
     }
     return args;
@@ -4117,7 +4182,8 @@ function defineAggregate(config) {
         arrowType: isAnyType2 ? nullType2() : type,
         isAnyType: isAnyType2,
         isVarargs: varargsSet.has(name),
-        isConst
+        isConst,
+        ...constraintSpecFields(config.argConstraints?.[name])
       });
     }
   }
@@ -9079,8 +9145,9 @@ function extractArgMap(cfg, args) {
     }
   }
   for (let i = 0;i < constNames.length; i++) {
+    let v;
     try {
-      let v = args.get(i);
+      v = args.get(i);
       const field3 = args.argumentsSchema?.fields.find((f) => f.name === `positional_${i}`);
       if (field3 && isDecimal(field3.type)) {
         const scale = field3.type.scale;
@@ -9091,12 +9158,17 @@ function extractArgMap(cfg, args) {
       } else if (typeof v === "bigint") {
         v = Number(v);
       }
-      out[constNames[i]] = v;
     } catch {
       const def = cfg.argDefaults?.[constNames[i]];
       if (def !== undefined)
         out[constNames[i]] = def;
+      continue;
+    }
+    const constraints = cfg.argConstraints?.[constNames[i]];
+    if (constraints !== undefined) {
+      validateConstConstraints(constNames[i], constraints, v);
     }
+    out[constNames[i]] = v;
   }
   if (cfg.argDefaults) {
     for (const [name, def] of Object.entries(cfg.argDefaults)) {
@@ -10996,4 +11068,4 @@ export {
   ArgumentValidationError
 };
 
-//# debugId=B8E8A46EBC37A19064756E2164756E21
+//# debugId=606DBE277F7C8D1D64756E2164756E21