sis-tools 0.1.0

package/src/index.ts

@@ -0,0 +1,104 @@
+/**
+ * SIS - Semantic Integration System
+ *
+ * Intelligent tool resolution for LLMs using semantic embeddings.
+ */
+
+// Core
+export { SIS } from "./sis";
+export type { SISOptions, RegisterOptions, StoreOptions, ResolveFormat, ResolveOptions } from "./sis";
+
+// Types
+export type {
+  Tool,
+  ToolHandler,
+  ToolParameter,
+  ToolParameters,
+  ToolExample,
+  ToolMetadata,
+  ToolMatch,
+  ResolvedTool,
+  ToolSchema,
+  OpenAIToolSchema,
+  AnthropicToolSchema,
+} from "./types";
+export { toSchema, toOpenAISchema, toAnthropicSchema } from "./types";
+
+// Embeddings
+export type { EmbeddingProvider } from "./embeddings";
+export { OpenAIEmbeddings, CohereEmbeddings, GoogleEmbeddings, getProvider } from "./embeddings";
+
+// Store
+export { VectorStore } from "./store";
+
+// Scoring
+export type { SimilarityFunction, ScoringFunction } from "./scoring";
+export {
+  CosineSimilarity,
+  EuclideanSimilarity,
+  DotProductSimilarity,
+  PriorityScoring,
+  WeightedScoring,
+  TagBoostScoring,
+  CompositeScoring,
+  DEFAULT_SIMILARITY,
+  DEFAULT_SCORING,
+} from "./scoring";
+
+// Formatters
+export type { ToolFormatter } from "./formatters";
+export {
+  RawFormatter,
+  OpenAIFormatter,
+  AnthropicFormatter,
+  GeminiFormatter,
+  MistralFormatter,
+  LlamaFormatter,
+  CohereFormatter,
+  MinimalFormatter,
+  VerboseFormatter,
+  registerFormatter,
+  unregisterFormatter,
+  getFormatter,
+  listFormatters,
+  hasFormatter,
+  formatTools,
+} from "./formatters";
+
+// Hooks
+export type { Hook, HookContext, HookFunction } from "./hooks";
+export {
+  HookType,
+  HookRegistry,
+  createHook,
+  createContext,
+  cancelContext,
+  setContextError,
+  LoggingHook,
+  TimingHook,
+  MetricsHook,
+  CachingHook,
+} from "./hooks";
+
+// Validators
+export type {
+  Validator,
+  ValidationResult,
+  ToolSchemaValidatorOptions,
+  ParameterValidatorOptions,
+  ResultValidatorOptions,
+  EmbeddingValidatorOptions,
+} from "./validators";
+export {
+  ValidationError,
+  ToolSchemaValidator,
+  ParameterValidator,
+  ResultValidator,
+  EmbeddingValidator,
+  CompositeValidator,
+  ValidatorRegistry,
+  createValidationResult,
+  mergeValidationResults,
+  createStrictValidator,
+  createLenientValidator,
+} from "./validators";

package/src/optional-peer-deps.d.ts

@@ -0,0 +1,17 @@
+declare module "openai" {
+  export const OpenAI: any;
+  const _default: any;
+  export default _default;
+}
+
+declare module "cohere-ai" {
+  export const CohereClient: any;
+  const _default: any;
+  export default _default;
+}
+
+declare module "@google/generative-ai" {
+  export const GoogleGenerativeAI: any;
+  const _default: any;
+  export default _default;
+}

package/src/scoring.ts

