@radaros/core 0.1.0

package/src/tools/tool-executor.ts

@@ -0,0 +1,131 @@
+import { createRequire } from "node:module";
+import type { ToolCall } from "../models/types.js";
+import type { RunContext } from "../agent/run-context.js";
+import type { ToolDef, ToolCallResult } from "./types.js";
+
+const _require = createRequire(import.meta.url);
+
+export class ToolExecutor {
+  private tools: Map<string, ToolDef>;
+  private concurrency: number;
+
+  constructor(tools: ToolDef[], concurrency: number = 5) {
+    this.tools = new Map(tools.map((t) => [t.name, t]));
+    this.concurrency = concurrency;
+  }
+
+  async executeAll(
+    toolCalls: ToolCall[],
+    ctx: RunContext
+  ): Promise<ToolCallResult[]> {
+    const results: ToolCallResult[] = [];
+
+    for (let i = 0; i < toolCalls.length; i += this.concurrency) {
+      const batch = toolCalls.slice(i, i + this.concurrency);
+      const batchResults = await Promise.allSettled(
+        batch.map((tc) => this.executeSingle(tc, ctx))
+      );
+
+      for (let j = 0; j < batchResults.length; j++) {
+        const settled = batchResults[j];
+        const tc = batch[j];
+
+        if (settled.status === "fulfilled") {
+          results.push(settled.value);
+        } else {
+          results.push({
+            toolCallId: tc.id,
+            toolName: tc.name,
+            result: `Error: ${settled.reason?.message ?? "Unknown error"}`,
+            error: settled.reason?.message ?? "Unknown error",
+          });
+        }
+      }
+    }
+
+    return results;
+  }
+
+  private async executeSingle(
+    toolCall: ToolCall,
+    ctx: RunContext
+  ): Promise<ToolCallResult> {
+    const tool = this.tools.get(toolCall.name);
+    if (!tool) {
+      return {
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        result: `Error: Tool "${toolCall.name}" not found`,
+        error: `Tool "${toolCall.name}" not found`,
+      };
+    }
+
+    ctx.eventBus.emit("tool.call", {
+      runId: ctx.runId,
+      toolName: toolCall.name,
+      args: toolCall.arguments,
+    });
+
+    const parsed = tool.parameters.safeParse(toolCall.arguments);
+    if (!parsed.success) {
+      const errMsg = `Invalid arguments: ${parsed.error.message}`;
+      const result: ToolCallResult = {
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        result: errMsg,
+        error: errMsg,
+      };
+
+      ctx.eventBus.emit("tool.result", {
+        runId: ctx.runId,
+        toolName: toolCall.name,
+        result: errMsg,
+      });
+
+      return result;
+    }
+
+    const rawResult = await tool.execute(parsed.data, ctx);
+    const resultContent =
+      typeof rawResult === "string" ? rawResult : rawResult.content;
+
+    ctx.eventBus.emit("tool.result", {
+      runId: ctx.runId,
+      toolName: toolCall.name,
+      result: resultContent,
+    });
+
+    return {
+      toolCallId: toolCall.id,
+      toolName: toolCall.name,
+      result: rawResult,
+    };
+  }
+
+  getToolDefinitions(): Array<{
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+  }> {
+    const { zodToJsonSchema } = _require("zod-to-json-schema");
+    const defs: Array<{
+      name: string;
+      description: string;
+      parameters: Record<string, unknown>;
+    }> = [];
+
+    for (const tool of this.tools.values()) {
+      const jsonSchema = zodToJsonSchema(tool.parameters, {
+        target: "openApi3",
+      });
+
+      defs.push({
+        name: tool.name,
+        description: tool.description,
+        parameters: jsonSchema as Record<string, unknown>,
+      });
+    }
+
+    return defs;
+  }
+}

package/src/tools/types.ts

