sis-tools 0.1.0

package/src/embeddings/openai.ts

@@ -0,0 +1,87 @@
+/**
+ * OpenAI embedding provider
+ */
+
+import type { EmbeddingProvider } from "./base";
+
+interface OpenAIEmbeddingsOptions {
+  model?: string;
+  apiKey?: string;
+  dimensions?: number;
+}
+
+const DEFAULT_DIMENSIONS: Record<string, number> = {
+  "text-embedding-3-small": 1536,
+  "text-embedding-3-large": 3072,
+  "text-embedding-ada-002": 1536,
+};
+
+export class OpenAIEmbeddings implements EmbeddingProvider {
+  private client: any | null = null;
+  private model: string;
+  private apiKey?: string;
+  readonly dimensions: number;
+
+  constructor(options: OpenAIEmbeddingsOptions = {}) {
+    const { model = "text-embedding-3-small", apiKey, dimensions } = options;
+
+    this.model = model;
+    this.apiKey = apiKey;
+    this.dimensions = dimensions ?? DEFAULT_DIMENSIONS[model] ?? 1536;
+  }
+
+  private async ensureClient(): Promise<any> {
+    if (this.client) {
+      return this.client;
+    }
+
+    try {
+      const mod: any = await import("openai");
+      const OpenAI = mod?.OpenAI ?? mod?.default?.OpenAI ?? mod?.default;
+      if (!OpenAI) {
+        throw new Error("OpenAI export not found");
+      }
+      this.client = new OpenAI({ apiKey: this.apiKey });
+      return this.client;
+    } catch {
+      throw new Error(
+        "OpenAI provider requires the openai package. Install with: npm install openai"
+      );
+    }
+  }
+
+  async embed(text: string): Promise<number[]> {
+    const client = await this.ensureClient();
+    const params: Record<string, unknown> = {
+      model: this.model,
+      input: text,
+    };
+
+    if (this.model.includes("text-embedding-3")) {
+      params.dimensions = this.dimensions;
+    }
+
+    const response = await client.embeddings.create(params);
+    return response.data[0].embedding;
+  }
+
+  async embedBatch(texts: string[]): Promise<number[][]> {
+    const client = await this.ensureClient();
+    const params: Record<string, unknown> = {
+      model: this.model,
+      input: texts,
+    };
+
+    if (this.model.includes("text-embedding-3")) {
+      params.dimensions = this.dimensions;
+    }
+
+    const response = await client.embeddings.create(params);
+
+    // Sort by index to ensure order matches input
+    const sorted = [...response.data].sort(
+      (a: { index: number }, b: { index: number }) => a.index - b.index
+    );
+    return sorted.map((item: { embedding: number[] }) => item.embedding);
+  }
+}

package/src/formatters.ts

