@providerprotocol/ai 0.0.38 → 0.0.39

package/dist/tool-D22EhP5F.d.ts

@@ -0,0 +1,507 @@
+/**
+ * @fileoverview JSON Schema types for tool parameters and structured outputs.
+ *
+ * Provides TypeScript interfaces for defining JSON Schema objects used in
+ * LLM tool definitions and structured output specifications.
+ *
+ * @module types/schema
+ */
+/**
+ * Primitive and composite JSON Schema property types.
+ *
+ * These types correspond to the JSON Schema specification's allowed type values.
+ */
+type JSONSchemaPropertyType = 
+/** String values */
+'string'
+/** Floating point numbers */
+ | 'number'
+/** Whole numbers */
+ | 'integer'
+/** Boolean true/false values */
+ | 'boolean'
+/** Ordered lists of values */
+ | 'array'
+/** Key-value mappings */
+ | 'object'
+/** Explicit null value */
+ | 'null';
+/**
+ * JSON Schema property definition.
+ *
+ * Describes a single property within a JSON Schema object, including
+ * type constraints, validation rules, and nested structure definitions.
+ *
+ * @example
+ * ```typescript
+ * const nameProperty: JSONSchemaProperty = {
+ *   type: 'string',
+ *   description: 'User name',
+ *   minLength: 1,
+ *   maxLength: 100
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const tagsProperty: JSONSchemaProperty = {
+ *   type: 'array',
+ *   description: 'List of tags',
+ *   items: { type: 'string' },
+ *   minItems: 1,
+ *   uniqueItems: true
+ * };
+ * ```
+ */
+interface JSONSchemaProperty {
+    /** The JSON type of this property */
+    type: JSONSchemaPropertyType;
+    /** Human-readable description for the LLM */
+    description?: string;
+    /** Allowed values (enumeration) */
+    enum?: unknown[];
+    /** Constant value this property must equal */
+    const?: unknown;
+    /** Default value if not provided */
+    default?: unknown;
+    /** Minimum string length (string type only) */
+    minLength?: number;
+    /** Maximum string length (string type only) */
+    maxLength?: number;
+    /** Regular expression pattern for validation (string type only) */
+    pattern?: string;
+    /** Semantic format hint (string type only) */
+    format?: 'email' | 'uri' | 'date' | 'date-time' | 'uuid';
+    /** Minimum value inclusive (number/integer types only) */
+    minimum?: number;
+    /** Maximum value inclusive (number/integer types only) */
+    maximum?: number;
+    /** Minimum value exclusive (number/integer types only) */
+    exclusiveMinimum?: number;
+    /** Maximum value exclusive (number/integer types only) */
+    exclusiveMaximum?: number;
+    /** Value must be divisible by this (number/integer types only) */
+    multipleOf?: number;
+    /** Schema for array elements (array type only) */
+    items?: JSONSchemaProperty;
+    /** Minimum array length (array type only) */
+    minItems?: number;
+    /** Maximum array length (array type only) */
+    maxItems?: number;
+    /** Whether array elements must be unique (array type only) */
+    uniqueItems?: boolean;
+    /** Nested property definitions (object type only) */
+    properties?: Record<string, JSONSchemaProperty>;
+    /** List of required property names (object type only) */
+    required?: string[];
+    /** Whether additional properties are allowed (object type only) */
+    additionalProperties?: boolean;
+}
+/**
+ * Root JSON Schema for tool parameters or structured outputs.
+ *
+ * This is the top-level schema definition used when defining tool
+ * parameters or requesting structured output from an LLM.
+ *
+ * @example
+ * ```typescript
+ * const weatherToolSchema: JSONSchema = {
+ *   type: 'object',
+ *   description: 'Parameters for getting weather information',
+ *   properties: {
+ *     location: {
+ *       type: 'string',
+ *       description: 'City name or coordinates'
+ *     },
+ *     units: {
+ *       type: 'string',
+ *       enum: ['celsius', 'fahrenheit'],
+ *       description: 'Temperature units'
+ *     }
+ *   },
+ *   required: ['location']
+ * };
+ * ```
+ */
+interface JSONSchema {
+    /** Root schemas are always objects */
+    type: 'object';
+    /** Property definitions for the object */
+    properties: Record<string, JSONSchemaProperty>;
+    /** List of required property names */
+    required?: string[];
+    /** Whether additional properties are allowed beyond those defined */
+    additionalProperties?: boolean;
+    /** Human-readable description of the schema's purpose */
+    description?: string;
+}
+/**
+ * Minimal interface for Zod v3 schema detection.
+ * Zod v3 schemas have a `_def` property containing schema definition.
+ */
+interface ZodV3Like {
+    _def: unknown;
+    parse: (data: unknown) => unknown;
+}
+/**
+ * Minimal interface for Zod v4 schema detection.
+ * Zod v4 schemas have a `_zod` property in addition to `_def`.
+ */
+interface ZodV4Like extends ZodV3Like {
+    _zod: unknown;
+}
+/**
+ * Union type representing any Zod-like schema.
+ * Allows accepting Zod schemas without requiring Zod as a direct dependency.
+ */
+type ZodLike = ZodV3Like | ZodV4Like;
+/**
+ * Structure input type that accepts either JSON Schema or Zod schemas.
+ *
+ * When a Zod schema is provided, it will be automatically converted
+ * to JSON Schema before being sent to the provider.
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * // Using Zod schema directly
+ * const model = llm({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   structure: z.object({
+ *     name: z.string(),
+ *     age: z.number(),
+ *   }),
+ * });
+ *
+ * // Using JSON Schema
+ * const model = llm({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   structure: {
+ *     type: 'object',
+ *     properties: {
+ *       name: { type: 'string' },
+ *       age: { type: 'number' },
+ *     },
+ *     required: ['name', 'age'],
+ *   },
+ * });
+ * ```
+ */
+type Structure = JSONSchema | ZodLike;
+
+/**
+ * @fileoverview Tool types for LLM function calling.
+ *
+ * Defines the interfaces for registering tools with LLMs, handling
+ * tool calls from the model, and managing tool execution strategies.
+ *
+ * @module types/tool
+ */
+
+/**
+ * Provider-namespaced metadata for tools.
+ *
+ * Each provider can attach its own metadata under its namespace,
+ * enabling provider-specific features like caching, strict mode, etc.
+ *
+ * @example
+ * ```typescript
+ * const metadata: ToolMetadata = {
+ *   anthropic: { cache_control: { type: 'ephemeral' } },
+ *   openrouter: { cache_control: { type: 'ephemeral', ttl: '1h' } }
+ * };
+ * ```
+ */
+interface ToolMetadata {
+    [provider: string]: Record<string, unknown> | undefined;
+}
+/**
+ * Tool call requested by the model.
+ *
+ * Represents a single function call request from the LLM, including
+ * the tool name and parsed arguments.
+ *
+ * @example
+ * ```typescript
+ * const toolCall: ToolCall = {
+ *   toolCallId: 'call_abc123',
+ *   toolName: 'get_weather',
+ *   arguments: { location: 'San Francisco', units: 'celsius' }
+ * };
+ * ```
+ */
+interface ToolCall {
+    /** Unique identifier for this tool call, used to match results */
+    toolCallId: string;
+    /** Name of the tool being called */
+    toolName: string;
+    /** Parsed arguments for the tool call */
+    arguments: Record<string, unknown>;
+}
+/**
+ * Result of tool execution.
+ *
+ * Returned after executing a tool, containing the result data
+ * and whether an error occurred.
+ *
+ * @example
+ * ```typescript
+ * const result: ToolResult = {
+ *   toolCallId: 'call_abc123',
+ *   result: { temperature: 72, conditions: 'sunny' }
+ * };
+ *
+ * // Error result
+ * const errorResult: ToolResult = {
+ *   toolCallId: 'call_abc123',
+ *   result: 'Location not found',
+ *   isError: true
+ * };
+ * ```
+ */
+interface ToolResult {
+    /** The tool call ID this result corresponds to */
+    toolCallId: string;
+    /** The result data (can be any serializable value) */
+    result: unknown;
+    /** Whether the tool execution resulted in an error */
+    isError?: boolean;
+}
+/**
+ * Tool definition for LLM function calling.
+ *
+ * Defines a tool that can be called by the LLM, including its
+ * name, description, parameter schema, and execution function.
+ *
+ * @typeParam TParams - The type of parameters the tool accepts
+ * @typeParam TResult - The type of result the tool returns
+ *
+ * @example
+ * ```typescript
+ * const weatherTool: Tool<{ location: string }, WeatherData> = {
+ *   name: 'get_weather',
+ *   description: 'Get current weather for a location',
+ *   parameters: {
+ *     type: 'object',
+ *     properties: {
+ *       location: { type: 'string', description: 'City name' }
+ *     },
+ *     required: ['location']
+ *   },
+ *   run: async (params) => {
+ *     return fetchWeather(params.location);
+ *   }
+ * };
+ * ```
+ */
+interface Tool<TParams = unknown, TResult = unknown> {
+    /** Tool name (must be unique within an llm() instance) */
+    name: string;
+    /** Human-readable description for the model to understand when to use this tool */
+    description: string;
+    /** JSON Schema defining the tool's parameters */
+    parameters: JSONSchema;
+    /**
+     * Provider-specific metadata, namespaced by provider name.
+     *
+     * Used for provider-specific features like prompt caching:
+     * @example
+     * ```typescript
+     * const tool: Tool = {
+     *   name: 'search_docs',
+     *   description: 'Search documentation',
+     *   parameters: {...},
+     *   run: async (params) => {...},
+     *   metadata: {
+     *     anthropic: { cache_control: { type: 'ephemeral' } }
+     *   }
+     * };
+     * ```
+     */
+    metadata?: ToolMetadata;
+    /**
+     * Executes the tool with the provided parameters.
+     *
+     * @param params - The parameters passed by the model
+     * @returns The tool result, synchronously or as a Promise
+     */
+    run(params: TParams): TResult | Promise<TResult>;
+    /**
+     * Optional approval handler for sensitive operations.
+     *
+     * If provided, this function is called before the tool executes.
+     * Return false to prevent execution.
+     *
+     * @param params - The parameters the tool would be called with
+     * @returns Whether to approve the execution
+     */
+    approval?(params: TParams): boolean | Promise<boolean>;
+}
+/**
+ * Tool input type that accepts Zod schemas for parameters.
+ *
+ * This is the user-facing type for defining tools. Zod schemas are
+ * automatically converted to JSON Schema before being sent to providers.
+ *
+ * @typeParam TParams - The type of parameters the tool accepts
+ * @typeParam TResult - The type of result the tool returns
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * const tool: ToolInput<{ location: string }> = {
+ *   name: 'get_weather',
+ *   description: 'Get weather for a location',
+ *   parameters: z.object({
+ *     location: z.string().describe('City name'),
+ *   }),
+ *   run: async (params) => fetchWeather(params.location),
+ * };
+ * ```
+ */
+interface ToolInput<TParams = unknown, TResult = unknown> {
+    /** Tool name (must be unique within an llm() instance) */
+    name: string;
+    /** Human-readable description for the model to understand when to use this tool */
+    description: string;
+    /** JSON Schema or Zod schema defining the tool's parameters */
+    parameters: Structure;
+    /** Provider-specific metadata, namespaced by provider name */
+    metadata?: ToolMetadata;
+    /** Executes the tool with the provided parameters */
+    run(params: TParams): TResult | Promise<TResult>;
+    /** Optional approval handler for sensitive operations */
+    approval?(params: TParams): boolean | Promise<boolean>;
+}
+/**
+ * Result from onBeforeCall hook indicating whether to proceed and optionally transformed params.
+ */
+interface BeforeCallResult {
+    /** Whether to proceed with tool execution */
+    proceed: boolean;
+    /** Transformed parameters to use instead of the original (optional) */
+    params?: unknown;
+}
+/**
+ * Result from onAfterCall hook optionally containing a transformed result.
+ */
+interface AfterCallResult {
+    /** Transformed result to use instead of the original */
+    result: unknown;
+}
+/**
+ * Strategy for controlling tool execution behavior.
+ *
+ * Provides hooks for monitoring, controlling, and transforming the tool execution
+ * loop during LLM inference.
+ *
+ * @example
+ * ```typescript
+ * const strategy: ToolUseStrategy = {
+ *   maxIterations: 5,
+ *   onToolCall: (tool, params) => {
+ *     console.log(`Calling ${tool.name} with`, params);
+ *   },
+ *   // Transform input parameters
+ *   onBeforeCall: (tool, params) => {
+ *     if (tool.name === 'search') {
+ *       return { proceed: true, params: { ...params, limit: 10 } };
+ *     }
+ *     return true;
+ *   },
+ *   // Transform output results
+ *   onAfterCall: (tool, params, result) => {
+ *     if (tool.name === 'fetch_data') {
+ *       return { result: sanitize(result) };
+ *     }
+ *   },
+ *   onMaxIterations: (iterations) => {
+ *     console.warn(`Reached max iterations: ${iterations}`);
+ *   }
+ * };
+ * ```
+ */
+interface ToolUseStrategy {
+    /** Maximum number of tool execution rounds (default: 10) */
+    maxIterations?: number;
+    /**
+     * Called when the model requests a tool call.
+     *
+     * @param tool - The tool being called
+     * @param params - The parameters for the call
+     */
+    onToolCall?(tool: Tool, params: unknown): void | Promise<void>;
+    /**
+     * Called before tool execution. Can skip execution or transform parameters.
+     *
+     * @param tool - The tool about to be executed
+     * @param params - The parameters for the call
+     * @returns One of:
+     *   - `false` to skip execution
+     *   - `true` to proceed with original params
+     *   - `BeforeCallResult` object to control execution and optionally transform params
+     */
+    onBeforeCall?(tool: Tool, params: unknown): boolean | BeforeCallResult | Promise<boolean | BeforeCallResult>;
+    /**
+     * Called after tool execution completes. Can transform the result.
+     *
+     * @param tool - The tool that was executed
+     * @param params - The parameters that were used
+     * @param result - The result from the tool
+     * @returns Void to use original result, or `AfterCallResult` to transform it
+     */
+    onAfterCall?(tool: Tool, params: unknown, result: unknown): void | AfterCallResult | Promise<void | AfterCallResult>;
+    /**
+     * Called when a tool execution throws an error.
+     *
+     * @param tool - The tool that failed
+     * @param params - The parameters that were used
+     * @param error - The error that was thrown
+     */
+    onError?(tool: Tool, params: unknown, error: Error): void | Promise<void>;
+    /**
+     * Called when the maximum iteration limit is reached.
+     *
+     * @param iterations - The number of iterations that were performed
+     */
+    onMaxIterations?(iterations: number): void | Promise<void>;
+}
+/**
+ * Record of a completed tool execution.
+ *
+ * Contains all information about a tool call that was executed,
+ * including timing and result data.
+ *
+ * @example
+ * ```typescript
+ * const execution: ToolExecution = {
+ *   toolName: 'get_weather',
+ *   toolCallId: 'call_abc123',
+ *   arguments: { location: 'San Francisco' },
+ *   result: { temperature: 72 },
+ *   isError: false,
+ *   duration: 150,
+ *   approved: true
+ * };
+ * ```
+ */
+interface ToolExecution {
+    /** Name of the tool that was called */
+    toolName: string;
+    /** Unique identifier for this tool call */
+    toolCallId: string;
+    /** Arguments that were passed to the tool */
+    arguments: Record<string, unknown>;
+    /** Result returned by the tool */
+    result: unknown;
+    /** Whether the tool execution resulted in an error */
+    isError: boolean;
+    /** Execution duration in milliseconds */
+    duration: number;
+    /** Whether approval was required and granted (undefined if no approval handler) */
+    approved?: boolean;
+}
+
+export type { AfterCallResult as A, BeforeCallResult as B, JSONSchema as J, Structure as S, ToolInput as T, ZodLike as Z, ZodV4Like as a, Tool as b, ToolCall as c, ToolResult as d, ToolExecution as e, ToolUseStrategy as f, JSONSchemaProperty as g, JSONSchemaPropertyType as h, ZodV3Like as i, ToolMetadata as j };

