@modelprofile.com/flexharness 10.14.0 → 10.15.0

package/ts/interfaces.ts

@@ -687,6 +687,9 @@ export const FLEX_TOOL_CATALOG_LIMITS = Object.freeze({
   maxDeclarationBytes: 16 * 1024,
   maxTags: 16,
   maxTagCharacters: 48,
+  maxAliases: 16,
+  maxAliasCharacters: 64,
+  maxVocabularyWords: 1024,
   maxExamples: 4,
   maxExampleBytes: 1024,
   maxSchemaBytes: 64 * 1024,
@@ -697,8 +700,16 @@ export const FLEX_TOOL_CATALOG_LIMITS = Object.freeze({
   maxDescribeTypes: 32,
   maxDescribeBytes: 64 * 1024,
   maxParamIssues: 10,
+  maxOutputTypeDepth: 32,
 });
 
+/**
+ * How many levels of named types a TypeScript declaration declares for a method's result by
+ * default: none. The result names its types, and `describe_tools({ types })` declares them on
+ * request, as a model needs them only to read fields of a result it has not seen.
+ */
+export const FLEX_TOOL_CATALOG_DEFAULT_OUTPUT_TYPE_DEPTH = 0;
+
 export interface IFlexCatalogSearchInput {
   /** Words to rank methods by. */
   query?: string;
@@ -788,10 +799,16 @@ export interface IFlexCatalogMethod<TScope = unknown, TParams = any, TResult = u
   method: string;
   /** One line of at most 120 characters, shown in search results. */
   summary: string;
-  /** The full description, shown with the declaration. */
+  /** The full description, shown with the declaration. An empty or blank one counts as absent. */
   description?: string;
   /** More words `search_tools` matches. */
   tags?: readonly string[];
+  /**
+   * Other names of the method, such as the one its users' language or a former API gives it:
+   * `search_tools` weighs them like the method's name, and ranks the method first for a query that
+   * names one.
+   */
+  aliases?: readonly string[];
   /** Code shown as `@example` in the declaration. */
   examples?: readonly string[];
   /** The parameter object's schema; `execute` validates every call against it. */
@@ -838,18 +855,34 @@ export interface IFlexCatalogProposalContext<TScope = unknown> {
 
 /** A named type that method declarations refer to; it needs a `declaration`, a `schema`, or both. */
 export interface IFlexCatalogType {
-  /** A JavaScript identifier such as `IMoney`. */
+  /**
+   * The type's name, such as `IMoney`, which `$ref`s to `#/$defs/<name>` use. A name that is no
+   * JavaScript identifier, such as `IEvent_order.created` as schema generators name instances of
+   * generics, is declared under an identifier made of it: each other character becomes `_`, and a
+   * reserved word or a leading digit is escaped with `_` (`IEvent_order_created`). Its declaration
+   * names the original, and `describe_tools` takes either.
+   */
   name: string;
+  /** An empty or blank description counts as absent. */
   description?: string;
   /** Validates parameters that refer to this type, and generates its declaration. */
   schema?: TFlexCatalogSchema;
-  /** Declaration text that replaces the generated one, such as `interface IMoney { … }`. */
+  /**
+   * Declaration text that replaces the generated one, such as `interface IMoney { … }`. It declares
+   * the identifier the type is declared under.
+   */
   declaration?: string;
 }
 
 export interface IFlexToolCatalog<TScope = unknown> {
   methods: readonly IFlexCatalogMethod<TScope>[];
   types?: readonly IFlexCatalogType[];
+  /**
+   * The words the catalog's users say for its own words, by the catalog's word:
+   * `{ voucher: ['Beleg', 'Belege'], 'gross amount': ['Bruttobetrag'] }`. A `search_tools` query that
+   * says every word of an alias searches for the catalog's words as well.
+   */
+  vocabulary?: Readonly<Record<string, readonly string[]>>;
   /**
    * Receives the calls `onCall` proposed, as one batch: the proposed call of an `execute`, or every
    * call a `run_code` program proposed, once the program finished. A failed program proposes
@@ -867,6 +900,20 @@ export interface IFlexToolCatalogOptions {
    * across the session, or `json-schema` with each method's self-contained JSON Schema.
    */
   declarations?: 'typescript' | 'json-schema';
+  /**
+   * How many levels of named types a TypeScript declaration declares for a method's result:
+   * `0` (the default) none, `1` the types the result names, each further level the types those
+   * name. A parameter's types are always declared in full, since a call has to match them. The
+   * declaration lists the types it names but does not declare; `describe_tools({ types })`
+   * declares them on request.
+   */
+  outputTypeDepth?: number;
+  /**
+   * `search_tools` follows its results with the declaration of the top match when one match
+   * clearly leads, so the model can call it without a `describe_tools` step: the only match, or one
+   * whose name or alias the query names that ranks 1.25 times higher than the next. Default `true`.
+   */
+  describeTopMatch?: boolean;
   /**
    * Adds `run_code`, which runs a short TypeScript or JavaScript program against the catalog in a
    * QuickJS sandbox. Needs the optional peers `quickjs-emscripten-core`,

package/ts/utils.harnessoptions.ts

@@ -3,6 +3,8 @@ import {
   FLEX_CODE_MODE_DEFAULT_LIMITS,
   FLEX_CODE_MODE_MAXIMUM_LIMITS,
   FLEX_REVERSION_DEFAULT_LIMITS,
+  FLEX_TOOL_CATALOG_DEFAULT_OUTPUT_TYPE_DEPTH,
+  FLEX_TOOL_CATALOG_LIMITS,
   FLEX_REVERSION_MAXIMUM_LIMITS,
 } from './interfaces.js';
 import type {
@@ -162,6 +164,8 @@ export function normalizeSubagents(
 
 export interface INormalizedToolCatalogOptions {
   readonly declarations: 'typescript' | 'json-schema';
+  readonly outputTypeDepth: number;
+  readonly describeTopMatch: boolean;
   /** The limits of `run_code`; absent while code mode is off. */
   readonly codeMode?: Readonly<IFlexCodeModeLimits>;
 }
@@ -175,16 +179,35 @@ const isPlainOptions = (value: unknown): value is Record<string, unknown> =>
 export function normalizeToolCatalogOptions(
   options: IFlexToolCatalogOptions | undefined,
 ): INormalizedToolCatalogOptions {
-  if (options === undefined) return Object.freeze({ declarations: 'typescript' });
+  if (options === undefined) {
+    return Object.freeze({
+      declarations: 'typescript',
+      outputTypeDepth: FLEX_TOOL_CATALOG_DEFAULT_OUTPUT_TYPE_DEPTH,
+      describeTopMatch: true,
+    });
+  }
   if (!isPlainOptions(options)) throw new FlexHarnessValidationError('toolCatalog must be a plain object.');
-  const unsupported = Object.keys(options).find((key) => key !== 'declarations' && key !== 'codeMode');
+  const unsupported = Object.keys(options).find(
+    (key) => !['declarations', 'outputTypeDepth', 'describeTopMatch', 'codeMode'].includes(key),
+  );
   if (unsupported) throw new FlexHarnessValidationError(`toolCatalog does not support "${unsupported}".`);
   const declarations = options.declarations ?? 'typescript';
   if (declarations !== 'typescript' && declarations !== 'json-schema') {
     throw new FlexHarnessValidationError('toolCatalog.declarations must be "typescript" or "json-schema".');
   }
+  const outputTypeDepth: unknown = options.outputTypeDepth ?? FLEX_TOOL_CATALOG_DEFAULT_OUTPUT_TYPE_DEPTH;
+  if (
+    typeof outputTypeDepth !== 'number' || !Number.isSafeInteger(outputTypeDepth)
+    || outputTypeDepth < 0 || outputTypeDepth > FLEX_TOOL_CATALOG_LIMITS.maxOutputTypeDepth
+  ) {
+    throw new FlexHarnessValidationError(
+      `toolCatalog.outputTypeDepth must be an integer from 0 through ${FLEX_TOOL_CATALOG_LIMITS.maxOutputTypeDepth}.`,
+    );
+  }
+  const describeTopMatch = options.describeTopMatch ?? true;
+  if (typeof describeTopMatch !== 'boolean') throw new FlexHarnessValidationError('toolCatalog.describeTopMatch must be a boolean.');
   const codeMode = normalizeCodeModeLimits(options.codeMode);
-  return Object.freeze({ declarations, ...(codeMode ? { codeMode } : {}) });
+  return Object.freeze({ declarations, outputTypeDepth, describeTopMatch, ...(codeMode ? { codeMode } : {}) });
 }
 
 function normalizeCodeModeLimits(codeMode: unknown): Readonly<IFlexCodeModeLimits> | undefined {