@radaros/core 0.3.2 → 0.3.4

package/src/memory/user-memory.ts

@@ -0,0 +1,211 @@
+import { v4 as uuidv4 } from "uuid";
+import { z } from "zod";
+import { InMemoryStorage } from "../storage/in-memory.js";
+import type { StorageDriver } from "../storage/driver.js";
+import type { ModelProvider } from "../models/provider.js";
+import type { ChatMessage } from "../models/types.js";
+import type { ToolDef } from "../tools/types.js";
+
+const USER_MEMORY_NS = "memory:user";
+
+export interface UserMemoryConfig {
+  storage?: StorageDriver;
+  /** LLM used for auto-extraction of facts from conversations. */
+  model?: ModelProvider;
+  /** Maximum number of facts stored per user (default 100). */
+  maxFacts?: number;
+  /** Whether auto-extraction is enabled (default true). */
+  enabled?: boolean;
+}
+
+export interface UserFact {
+  id: string;
+  fact: string;
+  createdAt: Date;
+  source: "auto" | "manual";
+}
+
+const EXTRACTION_PROMPT = `You are a memory extraction assistant. Analyze the conversation below and extract important facts about the user that would be useful for future personalization.
+
+Rules:
+- Extract concrete facts like preferences, location, profession, interests, goals, communication style
+- Each fact should be a short, self-contained statement (e.g., "Lives in Mumbai", "Prefers concise answers")
+- Do NOT extract transient information (e.g., "asked about weather today")
+- Do NOT extract information about the assistant
+- If there are no new meaningful facts, return an empty array
+- Return ONLY a valid JSON array of strings, nothing else
+
+Existing facts about this user (avoid duplicates):
+{existingFacts}
+
+Conversation:
+{conversation}
+
+Return a JSON array of new fact strings:`;
+
+export class UserMemory {
+  private storage: StorageDriver;
+  private model?: ModelProvider;
+  private maxFacts: number;
+  private enabled: boolean;
+  private initPromise: Promise<void> | null = null;
+
+  constructor(config?: UserMemoryConfig) {
+    this.storage = config?.storage ?? new InMemoryStorage();
+    this.model = config?.model;
+    this.maxFacts = config?.maxFacts ?? 100;
+    this.enabled = config?.enabled ?? true;
+  }
+
+  private ensureInitialized(): Promise<void> {
+    if (!this.initPromise) {
+      this.initPromise = (async () => {
+        if (typeof (this.storage as any).initialize === "function") {
+          await (this.storage as any).initialize();
+        }
+      })();
+    }
+    return this.initPromise;
+  }
+
+  async getFacts(userId: string): Promise<UserFact[]> {
+    await this.ensureInitialized();
+    return (await this.storage.get<UserFact[]>(USER_MEMORY_NS, userId)) ?? [];
+  }
+
+  async addFacts(userId: string, facts: string[], source: "auto" | "manual" = "manual"): Promise<void> {
+    await this.ensureInitialized();
+    const existing = await this.getFacts(userId);
+    const existingSet = new Set(existing.map((f) => f.fact.toLowerCase()));
+
+    const newFacts: UserFact[] = [];
+    for (const fact of facts) {
+      const normalized = fact.trim();
+      if (!normalized || existingSet.has(normalized.toLowerCase())) continue;
+      newFacts.push({
+        id: uuidv4(),
+        fact: normalized,
+        createdAt: new Date(),
+        source,
+      });
+      existingSet.add(normalized.toLowerCase());
+    }
+
+    if (newFacts.length === 0) return;
+
+    let updated = [...existing, ...newFacts];
+    if (updated.length > this.maxFacts) {
+      updated = updated.slice(updated.length - this.maxFacts);
+    }
+
+    await this.storage.set(USER_MEMORY_NS, userId, updated);
+  }
+
+  async removeFact(userId: string, factId: string): Promise<void> {
+    await this.ensureInitialized();
+    const existing = await this.getFacts(userId);
+    const updated = existing.filter((f) => f.id !== factId);
+    await this.storage.set(USER_MEMORY_NS, userId, updated);
+  }
+
+  async clear(userId: string): Promise<void> {
+    await this.ensureInitialized();
+    await this.storage.delete(USER_MEMORY_NS, userId);
+  }
+
+  async getContextString(userId: string): Promise<string> {
+    if (!this.enabled) return "";
+    const facts = await this.getFacts(userId);
+    if (facts.length === 0) return "";
+    const factList = facts.map((f) => `- ${f.fact}`).join("\n");
+    return `What you know about this user:\n${factList}`;
+  }
+
+  asTool(config?: { name?: string; description?: string }): ToolDef {
+    const mem = this;
+    return {
+      name: config?.name ?? "recall_user_facts",
+      description:
+        config?.description ??
+        "Retrieve stored facts about the current user — preferences, background, interests, and other personal details from past conversations. Call this when the user asks what you know or remember about them.",
+      parameters: z.object({}),
+      execute: async (_args, ctx) => {
+        const uid = ctx.userId;
+        if (!uid) return "No user identified for this session.";
+        const facts = await mem.getFacts(uid);
+        if (facts.length === 0) return "No stored facts about this user yet.";
+        return facts.map((f) => `- ${f.fact}`).join("\n");
+      },
+    };
+  }
+
+  async extractAndStore(
+    userId: string,
+    messages: ChatMessage[],
+    fallbackModel?: ModelProvider
+  ): Promise<void> {
+    if (!this.enabled) return;
+
+    const model = this.model ?? fallbackModel;
+    if (!model) return;
+
+    try {
+      const existing = await this.getFacts(userId);
+      const existingStr =
+        existing.length > 0
+          ? existing.map((f) => `- ${f.fact}`).join("\n")
+          : "(none)";
+
+      const conversationStr = messages
+        .filter((m) => m.role === "user" || m.role === "assistant")
+        .map((m) => {
+          const content = typeof m.content === "string" ? m.content : "(multimodal)";
+          return `${m.role}: ${content}`;
+        })
+        .join("\n");
+
+      const prompt = EXTRACTION_PROMPT
+        .replace("{existingFacts}", existingStr)
+        .replace("{conversation}", conversationStr);
+
+      const response = await model.generate(
+        [{ role: "user", content: prompt }],
+        { temperature: 0, maxTokens: 500 }
+      );
+
+      const text =
+        typeof response.message.content === "string"
+          ? response.message.content
+          : "";
+
+      if (!text) return;
+
+      const jsonStr = this.extractJsonArray(text);
+      const parsed = JSON.parse(jsonStr);
+
+      if (Array.isArray(parsed) && parsed.length > 0) {
+        const validFacts = parsed.filter(
+          (f: unknown) => typeof f === "string" && f.trim().length > 0
+        );
+        if (validFacts.length > 0) {
+          await this.addFacts(userId, validFacts, "auto");
+        }
+      }
+    } catch (err) {
+      console.warn("[UserMemory] extractAndStore failed:", (err as Error).message ?? err);
+    }
+  }
+
+  private extractJsonArray(text: string): string {
+    const fenceMatch = text.match(/```(?:json)?\s*\n?([\s\S]*?)```/);
+    if (fenceMatch) return fenceMatch[1].trim();
+
+    const bracketStart = text.indexOf("[");
+    const bracketEnd = text.lastIndexOf("]");
+    if (bracketStart !== -1 && bracketEnd > bracketStart) {
+      return text.slice(bracketStart, bracketEnd + 1);
+    }
+
+    return text.trim();
+  }
+}