package/dist/{types-Cr4F0tVy.d.ts → types-CyXF0J7C.d.ts}

@@ -1,4 +1,4 @@
-import { S as StreamEvent } from './stream-sXhBtWjl.js';
+import { S as StreamEvent } from './stream-DVVUIKpz.js';
 
 /**
  * @fileoverview Pub-sub middleware types for stream resumption.
@@ -35,6 +35,12 @@ type CompletionCallback = () => void;
  * Unsubscribe function returned by subscribe.
  */
 type Unsubscribe = () => void;
+/**
+ * Final data callback when stream completes with data.
+ *
+ * @param data - The final data (typically serialized Turn)
+ */
+type FinalDataCallback = (data: unknown) => void;
 /**
  * Storage adapter interface for pub-sub middleware.
  *
@@ -57,12 +63,19 @@ interface PubSubAdapter {
     getEvents(streamId: string): Promise<StreamEvent[]>;
     /**
      * Subscribes to live events (creates lazily if needed).
+     *
+     * @param onFinalData - Optional callback for final data (Turn) before completion
      */
-    subscribe(streamId: string, onEvent: SubscriptionCallback, onComplete: CompletionCallback): Unsubscribe;
+    subscribe(streamId: string, onEvent: SubscriptionCallback, onComplete: CompletionCallback, onFinalData?: FinalDataCallback): Unsubscribe;
     /**
      * Publishes event to all subscribers.
      */
     publish(streamId: string, event: StreamEvent): void;
