@radaros/core 0.1.0

package/src/agent/types.ts

@@ -0,0 +1,77 @@
+import type { z } from "zod";
+import type { ModelProvider } from "../models/provider.js";
+import type { ToolDef, ToolCallResult } from "../tools/types.js";
+import type { Memory } from "../memory/memory.js";
+import type { StorageDriver } from "../storage/driver.js";
+import type { EventBus } from "../events/event-bus.js";
+import type { TokenUsage, StreamChunk, MessageContent } from "../models/types.js";
+import type { RunContext } from "./run-context.js";
+import type { LogLevel } from "../logger/logger.js";
+
+export interface AgentConfig {
+  name: string;
+  model: ModelProvider;
+  tools?: ToolDef[];
+  instructions?: string | ((ctx: RunContext) => string);
+  memory?: Memory;
+  storage?: StorageDriver;
+  sessionId?: string;
+  userId?: string;
+  addHistoryToMessages?: boolean;
+  numHistoryRuns?: number;
+  maxToolRoundtrips?: number;
+  temperature?: number;
+  structuredOutput?: z.ZodSchema;
+  hooks?: AgentHooks;
+  guardrails?: {
+    input?: InputGuardrail[];
+    output?: OutputGuardrail[];
+  };
+  eventBus?: EventBus;
+  /** Logging level. Set to "debug" for tool call details, "info" for summaries, "silent" to disable. Default: "silent". */
+  logLevel?: LogLevel;
+}
+
+export interface RunOpts {
+  sessionId?: string;
+  userId?: string;
+  metadata?: Record<string, unknown>;
+  /** Per-request API key override passed to the model provider. */
+  apiKey?: string;
+}
+
+export interface RunOutput {
+  text: string;
+  toolCalls: ToolCallResult[];
+  usage: TokenUsage;
+  /** Parsed structured output if structuredOutput schema is set. */
+  structured?: unknown;
+  durationMs?: number;
+}
+
+export interface AgentHooks {
+  beforeRun?: (ctx: RunContext) => Promise<void>;
+  afterRun?: (ctx: RunContext, output: RunOutput) => Promise<void>;
+  onToolCall?: (
+    ctx: RunContext,
+    toolName: string,
+    args: unknown
+  ) => Promise<void>;
+  onError?: (ctx: RunContext, error: Error) => Promise<void>;
+}
+
+export type GuardrailResult =
+  | { pass: true }
+  | { pass: false; reason: string };
+
+export interface InputGuardrail {
+  name: string;
+  validate: (input: MessageContent, ctx: RunContext) => Promise<GuardrailResult>;
+}
+
+export interface OutputGuardrail {
+  name: string;
+  validate: (output: RunOutput, ctx: RunContext) => Promise<GuardrailResult>;
+}
+
+export type { StreamChunk };

package/src/events/event-bus.ts

@@ -0,0 +1,45 @@
+import { EventEmitter } from "node:events";
+import type { AgentEventMap } from "./types.js";
+
+type EventKey = keyof AgentEventMap;
+
+export class EventBus {
+  private emitter = new EventEmitter();
+
+  constructor() {
+    this.emitter.setMaxListeners(100);
+  }
+
+  on<K extends EventKey>(
+    event: K,
+    handler: (data: AgentEventMap[K]) => void
+  ): this {
+    this.emitter.on(event, handler as (...args: unknown[]) => void);
+    return this;
+  }
+
+  once<K extends EventKey>(
+    event: K,
+    handler: (data: AgentEventMap[K]) => void
+  ): this {
+    this.emitter.once(event, handler as (...args: unknown[]) => void);
+    return this;
+  }
+
+  off<K extends EventKey>(
+    event: K,
+    handler: (data: AgentEventMap[K]) => void
+  ): this {
+    this.emitter.off(event, handler as (...args: unknown[]) => void);
+    return this;
+  }
+
+  emit<K extends EventKey>(event: K, data: AgentEventMap[K]): boolean {
+    return this.emitter.emit(event, data);
+  }
+
+  removeAllListeners(event?: EventKey): this {
+    this.emitter.removeAllListeners(event);
+    return this;
+  }
+}

package/src/events/types.ts