@@ -0,0 +1,249 @@
+/**
+ * Tool formatters for different LLM providers
+ */
+
+import type { ResolvedTool, ToolSchema } from "./types";
+
+/**
+ * Interface for custom tool formatters
+ */
+export interface ToolFormatter {
+  /** Format name used to identify this formatter */
+  readonly name: string;
+
+  /** Format a resolved tool for LLM consumption */
+  format(tool: ResolvedTool): Record<string, unknown>;
+
+  /** Format multiple tools (override for batch optimizations) */
+  formatBatch?(tools: ResolvedTool[]): Record<string, unknown>[];
+}
+
+/**
+ * Returns the tool schema as-is
+ */
+export class RawFormatter implements ToolFormatter {
+  readonly name = "raw";
+
+  format(tool: ResolvedTool): Record<string, unknown> {
+    return tool.schema as unknown as Record<string, unknown>;
+  }
+}
+
+/**
+ * Formatter for OpenAI function calling format
+ */
+export class OpenAIFormatter implements ToolFormatter {
+  readonly name = "openai";
+
+  format(tool: ResolvedTool): Record<string, unknown> {
+    return {
+      type: "function",
+      function: tool.schema,
+    };
+  }
+}
+
+/**
+ * Formatter for Anthropic tool use format
+ */
+export class AnthropicFormatter implements ToolFormatter {
+  readonly name = "anthropic";
+
+  format(tool: ResolvedTool): Record<string, unknown> {
+    return {
+      name: tool.schema.name,
+      description: tool.schema.description,
+      input_schema: tool.schema.parameters,
+    };
+  }
+}
+
+/**
+ * Formatter for Google Gemini function calling format
+ */
+export class GeminiFormatter implements ToolFormatter {
+  readonly name = "gemini";
+
+  format(tool: ResolvedTool): Record<string, unknown> {
+    return {
+      name: tool.schema.name,
+      description: tool.schema.description,
+      parameters: tool.schema.parameters,
+    };
+  }
+}
+
+/**
+ * Formatter for Mistral function calling format (OpenAI-compatible)
+ */
+export class MistralFormatter implements ToolFormatter {
+  readonly name = "mistral";
+
+  format(tool: ResolvedTool): Record<string, unknown> {
+    return {
+      type: "function",
+      function: {
+        name: tool.schema.name,
+        description: tool.schema.description,
+        parameters: tool.schema.parameters,
+      },
+    };
+  }
+}
+
+/**
+ * Formatter for Llama/Meta function calling format
+ */
+export class LlamaFormatter implements ToolFormatter {
+  readonly name = "llama";
+
+  format(tool: ResolvedTool): Record<string, unknown> {
+    return {
+      type: "function",
+      function: {
+        name: tool.schema.name,
+        description: tool.schema.description,
+        parameters: tool.schema.parameters,
+      },
+    };
+  }
+}
+
+/**
+ * Formatter for Cohere Command R format
+ */
+export class CohereFormatter implements ToolFormatter {
+  readonly name = "cohere";
+
+  format(tool: ResolvedTool): Record<string, unknown> {
+    const params = tool.schema.parameters;
+    const properties = params.properties as Record<string, Record<string, unknown>>;
+    const required = new Set(params.required);
+
+    const parameterDefinitions: Record<string, unknown> = {};
+    for (const [name, prop] of Object.entries(properties)) {
+      parameterDefinitions[name] = {
+        type: prop.type ?? "string",
+        description: prop.description ?? "",
+        required: required.has(name),
+      };
+    }
+
+    return {
+      name: tool.schema.name,
+      description: tool.schema.description,
+      parameter_definitions: parameterDefinitions,
+    };
+  }
+}
+
+/**
+ * Minimal formatter with just name and description
+ */
+export class MinimalFormatter implements ToolFormatter {
+  readonly name = "minimal";
+
+  format(tool: ResolvedTool): Record<string, unknown> {
+    return {
+      name: tool.schema.name,
+      description: tool.schema.description,
+    };
+  }
+}
+
+/**
+ * Verbose formatter with all available information
+ */
+export class VerboseFormatter implements ToolFormatter {
+  readonly name = "verbose";
+
+  format(tool: ResolvedTool): Record<string, unknown> {
+    return {
+      name: tool.name,
+      schema: tool.schema,
+      score: tool.score,
+      hasHandler: tool.handler !== undefined,
+    };
+  }
+}
+
+// Global formatter registry
+const formatters: Map<string, ToolFormatter> = new Map();
+
+/**
+ * Register a custom formatter
+ */
+export function registerFormatter(formatter: ToolFormatter): void {
+  formatters.set(formatter.name, formatter);
+}
+
+/**
+ * Unregister a formatter by name
+ */
+export function unregisterFormatter(name: string): boolean {
+  return formatters.delete(name);
+}
+
+/**
+ * Get a formatter by name
+ */
+export function getFormatter(name: string): ToolFormatter {
+  const formatter = formatters.get(name);
+  if (!formatter) {
+    const available = Array.from(formatters.keys()).join(", ");
+    throw new Error(`Unknown formatter '${name}'. Available: ${available}`);
+  }
+  return formatter;
+}
+
+/**
+ * List all registered formatter names
+ */
+export function listFormatters(): string[] {
+  return Array.from(formatters.keys());
+}
+
+/**
+ * Check if a formatter is registered
+ */
+export function hasFormatter(name: string): boolean {
+  return formatters.has(name);
+}
+
+/**
+ * Format tools using a formatter (by name or instance)
+ */
+export function formatTools(
+  tools: ResolvedTool[],
+  formatter: string | ToolFormatter
+): Record<string, unknown>[] {
+  const fmt = typeof formatter === "string" ? getFormatter(formatter) : formatter;
+
+  if (fmt.formatBatch) {
+    return fmt.formatBatch(tools);
+  }
+
+  return tools.map((tool) => fmt.format(tool));
+}
+
+// Register default formatters
+function registerDefaults(): void {
+  const defaults: ToolFormatter[] = [
+    new RawFormatter(),
+    new OpenAIFormatter(),
+    new AnthropicFormatter(),
+    new GeminiFormatter(),
+    new MistralFormatter(),
+    new LlamaFormatter(),
+    new CohereFormatter(),
+    new MinimalFormatter(),
+    new VerboseFormatter(),
+  ];
+
+  for (const formatter of defaults) {
+    registerFormatter(formatter);
+  }
+}
+
+// Initialize default formatters
+registerDefaults();

