@radaros/core 0.1.0

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@radaros/core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch"
+  },
+  "dependencies": {
+    "uuid": "^11.0.0",
+    "zod": "^3.23.0",
+    "zod-to-json-schema": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.1",
+    "@types/uuid": "^10.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/sdk": "^0.30.0",
+    "@google/genai": "^0.10.0",
+    "@qdrant/js-client-rest": "^1.0.0",
+    "better-sqlite3": "^11.0.0",
+    "mongodb": "^6.0.0",
+    "ollama": "^0.5.0",
+    "openai": "^4.0.0 || ^5.0.0 || ^6.0.0",
+    "pg": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "openai": {
+      "optional": true
+    },
+    "@anthropic-ai/sdk": {
+      "optional": true
+    },
+    "@google/genai": {
+      "optional": true
+    },
+    "ollama": {
+      "optional": true
+    },
+    "better-sqlite3": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "mongodb": {
+      "optional": true
+    },
+    "@qdrant/js-client-rest": {
+      "optional": true
+    }
+  }
+}

package/src/agent/agent.ts

@@ -0,0 +1,314 @@
+import { v4 as uuidv4 } from "uuid";
+import { EventBus } from "../events/event-bus.js";
+import { InMemoryStorage } from "../storage/in-memory.js";
+import { SessionManager } from "../session/session-manager.js";
+import { ToolExecutor } from "../tools/tool-executor.js";
+import { Logger } from "../logger/logger.js";
+import { LLMLoop } from "./llm-loop.js";
+import { RunContext } from "./run-context.js";
+import { getTextContent, type ChatMessage, type MessageContent, type StreamChunk } from "../models/types.js";
+import type {
+  AgentConfig,
+  RunOpts,
+  RunOutput,
+} from "./types.js";
+
+export class Agent {
+  readonly name: string;
+  readonly eventBus: EventBus;
+  readonly instructions?: string | ((ctx: RunContext) => string);
+
+  private config: AgentConfig;
+  private sessionManager: SessionManager;
+  private llmLoop: LLMLoop;
+  private logger: Logger;
+
+  get tools() {
+    return this.config.tools ?? [];
+  }
+
+  get modelId(): string {
+    return this.config.model.modelId;
+  }
+
+  get providerId(): string {
+    return this.config.model.providerId;
+  }
+
+  get hasStructuredOutput(): boolean {
+    return !!this.config.structuredOutput;
+  }
+
+  constructor(config: AgentConfig) {
+    this.config = config;
+    this.name = config.name;
+    this.instructions = config.instructions;
+    this.eventBus = config.eventBus ?? new EventBus();
+
+    const storage = config.storage ?? new InMemoryStorage();
+    this.sessionManager = new SessionManager(storage);
+
+    this.logger = new Logger({
+      level: config.logLevel ?? "silent",
+      prefix: config.name,
+    });
+
+    const toolExecutor =
+      config.tools && config.tools.length > 0
+        ? new ToolExecutor(config.tools)
+        : null;
+
+    this.llmLoop = new LLMLoop(config.model, toolExecutor, {
+      maxToolRoundtrips: config.maxToolRoundtrips ?? 10,
+      temperature: config.temperature,
+      structuredOutput: config.structuredOutput,
+      logger: this.logger,
+    });
+  }
+
+  async run(input: MessageContent, opts?: RunOpts): Promise<RunOutput> {
+    const startTime = Date.now();
+    const sessionId = opts?.sessionId ?? this.config.sessionId ?? uuidv4();
+    const userId = opts?.userId ?? this.config.userId;
+    const inputText = typeof input === "string" ? input : getTextContent(input);
+
+    const session = await this.sessionManager.getOrCreate(sessionId, userId);
+
+    const ctx = new RunContext({
+      sessionId,
+      userId,
+      metadata: opts?.metadata ?? {},
+      eventBus: this.eventBus,
+      sessionState: { ...session.state },
+    });
+
+    this.logger.agentStart(this.name, inputText);
+
+    this.eventBus.emit("run.start", {
+      runId: ctx.runId,
+      agentName: this.name,
+      input: inputText,
+    });
+
+    try {
+      if (this.config.hooks?.beforeRun) {
+        await this.config.hooks.beforeRun(ctx);
+      }
+
+      if (this.config.guardrails?.input) {
+        for (const guardrail of this.config.guardrails.input) {
+          const result = await guardrail.validate(input, ctx);
+          if (!result.pass) {
+            throw new Error(
+              `Input guardrail "${guardrail.name}" blocked: ${result.reason}`
+            );
+          }
+        }
+      }
+
+      const messages = await this.buildMessages(input, sessionId, ctx);
+      const output = await this.llmLoop.run(messages, ctx, opts?.apiKey);
+
+      output.durationMs = Date.now() - startTime;
+
+      if (this.config.guardrails?.output) {
+        for (const guardrail of this.config.guardrails.output) {
+          const result = await guardrail.validate(output, ctx);
+          if (!result.pass) {
+            throw new Error(
+              `Output guardrail "${guardrail.name}" blocked: ${result.reason}`
+            );
+          }
+        }
+      }
+
+      await this.sessionManager.appendMessages(sessionId, [
+        { role: "user", content: inputText },
+        { role: "assistant", content: output.text },
+      ]);
+      await this.sessionManager.updateState(sessionId, ctx.sessionState);
+
+      if (this.config.memory) {
+        await this.config.memory.addMessages(sessionId, [
+          { role: "user", content: inputText },
+          { role: "assistant", content: output.text },
+        ]);
+      }
+
+      if (this.config.hooks?.afterRun) {
+        await this.config.hooks.afterRun(ctx, output);
+      }
+
+      this.logger.agentEnd(this.name, output.text, output.usage, output.durationMs);
+
+      this.eventBus.emit("run.complete", {
+        runId: ctx.runId,
+        output,
+      });
+
+      return output;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+
+      this.logger.error(`Run failed: ${err.message}`);
+
+      if (this.config.hooks?.onError) {
+        await this.config.hooks.onError(ctx, err);
+      }
+
+      this.eventBus.emit("run.error", {
+        runId: ctx.runId,
+        error: err,
+      });
+
+      throw err;
+    }
+  }
+
+  async *stream(
+    input: MessageContent,
+    opts?: RunOpts
+  ): AsyncGenerator<StreamChunk> {
+    const sessionId = opts?.sessionId ?? this.config.sessionId ?? uuidv4();
+    const userId = opts?.userId ?? this.config.userId;
+    const inputText = typeof input === "string" ? input : getTextContent(input);
+
+    const session = await this.sessionManager.getOrCreate(sessionId, userId);
+
+    const ctx = new RunContext({
+      sessionId,
+      userId,
+      metadata: opts?.metadata ?? {},
+      eventBus: this.eventBus,
+      sessionState: { ...session.state },
+    });
+
+    this.eventBus.emit("run.start", {
+      runId: ctx.runId,
+      agentName: this.name,
+      input: inputText,
+    });
+
+    let fullText = "";
+    let streamOk = false;
+
+    try {
+      if (this.config.hooks?.beforeRun) {
+        await this.config.hooks.beforeRun(ctx);
+      }
+
+      if (this.config.guardrails?.input) {
+        for (const guardrail of this.config.guardrails.input) {
+          const result = await guardrail.validate(input, ctx);
+          if (!result.pass) {
+            throw new Error(
+              `Input guardrail "${guardrail.name}" blocked: ${result.reason}`
+            );
+          }
+        }
+      }
+
+      const messages = await this.buildMessages(input, sessionId, ctx);
+
+      for await (const chunk of this.llmLoop.stream(messages, ctx, opts?.apiKey)) {
+        if (chunk.type === "text") {
+          fullText += chunk.text;
+        }
+        yield chunk;
+      }
+
+      streamOk = true;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+
+      if (this.config.hooks?.onError) {
+        await this.config.hooks.onError(ctx, err);
+      }
+
+      this.eventBus.emit("run.error", {
+        runId: ctx.runId,
+        error: err,
+      });
+
+      throw err;
+    } finally {
+      if (streamOk) {
+        await this.sessionManager.appendMessages(sessionId, [
+          { role: "user", content: inputText },
+          { role: "assistant", content: fullText },
+        ]);
+        await this.sessionManager.updateState(sessionId, ctx.sessionState);
+
+        if (this.config.memory) {
+          await this.config.memory.addMessages(sessionId, [
+            { role: "user", content: inputText },
+            { role: "assistant", content: fullText },
+          ]);
+        }
+
+        this.eventBus.emit("run.complete", {
+          runId: ctx.runId,
+          output: {
+            text: fullText,
+            toolCalls: [],
+            usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+          },
+        });
+      }
+    }
+  }
+
+  private async buildMessages(
+    input: MessageContent,
+    sessionId: string,
+    ctx: RunContext
+  ): Promise<ChatMessage[]> {
+    const messages: ChatMessage[] = [];
+
+    let systemContent = "";
+    if (this.config.instructions) {
+      systemContent =
+        typeof this.config.instructions === "function"
+          ? this.config.instructions(ctx)
+          : this.config.instructions;
+    }
+
+    if (this.config.memory) {
+      const memoryContext = await this.config.memory.getContextString(
+        sessionId
+      );
+      if (memoryContext) {
+        systemContent = systemContent
+          ? `${systemContent}\n\n${memoryContext}`
+          : memoryContext;
+      }
+    }
+
+    if (systemContent) {
+      messages.push({ role: "system", content: systemContent });
+    }
+
+    if (this.config.addHistoryToMessages !== false) {
+      const limit = this.config.numHistoryRuns
+        ? this.config.numHistoryRuns * 2
+        : 20;
+      const history = await this.sessionManager.getHistory(sessionId, limit);
+      if (history.length > 0) {
+        this.logger.info(`Loaded ${history.length} history messages for session ${sessionId}`);
+        if (messages.length > 0 && messages[0].role === "system") {
+          messages[0] = {
+            ...messages[0],
+            content: `${getTextContent(messages[0].content)}\n\nThis is a multi-turn conversation. The previous messages in this session are included below. Use them to maintain context and answer questions about prior exchanges.`,
+          };
+        }
+      }
+      messages.push(...history);
+    }
+
+    messages.push({ role: "user", content: input });
+
+    this.logger.info(`Sending ${messages.length} messages to LLM: ${messages.map(m => `[${m.role}: ${typeof m.content === 'string' ? m.content.slice(0, 40) : '(multimodal)'}]`).join(', ')}`);
+
+    return messages;
+  }
+}