@@ -0,0 +1,16 @@
+import type { RunOutput } from "../agent/types.js";
+
+export type AgentEventMap = {
+  "run.start": { runId: string; agentName: string; input: string };
+  "run.complete": { runId: string; output: RunOutput };
+  "run.error": { runId: string; error: Error };
+  "run.stream.chunk": { runId: string; chunk: string };
+  "tool.call": { runId: string; toolName: string; args: unknown };
+  "tool.result": { runId: string; toolName: string; result: unknown };
+  "team.delegate": { runId: string; memberId: string; task: string };
+  "workflow.step": {
+    runId: string;
+    stepName: string;
+    status: "start" | "done" | "error";
+  };
+};

package/src/guardrails/types.ts

@@ -0,0 +1,5 @@
+export type {
+  InputGuardrail,
+  OutputGuardrail,
+  GuardrailResult,
+} from "../agent/types.js";

package/src/hooks/types.ts

@@ -0,0 +1,6 @@
+export type {
+  AgentHooks,
+  InputGuardrail,
+  OutputGuardrail,
+  GuardrailResult,
+} from "../agent/types.js";

package/src/index.ts

@@ -0,0 +1,111 @@
+// Agent
+export { Agent } from "./agent/agent.js";
+export { RunContext } from "./agent/run-context.js";
+export { LLMLoop } from "./agent/llm-loop.js";
+export type {
+  AgentConfig,
+  RunOpts,
+  RunOutput,
+  AgentHooks,
+  InputGuardrail,
+  OutputGuardrail,
+  GuardrailResult,
+} from "./agent/types.js";
+
+// Team
+export { Team } from "./team/team.js";
+export { TeamMode } from "./team/types.js";
+export type { TeamConfig } from "./team/types.js";
+
+// Workflow
+export { Workflow } from "./workflow/workflow.js";
+export type {
+  WorkflowConfig,
+  WorkflowResult,
+  StepDef,
+  StepResult,
+  AgentStep,
+  FunctionStep,
+  ConditionStep,
+  ParallelStep,
+} from "./workflow/types.js";
+
+// Models
+export type { ModelProvider } from "./models/provider.js";
+export type {
+  ChatMessage,
+  MessageRole,
+  MessageContent,
+  ContentPart,
+  TextPart,
+  ImagePart,
+  AudioPart,
+  FilePart,
+  ToolCall,
+  ToolDefinition,
+  TokenUsage,
+  ModelResponse,
+  StreamChunk,
+  ModelConfig,
+} from "./models/types.js";
+export { getTextContent, isMultiModal } from "./models/types.js";
+export { ModelRegistry, registry, openai, anthropic, google, ollama } from "./models/registry.js";
+export { OpenAIProvider } from "./models/providers/openai.js";
+export { AnthropicProvider } from "./models/providers/anthropic.js";
+export { GoogleProvider } from "./models/providers/google.js";
+export { OllamaProvider } from "./models/providers/ollama.js";
+
+// Tools
+export { defineTool } from "./tools/define-tool.js";
+export { ToolExecutor } from "./tools/tool-executor.js";
+export type { ToolDef, ToolResult, ToolCallResult, Artifact } from "./tools/types.js";
+
+// Storage
+export type { StorageDriver } from "./storage/driver.js";
+export { InMemoryStorage } from "./storage/in-memory.js";
+export { SqliteStorage } from "./storage/sqlite.js";
+export { PostgresStorage } from "./storage/postgres.js";
+export { MongoDBStorage } from "./storage/mongodb.js";
+
+// Vector Stores
+export type {
+  VectorStore,
+  VectorDocument,
+  VectorSearchResult,
+  VectorSearchOptions,
+  EmbeddingProvider,
+} from "./vector/types.js";
+export { BaseVectorStore } from "./vector/base.js";
+export { InMemoryVectorStore } from "./vector/in-memory.js";
+export { PgVectorStore } from "./vector/pgvector.js";
+export type { PgVectorConfig } from "./vector/pgvector.js";
+export { QdrantVectorStore } from "./vector/qdrant.js";
+export type { QdrantConfig } from "./vector/qdrant.js";
+export { MongoDBVectorStore } from "./vector/mongodb.js";
+export type { MongoDBVectorConfig } from "./vector/mongodb.js";
+
+// Embedding Providers
+export { OpenAIEmbedding } from "./vector/embeddings/openai.js";
+export type { OpenAIEmbeddingConfig } from "./vector/embeddings/openai.js";
+export { GoogleEmbedding } from "./vector/embeddings/google.js";
+export type { GoogleEmbeddingConfig } from "./vector/embeddings/google.js";
+
+// Knowledge Base
+export { KnowledgeBase } from "./knowledge/knowledge-base.js";
+export type { KnowledgeBaseConfig, KnowledgeBaseToolConfig } from "./knowledge/knowledge-base.js";
+
+// Session
+export { SessionManager } from "./session/session-manager.js";
+export type { Session } from "./session/types.js";
+
+// Memory
+export { Memory } from "./memory/memory.js";
+export type { MemoryConfig, MemoryEntry } from "./memory/types.js";
+
+// Events
+export { EventBus } from "./events/event-bus.js";
+export type { AgentEventMap } from "./events/types.js";
+
+// Logger
+export { Logger } from "./logger/logger.js";
+export type { LogLevel, LoggerConfig } from "./logger/logger.js";

