sis-tools 0.1.0

package/src/types.ts

@@ -0,0 +1,136 @@
+/**
+ * Type definitions for SIS
+ */
+
+export interface ToolParameter {
+  type: string;
+  description?: string;
+  required?: boolean;
+  default?: unknown;
+}
+
+export interface ToolParameters {
+  [key: string]: ToolParameter;
+}
+
+export interface ToolExample {
+  query: string;
+  input?: Record<string, unknown>;
+  output?: unknown;
+}
+
+export interface ToolMetadata {
+  version?: string;
+  author?: string;
+  tags?: string[];
+  priority?: number;
+  [key: string]: unknown;
+}
+
+export interface Tool {
+  name: string;
+  description: string;
+  parameters: ToolParameters;
+  returns?: Record<string, unknown>;
+  semanticHints: string[];
+  examples: ToolExample[];
+  handler?: ToolHandler;
+  metadata: ToolMetadata;
+  embedding?: number[];
+}
+
+export type ToolHandler = (
+  params: Record<string, unknown>
+) => unknown | Promise<unknown>;
+
+export interface ToolMatch {
+  tool: Tool;
+  score: number;
+}
+
+export interface ResolvedTool {
+  name: string;
+  schema: ToolSchema;
+  score: number;
+  handler?: ToolHandler;
+}
+
+export interface ToolSchema {
+  name: string;
+  description: string;
+  parameters: {
+    type: "object";
+    properties: Record<string, unknown>;
+    required: string[];
+  };
+}
+
+export interface OpenAIToolSchema {
+  type: "function";
+  function: ToolSchema;
+}
+
+export interface AnthropicToolSchema {
+  name: string;
+  description: string;
+  input_schema: {
+    type: "object";
+    properties: Record<string, unknown>;
+    required: string[];
+  };
+}
+
+/**
+ * Convert a Tool to its JSON schema representation
+ */
+export function toSchema(tool: Tool): ToolSchema {
+  const required = Object.entries(tool.parameters)
+    .filter(([, v]) => v.required !== false)
+    .map(([k]) => k);
+
+  return {
+    name: tool.name,
+    description: tool.description,
+    parameters: {
+      type: "object",
+      properties: tool.parameters,
+      required,
+    },
+  };
+}
+
+/**
+ * Convert a Tool to OpenAI function calling format
+ */
+export function toOpenAISchema(tool: Tool): OpenAIToolSchema {
+  return {
+    type: "function",
+    function: toSchema(tool),
+  };
+}
+
+/**
+ * Convert a Tool to Anthropic tool use format
+ */
+export function toAnthropicSchema(tool: Tool): AnthropicToolSchema {
+  const schema = toSchema(tool);
+  return {
+    name: schema.name,
+    description: schema.description,
+    input_schema: schema.parameters,
+  };
+}
+
+export interface RemoteToolSchema {
+  name: string;
+  schema: ToolSchema;
+  score: number;
+}
+
+export interface RemoteResolveResponse {
+  results: RemoteToolSchema[];
+}
+
+export interface RemoteListResponse {
+  tools: string[];
+}

package/src/validators.ts