+    /**
+     * Sets final data to be sent to subscribers before completion.
+     * Typically used to send the serialized Turn.
+     */
+    setFinalData(streamId: string, data: unknown): void;
     /**
      * Notifies subscribers and removes stream from storage.
      */
@@ -93,4 +106,4 @@ interface MemoryAdapterOptions {
     maxStreams?: number;
 }
 
-export type { CompletionCallback as C, MemoryAdapterOptions as M, PubSubAdapter as P, StoredStream as S, Unsubscribe as U, PubSubOptions as a, SubscriptionCallback as b };
+export type { CompletionCallback as C, FinalDataCallback as F, MemoryAdapterOptions as M, PubSubAdapter as P, StoredStream as S, Unsubscribe as U, PubSubOptions as a, SubscriptionCallback as b };

package/dist/utils/index.d.ts

@@ -1,3 +1,5 @@
+import { Z as ZodLike, a as ZodV4Like, J as JSONSchema, T as ToolInput, b as Tool } from '../tool-D22EhP5F.js';
+
 /**
  * @fileoverview Partial JSON parser for streaming LLM responses.
  *
@@ -50,4 +52,66 @@ interface PartialParseResult<T = unknown> {
  */
 declare function parsePartialJson<T = unknown>(json: string): PartialParseResult<T>;
 