package/src/models/providers/anthropic.ts

@@ -81,6 +81,13 @@ export class AnthropicProvider implements ModelProvider {
     if (options?.tools?.length) {
       params.tools = this.toAnthropicTools(options.tools);
     }
+    if (options?.reasoning?.enabled) {
+      params.thinking = {
+        type: "enabled",
+        budget_tokens: options.reasoning.budgetTokens ?? 10000,
+      };
+      delete params.temperature;
+    }
 
     const client = this.getClient(options?.apiKey);
     const response = await client.messages.create(params);
@@ -109,11 +116,19 @@ export class AnthropicProvider implements ModelProvider {
     if (options?.tools?.length) {
       params.tools = this.toAnthropicTools(options.tools);
     }
+    if (options?.reasoning?.enabled) {
+      params.thinking = {
+        type: "enabled",
+        budget_tokens: options.reasoning.budgetTokens ?? 10000,
+      };
+      delete params.temperature;
+    }
 
     const client = this.getClient(options?.apiKey);
     const stream = await client.messages.create(params);
 
     let currentToolId = "";
+    let inThinkingBlock = false;
 
     for await (const event of stream) {
       switch (event.type) {
@@ -127,11 +142,15 @@ export class AnthropicProvider implements ModelProvider {
                 name: event.content_block.name,
               },
             };
+          } else if (event.content_block?.type === "thinking") {
+            inThinkingBlock = true;
           }
           break;
         }
         case "content_block_delta": {
-          if (event.delta?.type === "text_delta") {
+          if (event.delta?.type === "thinking_delta") {
+            yield { type: "thinking", text: event.delta.thinking };
+          } else if (event.delta?.type === "text_delta") {
             yield { type: "text", text: event.delta.text };
           } else if (event.delta?.type === "input_json_delta") {
             yield {
@@ -143,7 +162,9 @@ export class AnthropicProvider implements ModelProvider {
           break;
         }
         case "content_block_stop": {
-          if (currentToolId) {
+          if (inThinkingBlock) {
+            inThinkingBlock = false;
+          } else if (currentToolId) {
             yield { type: "tool_call_end", toolCallId: currentToolId };
             currentToolId = "";
           }
@@ -288,13 +309,16 @@ export class AnthropicProvider implements ModelProvider {
     }));
   }
 
-  private normalizeResponse(response: any): ModelResponse {
+  private normalizeResponse(response: any): ModelResponse & { thinking?: string } {
     const toolCalls: ToolCall[] = [];
     let textContent = "";
+    let thinkingContent = "";
 
     for (const block of response.content ?? []) {
       if (block.type === "text") {
         textContent += block.text;
+      } else if (block.type === "thinking") {
+        thinkingContent += block.thinking;
       } else if (block.type === "tool_use") {
         toolCalls.push({
           id: block.id,
@@ -316,7 +340,7 @@ export class AnthropicProvider implements ModelProvider {
     if (response.stop_reason === "tool_use") finishReason = "tool_calls";
     else if (response.stop_reason === "max_tokens") finishReason = "length";
 
-    return {
+    const result: ModelResponse & { thinking?: string } = {
       message: {
         role: "assistant",
         content: textContent || null,
@@ -326,5 +350,11 @@ export class AnthropicProvider implements ModelProvider {
       finishReason,
       raw: response,
     };
+
+    if (thinkingContent) {
+      result.thinking = thinkingContent;
+    }
+
+    return result;
   }
 }

package/src/models/providers/google.ts

@@ -82,6 +82,12 @@ export class GoogleProvider implements ModelProvider {
       }
     }
 
+    if (options?.reasoning?.enabled) {
+      config.thinkingConfig = {
+        thinkingBudget: options.reasoning.budgetTokens ?? 10000,
+      };
+    }
+
     const params: Record<string, unknown> = {
       model: this.modelId,
       contents,
@@ -116,6 +122,12 @@ export class GoogleProvider implements ModelProvider {
     if (options?.topP !== undefined) config.topP = options.topP;
     if (options?.stop) config.stopSequences = options.stop;
 
+    if (options?.reasoning?.enabled) {
+      config.thinkingConfig = {
+        thinkingBudget: options.reasoning.budgetTokens ?? 10000,
+      };
+    }
+
     const params: Record<string, unknown> = {
       model: this.modelId,
       contents,
@@ -142,7 +154,9 @@ export class GoogleProvider implements ModelProvider {
       if (!candidate?.content?.parts) continue;
 
       for (const part of candidate.content.parts) {
-        if (part.text) {
+        if (part.thought) {
+          yield { type: "thinking", text: part.text ?? "" };
+        } else if (part.text) {
           yield { type: "text", text: part.text };
         }
 
@@ -313,16 +327,19 @@ export class GoogleProvider implements ModelProvider {
     return cleaned;
   }
 
-  private normalizeResponse(response: any): ModelResponse {
+  private normalizeResponse(response: any): ModelResponse & { thinking?: string } {
     const candidate = response.candidates?.[0];
     const parts = candidate?.content?.parts ?? [];
 
     let textContent = "";
+    let thinkingContent = "";
     const toolCalls: ToolCall[] = [];
     let toolCallCounter = 0;
 
     for (const part of parts) {
-      if (part.text) {
+      if (part.thought && part.text) {
+        thinkingContent += part.text;
+      } else if (part.text) {
         textContent += part.text;
       }
       if (part.functionCall) {
@@ -334,10 +351,12 @@ export class GoogleProvider implements ModelProvider {
       }
     }
 
+    const thinkingTokens = response.usageMetadata?.thoughtsTokenCount ?? 0;
     const usage: TokenUsage = {
       promptTokens: response.usageMetadata?.promptTokenCount ?? 0,
       completionTokens: response.usageMetadata?.candidatesTokenCount ?? 0,
       totalTokens: response.usageMetadata?.totalTokenCount ?? 0,
+      ...(thinkingTokens > 0 ? { reasoningTokens: thinkingTokens } : {}),
     };
 
     let finishReason: ModelResponse["finishReason"] = "stop";
@@ -347,7 +366,7 @@ export class GoogleProvider implements ModelProvider {
     else if (candidate?.finishReason === "SAFETY")
       finishReason = "content_filter";
 
-    return {
+    const result: ModelResponse & { thinking?: string } = {
       message: {
         role: "assistant",
         content: textContent || null,
@@ -357,5 +376,11 @@ export class GoogleProvider implements ModelProvider {
       finishReason,
       raw: response,
     };
+
+    if (thinkingContent) {
+      result.thinking = thinkingContent;
+    }
+
+    return result;
   }
 }

package/src/models/providers/openai.ts

@@ -72,8 +72,12 @@ export class OpenAIProvider implements ModelProvider {
       messages: this.toOpenAIMessages(messages),
     };
 
-    if (options?.temperature !== undefined)
-      params.temperature = options.temperature;
+    if (options?.reasoning?.enabled) {
+      params.reasoning_effort = options.reasoning.effort ?? "medium";
+    } else {
+      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;
@@ -98,8 +102,12 @@ export class OpenAIProvider implements ModelProvider {
       stream: true,
     };
 
-    if (options?.temperature !== undefined)
-      params.temperature = options.temperature;
+    if (options?.reasoning?.enabled) {
+      params.reasoning_effort = options.reasoning.effort ?? "medium";
+    } else {
+      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;
@@ -165,11 +173,16 @@ export class OpenAIProvider implements ModelProvider {
         }
       }
 
+      if (delta?.reasoning_content) {
+        yield { type: "thinking", text: delta.reasoning_content };
+      }
+
       if (choice.finish_reason) {
         for (const [, tc] of activeToolCalls) {
           yield { type: "tool_call_end", toolCallId: tc.id };
         }
 
+        const reasoningTkns = chunk.usage?.completion_tokens_details?.reasoning_tokens ?? 0;
         yield {
           type: "finish",
           finishReason:
@@ -181,6 +194,7 @@ export class OpenAIProvider implements ModelProvider {
                 promptTokens: chunk.usage.prompt_tokens ?? 0,
                 completionTokens: chunk.usage.completion_tokens ?? 0,
                 totalTokens: chunk.usage.total_tokens ?? 0,
+                ...(reasoningTkns > 0 ? { reasoningTokens: reasoningTkns } : {}),
               }
             : undefined,
         };
@@ -287,7 +301,7 @@ export class OpenAIProvider implements ModelProvider {
     }));
   }
 
-  private normalizeResponse(response: any): ModelResponse {
+  private normalizeResponse(response: any): ModelResponse & { thinking?: string } {
     const choice = response.choices[0];
     const msg = choice.message;
 
@@ -297,10 +311,12 @@ export class OpenAIProvider implements ModelProvider {
       arguments: JSON.parse(tc.function.arguments || "{}"),
     }));
 
+    const reasoningTokens = response.usage?.completion_tokens_details?.reasoning_tokens ?? 0;
     const usage: TokenUsage = {
       promptTokens: response.usage?.prompt_tokens ?? 0,
       completionTokens: response.usage?.completion_tokens ?? 0,
       totalTokens: response.usage?.total_tokens ?? 0,
+      ...(reasoningTokens > 0 ? { reasoningTokens } : {}),
     };
 
     let finishReason: ModelResponse["finishReason"] = "stop";
@@ -309,7 +325,7 @@ export class OpenAIProvider implements ModelProvider {
     else if (choice.finish_reason === "content_filter")
       finishReason = "content_filter";
 
-    return {
+    const result: ModelResponse & { thinking?: string } = {
       message: {
         role: "assistant",
         content: msg.content ?? null,
@@ -319,5 +335,11 @@ export class OpenAIProvider implements ModelProvider {
       finishReason,
       raw: response,
     };
+
+    if (msg.reasoning_content) {
+      result.thinking = msg.reasoning_content;
+    }
+
+    return result;
   }
 }

package/src/models/providers/vertex.ts

@@ -108,6 +108,12 @@ export class VertexAIProvider implements ModelProvider {
       }
     }
 
+    if (options?.reasoning?.enabled) {
+      config.thinkingConfig = {
+        thinkingBudget: options.reasoning.budgetTokens ?? 10000,
+      };
+    }
+
     const params: Record<string, unknown> = {
       model: this.modelId,
       contents,
@@ -140,6 +146,12 @@ export class VertexAIProvider implements ModelProvider {
     if (options?.topP !== undefined) config.topP = options.topP;
     if (options?.stop) config.stopSequences = options.stop;
 
+    if (options?.reasoning?.enabled) {
+      config.thinkingConfig = {
+        thinkingBudget: options.reasoning.budgetTokens ?? 10000,
+      };
+    }
+
     const params: Record<string, unknown> = {
       model: this.modelId,
       contents,
@@ -163,7 +175,9 @@ export class VertexAIProvider implements ModelProvider {
       if (!candidate?.content?.parts) continue;
 
       for (const part of candidate.content.parts) {
-        if (part.text) {
+        if (part.thought) {
+          yield { type: "thinking", text: part.text ?? "" };
+        } else if (part.text) {
           yield { type: "text", text: part.text };
         }
 
@@ -354,16 +368,21 @@ export class VertexAIProvider implements ModelProvider {
     return cleaned;
   }
 
-  private normalizeResponse(response: any): ModelResponse {
+  private normalizeResponse(response: any): ModelResponse & { thinking?: string } {
     const candidate = response.candidates?.[0];
     const parts = candidate?.content?.parts ?? [];
 
     let textContent = "";
+    let thinkingContent = "";
     const toolCalls: ToolCall[] = [];
     let toolCallCounter = 0;
 
     for (const part of parts) {
-      if (part.text) textContent += part.text;
+      if (part.thought && part.text) {
+        thinkingContent += part.text;
+      } else if (part.text) {
+        textContent += part.text;
+      }
       if (part.functionCall) {
         toolCalls.push({
           id: `vertex_tc_${toolCallCounter++}`,
@@ -373,10 +392,12 @@ export class VertexAIProvider implements ModelProvider {
       }
     }
 
+    const thinkingTokens = response.usageMetadata?.thoughtsTokenCount ?? 0;
     const usage: TokenUsage = {
       promptTokens: response.usageMetadata?.promptTokenCount ?? 0,
       completionTokens: response.usageMetadata?.candidatesTokenCount ?? 0,
       totalTokens: response.usageMetadata?.totalTokenCount ?? 0,
+      ...(thinkingTokens > 0 ? { reasoningTokens: thinkingTokens } : {}),
     };
 
     let finishReason: ModelResponse["finishReason"] = "stop";
@@ -386,7 +407,7 @@ export class VertexAIProvider implements ModelProvider {
     else if (candidate?.finishReason === "SAFETY")
       finishReason = "content_filter";
 
-    return {
+    const result: ModelResponse & { thinking?: string } = {
       message: {
         role: "assistant",
         content: textContent || null,
@@ -396,5 +417,11 @@ export class VertexAIProvider implements ModelProvider {
       finishReason,
       raw: response,
     };
+
+    if (thinkingContent) {
+      result.thinking = thinkingContent;
+    }
+
+    return result;
   }
 }

package/src/models/types.ts

@@ -64,6 +64,7 @@ export interface TokenUsage {
   promptTokens: number;
   completionTokens: number;
   totalTokens: number;
+  reasoningTokens?: number;
 }
 
 // ── Model response ────────────────────────────────────────────────────────
@@ -77,6 +78,7 @@ export interface ModelResponse {
 
 export type StreamChunk =
   | { type: "text"; text: string }
+  | { type: "thinking"; 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 }
@@ -84,6 +86,14 @@ export type StreamChunk =
 
 // ── Model config ──────────────────────────────────────────────────────────
 
+export interface ReasoningConfig {
+  enabled: boolean;
+  /** Reasoning effort for OpenAI o-series models. */
+  effort?: "low" | "medium" | "high";
+  /** Token budget for thinking (Anthropic / Gemini). */
+  budgetTokens?: number;
+}
+
 export interface ModelConfig {
   temperature?: number;
   maxTokens?: number;
@@ -92,6 +102,8 @@ export interface ModelConfig {
   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;
+  /** Enable extended thinking / reasoning. */
+  reasoning?: ReasoningConfig;
 }
 
 // ── Helpers ───────────────────────────────────────────────────────────────

package/src/tools/define-tool.ts

@@ -1,6 +1,6 @@
 import type { z } from "zod";
 import type { RunContext } from "../agent/run-context.js";
-import type { ToolDef, ToolResult } from "./types.js";
+import type { ToolDef, ToolResult, ToolCacheConfig } from "./types.js";
 
 export function defineTool<T extends z.ZodObject<any>>(config: {
   name: string;
@@ -10,11 +10,13 @@ export function defineTool<T extends z.ZodObject<any>>(config: {
     args: z.infer<T>,
     ctx: RunContext
   ) => Promise<string | ToolResult>;
+  cache?: ToolCacheConfig;
 }): ToolDef {
   return {
     name: config.name,
     description: config.description,
     parameters: config.parameters,
     execute: config.execute as ToolDef["execute"],
+    cache: config.cache,
   };
 }