@radaros/core 0.1.0

package/src/models/providers/openai.ts

@@ -0,0 +1,323 @@
+import { createRequire } from "node:module";
+import type { ModelProvider } from "../provider.js";
+import {
+  getTextContent,
+  isMultiModal,
+  type ChatMessage,
+  type ContentPart,
+  type ModelConfig,
+  type ModelResponse,
+  type StreamChunk,
+  type ToolDefinition,
+  type TokenUsage,
+  type ToolCall,
+} from "../types.js";
+
+const _require = createRequire(import.meta.url);
+
+interface OpenAIConfig {
+  apiKey?: string;
+  baseURL?: string;
+}
+
+export class OpenAIProvider implements ModelProvider {
+  readonly providerId = "openai";
+  readonly modelId: string;
+  private client: any;
+  private OpenAICtor: any;
+  private baseURL?: string;
+  private clientCache = new Map<string, any>();
+
+  constructor(modelId: string, config?: OpenAIConfig) {
+    this.modelId = modelId;
+    this.baseURL = config?.baseURL;
+    try {
+      const mod = _require("openai");
+      this.OpenAICtor = mod.default ?? mod;
+      const key = config?.apiKey ?? process.env.OPENAI_API_KEY;
+      if (key) {
+        this.client = new this.OpenAICtor({ apiKey: key, baseURL: config?.baseURL });
+      }
+    } catch {
+      throw new Error(
+        "openai package is required for OpenAIProvider. Install it: npm install openai"
+      );
+    }
+  }
+
+  private getClient(apiKey?: string): any {
+    if (apiKey) {
+      let cached = this.clientCache.get(apiKey);
+      if (!cached) {
+        cached = new this.OpenAICtor({ apiKey, baseURL: this.baseURL });
+        this.clientCache.set(apiKey, cached);
+      }
+      return cached;
+    }
+    if (this.client) return this.client;
+    const envKey = process.env.OPENAI_API_KEY;
+    if (envKey) {
+      this.client = new this.OpenAICtor({ apiKey: envKey, baseURL: this.baseURL });
+      return this.client;
+    }
+    throw new Error("No OpenAI API key provided. Pass it via the x-openai-api-key header, apiKey in request body, or set OPENAI_API_KEY env var.");
+  }
+
+  async generate(
+    messages: ChatMessage[],
+    options?: ModelConfig & { tools?: ToolDefinition[] }
+  ): Promise<ModelResponse> {
+    const params: Record<string, unknown> = {
+      model: this.modelId,
+      messages: this.toOpenAIMessages(messages),
+    };
+
+    if (options?.temperature !== undefined)
+      params.temperature = options.temperature;
+    if (options?.maxTokens !== undefined)
+      params.max_tokens = options.maxTokens;
+    if (options?.topP !== undefined) params.top_p = options.topP;
+    if (options?.stop) params.stop = options.stop;
+    this.applyResponseFormat(params, options);
+    if (options?.tools?.length) {
+      params.tools = this.toOpenAITools(options.tools);
+    }
+
+    const client = this.getClient(options?.apiKey);
+    const response = await client.chat.completions.create(params);
+    return this.normalizeResponse(response);
+  }
+
+  async *stream(
+    messages: ChatMessage[],
+    options?: ModelConfig & { tools?: ToolDefinition[] }
+  ): AsyncGenerator<StreamChunk> {
+    const params: Record<string, unknown> = {
+      model: this.modelId,
+      messages: this.toOpenAIMessages(messages),
+      stream: true,
+    };
+
+    if (options?.temperature !== undefined)
+      params.temperature = options.temperature;
+    if (options?.maxTokens !== undefined)
+      params.max_tokens = options.maxTokens;
+    if (options?.topP !== undefined) params.top_p = options.topP;
+    if (options?.stop) params.stop = options.stop;
+    this.applyResponseFormat(params, options);
+    if (options?.tools?.length) {
+      params.tools = this.toOpenAITools(options.tools);
+    }
+
+    const client = this.getClient(options?.apiKey);
+    const stream = await client.chat.completions.create(params);
+
+    const activeToolCalls = new Map<
+      number,
+      { id: string; name: string; args: string }
+    >();
+
+    for await (const chunk of stream) {
+      const choice = chunk.choices?.[0];
+      if (!choice) continue;
+
+      const delta = choice.delta;
+
+      if (delta?.content) {
+        yield { type: "text", text: delta.content };
+      }
+
+      if (delta?.tool_calls) {
+        for (const tc of delta.tool_calls) {
+          const idx = tc.index ?? 0;
+
+          if (tc.id) {
+            activeToolCalls.set(idx, {
+              id: tc.id,
+              name: tc.function?.name ?? "",
+              args: tc.function?.arguments ?? "",
+            });
+            yield {
+              type: "tool_call_start",
+              toolCall: {
+                id: tc.id,
+                name: tc.function?.name ?? "",
+              },
+            };
+          } else if (tc.function?.arguments) {
+            const existing = activeToolCalls.get(idx);
+            if (existing) {
+              existing.args += tc.function.arguments;
+              yield {
+                type: "tool_call_delta",
+                toolCallId: existing.id,
+                argumentsDelta: tc.function.arguments,
+              };
+            }
+          }
+
+          if (tc.function?.name && !tc.id) {
+            const existing = activeToolCalls.get(idx);
+            if (existing) {
+              existing.name = tc.function.name;
+            }
+          }
+        }
+      }
+
+      if (choice.finish_reason) {
+        for (const [, tc] of activeToolCalls) {
+          yield { type: "tool_call_end", toolCallId: tc.id };
+        }
+
+        yield {
+          type: "finish",
+          finishReason:
+            choice.finish_reason === "tool_calls"
+              ? "tool_calls"
+              : choice.finish_reason,
+          usage: chunk.usage
+            ? {
+                promptTokens: chunk.usage.prompt_tokens ?? 0,
+                completionTokens: chunk.usage.completion_tokens ?? 0,
+                totalTokens: chunk.usage.total_tokens ?? 0,
+              }
+            : undefined,
+        };
+      }
+    }
+  }
+
+  private applyResponseFormat(params: Record<string, unknown>, options?: ModelConfig): void {
+    if (!options?.responseFormat) return;
+    if (options.responseFormat === "json") {
+      params.response_format = { type: "json_object" };
+    } else if (options.responseFormat === "text") {
+      // default
+    } else if (typeof options.responseFormat === "object") {
+      params.response_format = {
+        type: "json_schema",
+        json_schema: {
+          name: options.responseFormat.name ?? "response",
+          schema: options.responseFormat.schema,
+          strict: true,
+        },
+      };
+    }
+  }
+
+  private toOpenAIMessages(messages: ChatMessage[]): unknown[] {
+    return messages.map((msg) => {
+      if (msg.role === "assistant" && msg.toolCalls?.length) {
+        return {
+          role: "assistant",
+          content: getTextContent(msg.content),
+          tool_calls: msg.toolCalls.map((tc) => ({
+            id: tc.id,
+            type: "function",
+            function: {
+              name: tc.name,
+              arguments: JSON.stringify(tc.arguments),
+            },
+          })),
+        };
+      }
+
+      if (msg.role === "tool") {
+        return {
+          role: "tool",
+          tool_call_id: msg.toolCallId,
+          content: getTextContent(msg.content),
+        };
+      }
+
+      if (isMultiModal(msg.content)) {
+        return {
+          role: msg.role,
+          content: msg.content.map((part) => this.partToOpenAI(part)),
+        };
+      }
+
+      return {
+        role: msg.role,
+        content: msg.content ?? "",
+      };
+    });
+  }
+
+  private partToOpenAI(part: ContentPart): unknown {
+    switch (part.type) {
+      case "text":
+        return { type: "text", text: part.text };
+      case "image": {
+        const isUrl = part.data.startsWith("http://") || part.data.startsWith("https://");
+        return {
+          type: "image_url",
+          image_url: {
+            url: isUrl ? part.data : `data:${part.mimeType ?? "image/png"};base64,${part.data}`,
+          },
+        };
+      }
+      case "audio":
+        return {
+          type: "input_audio",
+          input_audio: {
+            data: part.data,
+            format: part.mimeType?.split("/")[1] ?? "mp3",
+          },
+        };
+      case "file":
+        return {
+          type: "text",
+          text: `[File: ${part.filename ?? "attachment"} (${part.mimeType})]`,
+        };
+    }
+  }
+
+  private toOpenAITools(
+    tools: ToolDefinition[]
+  ): unknown[] {
+    return tools.map((t) => ({
+      type: "function",
+      function: {
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters,
+      },
+    }));
+  }
+
+  private normalizeResponse(response: any): ModelResponse {
+    const choice = response.choices[0];
+    const msg = choice.message;
+
+    const toolCalls: ToolCall[] = (msg.tool_calls ?? []).map((tc: any) => ({
+      id: tc.id,
+      name: tc.function.name,
+      arguments: JSON.parse(tc.function.arguments || "{}"),
+    }));
+
+    const usage: TokenUsage = {
+      promptTokens: response.usage?.prompt_tokens ?? 0,
+      completionTokens: response.usage?.completion_tokens ?? 0,
+      totalTokens: response.usage?.total_tokens ?? 0,
+    };
+
+    let finishReason: ModelResponse["finishReason"] = "stop";
+    if (choice.finish_reason === "tool_calls") finishReason = "tool_calls";
+    else if (choice.finish_reason === "length") finishReason = "length";
+    else if (choice.finish_reason === "content_filter")
+      finishReason = "content_filter";
+
+    return {
+      message: {
+        role: "assistant",
+        content: msg.content ?? null,
+        toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+      },
+      usage,
+      finishReason,
+      raw: response,
+    };
+  }
+}