package/src/knowledge/knowledge-base.ts

@@ -0,0 +1,146 @@
+import { z } from "zod";
+import type { ToolDef } from "../tools/types.js";
+import type {
+  VectorStore,
+  VectorDocument,
+  VectorSearchResult,
+  VectorSearchOptions,
+} from "../vector/types.js";
+
+export interface KnowledgeBaseConfig {
+  /** Display name used in tool description auto-generation. */
+  name: string;
+  /** The underlying vector store (any backend). */
+  vectorStore: VectorStore;
+  /** Collection/index name inside the vector store. */
+  collection?: string;
+}
+
+export interface KnowledgeBaseToolConfig {
+  /** Tool name exposed to the LLM. Defaults to `search_<collection>`. */
+  toolName?: string;
+  /** Custom tool description. A sensible default is generated from the KB name. */
+  description?: string;
+  /** Number of results to return per search. Default 5. */
+  topK?: number;
+  /** Minimum similarity score to include. */
+  minScore?: number;
+  /** Metadata filter applied to every search. */
+  filter?: Record<string, unknown>;
+  /** Custom formatter for search results. Defaults to numbered list with scores. */
+  formatResults?: (results: VectorSearchResult[]) => string;
+}
+
+export class KnowledgeBase {
+  readonly name: string;
+  readonly collection: string;
+  private store: VectorStore;
+  private initialized = false;
+
+  constructor(config: KnowledgeBaseConfig) {
+    this.name = config.name;
+    this.store = config.vectorStore;
+    this.collection = config.collection ?? config.name.toLowerCase().replace(/\s+/g, "_");
+  }
+
+  async initialize(): Promise<void> {
+    if (this.initialized) return;
+    await this.store.initialize();
+    this.initialized = true;
+  }
+
+  async add(doc: VectorDocument): Promise<void> {
+    await this.ensureInit();
+    await this.store.upsert(this.collection, doc);
+  }
+
+  async addDocuments(docs: VectorDocument[]): Promise<void> {
+    await this.ensureInit();
+    await this.store.upsertBatch(this.collection, docs);
+  }
+
+  async search(
+    query: string,
+    options?: VectorSearchOptions
+  ): Promise<VectorSearchResult[]> {
+    await this.ensureInit();
+    return this.store.search(this.collection, query, options);
+  }
+
+  async get(id: string): Promise<VectorDocument | null> {
+    await this.ensureInit();
+    return this.store.get(this.collection, id);
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.ensureInit();
+    await this.store.delete(this.collection, id);
+  }
+
+  async clear(): Promise<void> {
+    await this.store.dropCollection(this.collection);
+  }
+
+  async close(): Promise<void> {
+    await this.store.close();
+  }
+
+  /**
+   * Returns a ToolDef that an Agent can use to search this knowledge base.
+   * Plug the result directly into `Agent({ tools: [kb.asTool()] })`.
+   */
+  asTool(config: KnowledgeBaseToolConfig = {}): ToolDef {
+    const topK = config.topK ?? 5;
+    const minScore = config.minScore;
+    const filter = config.filter;
+    const toolName =
+      config.toolName ?? `search_${this.collection}`;
+    const description =
+      config.description ??
+      `Search the "${this.name}" knowledge base for relevant information. Use this before answering questions related to ${this.name}.`;
+
+    const formatResults =
+      config.formatResults ?? defaultFormatResults;
+
+    const kb = this;
+
+    return {
+      name: toolName,
+      description,
+      parameters: z.object({
+        query: z.string().describe("Search query to find relevant documents"),
+      }),
+      execute: async (args: Record<string, unknown>) => {
+        const results = await kb.search(args.query as string, {
+          topK,
+          minScore,
+          filter,
+        });
+
+        if (results.length === 0) {
+          return "No relevant documents found in the knowledge base.";
+        }
+
+        return formatResults(results);
+      },
+    };
+  }
+
+  private async ensureInit(): Promise<void> {
+    if (!this.initialized) await this.initialize();
+  }
+}
+
+function defaultFormatResults(results: VectorSearchResult[]): string {
+  const lines = results.map((r, i) => {
+    const meta = r.metadata
+      ? Object.entries(r.metadata)
+          .filter(([, v]) => v !== undefined)
+          .map(([k, v]) => `${k}: ${v}`)
+          .join(", ")
+      : "";
+    const metaStr = meta ? ` | ${meta}` : "";
+    return `[${i + 1}] (score: ${r.score.toFixed(3)}${metaStr})\n${r.content}`;
+  });
+  return `Found ${results.length} relevant document(s):\n\n${lines.join("\n\n")}`;
+}

