sis-tools 0.1.0

package/src/sis.ts

@@ -0,0 +1,572 @@
+/**
+ * Core SIS implementation
+ */
+
+import type {
+  Tool,
+  ToolHandler,
+  ToolParameters,
+  ToolExample,
+  ToolMetadata,
+  ResolvedTool,
+  OpenAIToolSchema,
+  AnthropicToolSchema,
+} from "./types";
+import { toSchema, toOpenAISchema, toAnthropicSchema } from "./types";
+import type { EmbeddingProvider, ProviderName, ProviderOptions } from "./embeddings";
+import { getProvider, buildToolText } from "./embeddings";
+import { VectorStore } from "./store";
+
+// Import customization systems
+import type { SimilarityFunction, ScoringFunction } from "./scoring";
+import { DEFAULT_SIMILARITY, DEFAULT_SCORING } from "./scoring";
+import type { ToolFormatter } from "./formatters";
+import { getFormatter, hasFormatter, formatTools } from "./formatters";
+import type { Hook } from "./hooks";
+import { HookRegistry, HookType, createContext } from "./hooks";
+import type { ValidatorRegistry } from "./validators";
+import { ValidationError } from "./validators";
+
+export interface SISOptions {
+  embeddingProvider?: ProviderName | EmbeddingProvider;
+  defaultTopK?: number;
+  defaultThreshold?: number;
+  providerOptions?: ProviderOptions;
+  remoteUrl?: string;
+  projectId?: string;
+  // New customization options
+  similarity?: SimilarityFunction;
+  scoring?: ScoringFunction;
+  validators?: ValidatorRegistry;
+  validateOnRegister?: boolean;
+  validateOnExecute?: boolean;
+}
+
+export interface RegisterOptions {
+  name: string;
+  description: string;
+  parameters?: ToolParameters;
+  handler?: ToolHandler;
+  semanticHints?: string[];
+  examples?: ToolExample[];
+  metadata?: ToolMetadata;
+}
+
+export interface StoreOptions extends RegisterOptions {
+  embedding: number[];
+}
+
+export type ResolveFormat = "raw" | "openai" | "anthropic" | string;
+
+export interface ResolveOptions {
+  topK?: number;
+  threshold?: number;
+  format?: ResolveFormat | ToolFormatter;
+}
+
+/**
+ * Semantic Integration System - Intelligent tool resolution
+ *
+ * @example
+ * const sis = new SIS({ embeddingProvider: 'openai' });
+ *
+ * sis.register({
+ *   name: 'web_search',
+ *   description: 'Search the web for information',
+ *   parameters: { query: { type: 'string' } },
+ *   handler: async ({ query }) => searchApi(query)
+ * });
+ *
+ * await sis.initialize();
+ * const tools = await sis.resolve("what's the weather?");
+ *
+ * // With custom formatter
+ * const geminiTools = await sis.resolve("query", { format: "gemini" });
+ */
+export class SIS {
+  private _embeddings: EmbeddingProvider;
+  private _vectorStore: VectorStore;
+  private _pendingTools: Tool[];
+  private _defaultTopK: number;
+  private _defaultThreshold: number;
+  private _initialized: boolean;
+  private _remoteUrl?: string;
+  private _projectId?: string;
+
+  // Customization systems
+  private _similarity: SimilarityFunction;
+  private _scoring: ScoringFunction;
+  private _hooks: HookRegistry;
+  private _validators?: ValidatorRegistry;
+  private _validateOnRegister: boolean;
+  private _validateOnExecute: boolean;
+
+  constructor(options: SISOptions = {}) {
+    const {
+      embeddingProvider = "openai",
+      defaultTopK = 5,
+      defaultThreshold = 0.3,
+      providerOptions = {},
+      similarity,
+      scoring,
+      validators,
+      validateOnRegister = false,
+      validateOnExecute = false,
+    } = options;
+
+    if (typeof embeddingProvider === "string") {
+      this._embeddings = getProvider(embeddingProvider, providerOptions);
+    } else {
+      this._embeddings = embeddingProvider;
+    }
+
+    this._vectorStore = new VectorStore();
+    this._pendingTools = [];
+    this._defaultTopK = defaultTopK;
+    this._defaultThreshold = defaultThreshold;
+    this._initialized = false;
+    this._remoteUrl = options.remoteUrl;
+    this._projectId = options.projectId;
+
+    // Initialize customization systems
+    this._similarity = similarity ?? DEFAULT_SIMILARITY;
+    this._scoring = scoring ?? DEFAULT_SCORING;
+    this._hooks = new HookRegistry();
+    this._validators = validators;
+    this._validateOnRegister = validateOnRegister;
+    this._validateOnExecute = validateOnExecute;
+  }
+
+  // Properties for accessing customization systems
+
+  /** Get the hook registry for registering middleware */
+  get hooks(): HookRegistry {
+    return this._hooks;
+  }
+
+  /** Get the validator registry */
+  get validators(): ValidatorRegistry | undefined {
+    return this._validators;
+  }
+
+  /** Get the current similarity function */
+  get similarity(): SimilarityFunction {
+    return this._similarity;
+  }
+
+  /** Set a new similarity function */
+  set similarity(fn: SimilarityFunction) {
+    this._similarity = fn;
+  }
+
+  /** Get the current scoring function */
+  get scoring(): ScoringFunction {
+    return this._scoring;
+  }
+
+  /** Set a new scoring function */
+  set scoring(fn: ScoringFunction) {
+    this._scoring = fn;
+  }
+
+  /** Register a hook */
+  registerHook(hook: Hook): void {
+    this._hooks.register(hook);
+  }
+
+  /** Unregister a hook */
+  unregisterHook(hook: Hook): boolean {
+    return this._hooks.unregister(hook);
+  }
+
+  /**
+   * Register a tool programmatically
+   */
+  register(options: RegisterOptions): Tool {
+    const tool: Tool = {
+      name: options.name,
+      description: options.description,
+      parameters: options.parameters ?? {},
+      semanticHints: options.semanticHints ?? [],
+      examples: options.examples ?? [],
+      handler: options.handler,
+      metadata: options.metadata ?? {},
+    };
+
+    // Validate if enabled
+    if (this._validateOnRegister && this._validators) {
+      const result = this._validators.validateTool(tool);
+      if (!result.valid) {
+        throw new ValidationError(result);
+      }
+    }
+
+    this._pendingTools.push(tool);
+    return tool;
+  }
+
+  /**
+   * Store (upsert) a tool with a precomputed embedding.
+   *
+   * This bypasses the embedding provider, allowing custom embedding workflows.
+   */
+  store(options: StoreOptions): Tool {
+    const tool: Tool = {
+      name: options.name,
+      description: options.description,
+      parameters: options.parameters ?? {},
+      semanticHints: options.semanticHints ?? [],
+      examples: options.examples ?? [],
+      handler: options.handler,
+      metadata: options.metadata ?? {},
+    };
+
+    // Validate tool schema if enabled
+    if (this._validateOnRegister && this._validators) {
+      const result = this._validators.validateTool(tool);
+      if (!result.valid) {
+        throw new ValidationError(result);
+      }
+    }
+
+    // Validate embedding
+    if (this._validators) {
+      const embeddingResult = this._validators.validateEmbedding(options.embedding);
+      if (!embeddingResult.valid) {
+        throw new ValidationError(embeddingResult);
+      }
+    }
+
+    if (options.embedding.length !== this._embeddings.dimensions) {
+      throw new Error(
+        `Embedding dimensions must match provider: ${options.embedding.length} !== ${this._embeddings.dimensions}`
+      );
+    }
+
+    // Upsert into the local store
+    if (this._vectorStore.has(tool.name)) {
+      this._vectorStore.remove(tool.name);
+    }
+    this._vectorStore.add(tool, options.embedding);
+    return tool;
+  }
+
+  /**
+   * Initialize embeddings for all pending tools
+   */
+  async initialize(): Promise<void> {
+    if (this._pendingTools.length === 0) {
+      this._initialized = true;
+      return;
+    }
+
+    // PRE_EMBED hook
+    let ctx = createContext(HookType.PRE_EMBED, { tools: this._pendingTools });
+    ctx = await this._hooks.run(HookType.PRE_EMBED, ctx);
+    if (ctx.cancelled) {
+      return;
+    }
+
+    // Build text representations for embedding
+    const texts = this._pendingTools.map((tool) =>
+      buildToolText(
+        tool.name,
+        tool.description,
+        tool.semanticHints,
+        tool.examples
+      )
+    );
+
+    // Batch embed all tools
+    const embeddings = await this._embeddings.embedBatch(texts);
+
+    // Add to store
+    this._vectorStore.addBatch(this._pendingTools, embeddings);
+
+    // POST_EMBED hook
+    ctx = createContext(HookType.POST_EMBED, {
+      tools: this._pendingTools,
+      embeddings,
+    });
+    await this._hooks.run(HookType.POST_EMBED, ctx);
+
+    this._pendingTools = [];
+    this._initialized = true;
+  }
+
+  /**
+   * Resolve tools for a query (raw format)
+   */
+  async resolve(
+    query: string,
+    options?: { topK?: number; threshold?: number; format?: "raw" }
+  ): Promise<ResolvedTool[]>;
+
+  /**
+   * Resolve tools for a query (OpenAI format)
+   */
+  async resolve(
+    query: string,
+    options: { topK?: number; threshold?: number; format: "openai" }
+  ): Promise<OpenAIToolSchema[]>;
+
+  /**
+   * Resolve tools for a query (Anthropic format)
+   */
+  async resolve(
+    query: string,
+    options: { topK?: number; threshold?: number; format: "anthropic" }
+  ): Promise<AnthropicToolSchema[]>;
+
+  /**
+   * Resolve tools for a query (custom format)
+   */
+  async resolve(
+    query: string,
+    options: { topK?: number; threshold?: number; format: string | ToolFormatter }
+  ): Promise<Record<string, unknown>[]>;
+
+  /**
+   * Resolve tools for a query
+   */
+  async resolve(
+    query: string,
+    options: ResolveOptions = {}
+  ): Promise<ResolvedTool[] | OpenAIToolSchema[] | AnthropicToolSchema[] | Record<string, unknown>[]> {
+    // Auto-initialize if needed
+    if (!this._initialized) {
+      await this.initialize();
+    }
+
+    const topK = options.topK ?? this._defaultTopK;
+    const threshold = options.threshold ?? this._defaultThreshold;
+    const format = options.format ?? "raw";
+
+    // PRE_RESOLVE hook
+    let ctx = createContext(HookType.PRE_RESOLVE, {
+      query,
+      topK,
+      threshold,
+      format,
+    });
+    ctx = await this._hooks.run(HookType.PRE_RESOLVE, ctx);
+    if (ctx.cancelled) {
+      if (ctx.data.cachedResults) {
+        return ctx.data.cachedResults as ResolvedTool[];
+      }
+      return [];
+    }
+
+    // Allow hooks to modify parameters
+    const finalQuery = (ctx.data.query as string) ?? query;
+    const finalTopK = (ctx.data.topK as number) ?? topK;
+    const finalThreshold = (ctx.data.threshold as number) ?? threshold;
+
+    // Check for remote resolution
+    if (this._remoteUrl && this._projectId) {
+      const response = await fetch(
+        `${this._remoteUrl}/v1/projects/${this._projectId}/resolve`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ query: finalQuery, top_k: finalTopK, threshold: finalThreshold }),
+        }
+      );
+
+      if (!response.ok) {
+        throw new Error(`Remote resolution failed: ${response.statusText}`);
+      }
+
+      const data = (await response.json()) as { results: ResolvedTool[] };
+      const results = data.results;
+
+      return this.formatResults(results, format);
+    }
+
+    // Embed the query
+    const queryEmbedding = await this._embeddings.embed(finalQuery);
+
+    // PRE_SEARCH hook
+    let searchCtx = createContext(HookType.PRE_SEARCH, {
+      query: finalQuery,
+      queryEmbedding,
+      topK: finalTopK,
+      threshold: finalThreshold,
+    });
+    searchCtx = await this._hooks.run(HookType.PRE_SEARCH, searchCtx);
+
+    // Search for matching tools with custom similarity/scoring
+    const matches = this._vectorStore.search(
+      queryEmbedding,
+      finalTopK,
+      finalThreshold,
+      this._similarity,
+      this._scoring
+    );
+
+    // POST_SEARCH hook
+    let postSearchCtx = createContext(HookType.POST_SEARCH, {
+      query: finalQuery,
+      matches,
+    });
+    postSearchCtx = await this._hooks.run(HookType.POST_SEARCH, postSearchCtx);
+    const finalMatches = (postSearchCtx.data.matches as typeof matches) ?? matches;
+
+    // Convert to resolved tools
+    const resolved: ResolvedTool[] = finalMatches.map((match) => ({
+      name: match.tool.name,
+      schema: toSchema(match.tool),
+      score: match.score,
+      handler: match.tool.handler,
+    }));
+
+    // Format output
+    const results = this.formatResults(resolved, format);
+
+    // POST_RESOLVE hook
+    let postCtx = createContext(HookType.POST_RESOLVE, {
+      query: finalQuery,
+      results,
+      resolved,
+    });
+    postCtx = await this._hooks.run(HookType.POST_RESOLVE, postCtx);
+
+    return (postCtx.data.results as typeof results) ?? results;
+  }
+
+  /**
+   * Format results based on format option
+   */
+  private formatResults(
+    resolved: ResolvedTool[],
+    format: ResolveFormat | ToolFormatter
+  ): ResolvedTool[] | OpenAIToolSchema[] | AnthropicToolSchema[] | Record<string, unknown>[] {
+    if (format === "raw") {
+      return resolved;
+    }
+
+    if (typeof format === "object" && "format" in format) {
+      // ToolFormatter instance
+      return formatTools(resolved, format);
+    }
+
+    if (typeof format === "string") {
+      // Check if it's a registered formatter
+      if (hasFormatter(format)) {
+        return formatTools(resolved, format);
+      }
+
+      // Built-in formats
+      if (format === "openai") {
+        return resolved.map((r) => ({
+          type: "function" as const,
+          function: r.schema,
+        }));
+      }
+
+      if (format === "anthropic") {
+        return resolved.map((r) => ({
+          name: r.schema.name,
+          description: r.schema.description,
+          input_schema: r.schema.parameters,
+        }));
+      }
+
+      throw new Error(`Unknown format: ${format}`);
+    }
+
+    return resolved;
+  }
+
+  /**
+   * Resolve the single best matching tool
+   */
+  async resolveOne(
+    query: string,
+    threshold?: number
+  ): Promise<ResolvedTool | null> {
+    const results = await this.resolve(query, { topK: 1, threshold });
+    return results.length > 0 ? (results[0] as ResolvedTool) : null;
+  }
+
+  /**
+   * Get a registered tool by name
+   */
+  getTool(name: string): Tool | undefined {
+    return this._vectorStore.get(name);
+  }
+
+  /**
+   * List all registered tool names
+   */
+  listTools(): string[] {
+    return this._vectorStore.getAll().map((t) => t.name);
+  }
+
+  /**
+   * Number of registered tools
+   */
+  get toolCount(): number {
+    return this._vectorStore.size + this._pendingTools.length;
+  }
+
+  /**
+   * Execute a tool by name
+   */
+  async execute(
+    toolName: string,
+    params: Record<string, unknown>
+  ): Promise<unknown> {
+    const tool = this._vectorStore.get(toolName);
+    if (!tool) {
+      throw new Error(`Tool not found: ${toolName}`);
+    }
+    if (!tool.handler) {
+      throw new Error(`Tool has no handler: ${toolName}`);
+    }
+
+    // PRE_EXECUTE hook
+    let ctx = createContext(HookType.PRE_EXECUTE, {
+      tool,
+      toolName,
+      params,
+    });
+    ctx = await this._hooks.run(HookType.PRE_EXECUTE, ctx);
+    if (ctx.cancelled) {
+      if (ctx.error) {
+        throw ctx.error;
+      }
+      return null;
+    }
+
+    // Validate parameters if enabled
+    if (this._validateOnExecute && this._validators) {
+      const paramsResult = this._validators.validateParams(tool, params);
+      if (!paramsResult.valid) {
+        throw new ValidationError(paramsResult);
+      }
+    }
+
+    // Execute the handler
+    const result = await tool.handler(params);
+
+    // Validate result if enabled
+    if (this._validateOnExecute && this._validators) {
+      const resultValidation = this._validators.validateResult(tool, result);
+      if (!resultValidation.valid) {
+        throw new ValidationError(resultValidation);
+      }
+    }
+
+    // POST_EXECUTE hook
+    let postCtx = createContext(HookType.POST_EXECUTE, {
+      tool,
+      toolName,
+      params,
+      result,
+    });
+    postCtx = await this._hooks.run(HookType.POST_EXECUTE, postCtx);
+
+    return (postCtx.data.result as unknown) ?? result;
+  }
+}