@@ -0,0 +1,27 @@
+import type { z } from "zod";
+import type { RunContext } from "../agent/run-context.js";
+
+export interface Artifact {
+  type: string;
+  data: unknown;
+  mimeType?: string;
+}
+
+export interface ToolResult {
+  content: string;
+  artifacts?: Artifact[];
+}
+
+export interface ToolDef {
+  name: string;
+  description: string;
+  parameters: z.ZodObject<any>;
+  execute: (args: Record<string, unknown>, ctx: RunContext) => Promise<string | ToolResult>;
+}
+
+export interface ToolCallResult {
+  toolCallId: string;
+  toolName: string;
+  result: string | ToolResult;
+  error?: string;
+}

package/src/vector/base.ts

@@ -0,0 +1,44 @@
+import type {
+  VectorStore,
+  VectorDocument,
+  VectorSearchResult,
+  VectorSearchOptions,
+  EmbeddingProvider,
+} from "./types.js";
+
+export abstract class BaseVectorStore implements VectorStore {
+  constructor(protected embedder?: EmbeddingProvider) {}
+
+  protected async ensureEmbedding(doc: VectorDocument): Promise<number[]> {
+    if (doc.embedding) return doc.embedding;
+    if (!this.embedder) {
+      throw new Error(
+        "No embedding provided on document and no EmbeddingProvider configured"
+      );
+    }
+    return this.embedder.embed(doc.content);
+  }
+
+  protected async ensureQueryVector(query: number[] | string): Promise<number[]> {
+    if (Array.isArray(query)) return query;
+    if (!this.embedder) {
+      throw new Error(
+        "String query requires an EmbeddingProvider to be configured"
+      );
+    }
+    return this.embedder.embed(query);
+  }
+
+  abstract initialize(): Promise<void>;
+  abstract upsert(collection: string, doc: VectorDocument): Promise<void>;
+  abstract upsertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
+  abstract search(
+    collection: string,
+    query: number[] | string,
+    options?: VectorSearchOptions
+  ): Promise<VectorSearchResult[]>;
+  abstract delete(collection: string, id: string): Promise<void>;
+  abstract get(collection: string, id: string): Promise<VectorDocument | null>;
+  abstract dropCollection(collection: string): Promise<void>;
+  abstract close(): Promise<void>;
+}

package/src/vector/embeddings/google.ts

@@ -0,0 +1,64 @@
+import { createRequire } from "node:module";
+import type { EmbeddingProvider } from "../types.js";
+
+const _require = createRequire(import.meta.url);
+
+export interface GoogleEmbeddingConfig {
+  apiKey?: string;
+  model?: string;
+  dimensions?: number;
+}
+
+const MODEL_DIMENSIONS: Record<string, number> = {
+  "text-embedding-004": 768,
+  "embedding-001": 768,
+};
+
+export class GoogleEmbedding implements EmbeddingProvider {
+  readonly dimensions: number;
+  private ai: any;
+  private model: string;
+
+  constructor(config: GoogleEmbeddingConfig = {}) {
+    this.model = config.model ?? "text-embedding-004";
+    this.dimensions =
+      config.dimensions ?? MODEL_DIMENSIONS[this.model] ?? 768;
+
+    try {
+      const { GoogleGenAI } = _require("@google/genai");
+      this.ai = new GoogleGenAI({
+        apiKey: config.apiKey ?? process.env.GOOGLE_API_KEY,
+      });
+    } catch {
+      throw new Error(
+        "@google/genai is required for GoogleEmbedding. Install it: npm install @google/genai"
+      );
+    }
+  }
+
+  async embed(text: string): Promise<number[]> {
+    const result = await this.ai.models.embedContent({
+      model: this.model,
+      contents: text,
+      ...(this.dimensions !== MODEL_DIMENSIONS[this.model]
+        ? { config: { outputDimensionality: this.dimensions } }
+        : {}),
+    });
+    return result.embeddings[0].values;
+  }
+
+  async embedBatch(texts: string[]): Promise<number[][]> {
+    const results = await Promise.all(
+      texts.map((text) =>
+        this.ai.models.embedContent({
+          model: this.model,
+          contents: text,
+          ...(this.dimensions !== MODEL_DIMENSIONS[this.model]
+            ? { config: { outputDimensionality: this.dimensions } }
+            : {}),
+        })
+      )
+    );
+    return results.map((r: any) => r.embeddings[0].values);
+  }
+}