@@ -0,0 +1,198 @@
+/**
+ * Similarity and scoring functions for semantic search
+ */
+
+import type { Tool } from "./types";
+
+/**
+ * Interface for custom similarity functions
+ */
+export interface SimilarityFunction {
+  /**
+   * Compute similarity score between query and tool embeddings
+   * @param queryEmbedding - The query vector
+   * @param toolEmbedding - The tool's embedding vector
+   * @returns Similarity score, typically in range [0, 1]
+   */
+  compute(queryEmbedding: number[], toolEmbedding: number[]): number;
+}
+
+/**
+ * Interface for custom scoring/ranking functions
+ */
+export interface ScoringFunction {
+  /**
+   * Apply custom scoring logic to similarity score
+   * @param similarity - Raw similarity score from SimilarityFunction
+   * @param tool - The tool being scored (access metadata here)
+   * @returns Final score for ranking. Higher is better.
+   */
+  score(similarity: number, tool: Tool): number;
+}
+
+/**
+ * Default cosine similarity implementation
+ */
+export class CosineSimilarity implements SimilarityFunction {
+  compute(a: number[], b: number[]): number {
+    if (a.length !== b.length) {
+      throw new Error(`Vector dimensions must match: ${a.length} !== ${b.length}`);
+    }
+
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+
+    for (let i = 0; i < a.length; i++) {
+      dotProduct += a[i] * b[i];
+      normA += a[i] * a[i];
+      normB += b[i] * b[i];
+    }
+
+    normA = Math.sqrt(normA);
+    normB = Math.sqrt(normB);
+
+    if (normA === 0 || normB === 0) {
+      return 0;
+    }
+
+    return dotProduct / (normA * normB);
+  }
+}
+
+/**
+ * Euclidean distance converted to similarity score
+ * Uses: similarity = 1 / (1 + distance)
+ */
+export class EuclideanSimilarity implements SimilarityFunction {
+  compute(a: number[], b: number[]): number {
+    if (a.length !== b.length) {
+      throw new Error(`Vector dimensions must match: ${a.length} !== ${b.length}`);
+    }
+
+    let sumSquares = 0;
+    for (let i = 0; i < a.length; i++) {
+      const diff = a[i] - b[i];
+      sumSquares += diff * diff;
+    }
+
+    const distance = Math.sqrt(sumSquares);
+    return 1.0 / (1.0 + distance);
+  }
+}
+
+/**
+ * Dot product similarity (unnormalized cosine)
+ */
+export class DotProductSimilarity implements SimilarityFunction {
+  compute(a: number[], b: number[]): number {
+    if (a.length !== b.length) {
+      throw new Error(`Vector dimensions must match: ${a.length} !== ${b.length}`);
+    }
+
+    let dotProduct = 0;
+    for (let i = 0; i < a.length; i++) {
+      dotProduct += a[i] * b[i];
+    }
+
+    return dotProduct;
+  }
+}
+
+/**
+ * Default priority-based scoring
+ * Multiplies similarity by tool's priority metadata
+ */
+export class PriorityScoring implements ScoringFunction {
+  private maxScore: number;
+
+  constructor(maxScore: number = 1.0) {
+    this.maxScore = maxScore;
+  }
+
+  score(similarity: number, tool: Tool): number {
+    const priority = (tool.metadata.priority as number) ?? 1.0;
+    const boosted = similarity * priority;
+    return Math.min(boosted, this.maxScore);
+  }
+}
+
+/**
+ * Weighted scoring combining multiple factors
+ */
+export class WeightedScoring implements ScoringFunction {
+  private similarityWeight: number;
+  private priorityWeight: number;
+  private maxScore: number;
+
+  constructor(
+    similarityWeight: number = 0.8,
+    priorityWeight: number = 0.2,
+    maxScore: number = 1.0
+  ) {
+    this.similarityWeight = similarityWeight;
+    this.priorityWeight = priorityWeight;
+    this.maxScore = maxScore;
+  }
+
+  score(similarity: number, tool: Tool): number {
+    const priority = (tool.metadata.priority as number) ?? 1.0;
+    const normalizedPriority = Math.min(priority / 2.0, 1.0);
+
+    const weighted =
+      this.similarityWeight * similarity +
+      this.priorityWeight * normalizedPriority;
+
+    return Math.min(weighted, this.maxScore);
+  }
+}
+
+/**
+ * Scoring that boosts tools matching specified tags
+ */
+export class TagBoostScoring implements ScoringFunction {
+  private boostTags: Set<string>;
+  private boostFactor: number;
+  private maxScore: number;
+
+  constructor(
+    boostTags: string[] = [],
+    boostFactor: number = 1.5,
+    maxScore: number = 1.0
+  ) {
+    this.boostTags = new Set(boostTags);
+    this.boostFactor = boostFactor;
+    this.maxScore = maxScore;
+  }
+
+  score(similarity: number, tool: Tool): number {
+    const toolTags = new Set(tool.metadata.tags as string[] ?? []);
+    const hasMatchingTag = [...toolTags].some(tag => this.boostTags.has(tag));
+
+    const boosted = hasMatchingTag ? similarity * this.boostFactor : similarity;
+    return Math.min(boosted, this.maxScore);
+  }
+}
+
+/**
+ * Combine multiple scoring functions in sequence
+ */
+export class CompositeScoring implements ScoringFunction {
+  private scorers: ScoringFunction[];
+
+  constructor(scorers: ScoringFunction[]) {
+    this.scorers = scorers;
+  }
+
+  score(similarity: number, tool: Tool): number {
+    let currentScore = similarity;
+    for (const scorer of this.scorers) {
+      currentScore = scorer.score(currentScore, tool);
+    }
+    return currentScore;
+  }
+}
+
+// Default instances for convenience
+export const DEFAULT_SIMILARITY = new CosineSimilarity();
+export const DEFAULT_SCORING = new PriorityScoring();