@agnt5/sdk 0.2.1

package/dist/schema-utils.js

@@ -0,0 +1,444 @@
+/**
+ * Schema conversion utilities for structured output support.
+ *
+ * This module provides utilities to convert TypeScript schemas (Zod, TypeBox, or manual)
+ * to JSON Schema format for LLM structured output generation, function signatures,
+ * and tool definitions.
+ */
+/**
+ * Auto-detect format type and convert to JSON schema.
+ *
+ * @param schema - Zod schema, TypeBox schema, or JSON schema object
+ * @param options - Conversion options
+ * @returns Tuple of [format_type, json_schema]
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { detectFormatType } from '@agnt5/sdk';
+ *
+ * const UserSchema = z.object({
+ *   name: z.string(),
+ *   age: z.number(),
+ * });
+ *
+ * const [format, schema] = detectFormatType(UserSchema);
+ * // format: 'zod'
+ * // schema: { type: 'object', properties: { ... }, required: ['name', 'age'] }
+ * ```
+ */
+export function detectFormatType(schema, options = {}) {
+    // Check for Zod schema
+    if (isZodSchema(schema)) {
+        return ['zod', zodToJsonSchema(schema, options)];
+    }
+    // Check for TypeBox schema
+    if (isTypeBoxSchema(schema)) {
+        return ['typebox', typeBoxToJsonSchema(schema, options)];
+    }
+    // Check for raw JSON schema
+    if (isJsonSchema(schema)) {
+        return ['raw', schema];
+    }
+    throw new Error(`Unsupported schema type. Expected Zod schema, TypeBox schema, or JSON Schema object.`);
+}
+/**
+ * Check if value is a Zod schema
+ */
+export function isZodSchema(value) {
+    // Zod schemas have a _def property
+    return value && typeof value === 'object' && '_def' in value && 'parse' in value;
+}
+/**
+ * Check if value is a TypeBox schema
+ */
+export function isTypeBoxSchema(value) {
+    // TypeBox schemas have [Kind] and [Symbol] properties
+    return value && typeof value === 'object' && ('$id' in value || 'kind' in value) && 'type' in value;
+}
+/**
+ * Check if value is a raw JSON schema
+ */
+export function isJsonSchema(value) {
+    return value && typeof value === 'object' && 'type' in value;
+}
+/**
+ * Convert Zod schema to JSON Schema.
+ *
+ * @param schema - Zod schema
+ * @param options - Conversion options
+ * @returns JSON Schema object
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * const schema = z.object({
+ *   name: z.string().describe('User name'),
+ *   age: z.number().int().positive(),
+ *   email: z.string().email().optional(),
+ * });
+ *
+ * const jsonSchema = zodToJsonSchema(schema);
+ * ```
+ */
+export function zodToJsonSchema(schema, options = {}) {
+    if (!isZodSchema(schema)) {
+        throw new Error('Expected Zod schema');
+    }
+    try {
+        // Try to use zod-to-json-schema library if available
+        const zodToJsonSchemaLib = tryRequire('zod-to-json-schema');
+        if (zodToJsonSchemaLib && zodToJsonSchemaLib.zodToJsonSchema) {
+            return zodToJsonSchemaLib.zodToJsonSchema(schema, {
+                target: 'openApi3',
+                strictUnions: true,
+            });
+        }
+        // Fallback: basic Zod schema conversion
+        return zodToJsonSchemaBasic(schema, options);
+    }
+    catch (error) {
+        throw new Error(`Failed to convert Zod schema to JSON Schema: ${error.message}`);
+    }
+}
+/**
+ * Basic Zod to JSON Schema conversion (fallback when zod-to-json-schema is not available)
+ */
+function zodToJsonSchemaBasic(schema, options = {}) {
+    const def = schema._def;
+    const typeName = def.typeName;
+    switch (typeName) {
+        case 'ZodString':
+            return { type: 'string', ...(def.description && options.includeDescriptions ? { description: def.description } : {}) };
+        case 'ZodNumber':
+            return { type: 'number', ...(def.description && options.includeDescriptions ? { description: def.description } : {}) };
+        case 'ZodBoolean':
+            return { type: 'boolean', ...(def.description && options.includeDescriptions ? { description: def.description } : {}) };
+        case 'ZodArray':
+            return {
+                type: 'array',
+                items: zodToJsonSchemaBasic(def.type, options),
+                ...(def.description && options.includeDescriptions ? { description: def.description } : {}),
+            };
+        case 'ZodObject': {
+            const properties = {};
+            const required = [];
+            const shape = def.shape();
+            for (const [key, value] of Object.entries(shape)) {
+                properties[key] = zodToJsonSchemaBasic(value, options);
+                // Check if field is required (not optional)
+                const fieldDef = value._def;
+                if (fieldDef.typeName !== 'ZodOptional') {
+                    required.push(key);
+                }
+            }
+            return {
+                type: 'object',
+                properties,
+                ...(required.length > 0 ? { required } : {}),
+                ...(options.strict ? { additionalProperties: false } : {}),
+                ...(def.description && options.includeDescriptions ? { description: def.description } : {}),
+            };
+        }
+        case 'ZodOptional':
+            return zodToJsonSchemaBasic(def.innerType, options);
+        case 'ZodNullable':
+            return {
+                anyOf: [zodToJsonSchemaBasic(def.innerType, options), { type: 'null' }],
+            };
+        case 'ZodEnum':
+            return {
+                type: 'string',
+                enum: def.values,
+                ...(def.description && options.includeDescriptions ? { description: def.description } : {}),
+            };
+        case 'ZodLiteral':
+            return { const: def.value };
+        case 'ZodUnion':
+            return {
+                anyOf: def.options.map((opt) => zodToJsonSchemaBasic(opt, options)),
+            };
+        default:
+            return { type: 'string', description: `Zod type: ${typeName}` };
+    }
+}
+/**
+ * Convert TypeBox schema to JSON Schema.
+ *
+ * TypeBox schemas are already JSON Schema compatible, so this is mostly a pass-through.
+ *
+ * @param schema - TypeBox schema
+ * @param options - Conversion options
+ * @returns JSON Schema object
+ *
+ * @example
+ * ```typescript
+ * import { Type } from '@sinclair/typebox';
+ *
+ * const schema = Type.Object({
+ *   name: Type.String(),
+ *   age: Type.Number(),
+ * });
+ *
+ * const jsonSchema = typeBoxToJsonSchema(schema);
+ * ```
+ */
+export function typeBoxToJsonSchema(schema, options = {}) {
+    if (!isTypeBoxSchema(schema)) {
+        throw new Error('Expected TypeBox schema');
+    }
+    // TypeBox schemas are already JSON Schema compatible
+    const jsonSchema = { ...schema };
+    // Apply options
+    if (options.strict && jsonSchema.type === 'object' && !('additionalProperties' in jsonSchema)) {
+        jsonSchema.additionalProperties = false;
+    }
+    return jsonSchema;
+}
+/**
+ * Try to require a module, return undefined if not available
+ */
+function tryRequire(moduleName) {
+    try {
+        // Dynamic import at runtime
+        return require(moduleName);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Convert basic TypeScript types to JSON Schema types.
+ *
+ * This is a utility for manual schema generation when you don't want to use Zod or TypeBox.
+ *
+ * @param typeName - TypeScript type name ('string', 'number', 'boolean', etc.)
+ * @param options - Additional schema options
+ * @returns JSON Schema type definition
+ *
+ * @example
+ * ```typescript
+ * const stringSchema = typeToSchema('string', { description: 'User name' });
+ * // { type: 'string', description: 'User name' }
+ *
+ * const arraySchema = typeToSchema('array', { items: { type: 'number' } });
+ * // { type: 'array', items: { type: 'number' } }
+ * ```
+ */
+export function typeToSchema(typeName, options = {}) {
+    return {
+        type: typeName,
+        ...options,
+    };
+}
+/**
+ * Create an object schema from property definitions.
+ *
+ * @param properties - Object property definitions
+ * @param required - Array of required property names
+ * @param options - Additional schema options
+ * @returns JSON Schema object definition
+ *
+ * @example
+ * ```typescript
+ * const userSchema = createObjectSchema({
+ *   name: { type: 'string', description: 'User name' },
+ *   age: { type: 'number', minimum: 0 },
+ *   email: { type: 'string', format: 'email' },
+ * }, ['name', 'age']);
+ * ```
+ */
+export function createObjectSchema(properties, required, options = {}) {
+    return {
+        type: 'object',
+        properties,
+        ...(required && required.length > 0 ? { required } : {}),
+        ...options,
+    };
+}
+/**
+ * Create an array schema with item type.
+ *
+ * @param items - Schema for array items
+ * @param options - Additional schema options
+ * @returns JSON Schema array definition
+ *
+ * @example
+ * ```typescript
+ * const numbersSchema = createArraySchema({ type: 'number' });
+ * const usersSchema = createArraySchema({
+ *   type: 'object',
+ *   properties: {
+ *     name: { type: 'string' },
+ *     age: { type: 'number' },
+ *   },
+ * });
+ * ```
+ */
+export function createArraySchema(items, options = {}) {
+    return {
+        type: 'array',
+        items,
+        ...options,
+    };
+}
+/**
+ * Create an enum schema.
+ *
+ * @param values - Allowed enum values
+ * @param options - Additional schema options
+ * @returns JSON Schema enum definition
+ *
+ * @example
+ * ```typescript
+ * const statusSchema = createEnumSchema(['pending', 'active', 'completed']);
+ * const roleSchema = createEnumSchema(['admin', 'user', 'guest'], {
+ *   description: 'User role',
+ * });
+ * ```
+ */
+export function createEnumSchema(values, options = {}) {
+    return {
+        type: typeof values[0],
+        enum: values,
+        ...options,
+    };
+}
+/**
+ * Create a union schema (anyOf).
+ *
+ * @param schemas - Array of possible schemas
+ * @param options - Additional schema options
+ * @returns JSON Schema union definition
+ *
+ * @example
+ * ```typescript
+ * const stringOrNumber = createUnionSchema([
+ *   { type: 'string' },
+ *   { type: 'number' },
+ * ]);
+ * ```
+ */
+export function createUnionSchema(schemas, options = {}) {
+    return {
+        anyOf: schemas,
+        ...options,
+    };
+}
+/**
+ * Make a schema optional (allows null).
+ *
+ * @param schema - Base schema
+ * @returns Schema that allows the base type or null
+ *
+ * @example
+ * ```typescript
+ * const optionalString = makeOptional({ type: 'string' });
+ * // { anyOf: [{ type: 'string' }, { type: 'null' }] }
+ * ```
+ */
+export function makeOptional(schema) {
+    return {
+        anyOf: [schema, { type: 'null' }],
+    };
+}
+/**
+ * Merge multiple schemas into one (allOf).
+ *
+ * @param schemas - Array of schemas to merge
+ * @returns Merged schema
+ *
+ * @example
+ * ```typescript
+ * const baseSchema = { type: 'object', properties: { id: { type: 'string' } } };
+ * const extraSchema = { properties: { name: { type: 'string' } } };
+ * const merged = mergeSchemas([baseSchema, extraSchema]);
+ * ```
+ */
+export function mergeSchemas(schemas) {
+    return {
+        allOf: schemas,
+    };
+}
+/**
+ * Validate a value against a JSON schema.
+ *
+ * This is a basic validator. For production use, consider using a dedicated library like Ajv.
+ *
+ * @param value - Value to validate
+ * @param schema - JSON Schema to validate against
+ * @returns True if valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const schema = { type: 'object', properties: { name: { type: 'string' } } };
+ * validateSchema({ name: 'Alice' }, schema); // true
+ * validateSchema({ name: 123 }, schema); // false
+ * ```
+ */
+export function validateSchema(value, schema) {
+    try {
+        // Try to use Ajv if available
+        const Ajv = tryRequire('ajv');
+        if (Ajv) {
+            const ajv = new Ajv();
+            const validate = ajv.compile(schema);
+            return validate(value);
+        }
+        // Fallback: basic type checking
+        return basicValidateSchema(value, schema);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Basic schema validation (fallback when Ajv is not available)
+ */
+function basicValidateSchema(value, schema) {
+    const { type } = schema;
+    switch (type) {
+        case 'string':
+            return typeof value === 'string';
+        case 'number':
+        case 'integer':
+            return typeof value === 'number';
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'array':
+            return Array.isArray(value);
+        case 'object':
+            return typeof value === 'object' && value !== null && !Array.isArray(value);
+        case 'null':
+            return value === null;
+        default:
+            return true; // Unknown type, pass validation
+    }
+}
+/**
+ * Extract description from JSDoc comment.
+ *
+ * @param func - Function to extract description from
+ * @returns Description string or undefined
+ *
+ * @example
+ * ```typescript
+ * /​**
+ *  * This is a greeting function
+ *  *​/
+ * function greet(name: string) { ... }
+ *
+ * extractFunctionDescription(greet); // 'This is a greeting function'
+ * ```
+ */
+export function extractFunctionDescription(func) {
+    // Try to extract from function toString (limited, but works in some cases)
+    const funcStr = func.toString();
+    const jsdocMatch = funcStr.match(/\/\*\*\s*\n?\s*\*\s*(.+?)\s*\n/);
+    if (jsdocMatch && jsdocMatch[1]) {
+        return jsdocMatch[1].trim();
+    }
+    return undefined;
+}
+//# sourceMappingURL=schema-utils.js.map

package/dist/schema-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-utils.js","sourceRoot":"","sources":["../src/schema-utils.ts"],"names":[],"mappings":"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"}

package/dist/scorer.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Scorer framework for evaluating component outputs.
+ *
+ * Provides a @scorer decorator, registry, built-in scorers, and
+ * a ScorerRequest/ScorerResult protocol matching the Python SDK.
+ */
+/** Scorer request containing output and optional expected value */
+export interface ScorerRequest {
+    /** Component output (required) */
+    output: any;
+    /** Expected output (optional) */
+    expected?: any;
+    /** Original input (optional) */
+    input?: any;
+    /** Trace events from execution (optional) */
+    trace?: TraceEvent[];
+    /** Scorer-specific configuration (optional) */
+    config?: Record<string, any>;
+}
+/** A trace event from component execution */
+export interface TraceEvent {
+    eventType: string;
+    eventId: string;
+    correlationId: string;
+    parentCorrelationId?: string;
+    timestampNs: number;
+    data: Record<string, any>;
+    name?: string;
+}
+/** Result of a scorer evaluation */
+export declare class ScorerResult {
+    /** Score between 0.0 and 1.0 */
+    readonly score: number;
+    /** Whether the evaluation passed */
+    readonly passed: boolean;
+    /** Human-readable label */
+    readonly label?: string;
+    /** Explanation of the scoring decision */
+    readonly explanation?: string;
+    /** Additional metadata */
+    readonly metadata?: Record<string, any>;
+    constructor(opts: {
+        score: number;
+        passed?: boolean;
+        label?: string;
+        explanation?: string;
+        metadata?: Record<string, any>;
+    });
+    /** Create a passing result */
+    static pass(explanation?: string): ScorerResult;
+    /** Create a failing result */
+    static fail(explanation?: string): ScorerResult;
+}
+/** Summary of a scorer result (used in EvalResponse) */
+export interface ScorerResultSummary {
+    scorer: string;
+    score: number;
+    passed: boolean;
+    explanation?: string;
+    label?: string;
+    metadata?: Record<string, any>;
+}
+/** Context provided to scorer functions */
+export interface ScorerContext {
+    runId: string;
+    correlationId: string;
+    parentCorrelationId?: string;
+    attempt: number;
+    log: (message: string, extra?: Record<string, any>) => void;
+}
+/** Scorer handler function signature */
+export type ScorerHandler = (ctx: ScorerContext, request: ScorerRequest) => ScorerResult | Promise<ScorerResult>;
+/** Configuration for a registered scorer */
+export interface ScorerConfig {
+    name: string;
+    handler: ScorerHandler;
+    description: string;
+    isAsync: boolean;
+    inputSchema?: Record<string, any>;
+}
+/**
+ * Decorator to register a function as a scorer.
+ *
+ * @example
+ * ```typescript
+ * const checkFormat = scorer('format_check', 'Checks output format')(
+ *   async (ctx, request) => {
+ *     const valid = typeof request.output === 'string';
+ *     return new ScorerResult({ score: valid ? 1 : 0, passed: valid });
+ *   }
+ * );
+ * ```
+ */
+export declare function scorer(name?: string, description?: string): <F extends ScorerHandler>(handler: F) => F;
+/** Check if a function is a scorer */
+export declare function isScorer(fn: any): boolean;
+/** Get scorer config from a decorated function */
+export declare function getScorerConfig(fn: any): ScorerConfig | undefined;
+/**
+ * Global registry for scorer components.
+ */
+export declare class ScorerRegistry {
+    private static _scorers;
+    static register(config: ScorerConfig): void;
+    static get(name: string): ScorerConfig | undefined;
+    static all(): Map<string, ScorerConfig>;
+    static listNames(): string[];
+    static clear(): void;
+}
+/** Exact match: output === expected */
+export declare function exactMatch(request: ScorerRequest): ScorerResult;
+/** Contains: output includes expected substring */
+export declare function contains(request: ScorerRequest): ScorerResult;
+/** JSON valid: output is valid JSON */
+export declare function jsonValid(request: ScorerRequest): ScorerResult;
+/** Regex match: output matches the expected regex pattern */
+export declare function regexMatch(request: ScorerRequest): ScorerResult;
+/** Levenshtein distance: normalized similarity score */
+export declare function levenshtein(request: ScorerRequest): ScorerResult;
+/**
+ * Run a scorer by name against a request.
+ */
+export declare function runScorer(scorerName: string, request: ScorerRequest, ctx?: ScorerContext): Promise<ScorerResult>;
+/** Helper methods for ScorerRequest */
+export declare function getRequestConfig(request: ScorerRequest, key: string, defaultValue?: any): any;
+/** Get trace events by type from a ScorerRequest */
+export declare function getTraceEvents(request: ScorerRequest, eventType: string): TraceEvent[];
+/** Get total tokens from trace events */
+export declare function getTotalTokens(request: ScorerRequest): number;
+//# sourceMappingURL=scorer.d.ts.map

package/dist/scorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scorer.d.ts","sourceRoot":"","sources":["../src/scorer.ts"],"names":[],"mappings":"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"}