@zmdb/ai 1.0.0-beta.1

package/src/http/types.ts

@@ -0,0 +1,83 @@
+// Public contracts shared by the @zmdb/ai compiler and HTTP entry points.
+import type { ToolSpec } from '../index.js';
+
+export type ToolProvider = 'openai' | 'openai-strict' | 'anthropic' | 'gemini' | 'json-schema';
+
+export interface ToolSpecRefusal {
+  readonly provider: ToolProvider;
+  readonly path: string;
+  readonly construct: string;
+  readonly reason: string;
+  readonly suggestion: string;
+}
+
+export class ToolSpecRefusalError extends Error {
+  readonly refusal: ToolSpecRefusal;
+
+  constructor(refusal: ToolSpecRefusal) {
+    super(
+      `Tool input ${refusal.path || '<root>'} cannot become a ${refusal.provider} tool: ` +
+        `${refusal.reason} (${refusal.construct}). ${refusal.suggestion}`,
+    );
+    this.name = 'ToolSpecRefusalError';
+    this.refusal = refusal;
+  }
+}
+
+export interface OpenApiOperationIdentity {
+  readonly method: string;
+  readonly path: string;
+  readonly operationId: string;
+}
+
+export interface OpenApiToolsOptions {
+  readonly provider?: ToolProvider;
+  readonly include?: (operation: OpenApiOperationIdentity) => boolean;
+}
+
+export interface OpenApiToolRequest {
+  readonly method: string;
+  readonly path: string;
+  readonly pathParameters: readonly string[];
+  readonly queryParameters: readonly string[];
+  readonly bodyParameters: readonly string[];
+  readonly hasBody: boolean;
+}
+
+/**
+ * One checked-in generated tool. `validate` is intentionally a normal
+ * `assert<T>` call in generated source: the existing AOT transform compiles it
+ * from TypeScript's IR, so this path does not grow a second validator engine.
+ */
+export interface OpenApiGeneratedTool<T> {
+  readonly spec: ToolSpec;
+  readonly request: OpenApiToolRequest;
+  readonly validate: (input: unknown) => T;
+}
+
+export interface OpenApiCallerOptions {
+  readonly baseUrl: string;
+  readonly allowedBaseUrls: readonly string[];
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly timeoutMs?: number;
+  readonly maxResponseBytes?: number;
+  readonly fetch?: typeof globalThis.fetch;
+}
+
+export interface BoundOpenApiTool<T> {
+  readonly spec: ToolSpec;
+  readonly validate: (input: unknown) => T;
+  readonly handler: (input: T) => Promise<unknown>;
+}
+
+export class OpenApiHttpError extends Error {
+  readonly status: number;
+  readonly body: string;
+
+  constructor(status: number, body: string) {
+    super(`OpenAPI tool request failed with HTTP ${status}: ${body}`);
+    this.name = 'OpenApiHttpError';
+    this.status = status;
+    this.body = body;
+  }
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+import { type CoreSchema } from '@zmdb/schema';
+
+import { toolFor, type ToolOptions, type ToolSpec } from './providers.js';
+
+export function toolFromSchema(name: string, schema: CoreSchema<string>, opts?: ToolOptions): ToolSpec {
+  return toolFor('json-schema', name, schema, opts);
+}
+
+export interface ParseResult<T> {
+  success: boolean;
+  data?: T;
+  errors?: readonly string[];
+}
+
+export function lenientParse<T = unknown>(text: string, coerce?: (v: unknown) => T): ParseResult<T> {
+  // strip a leading/trailing markdown code fence (```json … ```)
+  const stripped = text
+    .trim()
+    .replace(/^```(?:json)?\s*/i, '')
+    .replace(/\s*```$/, '')
+    .trim();
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stripped);
+  } catch (err) {
+    return { success: false, errors: [err instanceof Error ? err.message : 'invalid JSON'] };
+  }
+  // boundary: with no `coerce` there is nothing to check the payload against —
+  // `T` is the caller's claim about the model's output, exactly as with
+  // `JSON.parse`. Pass a `coerce` (or run the AOT validator) to make it proven.
+  if (!coerce) return { success: true, data: parsed as T };
+  try {
+    return { success: true, data: coerce(parsed) };
+  } catch (err) {
+    return { success: false, errors: [err instanceof Error ? err.message : 'coercion failed'] };
+  }
+}
+
+export { toolFor };
+export type { ToolOptions, ToolProvider, ToolSchema, ToolSpec, ToolSpecFor } from './providers.js';

package/src/providers.ts