package/src/agent/llm-loop.ts

@@ -0,0 +1,263 @@
+import { createRequire } from "node:module";
+import type { z } from "zod";
+import type { ModelProvider } from "../models/provider.js";
+import {
+  getTextContent,
+  type ChatMessage,
+  type ModelConfig,
+  type StreamChunk,
+  type ToolDefinition,
+} from "../models/types.js";
+import type { ToolExecutor } from "../tools/tool-executor.js";
+import type { RunContext } from "./run-context.js";
+import type { RunOutput } from "./types.js";
+import type { ToolCallResult } from "../tools/types.js";
+import type { Logger } from "../logger/logger.js";
+
+const _require = createRequire(import.meta.url);
+
+export class LLMLoop {
+  private provider: ModelProvider;
+  private toolExecutor: ToolExecutor | null;
+  private maxToolRoundtrips: number;
+  private temperature?: number;
+  private maxTokens?: number;
+  private structuredOutput?: z.ZodSchema;
+  private logger?: Logger;
+
+  constructor(
+    provider: ModelProvider,
+    toolExecutor: ToolExecutor | null,
+    options: {
+      maxToolRoundtrips: number;
+      temperature?: number;
+      maxTokens?: number;
+      structuredOutput?: z.ZodSchema;
+      logger?: Logger;
+    }
+  ) {
+    this.provider = provider;
+    this.toolExecutor = toolExecutor;
+    this.maxToolRoundtrips = options.maxToolRoundtrips;
+    this.temperature = options.temperature;
+    this.maxTokens = options.maxTokens;
+    this.structuredOutput = options.structuredOutput;
+    this.logger = options.logger;
+  }
+
+  async run(messages: ChatMessage[], ctx: RunContext, apiKey?: string): Promise<RunOutput> {
+    const allToolCalls: ToolCallResult[] = [];
+    let totalPromptTokens = 0;
+    let totalCompletionTokens = 0;
+    const currentMessages = [...messages];
+    const toolDefs = this.toolExecutor?.getToolDefinitions() ?? [];
+
+    for (let roundtrip = 0; roundtrip <= this.maxToolRoundtrips; roundtrip++) {
+      const modelConfig: ModelConfig & { tools?: ToolDefinition[] } = {};
+      if (apiKey) modelConfig.apiKey = apiKey;
+      if (this.temperature !== undefined)
+        modelConfig.temperature = this.temperature;
+      if (this.maxTokens !== undefined) modelConfig.maxTokens = this.maxTokens;
+      if (toolDefs.length > 0) modelConfig.tools = toolDefs;
+
+      if (this.structuredOutput) {
+        modelConfig.responseFormat = {
+          type: "json_schema",
+          schema: this.zodToJsonSchema(this.structuredOutput),
+          name: "structured_response",
+        };
+      }
+
+      const response = await this.provider.generate(
+        currentMessages,
+        modelConfig
+      );
+
+      totalPromptTokens += response.usage.promptTokens;
+      totalCompletionTokens += response.usage.completionTokens;
+
+      currentMessages.push(response.message);
+
+      if (
+        response.finishReason !== "tool_calls" ||
+        !response.message.toolCalls?.length ||
+        !this.toolExecutor
+      ) {
+        const text = getTextContent(response.message.content);
+
+        const output: RunOutput = {
+          text,
+          toolCalls: allToolCalls,
+          usage: {
+            promptTokens: totalPromptTokens,
+            completionTokens: totalCompletionTokens,
+            totalTokens: totalPromptTokens + totalCompletionTokens,
+          },
+        };
+
+        if (this.structuredOutput && text) {
+          try {
+            const jsonStr = this.extractJson(text);
+            const parsed = JSON.parse(jsonStr);
+            output.structured = this.structuredOutput.parse(parsed);
+          } catch {
+            // structured parsing failed, raw text is still available
+          }
+        }
+
+        return output;
+      }
+
+      const toolResults = await this.toolExecutor.executeAll(
+        response.message.toolCalls,
+        ctx
+      );
+
+      allToolCalls.push(...toolResults);
+
+      for (const result of toolResults) {
+        const content =
+          typeof result.result === "string"
+            ? result.result
+            : result.result.content;
+
+        this.logger?.toolCall(result.toolName, {});
+        this.logger?.toolResult(result.toolName, typeof content === "string" ? content : JSON.stringify(content));
+
+        currentMessages.push({
+          role: "tool",
+          content,
+          toolCallId: result.toolCallId,
+          name: result.toolName,
+        });
+      }
+    }
+
+    const lastAssistantMsg = currentMessages
+      .reverse()
+      .find((m) => m.role === "assistant");
+
+    const text = getTextContent(lastAssistantMsg?.content ?? null);
+
+    return {
+      text,
+      toolCalls: allToolCalls,
+      usage: {
+        promptTokens: totalPromptTokens,
+        completionTokens: totalCompletionTokens,
+        totalTokens: totalPromptTokens + totalCompletionTokens,
+      },
+    };
+  }
+
+  async *stream(
+    messages: ChatMessage[],
+    ctx: RunContext,
+    apiKey?: string
+  ): AsyncGenerator<StreamChunk> {
+    const currentMessages = [...messages];
+    const toolDefs = this.toolExecutor?.getToolDefinitions() ?? [];
+
+    for (let roundtrip = 0; roundtrip <= this.maxToolRoundtrips; roundtrip++) {
+      const modelConfig: ModelConfig & { tools?: ToolDefinition[] } = {};
+      if (apiKey) modelConfig.apiKey = apiKey;
+      if (this.temperature !== undefined)
+        modelConfig.temperature = this.temperature;
+      if (this.maxTokens !== undefined) modelConfig.maxTokens = this.maxTokens;
+      if (toolDefs.length > 0) modelConfig.tools = toolDefs;
+
+      let fullText = "";
+      const pendingToolCalls: Array<{
+        id: string;
+        name: string;
+        args: string;
+      }> = [];
+      let finishReason = "stop";
+
+      const streamGen = this.provider.stream(currentMessages, modelConfig);
+
+      for await (const chunk of streamGen) {
+        yield chunk;
+
+        if (chunk.type === "text") {
+          fullText += chunk.text;
+          ctx.eventBus.emit("run.stream.chunk", {
+            runId: ctx.runId,
+            chunk: chunk.text,
+          });
+        } else if (chunk.type === "tool_call_start") {
+          pendingToolCalls.push({
+            id: chunk.toolCall.id,
+            name: chunk.toolCall.name,
+            args: "",
+          });
+        } else if (chunk.type === "tool_call_delta") {
+          const tc = pendingToolCalls.find(
+            (t) => t.id === chunk.toolCallId
+          );
+          if (tc) {
+            tc.args += chunk.argumentsDelta;
+          }
+        } else if (chunk.type === "finish") {
+          finishReason = chunk.finishReason;
+        }
+      }
+
+      if (finishReason !== "tool_calls" || pendingToolCalls.length === 0 || !this.toolExecutor) {
+        return;
+      }
+
+      const assistantMsg: ChatMessage = {
+        role: "assistant",
+        content: fullText || null,
+        toolCalls: pendingToolCalls.map((tc) => ({
+          id: tc.id,
+          name: tc.name,
+          arguments: JSON.parse(tc.args || "{}"),
+        })),
+      };
+      currentMessages.push(assistantMsg);
+
+      const toolResults = await this.toolExecutor.executeAll(
+        assistantMsg.toolCalls!,
+        ctx
+      );
+
+      for (const result of toolResults) {
+        const content =
+          typeof result.result === "string"
+            ? result.result
+            : result.result.content;
+
+        currentMessages.push({
+          role: "tool",
+          content,
+          toolCallId: result.toolCallId,
+          name: result.toolName,
+        });
+      }
+    }
+  }
+
+  private extractJson(text: string): string {
+    const fenceMatch = text.match(/```(?:json)?\s*\n?([\s\S]*?)```/);
+    if (fenceMatch) return fenceMatch[1].trim();
+
+    const braceStart = text.indexOf("{");
+    const braceEnd = text.lastIndexOf("}");
+    if (braceStart !== -1 && braceEnd > braceStart) {
+      return text.slice(braceStart, braceEnd + 1);
+    }
+
+    return text.trim();
+  }
+
+  private zodToJsonSchema(schema: z.ZodSchema): Record<string, unknown> {
+    try {
+      const { zodToJsonSchema } = _require("zod-to-json-schema");
+      return zodToJsonSchema(schema, { target: "openApi3" }) as Record<string, unknown>;
+    } catch {
+      return {};
+    }
+  }
+}

package/src/agent/run-context.ts

@@ -0,0 +1,35 @@
+import { v4 as uuidv4 } from "uuid";
+import type { EventBus } from "../events/event-bus.js";
+
+export class RunContext {
+  readonly runId: string;
+  readonly sessionId: string;
+  readonly userId?: string;
+  readonly metadata: Record<string, unknown>;
+  readonly eventBus: EventBus;
+  sessionState: Record<string, unknown>;
+
+  constructor(opts: {
+    sessionId: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+    eventBus: EventBus;
+    sessionState?: Record<string, unknown>;
+    runId?: string;
+  }) {
+    this.runId = opts.runId ?? uuidv4();
+    this.sessionId = opts.sessionId;
+    this.userId = opts.userId;
+    this.metadata = opts.metadata ?? {};
+    this.eventBus = opts.eventBus;
+    this.sessionState = opts.sessionState ?? {};
+  }
+
+  getState<T>(key: string): T | undefined {
+    return this.sessionState[key] as T | undefined;
+  }
+
+  setState(key: string, value: unknown): void {
+    this.sessionState[key] = value;
+  }
+}