package/src/models/registry.ts

@@ -0,0 +1,90 @@
+import type { ModelProvider } from "./provider.js";
+import { OpenAIProvider } from "./providers/openai.js";
+import { AnthropicProvider } from "./providers/anthropic.js";
+import { GoogleProvider } from "./providers/google.js";
+import { OllamaProvider } from "./providers/ollama.js";
+
+type ProviderFactory = (
+  modelId: string,
+  config?: Record<string, unknown>
+) => ModelProvider;
+
+export class ModelRegistry {
+  private factories = new Map<string, ProviderFactory>();
+
+  register(providerId: string, factory: ProviderFactory): void {
+    this.factories.set(providerId, factory);
+  }
+
+  resolve(
+    providerId: string,
+    modelId: string,
+    config?: Record<string, unknown>
+  ): ModelProvider {
+    const factory = this.factories.get(providerId);
+    if (!factory) {
+      throw new Error(
+        `Unknown provider "${providerId}". Register it first with registry.register().`
+      );
+    }
+    return factory(modelId, config);
+  }
+
+  has(providerId: string): boolean {
+    return this.factories.has(providerId);
+  }
+}
+
+export const registry = new ModelRegistry();
+
+registry.register(
+  "openai",
+  (modelId, config) =>
+    new OpenAIProvider(modelId, config as { apiKey?: string; baseURL?: string })
+);
+
+registry.register(
+  "anthropic",
+  (modelId, config) =>
+    new AnthropicProvider(modelId, config as { apiKey?: string })
+);
+
+registry.register(
+  "google",
+  (modelId, config) =>
+    new GoogleProvider(modelId, config as { apiKey?: string })
+);
+
+registry.register(
+  "ollama",
+  (modelId, config) =>
+    new OllamaProvider(modelId, config as { host?: string })
+);
+
+export function openai(
+  modelId: string,
+  config?: { apiKey?: string; baseURL?: string }
+): ModelProvider {
+  return registry.resolve("openai", modelId, config);
+}
+
+export function anthropic(
+  modelId: string,
+  config?: { apiKey?: string }
+): ModelProvider {
+  return registry.resolve("anthropic", modelId, config);
+}
+
+export function google(
+  modelId: string,
+  config?: { apiKey?: string }
+): ModelProvider {
+  return registry.resolve("google", modelId, config);
+}
+
+export function ollama(
+  modelId: string,
+  config?: { host?: string }
+): ModelProvider {
+  return registry.resolve("ollama", modelId, config);
+}