package/src/logger/logger.ts

@@ -0,0 +1,232 @@
+export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  silent: 4,
+};
+
+const C = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  italic: "\x1b[3m",
+
+  black: "\x1b[30m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  white: "\x1b[37m",
+
+  bgBlack: "\x1b[40m",
+  bgRed: "\x1b[41m",
+  bgGreen: "\x1b[42m",
+  bgYellow: "\x1b[43m",
+  bgBlue: "\x1b[44m",
+  bgMagenta: "\x1b[45m",
+  bgCyan: "\x1b[46m",
+
+  gray: "\x1b[90m",
+  brightGreen: "\x1b[92m",
+  brightYellow: "\x1b[93m",
+  brightBlue: "\x1b[94m",
+  brightMagenta: "\x1b[95m",
+  brightCyan: "\x1b[96m",
+};
+
+function noColor(str: string): string {
+  return str.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+export interface LoggerConfig {
+  level?: LogLevel;
+  color?: boolean;
+  prefix?: string;
+}
+
+export class Logger {
+  private level: LogLevel;
+  private color: boolean;
+  private prefix: string;
+
+  constructor(config: LoggerConfig = {}) {
+    this.level = config.level ?? "info";
+    this.color = config.color ?? process.stdout.isTTY !== false;
+    this.prefix = config.prefix ?? "radaros";
+  }
+
+  private c(code: string, text: string): string {
+    return this.color ? `${code}${text}${C.reset}` : text;
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    return LEVEL_ORDER[level] >= LEVEL_ORDER[this.level];
+  }
+
+  private tag(level: LogLevel): string {
+    switch (level) {
+      case "debug":
+        return this.c(C.gray, "DBG");
+      case "info":
+        return this.c(C.brightCyan, "INF");
+      case "warn":
+        return this.c(C.brightYellow, "WRN");
+      case "error":
+        return this.c(C.red, "ERR");
+      default:
+        return "";
+    }
+  }
+
+  private timestamp(): string {
+    const now = new Date();
+    const ts = now.toISOString().slice(11, 23);
+    return this.c(C.dim, ts);
+  }
+
+  private log(level: LogLevel, msg: string, data?: Record<string, unknown>): void {
+    if (!this.shouldLog(level)) return;
+    const parts = [
+      this.timestamp(),
+      this.tag(level),
+      this.c(C.dim, `[${this.prefix}]`),
+      msg,
+    ];
+    if (data && Object.keys(data).length > 0) {
+      const formatted = Object.entries(data)
+        .map(([k, v]) => `${this.c(C.dim, k + "=")}${this.formatValue(v)}`)
+        .join(" ");
+      parts.push(formatted);
+    }
+    console.log(parts.join(" "));
+  }
+
+  private formatValue(v: unknown): string {
+    if (typeof v === "number") return this.c(C.brightGreen, String(v));
+    if (typeof v === "string") return this.c(C.yellow, `"${v}"`);
+    if (typeof v === "boolean") return this.c(C.magenta, String(v));
+    return String(v);
+  }
+
+  debug(msg: string, data?: Record<string, unknown>) {
+    this.log("debug", msg, data);
+  }
+
+  info(msg: string, data?: Record<string, unknown>) {
+    this.log("info", msg, data);
+  }
+
+  warn(msg: string, data?: Record<string, unknown>) {
+    this.log("warn", msg, data);
+  }
+
+  error(msg: string, data?: Record<string, unknown>) {
+    this.log("error", msg, data);
+  }
+
+  // ── Formatted agent output helpers ────────────────────────────────────
+
+  private readonly boxWidth = 80;
+
+  private pipe(): string {
+    return this.c(C.brightCyan, "│");
+  }
+
+  private printBoxLine(label: string, value: string, labelColor = C.dim, valueColor = C.white): void {
+    const lines = value.split("\n");
+    const prefix = `${this.pipe()} ${this.c(labelColor, label)}`;
+    console.log(`${prefix}${this.c(valueColor, lines[0])}`);
+    const pad = " ".repeat(noColor(label).length);
+    for (let i = 1; i < lines.length; i++) {
+      console.log(`${this.pipe()} ${pad}${this.c(valueColor, lines[i])}`);
+    }
+  }
+
+  agentStart(agentName: string, input: string): void {
+    if (!this.shouldLog("info")) return;
+    const title = ` Agent: ${agentName} `;
+    const lineLen = Math.max(0, this.boxWidth - title.length - 2);
+    console.log("");
+    console.log(
+      this.c(C.bold + C.brightCyan, "┌─") +
+        this.c(C.bold + C.brightCyan, title) +
+        this.c(C.dim, "─".repeat(lineLen))
+    );
+    this.printBoxLine("Input:  ", input);
+    console.log(this.pipe());
+  }
+
+  toolCall(toolName: string, args: Record<string, unknown>): void {
+    if (!this.shouldLog("debug")) return;
+    const argsStr = JSON.stringify(args, null, 2);
+    console.log(
+      `${this.pipe()} ${this.c(C.brightMagenta, "⚡")} ${this.c(C.magenta, toolName)}`
+    );
+    if (argsStr !== "{}" && argsStr !== "[]") {
+      const truncated = argsStr.length > 200 ? argsStr.slice(0, 200) + "…" : argsStr;
+      for (const line of truncated.split("\n")) {
+        console.log(`${this.pipe()}   ${this.c(C.dim, line)}`);
+      }
+    }
+  }
+
+  toolResult(toolName: string, result: string): void {
+    if (!this.shouldLog("debug")) return;
+    const truncated = result.length > 300 ? result.slice(0, 300) + "…" : result;
+    console.log(
+      `${this.pipe()} ${this.c(C.green, "✓")} ${this.c(C.dim, toolName + " →")}`
+    );
+    for (const line of truncated.split("\n")) {
+      console.log(`${this.pipe()}   ${this.c(C.gray, line)}`);
+    }
+    console.log(this.pipe());
+  }
+
+  agentEnd(
+    agentName: string,
+    output: string,
+    usage: { promptTokens: number; completionTokens: number; totalTokens: number },
+    durationMs: number
+  ): void {
+    if (!this.shouldLog("info")) return;
+
+    console.log(this.pipe());
+    this.printBoxLine("Output: ", output);
+    console.log(this.pipe());
+
+    const tokensLine =
+      this.c(C.dim, "Tokens: ") +
+      this.c(C.brightGreen, `↑ ${usage.promptTokens}`) +
+      this.c(C.dim, "  ") +
+      this.c(C.brightGreen, `↓ ${usage.completionTokens}`) +
+      this.c(C.dim, "  ") +
+      this.c(C.bold + C.brightGreen, `Σ ${usage.totalTokens}`);
+
+    const duration =
+      this.c(C.dim, "Duration: ") +
+      this.c(C.yellow, this.formatDuration(durationMs));
+
+    console.log(`${this.pipe()} ${tokensLine}`);
+    console.log(`${this.pipe()} ${duration}`);
+    console.log(
+      this.c(C.bold + C.brightCyan, "└") +
+        this.c(C.dim, "─".repeat(this.boxWidth - 1))
+    );
+  }
+
+  separator(): void {
+    if (!this.shouldLog("info")) return;
+    console.log(this.c(C.dim, "─".repeat(this.boxWidth)));
+  }
+
+  private formatDuration(ms: number): string {
+    if (ms < 1000) return `${ms}ms`;
+    const secs = (ms / 1000).toFixed(1);
+    return `${secs}s`;
+  }
+}