package/src/vector/embeddings/openai.ts

@@ -0,0 +1,66 @@
+import { createRequire } from "node:module";
+import type { EmbeddingProvider } from "../types.js";
+
+const _require = createRequire(import.meta.url);
+
+export interface OpenAIEmbeddingConfig {
+  apiKey?: string;
+  baseURL?: string;
+  model?: string;
+  dimensions?: number;
+}
+
+const MODEL_DIMENSIONS: Record<string, number> = {
+  "text-embedding-3-small": 1536,
+  "text-embedding-3-large": 3072,
+  "text-embedding-ada-002": 1536,
+};
+
+export class OpenAIEmbedding implements EmbeddingProvider {
+  readonly dimensions: number;
+  private client: any;
+  private model: string;
+
+  constructor(config: OpenAIEmbeddingConfig = {}) {
+    this.model = config.model ?? "text-embedding-3-small";
+    this.dimensions =
+      config.dimensions ?? MODEL_DIMENSIONS[this.model] ?? 1536;
+
+    try {
+      const mod = _require("openai");
+      const OpenAI = mod.default ?? mod;
+      this.client = new OpenAI({
+        apiKey: config.apiKey ?? process.env.OPENAI_API_KEY,
+        baseURL: config.baseURL,
+      });
+    } catch {
+      throw new Error(
+        "openai package is required for OpenAIEmbedding. Install it: npm install openai"
+      );
+    }
+  }
+
+  async embed(text: string): Promise<number[]> {
+    const response = await this.client.embeddings.create({
+      model: this.model,
+      input: text,
+      ...(this.dimensions !== MODEL_DIMENSIONS[this.model]
+        ? { dimensions: this.dimensions }
+        : {}),
+    });
+    return response.data[0].embedding;
+  }
+
+  async embedBatch(texts: string[]): Promise<number[][]> {
+    const response = await this.client.embeddings.create({
+      model: this.model,
+      input: texts,
+      ...(this.dimensions !== MODEL_DIMENSIONS[this.model]
+        ? { dimensions: this.dimensions }
+        : {}),
+    });
+    return response.data
+      .sort((a: any, b: any) => a.index - b.index)
+      .map((d: any) => d.embedding);
+  }
+}

package/src/vector/in-memory.ts

@@ -0,0 +1,115 @@
+import { BaseVectorStore } from "./base.js";
+import type {
+  VectorDocument,
+  VectorSearchResult,
+  VectorSearchOptions,
+  EmbeddingProvider,
+} from "./types.js";
+
+interface StoredDoc {
+  id: string;
+  content: string;
+  embedding: number[];
+  metadata: Record<string, unknown>;
+}
+
+export class InMemoryVectorStore extends BaseVectorStore {
+  private collections = new Map<string, Map<string, StoredDoc>>();
+
+  constructor(embedder?: EmbeddingProvider) {
+    super(embedder);
+  }
+
+  async initialize(): Promise<void> {}
+
+  private getCol(collection: string): Map<string, StoredDoc> {
+    let col = this.collections.get(collection);
+    if (!col) {
+      col = new Map();
+      this.collections.set(collection, col);
+    }
+    return col;
+  }
+
+  async upsert(collection: string, doc: VectorDocument): Promise<void> {
+    const embedding = await this.ensureEmbedding(doc);
+    this.getCol(collection).set(doc.id, {
+      id: doc.id,
+      content: doc.content,
+      embedding,
+      metadata: doc.metadata ?? {},
+    });
+  }
+
+  async upsertBatch(collection: string, docs: VectorDocument[]): Promise<void> {
+    for (const doc of docs) {
+      await this.upsert(collection, doc);
+    }
+  }
+
+  async search(
+    collection: string,
+    query: number[] | string,
+    options?: VectorSearchOptions
+  ): Promise<VectorSearchResult[]> {
+    const vec = await this.ensureQueryVector(query);
+    const topK = options?.topK ?? 10;
+    const col = this.getCol(collection);
+
+    const scored: VectorSearchResult[] = [];
+    for (const doc of col.values()) {
+      const score = this.cosineSimilarity(vec, doc.embedding);
+      if (options?.minScore != null && score < options.minScore) continue;
+      if (options?.filter) {
+        let match = true;
+        for (const [k, v] of Object.entries(options.filter)) {
+          if (doc.metadata[k] !== v) {
+            match = false;
+            break;
+          }
+        }
+        if (!match) continue;
+      }
+      scored.push({
+        id: doc.id,
+        content: doc.content,
+        score,
+        metadata: doc.metadata,
+      });
+    }
+
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, topK);
+  }
+
+  private cosineSimilarity(a: number[], b: number[]): number {
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+      dot += a[i] * b[i];
+      normA += a[i] * a[i];
+      normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom === 0 ? 0 : dot / denom;
+  }
+
+  async delete(collection: string, id: string): Promise<void> {
+    this.getCol(collection).delete(id);
+  }
+
+  async get(collection: string, id: string): Promise<VectorDocument | null> {
+    const doc = this.getCol(collection).get(id);
+    if (!doc) return null;
+    return { id: doc.id, content: doc.content, metadata: doc.metadata };
+  }
+
+  async dropCollection(collection: string): Promise<void> {
+    this.collections.delete(collection);
+  }
+
+  async close(): Promise<void> {
+    this.collections.clear();
+  }
+}