package/src/store.ts

@@ -0,0 +1,134 @@
+/**
+ * Vector store for tool embeddings
+ */
+
+import type { Tool, ToolMatch } from "./types";
+import type { SimilarityFunction, ScoringFunction } from "./scoring";
+import { DEFAULT_SIMILARITY, DEFAULT_SCORING } from "./scoring";
+
+/**
+ * In-memory vector store for tool embeddings.
+ *
+ * Uses cosine similarity by default for matching. Supports custom
+ * similarity and scoring functions for advanced use cases.
+ *
+ * For production use with many tools, consider using an external
+ * store like Pinecone, Chroma, or Qdrant.
+ */
+export class VectorStore {
+  private tools: Tool[] = [];
+  private embeddings: number[][] = [];
+
+  /**
+   * Add a tool with its embedding to the store
+   */
+  add(tool: Tool, embedding: number[]): void {
+    tool.embedding = embedding;
+    this.tools.push(tool);
+    this.embeddings.push(embedding);
+  }
+
+  /**
+   * Add multiple tools with embeddings
+   */
+  addBatch(tools: Tool[], embeddings: number[][]): void {
+    for (let i = 0; i < tools.length; i++) {
+      this.add(tools[i], embeddings[i]);
+    }
+  }
+
+  /**
+   * Search for similar tools
+   *
+   * @param queryEmbedding - The query embedding vector
+   * @param topK - Maximum number of results
+   * @param threshold - Minimum score to include
+   * @param similarityFn - Custom similarity function (defaults to cosine)
+   * @param scoringFn - Custom scoring function (defaults to priority scoring)
+   */
+  search(
+    queryEmbedding: number[],
+    topK: number = 5,
+    threshold: number = 0.0,
+    similarityFn?: SimilarityFunction,
+    scoringFn?: ScoringFunction
+  ): ToolMatch[] {
+    if (this.tools.length === 0) {
+      return [];
+    }
+
+    // Use provided functions or defaults
+    const simFn = similarityFn ?? DEFAULT_SIMILARITY;
+    const scoreFn = scoringFn ?? DEFAULT_SCORING;
+
+    const matches: ToolMatch[] = [];
+
+    for (let i = 0; i < this.tools.length; i++) {
+      const tool = this.tools[i];
+      const embedding = this.embeddings[i];
+
+      // Compute similarity
+      const similarity = simFn.compute(queryEmbedding, embedding);
+
+      // Apply scoring (includes priority boost by default)
+      const finalScore = scoreFn.score(similarity, tool);
+
+      if (finalScore >= threshold) {
+        matches.push({ tool, score: finalScore });
+      }
+    }
+
+    // Sort by score descending and take top_k
+    matches.sort((a, b) => b.score - a.score);
+    return matches.slice(0, topK);
+  }
+
+  /**
+   * Remove a tool by name
+   */
+  remove(toolName: string): boolean {
+    const index = this.tools.findIndex((t) => t.name === toolName);
+    if (index !== -1) {
+      this.tools.splice(index, 1);
+      this.embeddings.splice(index, 1);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Remove all tools from the store
+   */
+  clear(): void {
+    this.tools = [];
+    this.embeddings = [];
+  }
+
+  /**
+   * Get a tool by name
+   */
+  get(toolName: string): Tool | undefined {
+    return this.tools.find((t) => t.name === toolName);
+  }
+
+  /**
+   * Number of tools in the store
+   */
+  get size(): number {
+    return this.tools.length;
+  }
+
+  /**
+   * Check if a tool exists by name
+   */
+  has(toolName: string): boolean {
+    return this.tools.some((t) => t.name === toolName);
+  }
+
+  /**
+   * Get all tools
+   */
+  getAll(): Tool[] {
+    return [...this.tools];
+  }
+}