-export { type PartialParseResult, parsePartialJson };
+/**
+ * @fileoverview Zod schema utilities for structured output.
+ *
+ * Provides detection and conversion utilities for Zod schemas,
+ * supporting both Zod v3 and v4 schemas.
+ *
+ * @module utils/zod
+ */
+
+/**
+ * Checks if a value is a Zod schema (v3 or v4).
+ *
+ * @param value - Value to check
+ * @returns True if the value appears to be a Zod schema
+ */
+declare function isZodSchema(value: unknown): value is ZodLike;
+/**
+ * Checks if a Zod schema is v4 or later.
+ *
+ * @param schema - Zod schema to check
+ * @returns True if the schema is Zod v4+
+ */
+declare function isZodV4(schema: ZodLike): schema is ZodV4Like;
+/**
+ * Converts a Zod schema to JSON Schema.
+ *
+ * For Zod v4+, uses native `z.toJSONSchema()`.
+ * For Zod v3, uses `zod-to-json-schema` package.
+ *
+ * @param schema - Zod schema to convert
+ * @returns JSON Schema representation
+ * @throws Error if required dependencies are not installed
+ */
+declare function zodToJSONSchema(schema: ZodLike): Promise<JSONSchema>;
+/**
+ * Synchronous version of zodToJSONSchema.
+ * Requires modules to be cached via prior async load.
+ *
+ * @param schema - Zod schema to convert
+ * @returns JSON Schema representation
+ * @throws Error if modules not loaded or dependencies missing
+ */
+declare function zodToJSONSchemaSync(schema: ZodLike): JSONSchema;
+/**
+ * Resolves a structure parameter that may be JSONSchema or Zod schema.
+ * Validates that the result is an object schema.
+ *
+ * @param structure - JSONSchema or Zod schema (must be object type)
+ * @returns Resolved JSONSchema
+ * @throws Error if schema is not an object type
+ */
+declare function resolveStructure(structure: JSONSchema | ZodLike): JSONSchema;
+/**
+ * Resolves an array of tools, converting any Zod parameters to JSONSchema.
+ * Validates that each tool's parameters is an object schema.
+ *
+ * @param tools - Array of tools with Structure parameters
+ * @returns Array of tools with resolved JSONSchema parameters
+ * @throws Error if any tool parameters is not an object schema
+ */
+declare function resolveTools(tools: ToolInput[]): Tool[];
+
+export { type PartialParseResult, isZodSchema, isZodV4, parsePartialJson, resolveStructure, resolveTools, zodToJSONSchema, zodToJSONSchemaSync };