@@ -0,0 +1,443 @@
+import { type CoreSchema } from '@zmdb/schema';
+import {
+  jsonSchemaForColumn,
+  jsonSchemaFromShape,
+  shapeOfVariant,
+  type JsonSchemaObject,
+  type ShapeIR,
+} from '@zmdb/schema/ir';
+
+import { ToolSpecRefusalError, type ToolProvider, type ToolSpecRefusal } from './http/types.js';
+
+export type { ToolProvider, ToolSpecRefusal };
+export { ToolSpecRefusalError };
+
+export interface ToolOptions {
+  readonly description?: string;
+}
+
+export type ToolSchema = CoreSchema<string>;
+
+export interface ToolSpec {
+  readonly name: string;
+  readonly description?: string;
+  readonly parameters: JsonSchemaObject;
+}
+
+export interface StrictJsonSchemaObject extends JsonSchemaObject {
+  readonly additionalProperties: false;
+}
+
+export interface GeminiSchemaObject extends JsonSchemaObject {}
+
+export interface ToolSpecFor {
+  readonly openai: {
+    readonly type: 'function';
+    readonly function: {
+      readonly name: string;
+      readonly description?: string;
+      readonly parameters: JsonSchemaObject;
+    };
+  };
+  readonly 'openai-strict': {
+    readonly type: 'function';
+    readonly function: {
+      readonly name: string;
+      readonly description?: string;
+      readonly strict: true;
+      readonly parameters: StrictJsonSchemaObject;
+    };
+  };
+  readonly anthropic: {
+    readonly name: string;
+    readonly description?: string;
+    readonly input_schema: JsonSchemaObject;
+  };
+  readonly gemini: {
+    readonly name: string;
+    readonly description?: string;
+    readonly parameters: GeminiSchemaObject;
+  };
+  readonly 'json-schema': ToolSpec;
+}
+
+export interface ToolDialect {
+  readonly allowedKeywords: ReadonlySet<string>;
+  readonly maxProperties?: number;
+  readonly source: string;
+  readonly verifiedOn: '2026-09-04';
+}
+
+const COMMON_KEYWORDS = [
+  'type',
+  'format',
+  'enum',
+  'const',
+  'minimum',
+  'maximum',
+  'minLength',
+  'maxLength',
+  'pattern',
+  'items',
+  'minItems',
+  'maxItems',
+  'properties',
+  'required',
+  'anyOf',
+  'additionalProperties',
+] as const;
+
+/**
+ * Provider constraints are data rather than branches scattered through the emitter.
+ *
+ * The cap is deliberately below every provider's moving request-size ceiling. It is a
+ * build-time guard against producing a tool definition large enough to be rejected after
+ * deployment, not a promise that a provider will accept every document below it.
+ */
+export const TOOL_DIALECTS: Readonly<Record<ToolProvider, ToolDialect>> = {
+  openai: {
+    allowedKeywords: new Set<string>(COMMON_KEYWORDS),
+    maxProperties: 1_024,
+    source: 'https://platform.openai.com/docs/guides/structured-outputs',
+    verifiedOn: '2026-09-04',
+  },
+  'openai-strict': {
+    allowedKeywords: new Set<string>(COMMON_KEYWORDS),
+    maxProperties: 1_024,
+    source: 'https://platform.openai.com/docs/guides/structured-outputs',
+    verifiedOn: '2026-09-04',
+  },
+  anthropic: {
+    allowedKeywords: new Set<string>(COMMON_KEYWORDS),
+    maxProperties: 1_024,
+    source: 'https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use',
+    verifiedOn: '2026-09-04',
+  },
+  gemini: {
+    allowedKeywords: new Set<string>([...COMMON_KEYWORDS, 'nullable']),
+    maxProperties: 1_024,
+    source: 'https://ai.google.dev/api/caching#Schema',
+    verifiedOn: '2026-09-04',
+  },
+  'json-schema': {
+    allowedKeywords: new Set<string>(COMMON_KEYWORDS),
+    source: 'https://json-schema.org/draft/2020-12/json-schema-core.html',
+    verifiedOn: '2026-09-04',
+  },
+};
+
+type AnyToolSpec = ToolSpecFor[ToolProvider];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isToolSchema(value: unknown): value is ToolSchema {
+  if (!isRecord(value)) return false;
+  const ir = value['ir'];
+  return isRecord(ir) && Array.isArray(ir['columns']);
+}
+
+function descriptionPart(description: string | undefined): { readonly description: string } | object {
+  return description ? { description } : {};
+}
+
+function refusal(provider: ToolProvider, path: string, construct: string, reason: string, suggestion: string): never {
+  throw new ToolSpecRefusalError({ provider, path, construct, reason, suggestion });
+}
+
+function joinPath(parent: string, child: string): string {
+  return parent.length === 0 ? child : `${parent}.${child}`;
+}
+
+function nullableType(value: unknown): unknown {
+  if (typeof value === 'string') return value === 'null' ? value : [value, 'null'];
+  if (!Array.isArray(value)) return value;
+  return value.includes('null') ? [...value] : [...value, 'null'];
+}
+
+function requiredNames(value: Record<string, unknown>): ReadonlySet<string> {
+  const required = value['required'];
+  if (!Array.isArray(required)) return new Set();
+  return new Set(required.filter(name => typeof name === 'string'));
+}
+
+function propertiesOf(value: Record<string, unknown>): Record<string, unknown> | undefined {
+  const properties = value['properties'];
+  return isRecord(properties) ? properties : undefined;
+}
+
+function translateNode(
+  provider: 'openai-strict' | 'gemini',
+  value: Record<string, unknown>,
+  path: string,
+  optional: boolean,
+): Record<string, unknown> {
+  if (Object.keys(value).length === 0) {
+    refusal(
+      provider,
+      path,
+      'untyped json',
+      'the provider requires a type for every tool property, but this column emits no type',
+      'declare the payload with WireAs<W>, or omit the column from the tool',
+    );
+  }
+
+  const dialect = TOOL_DIALECTS[provider];
+  for (const keyword of Object.keys(value)) {
+    if (!dialect.allowedKeywords.has(keyword)) {
+      refusal(
+        provider,
+        path,
+        `unsupported keyword ${keyword}`,
+        `${provider} cannot express the emitted ${keyword} keyword without changing its meaning`,
+        'declare a provider-compatible wire shape, or omit the column from the tool',
+      );
+    }
+  }
+
+  const result: Record<string, unknown> = {};
+  const nested = propertiesOf(value);
+  const nestedRequired = requiredNames(value);
+
+  for (const [keyword, raw] of Object.entries(value)) {
+    if (provider === 'openai-strict' && keyword === 'format' && raw === 'int64') continue;
+
+    if (keyword === 'properties' && nested !== undefined) {
+      const properties: Record<string, unknown> = {};
+      for (const name of Object.keys(nested).toSorted()) {
+        const child = nested[name];
+        if (!isRecord(child)) {
+          refusal(
+            provider,
+            joinPath(path, name),
+            'non-object property schema',
+            'the emitted property schema is not an object',
+            'declare the property with a JSON-Schema-compatible wire type',
+          );
+        }
+        properties[name] = translateNode(provider, child, joinPath(path, name), !nestedRequired.has(name));
+      }
+      result[keyword] = properties;
+      continue;
+    }
+
+    if (keyword === 'items' && isRecord(raw)) {
+      result[keyword] = translateNode(provider, raw, `${path}[]`, false);
+      continue;
+    }
+
+    if (keyword === 'anyOf' && Array.isArray(raw)) {
+      result[keyword] = raw.map((member, index) => {
+        if (!isRecord(member)) {
+          refusal(
+            provider,
+            `${path}|${String(index)}`,
+            'non-object union member',
+            'the emitted union member is not a schema object',
+            'declare every union member with a provider-compatible wire type',
+          );
+        }
+        return translateNode(provider, member, `${path}|${String(index)}`, false);
+      });
+      continue;
+    }
+
+    if (keyword === 'required' && nested !== undefined && provider === 'openai-strict') {
+      result[keyword] = Object.keys(nested).toSorted();
+      continue;
+    }
+
+    if (keyword === 'type' && provider === 'gemini' && Array.isArray(raw)) {
+      const nonNull = raw.filter(item => item !== 'null');
+      if (nonNull.length !== 1 || !raw.includes('null')) {
+        refusal(
+          provider,
+          path,
+          'type union',
+          'Gemini cannot express this type array without changing the accepted values',
+          'declare a single nullable wire type, or omit the column from the tool',
+        );
+      }
+      result[keyword] = nonNull[0];
+      result['nullable'] = true;
+      continue;
+    }
+
+    result[keyword] = raw;
+  }
+
+  if (provider === 'openai-strict') {
+    if (optional) result['type'] = nullableType(result['type']);
+    if (nested !== undefined) result['additionalProperties'] = false;
+  }
+  return result;
+}
+
+function visibleShape(shape: ShapeIR): ShapeIR {
+  return shape
+    .filter(entry => !entry.column.sensitive)
+    .toSorted((left, right) => left.column.name.localeCompare(right.column.name));
+}
+
+function propertyCount(value: unknown): number {
+  if (Array.isArray(value)) return value.reduce((total, item) => total + propertyCount(item), 0);
+  if (!isRecord(value)) return 0;
+  const properties = propertiesOf(value);
+  let count = properties === undefined ? 0 : Object.keys(properties).length;
+  for (const item of Object.values(value)) count += propertyCount(item);
+  return count;
+}
+
+function enforceShape(provider: ToolProvider, shape: ShapeIR, document: JsonSchemaObject): void {
+  if (shape.length === 0 && provider !== 'json-schema') {
+    refusal(
+      provider,
+      '',
+      'empty create schema',
+      'the create variant has no visible properties',
+      'drop the tool, or unmark a Sensitive column that the model is allowed to supply',
+    );
+  }
+  const maximum = TOOL_DIALECTS[provider].maxProperties;
+  const count = propertyCount(document);
+  if (maximum !== undefined && count > maximum) {
+    refusal(
+      provider,
+      '',
+      `property limit ${String(maximum)}`,
+      `the tool contains ${String(count)} properties, above the provider cap of ${String(maximum)}`,
+      'split the operation into smaller tools',
+    );
+  }
+}
+
+/**
+ * The provider's parameter document, directly from the declaration IR.
+ *
+ * This is exported for the AOT emitter. Applications should call {@link toolFor}; exposing
+ * the pure step keeps runtime and build-time output byte-identical without a second walker.
+ */
+export function toolSchemaForProvider(provider: ToolProvider, shape: ShapeIR): JsonSchemaObject {
+  const visible = visibleShape(shape);
+  const generic = jsonSchemaFromShape(visible);
+  enforceShape(provider, visible, generic);
+
+  if (provider !== 'openai-strict' && provider !== 'gemini') return generic;
+
+  const properties: Record<string, unknown> = {};
+  for (const { column, optional } of visible) {
+    properties[column.name] = translateNode(provider, jsonSchemaForColumn(column), column.name, optional);
+  }
+
+  if (provider === 'openai-strict') {
+    const strict: StrictJsonSchemaObject = {
+      type: 'object',
+      properties,
+      required: visible.map(entry => entry.column.name),
+      additionalProperties: false,
+    };
+    return strict;
+  }
+
+  return {
+    type: 'object',
+    properties,
+    required: generic.required,
+  };
+}
+
+export function frameTool(
+  provider: ToolProvider,
+  name: string,
+  parameters: JsonSchemaObject,
+  options: ToolOptions = {},
+): AnyToolSpec {
+  const described = descriptionPart(options.description);
+  switch (provider) {
+    case 'openai':
+      return { type: 'function', function: { name, ...described, parameters } };
+    case 'openai-strict':
+      return {
+        type: 'function',
+        function: {
+          name,
+          ...described,
+          strict: true,
+          parameters: {
+            ...parameters,
+            additionalProperties: false,
+          },
+        },
+      };
+    case 'anthropic':
+      return { name, ...described, input_schema: parameters };
+    case 'gemini':
+      return { name, ...described, parameters };
+    case 'json-schema':
+      return { name, ...described, parameters };
+  }
+}
+
+export function toolFor<_T>(provider: 'openai', name: string, options?: ToolOptions): ToolSpecFor['openai'];
+export function toolFor<_T>(
+  provider: 'openai-strict',
+  name: string,
+  options?: ToolOptions,
+): ToolSpecFor['openai-strict'];
+export function toolFor<_T>(provider: 'anthropic', name: string, options?: ToolOptions): ToolSpecFor['anthropic'];
+export function toolFor<_T>(provider: 'gemini', name: string, options?: ToolOptions): ToolSpecFor['gemini'];
+export function toolFor<_T>(provider: 'json-schema', name: string, options?: ToolOptions): ToolSpecFor['json-schema'];
+export function toolFor<_T, P extends ToolProvider>(provider: P, name: string, options?: ToolOptions): ToolSpecFor[P];
+export function toolFor(
+  provider: 'openai',
+  name: string,
+  schema: ToolSchema,
+  options?: ToolOptions,
+): ToolSpecFor['openai'];
+export function toolFor(
+  provider: 'openai-strict',
+  name: string,
+  schema: ToolSchema,
+  options?: ToolOptions,
+): ToolSpecFor['openai-strict'];
+export function toolFor(
+  provider: 'anthropic',
+  name: string,
+  schema: ToolSchema,
+  options?: ToolOptions,
+): ToolSpecFor['anthropic'];
+export function toolFor(
+  provider: 'gemini',
+  name: string,
+  schema: ToolSchema,
+  options?: ToolOptions,
+): ToolSpecFor['gemini'];
+export function toolFor(
+  provider: 'json-schema',
+  name: string,
+  schema: ToolSchema,
+  options?: ToolOptions,
+): ToolSpecFor['json-schema'];
+export function toolFor<P extends ToolProvider>(
+  provider: P,
+  name: string,
+  schema: ToolSchema,
+  options?: ToolOptions,
+): ToolSpecFor[P];
+export function toolFor(
+  provider: ToolProvider,
+  name: string,
+  schemaOrOptions?: ToolSchema | ToolOptions,
+  options: ToolOptions = {},
+): AnyToolSpec {
+  if (!isToolSchema(schemaOrOptions)) {
+    throw new Error(
+      'toolFor<T>() was not replaced at build time. It is compiled away by @zmdb/compiler ' +
+        '(the unplugin, Metro adapter, or project compiler), which did not run over this file — a type argument cannot ' +
+        'be read at runtime, so there is nothing to fall back to.',
+    );
+  }
+  const parameters = toolSchemaForProvider(provider, shapeOfVariant(schemaOrOptions.ir, 'create'));
+  return frameTool(provider, name, parameters, options);
+}