package/src/vector/mongodb.ts

@@ -0,0 +1,241 @@
+import { createRequire } from "node:module";
+import { BaseVectorStore } from "./base.js";
+import type {
+  VectorDocument,
+  VectorSearchResult,
+  VectorSearchOptions,
+  EmbeddingProvider,
+} from "./types.js";
+
+const _require = createRequire(import.meta.url);
+
+export interface MongoDBVectorConfig {
+  uri: string;
+  dbName?: string;
+  /** Atlas Search index name (must be pre-created for $vectorSearch). Defaults to "vector_index". */
+  indexName?: string;
+}
+
+export class MongoDBVectorStore extends BaseVectorStore {
+  private client: any;
+  private db: any;
+  private indexName: string;
+  private dbName: string;
+  private useAtlas: boolean | null = null;
+
+  constructor(config: MongoDBVectorConfig, embedder?: EmbeddingProvider) {
+    super(embedder);
+    this.indexName = config.indexName ?? "vector_index";
+    this.dbName = config.dbName ?? "radaros_vectors";
+    try {
+      const { MongoClient } = _require("mongodb");
+      this.client = new MongoClient(config.uri);
+    } catch {
+      throw new Error(
+        "mongodb is required for MongoDBVectorStore. Install it: npm install mongodb"
+      );
+    }
+  }
+
+  async initialize(): Promise<void> {
+    await this.client.connect();
+    this.db = this.client.db(this.dbName);
+  }
+
+  private col(collection: string) {
+    return this.db.collection(collection);
+  }
+
+  async upsert(collection: string, doc: VectorDocument): Promise<void> {
+    const embedding = await this.ensureEmbedding(doc);
+    await this.col(collection).updateOne(
+      { _id: doc.id },
+      {
+        $set: {
+          content: doc.content,
+          embedding,
+          metadata: doc.metadata ?? {},
+          updatedAt: new Date(),
+        },
+      },
+      { upsert: true }
+    );
+  }
+
+  async upsertBatch(collection: string, docs: VectorDocument[]): Promise<void> {
+    const ops = await Promise.all(
+      docs.map(async (doc) => {
+        const embedding = await this.ensureEmbedding(doc);
+        return {
+          updateOne: {
+            filter: { _id: doc.id },
+            update: {
+              $set: {
+                content: doc.content,
+                embedding,
+                metadata: doc.metadata ?? {},
+                updatedAt: new Date(),
+              },
+            },
+            upsert: true,
+          },
+        };
+      })
+    );
+    if (ops.length > 0) {
+      await this.col(collection).bulkWrite(ops);
+    }
+  }
+
+  async search(
+    collection: string,
+    query: number[] | string,
+    options?: VectorSearchOptions
+  ): Promise<VectorSearchResult[]> {
+    const vec = await this.ensureQueryVector(query);
+
+    if (this.useAtlas === true) {
+      return this.atlasSearch(collection, vec, options);
+    }
+
+    if (this.useAtlas === false) {
+      return this.localSearch(collection, vec, options);
+    }
+
+    // First call: auto-detect Atlas support
+    try {
+      const results = await this.atlasSearch(collection, vec, options);
+      this.useAtlas = true;
+      return results;
+    } catch {
+      this.useAtlas = false;
+      return this.localSearch(collection, vec, options);
+    }
+  }
+
+  private async atlasSearch(
+    collection: string,
+    vec: number[],
+    options?: VectorSearchOptions
+  ): Promise<VectorSearchResult[]> {
+    const topK = options?.topK ?? 10;
+
+    const pipeline: Record<string, unknown>[] = [
+      {
+        $vectorSearch: {
+          index: this.indexName,
+          path: "embedding",
+          queryVector: vec,
+          numCandidates: topK * 10,
+          limit: topK,
+          ...(options?.filter ? { filter: this.buildFilter(options.filter) } : {}),
+        },
+      },
+      {
+        $addFields: {
+          score: { $meta: "vectorSearchScore" },
+        },
+      },
+    ];
+
+    if (options?.minScore != null) {
+      pipeline.push({ $match: { score: { $gte: options.minScore } } });
+    }
+
+    pipeline.push({
+      $project: { _id: 1, content: 1, score: 1, metadata: 1 },
+    });
+
+    const results = await this.col(collection).aggregate(pipeline).toArray();
+
+    return results.map((r: any) => ({
+      id: String(r._id),
+      content: r.content ?? "",
+      score: r.score,
+      metadata: r.metadata,
+    }));
+  }
+
+  private async localSearch(
+    collection: string,
+    vec: number[],
+    options?: VectorSearchOptions
+  ): Promise<VectorSearchResult[]> {
+    const topK = options?.topK ?? 10;
+    const filter: Record<string, unknown> = {};
+    if (options?.filter) {
+      for (const [k, v] of Object.entries(options.filter)) {
+        filter[`metadata.${k}`] = v;
+      }
+    }
+
+    const docs = await this.col(collection)
+      .find(filter, { projection: { _id: 1, content: 1, embedding: 1, metadata: 1 } })
+      .toArray();
+
+    const scored: VectorSearchResult[] = [];
+    for (const doc of docs) {
+      if (!doc.embedding) continue;
+      const score = cosine(vec, doc.embedding);
+      if (options?.minScore != null && score < options.minScore) continue;
+      scored.push({
+        id: String(doc._id),
+        content: doc.content ?? "",
+        score,
+        metadata: doc.metadata,
+      });
+    }
+
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, topK);
+  }
+
+  private buildFilter(
+    filter: Record<string, unknown>
+  ): Record<string, unknown> {
+    const conditions: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(filter)) {
+      conditions[`metadata.${key}`] = value;
+    }
+    return conditions;
+  }
+
+  async delete(collection: string, id: string): Promise<void> {
+    await this.col(collection).deleteOne({ _id: id });
+  }
+
+  async get(collection: string, id: string): Promise<VectorDocument | null> {
+    const doc = await this.col(collection).findOne({ _id: id });
+    if (!doc) return null;
+    return {
+      id: String(doc._id),
+      content: doc.content,
+      metadata: doc.metadata,
+    };
+  }
+
+  async dropCollection(collection: string): Promise<void> {
+    try {
+      await this.col(collection).drop();
+    } catch {
+      // collection may not exist
+    }
+  }
+
+  async close(): Promise<void> {
+    await this.client.close();
+  }
+}
+
+function cosine(a: number[], b: number[]): number {
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom === 0 ? 0 : dot / denom;
+}