@@ -0,0 +1,484 @@
+/**
+ * Validation system for SIS tools and parameters
+ */
+
+import type { Tool, ToolParameters } from "./types";
+
+/**
+ * Result of a validation operation
+ */
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+/**
+ * Create a validation result
+ */
+export function createValidationResult(
+  valid: boolean,
+  errors: string[] = [],
+  warnings: string[] = []
+): ValidationResult {
+  return { valid, errors, warnings };
+}
+
+/**
+ * Merge two validation results
+ */
+export function mergeValidationResults(
+  a: ValidationResult,
+  b: ValidationResult
+): ValidationResult {
+  return {
+    valid: a.valid && b.valid,
+    errors: [...a.errors, ...b.errors],
+    warnings: [...a.warnings, ...b.warnings],
+  };
+}
+
+/**
+ * Interface for validators
+ */
+export interface Validator<T = unknown> {
+  validate(data: T): ValidationResult;
+}
+
+/**
+ * Validation error
+ */
+export class ValidationError extends Error {
+  result: ValidationResult;
+
+  constructor(result: ValidationResult) {
+    super(`Validation failed: ${result.errors.join(", ")}`);
+    this.name = "ValidationError";
+    this.result = result;
+  }
+}
+
+/**
+ * Allowed JSON Schema types
+ */
+const ALLOWED_TYPES = new Set([
+  "string",
+  "integer",
+  "number",
+  "boolean",
+  "array",
+  "object",
+  "null",
+]);
+
+/**
+ * Options for ToolSchemaValidator
+ */
+export interface ToolSchemaValidatorOptions {
+  requireDescription?: boolean;
+  requireParameters?: boolean;
+  minDescriptionLength?: number;
+  maxDescriptionLength?: number;
+}
+
+/**
+ * Validates tool definitions
+ */
+export class ToolSchemaValidator implements Validator<Tool> {
+  private options: Required<ToolSchemaValidatorOptions>;
+
+  constructor(options: ToolSchemaValidatorOptions = {}) {
+    this.options = {
+      requireDescription: options.requireDescription ?? true,
+      requireParameters: options.requireParameters ?? false,
+      minDescriptionLength: options.minDescriptionLength ?? 0,
+      maxDescriptionLength: options.maxDescriptionLength ?? 1000,
+    };
+  }
+
+  validate(tool: Tool): ValidationResult {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    // Validate name
+    if (!tool.name) {
+      errors.push("Tool name is required");
+    } else if (!/^[\w-]+$/.test(tool.name)) {
+      warnings.push(`Tool name '${tool.name}' contains special characters`);
+    }
+
+    // Validate description
+    if (this.options.requireDescription && !tool.description) {
+      errors.push("Tool description is required");
+    } else if (tool.description) {
+      if (tool.description.length < this.options.minDescriptionLength) {
+        errors.push(
+          `Description must be at least ${this.options.minDescriptionLength} characters`
+        );
+      }
+      if (tool.description.length > this.options.maxDescriptionLength) {
+        errors.push(
+          `Description must be at most ${this.options.maxDescriptionLength} characters`
+        );
+      }
+    }
+
+    // Validate parameters
+    if (this.options.requireParameters && Object.keys(tool.parameters).length === 0) {
+      errors.push("Tool parameters are required");
+    }
+
+    // Validate parameter types
+    for (const [name, param] of Object.entries(tool.parameters)) {
+      if (param.type && !ALLOWED_TYPES.has(param.type)) {
+        errors.push(`Parameter '${name}' has invalid type '${param.type}'`);
+      }
+    }
+
+    return createValidationResult(errors.length === 0, errors, warnings);
+  }
+}
+
+/**
+ * Options for ParameterValidator
+ */
+export interface ParameterValidatorOptions {
+  strict?: boolean;
+  allowExtra?: boolean;
+}
+
+/**
+ * Validates execution parameters against tool schema
+ */
+export class ParameterValidator implements Validator<{ tool: Tool; params: Record<string, unknown> }> {
+  private options: Required<ParameterValidatorOptions>;
+
+  constructor(options: ParameterValidatorOptions = {}) {
+    this.options = {
+      strict: options.strict ?? false,
+      allowExtra: options.allowExtra ?? true,
+    };
+  }
+
+  validate(data: { tool: Tool; params: Record<string, unknown> }): ValidationResult {
+    const { tool, params } = data;
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    if (!tool) {
+      errors.push("Tool is required for parameter validation");
+      return createValidationResult(false, errors, warnings);
+    }
+
+    const properties = tool.parameters;
+
+    // Check required parameters in strict mode
+    if (this.options.strict) {
+      for (const [name, param] of Object.entries(properties)) {
+        if (param.required !== false && !(name in params)) {
+          errors.push(`Missing required parameter: ${name}`);
+        }
+      }
+    }
+
+    // Check parameter types
+    for (const [name, value] of Object.entries(params)) {
+      if (!(name in properties)) {
+        if (!this.options.allowExtra) {
+          errors.push(`Unknown parameter: ${name}`);
+        } else {
+          warnings.push(`Extra parameter provided: ${name}`);
+        }
+        continue;
+      }
+
+      const param = properties[name];
+      const typeError = this.checkType(name, value, param.type);
+      if (typeError) {
+        errors.push(typeError);
+      }
+    }
+
+    return createValidationResult(errors.length === 0, errors, warnings);
+  }
+
+  private checkType(name: string, value: unknown, expectedType?: string): string | null {
+    if (!expectedType) return null;
+
+    const typeMap: Record<string, (v: unknown) => boolean> = {
+      string: (v) => typeof v === "string",
+      integer: (v) => Number.isInteger(v),
+      number: (v) => typeof v === "number",
+      boolean: (v) => typeof v === "boolean",
+      array: (v) => Array.isArray(v),
+      object: (v) => typeof v === "object" && v !== null && !Array.isArray(v),
+      null: (v) => v === null,
+    };
+
+    const checker = typeMap[expectedType];
+    if (checker && !checker(value)) {
+      return `Parameter '${name}' expected ${expectedType}, got ${typeof value}`;
+    }
+
+    return null;
+  }
+}
+
+/**
+ * Options for ResultValidator
+ */
+export interface ResultValidatorOptions {
+  strict?: boolean;
+}
+
+/**
+ * Validates tool execution results
+ */
+export class ResultValidator implements Validator<{ tool: Tool; result: unknown }> {
+  private options: Required<ResultValidatorOptions>;
+
+  constructor(options: ResultValidatorOptions = {}) {
+    this.options = {
+      strict: options.strict ?? false,
+    };
+  }
+
+  validate(data: { tool: Tool; result: unknown }): ValidationResult {
+    const { tool, result } = data;
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    if (!tool) {
+      errors.push("Tool is required for result validation");
+      return createValidationResult(false, errors, warnings);
+    }
+
+    // If tool has return schema, validate against it
+    if (tool.returns) {
+      const expectedType = tool.returns.type as string;
+      const typeError = this.checkReturnType(result, expectedType);
+      if (typeError) {
+        if (this.options.strict) {
+          errors.push(typeError);
+        } else {
+          warnings.push(typeError);
+        }
+      }
+    }
+
+    return createValidationResult(errors.length === 0, errors, warnings);
+  }
+
+  private checkReturnType(value: unknown, expectedType?: string): string | null {
+    if (!expectedType) return null;
+
+    const typeMap: Record<string, (v: unknown) => boolean> = {
+      string: (v) => typeof v === "string",
+      integer: (v) => Number.isInteger(v),
+      number: (v) => typeof v === "number",
+      boolean: (v) => typeof v === "boolean",
+      array: (v) => Array.isArray(v),
+      object: (v) => typeof v === "object" && v !== null && !Array.isArray(v),
+      null: (v) => v === null,
+    };
+
+    const checker = typeMap[expectedType];
+    if (checker && !checker(value)) {
+      return `Result expected ${expectedType}, got ${typeof value}`;
+    }
+
+    return null;
+  }
+}
+
+/**
+ * Options for EmbeddingValidator
+ */
+export interface EmbeddingValidatorOptions {
+  expectedDimensions?: number;
+  checkNormalization?: boolean;
+}
+
+/**
+ * Validates embedding vectors
+ */
+export class EmbeddingValidator implements Validator<number[]> {
+  private options: EmbeddingValidatorOptions;
+
+  constructor(options: EmbeddingValidatorOptions = {}) {
+    this.options = options;
+  }
+
+  validate(embedding: number[]): ValidationResult {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    if (!Array.isArray(embedding)) {
+      errors.push("Embedding must be an array");
+      return createValidationResult(false, errors, warnings);
+    }
+
+    if (embedding.length === 0) {
+      errors.push("Embedding cannot be empty");
+      return createValidationResult(false, errors, warnings);
+    }
+
+    // Check dimensions
+    if (
+      this.options.expectedDimensions !== undefined &&
+      embedding.length !== this.options.expectedDimensions
+    ) {
+      errors.push(
+        `Embedding dimensions mismatch: expected ${this.options.expectedDimensions}, got ${embedding.length}`
+      );
+    }
+
+    // Check for non-numeric values
+    for (let i = 0; i < embedding.length; i++) {
+      if (typeof embedding[i] !== "number") {
+        errors.push(`Embedding value at index ${i} is not numeric`);
+        break;
+      }
+    }
+
+    // Check normalization
+    if (this.options.checkNormalization && errors.length === 0) {
+      let sumSquares = 0;
+      for (const val of embedding) {
+        sumSquares += val * val;
+      }
+      const norm = Math.sqrt(sumSquares);
+      if (Math.abs(norm - 1.0) > 0.01) {
+        warnings.push(`Embedding is not normalized (norm=${norm.toFixed(4)})`);
+      }
+    }
+
+    return createValidationResult(errors.length === 0, errors, warnings);
+  }
+}
+
+/**
+ * Combines multiple validators
+ */
+export class CompositeValidator<T> implements Validator<T> {
+  private validators: Validator<T>[];
+
+  constructor(validators: Validator<T>[]) {
+    this.validators = validators;
+  }
+
+  validate(data: T): ValidationResult {
+    let result = createValidationResult(true);
+    for (const validator of this.validators) {
+      const subResult = validator.validate(data);
+      result = mergeValidationResults(result, subResult);
+    }
+    return result;
+  }
+}
+
+/**
+ * Registry for managing validators
+ */
+export class ValidatorRegistry {
+  schemaValidators: ToolSchemaValidator[] = [];
+  parameterValidators: ParameterValidator[] = [];
+  resultValidators: ResultValidator[] = [];
+  embeddingValidators: EmbeddingValidator[] = [];
+
+  addSchemaValidator(validator: ToolSchemaValidator): void {
+    this.schemaValidators.push(validator);
+  }
+
+  addParameterValidator(validator: ParameterValidator): void {
+    this.parameterValidators.push(validator);
+  }
+
+  addResultValidator(validator: ResultValidator): void {
+    this.resultValidators.push(validator);
+  }
+
+  addEmbeddingValidator(validator: EmbeddingValidator): void {
+    this.embeddingValidators.push(validator);
+  }
+
+  validateTool(tool: Tool): ValidationResult {
+    let result = createValidationResult(true);
+    for (const validator of this.schemaValidators) {
+      const subResult = validator.validate(tool);
+      result = mergeValidationResults(result, subResult);
+    }
+    return result;
+  }
+
+  validateParams(tool: Tool, params: Record<string, unknown>): ValidationResult {
+    let result = createValidationResult(true);
+    for (const validator of this.parameterValidators) {
+      const subResult = validator.validate({ tool, params });
+      result = mergeValidationResults(result, subResult);
+    }
+    return result;
+  }
+
+  validateResult(tool: Tool, resultValue: unknown): ValidationResult {
+    let result = createValidationResult(true);
+    for (const validator of this.resultValidators) {
+      const subResult = validator.validate({ tool, result: resultValue });
+      result = mergeValidationResults(result, subResult);
+    }
+    return result;
+  }
+
+  validateEmbedding(embedding: number[]): ValidationResult {
+    let result = createValidationResult(true);
+    for (const validator of this.embeddingValidators) {
+      const subResult = validator.validate(embedding);
+      result = mergeValidationResults(result, subResult);
+    }
+    return result;
+  }
+
+  clear(): void {
+    this.schemaValidators = [];
+    this.parameterValidators = [];
+    this.resultValidators = [];
+    this.embeddingValidators = [];
+  }
+}
+
+/**
+ * Create a registry with strict validators
+ */
+export function createStrictValidator(): ValidatorRegistry {
+  const registry = new ValidatorRegistry();
+  registry.addSchemaValidator(
+    new ToolSchemaValidator({
+      requireDescription: true,
+      minDescriptionLength: 10,
+    })
+  );
+  registry.addParameterValidator(new ParameterValidator({ strict: true }));
+  registry.addResultValidator(new ResultValidator({ strict: true }));
+  return registry;
+}
+
+/**
+ * Create a registry with lenient validators
+ */
+export function createLenientValidator(): ValidatorRegistry {
+  const registry = new ValidatorRegistry();
+  registry.addSchemaValidator(
+    new ToolSchemaValidator({
+      requireDescription: false,
+      minDescriptionLength: 0,
+    })
+  );
+  registry.addParameterValidator(
+    new ParameterValidator({
+      strict: false,
+      allowExtra: true,
+    })
+  );
+  registry.addResultValidator(new ResultValidator({ strict: false }));
+  return registry;
+}