package/src/models/types.ts

@@ -0,0 +1,112 @@
+export type MessageRole = "system" | "user" | "assistant" | "tool";
+
+// ── Multi-modal content parts ─────────────────────────────────────────────
+
+export interface TextPart {
+  type: "text";
+  text: string;
+}
+
+export interface ImagePart {
+  type: "image";
+  /** Base64-encoded image data OR a URL. */
+  data: string;
+  mimeType?: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+}
+
+export interface AudioPart {
+  type: "audio";
+  /** Base64-encoded audio data. */
+  data: string;
+  mimeType?: "audio/mp3" | "audio/wav" | "audio/ogg" | "audio/webm";
+}
+
+export interface FilePart {
+  type: "file";
+  /** Base64-encoded file data OR a URL. */
+  data: string;
+  mimeType: string;
+  filename?: string;
+}
+
+export type ContentPart = TextPart | ImagePart | AudioPart | FilePart;
+
+/** Convenience: plain string, or an array of multi-modal content parts. */
+export type MessageContent = string | ContentPart[];
+
+// ── Chat message ──────────────────────────────────────────────────────────
+
+export interface ChatMessage {
+  role: MessageRole;
+  content: MessageContent | null;
+  toolCalls?: ToolCall[];
+  toolCallId?: string;
+  name?: string;
+}
+
+// ── Tool definitions ──────────────────────────────────────────────────────
+
+export interface ToolCall {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+}
+
+// ── Token usage ───────────────────────────────────────────────────────────
+
+export interface TokenUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+
+// ── Model response ────────────────────────────────────────────────────────
+
+export interface ModelResponse {
+  message: ChatMessage;
+  usage: TokenUsage;
+  finishReason: "stop" | "tool_calls" | "length" | "content_filter";
+  raw: unknown;
+}
+
+export type StreamChunk =
+  | { type: "text"; text: string }
+  | { type: "tool_call_start"; toolCall: { id: string; name: string } }
+  | { type: "tool_call_delta"; toolCallId: string; argumentsDelta: string }
+  | { type: "tool_call_end"; toolCallId: string }
+  | { type: "finish"; finishReason: string; usage?: TokenUsage };
+
+// ── Model config ──────────────────────────────────────────────────────────
+
+export interface ModelConfig {
+  temperature?: number;
+  maxTokens?: number;
+  topP?: number;
+  stop?: string[];
+  responseFormat?: "text" | "json" | { type: "json_schema"; schema: Record<string, unknown>; name?: string };
+  /** Per-request API key override. When provided, the provider uses this key instead of the one set at construction. */
+  apiKey?: string;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+
+/** Extract the text content from a MessageContent value. */
+export function getTextContent(content: MessageContent | null): string {
+  if (content === null) return "";
+  if (typeof content === "string") return content;
+  return content
+    .filter((p): p is TextPart => p.type === "text")
+    .map((p) => p.text)
+    .join("");
+}
+
+/** Check if content has multi-modal parts. */
+export function isMultiModal(content: MessageContent | null): content is ContentPart[] {
+  return Array.isArray(content);
+}

package/src/session/session-manager.ts

@@ -0,0 +1,75 @@
+import type { StorageDriver } from "../storage/driver.js";
+import type { ChatMessage } from "../models/types.js";
+import type { Session } from "./types.js";
+
+const NAMESPACE = "sessions";
+
+export class SessionManager {
+  constructor(private storage: StorageDriver) {}
+
+  async getOrCreate(sessionId: string, userId?: string): Promise<Session> {
+    const existing = await this.storage.get<Session>(NAMESPACE, sessionId);
+    if (existing) return existing;
+
+    const session: Session = {
+      sessionId,
+      userId,
+      messages: [],
+      state: {},
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+
+    await this.storage.set(NAMESPACE, sessionId, session);
+    return session;
+  }
+
+  async appendMessage(sessionId: string, msg: ChatMessage): Promise<void> {
+    const session = await this.getOrCreate(sessionId);
+    session.messages.push(msg);
+    session.updatedAt = new Date();
+    await this.storage.set(NAMESPACE, sessionId, session);
+  }
+
+  async appendMessages(
+    sessionId: string,
+    msgs: ChatMessage[]
+  ): Promise<void> {
+    const session = await this.getOrCreate(sessionId);
+    session.messages.push(...msgs);
+    session.updatedAt = new Date();
+    await this.storage.set(NAMESPACE, sessionId, session);
+  }
+
+  async getHistory(
+    sessionId: string,
+    limit?: number
+  ): Promise<ChatMessage[]> {
+    const session = await this.storage.get<Session>(NAMESPACE, sessionId);
+    if (!session) return [];
+
+    if (limit && limit > 0) {
+      return session.messages.slice(-limit);
+    }
+    return session.messages;
+  }
+
+  async updateState(
+    sessionId: string,
+    patch: Record<string, unknown>
+  ): Promise<void> {
+    const session = await this.getOrCreate(sessionId);
+    Object.assign(session.state, patch);
+    session.updatedAt = new Date();
+    await this.storage.set(NAMESPACE, sessionId, session);
+  }
+
+  async getState(sessionId: string): Promise<Record<string, unknown>> {
+    const session = await this.storage.get<Session>(NAMESPACE, sessionId);
+    return session?.state ?? {};
+  }
+
+  async deleteSession(sessionId: string): Promise<void> {
+    await this.storage.delete(NAMESPACE, sessionId);
+  }
+}

package/src/session/types.ts

@@ -0,0 +1,10 @@
+import type { ChatMessage } from "../models/types.js";
+
+export interface Session {
+  sessionId: string;
+  userId?: string;
+  messages: ChatMessage[];
+  state: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+}

package/src/storage/driver.ts

@@ -0,0 +1,10 @@
+export interface StorageDriver {
+  get<T>(namespace: string, key: string): Promise<T | null>;
+  set<T>(namespace: string, key: string, value: T): Promise<void>;
+  delete(namespace: string, key: string): Promise<void>;
+  list<T>(
+    namespace: string,
+    prefix?: string
+  ): Promise<Array<{ key: string; value: T }>>;
+  close(): Promise<void>;
+}

package/src/storage/in-memory.ts

@@ -0,0 +1,44 @@
+import type { StorageDriver } from "./driver.js";
+
+export class InMemoryStorage implements StorageDriver {
+  private store = new Map<string, string>();
+
+  private makeKey(namespace: string, key: string): string {
+    return `${namespace}:${key}`;
+  }
+
+  async get<T>(namespace: string, key: string): Promise<T | null> {
+    const raw = this.store.get(this.makeKey(namespace, key));
+    if (raw === undefined) return null;
+    return JSON.parse(raw) as T;
+  }
+
+  async set<T>(namespace: string, key: string, value: T): Promise<void> {
+    this.store.set(this.makeKey(namespace, key), JSON.stringify(value));
+  }
+
+  async delete(namespace: string, key: string): Promise<void> {
+    this.store.delete(this.makeKey(namespace, key));
+  }
+
+  async list<T>(
+    namespace: string,
+    prefix?: string
+  ): Promise<Array<{ key: string; value: T }>> {
+    const nsPrefix = prefix ? `${namespace}:${prefix}` : `${namespace}:`;
+    const results: Array<{ key: string; value: T }> = [];
+
+    for (const [fullKey, raw] of this.store.entries()) {
+      if (fullKey.startsWith(nsPrefix)) {
+        const key = fullKey.slice(namespace.length + 1);
+        results.push({ key, value: JSON.parse(raw) as T });
+      }
+    }
+
+    return results;
+  }
+
+  async close(): Promise<void> {
+    this.store.clear();
+  }
+}