package/dist/utils/index.js

@@ -1,7 +1,21 @@
 import {
   parsePartialJson
 } from "../chunk-I53CI6ZZ.js";
+import {
+  isZodSchema,
+  isZodV4,
+  resolveStructure,
+  resolveTools,
+  zodToJSONSchema,
+  zodToJSONSchemaSync
+} from "../chunk-3Q5VELKG.js";
 export {
-  parsePartialJson
+  isZodSchema,
+  isZodV4,
+  parsePartialJson,
+  resolveStructure,
+  resolveTools,
+  zodToJSONSchema,
+  zodToJSONSchemaSync
 };
 //# sourceMappingURL=index.js.map

package/dist/xai/index.d.ts

@@ -1,5 +1,6 @@
-import { e as Provider } from '../llm-DS_-l71X.js';
-import '../stream-sXhBtWjl.js';
+import { e as Provider } from '../llm-CZqlijjK.js';
+import '../stream-DVVUIKpz.js';
+import '../tool-D22EhP5F.js';
 
 /**
  * xAI Chat Completions API parameters (OpenAI-compatible).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@providerprotocol/ai",
-  "version": "0.0.38",
+  "version": "0.0.39",
   "description": "UPP: Unified Provider Protocol for AI inference",
   "license": "MIT",
   "homepage": "https://providerprotocol.org",
@@ -184,10 +184,22 @@
     "eslint-plugin-import": "^2.32.0",
     "tsup": "^8.5.1",
     "typedoc": "^0.28.16",
-    "typedoc-plugin-markdown": "^4.9.0"
+    "typedoc-plugin-markdown": "^4.9.0",
+    "zod": "^4.3.6",
+    "zod-to-json-schema": "^3.25.1"
   },
   "peerDependencies": {
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "zod": "^3.23.0 || ^4.0.0",
+    "zod-to-json-schema": "^3.25.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    },
+    "zod-to-json-schema": {
+      "optional": true
+    }
   },
   "keywords": [
     "ai",