package/src/hooks.ts

@@ -0,0 +1,341 @@
+/**
+ * Middleware/hooks system for SIS
+ */
+
+import type { Tool, ResolvedTool, ToolMatch } from "./types";
+
+/**
+ * Types of hooks available in the SIS lifecycle
+ */
+export enum HookType {
+  // Registration hooks
+  PRE_REGISTER = "pre_register",
+  POST_REGISTER = "post_register",
+
+  // Initialization hooks
+  PRE_EMBED = "pre_embed",
+  POST_EMBED = "post_embed",
+
+  // Resolution hooks
+  PRE_RESOLVE = "pre_resolve",
+  POST_RESOLVE = "post_resolve",
+  PRE_SEARCH = "pre_search",
+  POST_SEARCH = "post_search",
+
+  // Execution hooks
+  PRE_EXECUTE = "pre_execute",
+  POST_EXECUTE = "post_execute",
+}
+
+/**
+ * Context passed to hooks
+ */
+export interface HookContext {
+  hookType: HookType;
+  data: Record<string, unknown>;
+  cancelled: boolean;
+  error: Error | null;
+}
+
+/**
+ * Create a new hook context
+ */
+export function createContext(
+  hookType: HookType,
+  data: Record<string, unknown> = {}
+): HookContext {
+  return {
+    hookType,
+    data,
+    cancelled: false,
+    error: null,
+  };
+}
+
+/**
+ * Cancel further processing
+ */
+export function cancelContext(context: HookContext, reason?: string): void {
+  context.cancelled = true;
+  if (reason) {
+    context.data.cancelReason = reason;
+  }
+}
+
+/**
+ * Set an error on the context
+ */
+export function setContextError(context: HookContext, error: Error): void {
+  context.error = error;
+  context.cancelled = true;
+}
+
+/**
+ * Interface for hooks
+ */
+export interface Hook {
+  /** The hook type this hook handles */
+  hookType: HookType;
+
+  /** Hook priority. Higher priority hooks run first. */
+  priority?: number;
+
+  /** Execute the hook */
+  execute(context: HookContext): Promise<HookContext> | HookContext;
+}
+
+/**
+ * Hook function type
+ */
+export type HookFunction = (
+  context: HookContext
+) => Promise<HookContext> | HookContext;
+
+/**
+ * Create a hook from a function
+ */
+export function createHook(
+  hookType: HookType,
+  fn: HookFunction,
+  priority: number = 0
+): Hook {
+  return {
+    hookType,
+    priority,
+    execute: fn,
+  };
+}
+
+/**
+ * Registry for managing hooks
+ */
+export class HookRegistry {
+  private hooks: Map<HookType, Hook[]> = new Map();
+
+  constructor() {
+    // Initialize all hook types
+    for (const type of Object.values(HookType)) {
+      this.hooks.set(type, []);
+    }
+  }
+
+  /**
+   * Register a hook
+   */
+  register(hook: Hook): void {
+    const hooks = this.hooks.get(hook.hookType) ?? [];
+    hooks.push(hook);
+    // Sort by priority (highest first)
+    hooks.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+    this.hooks.set(hook.hookType, hooks);
+  }
+
+  /**
+   * Register a function as a hook
+   */
+  on(
+    hookType: HookType,
+    fn: HookFunction,
+    priority: number = 0
+  ): Hook {
+    const hook = createHook(hookType, fn, priority);
+    this.register(hook);
+    return hook;
+  }
+
+  /**
+   * Unregister a hook
+   */
+  unregister(hook: Hook): boolean {
+    const hooks = this.hooks.get(hook.hookType) ?? [];
+    const index = hooks.indexOf(hook);
+    if (index !== -1) {
+      hooks.splice(index, 1);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Clear hooks
+   */
+  clear(hookType?: HookType): void {
+    if (hookType) {
+      this.hooks.set(hookType, []);
+    } else {
+      for (const type of Object.values(HookType)) {
+        this.hooks.set(type, []);
+      }
+    }
+  }
+
+  /**
+   * Get all hooks for a type
+   */
+  getHooks(hookType: HookType): Hook[] {
+    return [...(this.hooks.get(hookType) ?? [])];
+  }
+
+  /**
+   * Check if any hooks are registered for a type
+   */
+  hasHooks(hookType: HookType): boolean {
+    return (this.hooks.get(hookType) ?? []).length > 0;
+  }
+
+  /**
+   * Run all hooks of a given type
+   */
+  async run(hookType: HookType, context: HookContext): Promise<HookContext> {
+    const hooks = this.hooks.get(hookType) ?? [];
+
+    for (const hook of hooks) {
+      if (context.cancelled) {
+        break;
+      }
+
+      try {
+        const result = hook.execute(context);
+        if (result instanceof Promise) {
+          context = await result;
+        } else {
+          context = result;
+        }
+      } catch (error) {
+        setContextError(context, error as Error);
+        break;
+      }
+    }
+
+    return context;
+  }
+}
+
+// Pre-built hook implementations for common use cases
+
+/**
+ * Hook that logs hook execution
+ */
+export class LoggingHook implements Hook {
+  hookType: HookType;
+  priority = 0;
+  private logger: (message: string) => void;
+
+  constructor(hookType: HookType, logger?: (message: string) => void) {
+    this.hookType = hookType;
+    this.logger = logger ?? console.log;
+  }
+
+  execute(context: HookContext): HookContext {
+    this.logger(`[${this.hookType}] data=${JSON.stringify(context.data)}`);
+    return context;
+  }
+}
+
+/**
+ * Hook that records execution time
+ */
+export class TimingHook implements Hook {
+  hookType: HookType;
+  priority = 0;
+  private preHook: HookType;
+  private postHook: HookType;
+  private timingKey: string;
+
+  constructor(
+    preHook: HookType,
+    postHook: HookType,
+    timingKey: string = "timing"
+  ) {
+    this.preHook = preHook;
+    this.postHook = postHook;
+    this.hookType = preHook; // Will be updated when used
+    this.timingKey = timingKey;
+  }
+
+  execute(context: HookContext): HookContext {
+    if (context.hookType === this.preHook) {
+      context.data[`${this.timingKey}Start`] = performance.now();
+    } else if (context.hookType === this.postHook) {
+      const start = context.data[`${this.timingKey}Start`] as number;
+      if (start) {
+        const duration = performance.now() - start;
+        context.data[`${this.timingKey}Ms`] = duration;
+      }
+    }
+    return context;
+  }
+}
+
+/**
+ * Hook that collects metrics
+ */
+export class MetricsHook implements Hook {
+  hookType: HookType;
+  priority = 0;
+  count = 0;
+  errors = 0;
+
+  constructor(hookType: HookType) {
+    this.hookType = hookType;
+  }
+
+  execute(context: HookContext): HookContext {
+    this.count++;
+    if (context.error) {
+      this.errors++;
+    }
+    return context;
+  }
+
+  reset(): void {
+    this.count = 0;
+    this.errors = 0;
+  }
+}
+
+/**
+ * Hook that caches resolution results
+ */
+export class CachingHook implements Hook {
+  hookType = HookType.PRE_RESOLVE;
+  priority = 100; // Run early to check cache
+  private cache: Map<string, unknown[]> = new Map();
+  private maxSize: number;
+
+  constructor(maxSize: number = 100) {
+    this.maxSize = maxSize;
+  }
+
+  execute(context: HookContext): HookContext {
+    if (context.hookType === HookType.PRE_RESOLVE) {
+      const query = context.data.query as string;
+      if (query && this.cache.has(query)) {
+        context.data.cachedResults = this.cache.get(query);
+        context.data.cacheHit = true;
+      }
+    } else if (context.hookType === HookType.POST_RESOLVE) {
+      const query = context.data.query as string;
+      const results = context.data.results as unknown[];
+      if (query && results && !this.cache.has(query)) {
+        if (this.cache.size >= this.maxSize) {
+          // Remove oldest entry
+          const firstKey = this.cache.keys().next().value;
+          if (firstKey) {
+            this.cache.delete(firstKey);
+          }
+        }
+        this.cache.set(query, results);
+      }
+    }
+    return context;
+  }
+
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  get cacheSize(): number {
+    return this.cache.size;
+  }
+}