package/src/tool-runtime.ts

@@ -0,0 +1,91 @@
+import { validationIssuesOf, type ValidationIssue } from '@zmdb/validator';
+
+export interface InvocableTool<T> {
+  readonly validate: (args: unknown) => T;
+  readonly handler: (input: T, identity?: unknown) => unknown | PromiseLike<unknown>;
+}
+
+export type ToolInvocation =
+  | { readonly kind: 'success'; readonly content: string }
+  | { readonly kind: 'validation-error'; readonly error: unknown; readonly content?: string }
+  | { readonly kind: 'handler-error'; readonly error: unknown };
+
+export interface ToolAdapterOptions<T, Output = unknown> {
+  readonly description: string;
+  /**
+   * Validate the model-shaped value and return the decoded application value.
+   *
+   * This function belongs at the call site so an AOT validator can be inlined
+   * there. Custom wire codecs can decode in the same function before the
+   * handler receives the value.
+   */
+  readonly validate: (value: unknown) => T;
+  readonly execute: (input: T) => Output | PromiseLike<Output>;
+}
+
+export const serialiseToolResult = (result: unknown): string => {
+  if (typeof result === 'string') return result;
+  const serialised = JSON.stringify(result);
+  return serialised ?? 'undefined';
+};
+
+const validationErrorContent = (error: unknown): string | undefined => {
+  const issues = validationIssuesOf(error);
+  if (issues === undefined) return undefined;
+  return JSON.stringify(
+    issues.map(issue =>
+      issue.expected === undefined
+        ? { path: issue.path, message: issue.message }
+        : { path: issue.path, message: issue.message, expected: issue.expected },
+    ),
+  );
+};
+
+export async function invokeTool<T>(
+  entry: InvocableTool<T>,
+  args: unknown,
+  identity?: unknown,
+): Promise<ToolInvocation> {
+  let input: T;
+  try {
+    input = entry.validate(args);
+  } catch (error) {
+    const content = validationErrorContent(error);
+    return content === undefined ? { kind: 'validation-error', error } : { kind: 'validation-error', error, content };
+  }
+
+  try {
+    return { kind: 'success', content: serialiseToolResult(await entry.handler(input, identity)) };
+  } catch (error) {
+    return { kind: 'handler-error', error };
+  }
+}
+
+const validationLine = (issue: ValidationIssue): string =>
+  issue.expected === undefined ? `${issue.path}: ${issue.message}` : `${issue.path}: expected ${issue.expected}`;
+
+const validationFailure = (name: string, issues: readonly ValidationIssue[]): string => {
+  const details = issues.length === 0 ? 'validation failed without details' : issues.map(validationLine).join('\n');
+  return `Tool "${name}" rejected its arguments:\n${details}`;
+};
+
+/**
+ * A malformed model call is returned to the model so it can correct the next
+ * turn. Errors without a valid issue list, including handler failures, are
+ * application failures and remain thrown.
+ */
+export async function executeToolAdapter<T, Output>(
+  name: string,
+  value: unknown,
+  options: ToolAdapterOptions<T, Output>,
+): Promise<Awaited<Output> | string> {
+  let input: T;
+  try {
+    input = options.validate(value);
+  } catch (error) {
+    const issues = validationIssuesOf(error);
+    if (issues === undefined) throw error;
+    return validationFailure(name, issues);
+  }
+  return await options.execute(input);
+}