@paean-ai/adk 0.2.19 → 0.2.20

package/dist/esm/index_web.js

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export * from "./common.js";

package/dist/esm/memory/base_memory_service.js

@@ -0,0 +1,5 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */

package/dist/esm/memory/in_memory_memory_service.js

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+class InMemoryMemoryService {
+  constructor() {
+    this.memories = [];
+    this.sessionEvents = {};
+  }
+  async addSessionToMemory(session) {
+    const userKey = getUserKey(session.appName, session.userId);
+    if (!this.sessionEvents[userKey]) {
+      this.sessionEvents[userKey] = {};
+    }
+    this.sessionEvents[userKey][session.id] = session.events.filter(
+      (event) => {
+        var _a, _b, _c;
+        return ((_c = (_b = (_a = event.content) == null ? void 0 : _a.parts) == null ? void 0 : _b.length) != null ? _c : 0) > 0;
+      }
+    );
+  }
+  async searchMemory(req) {
+    var _a, _b;
+    const userKey = getUserKey(req.appName, req.userId);
+    if (!this.sessionEvents[userKey]) {
+      return Promise.resolve({ memories: [] });
+    }
+    const wordsInQuery = req.query.toLowerCase().split(/\s+/);
+    const response = { memories: [] };
+    for (const sessionEvents of Object.values(this.sessionEvents[userKey])) {
+      for (const event of sessionEvents) {
+        if (!((_b = (_a = event.content) == null ? void 0 : _a.parts) == null ? void 0 : _b.length)) {
+          continue;
+        }
+        const joinedText = event.content.parts.map((part) => part.text).filter((text) => !!text).join(" ");
+        const wordsInEvent = extractWordsLower(joinedText);
+        if (!wordsInEvent.size) {
+          continue;
+        }
+        const matchQuery = wordsInQuery.some((queryWord) => wordsInEvent.has(queryWord));
+        if (matchQuery) {
+          response.memories.push({
+            content: event.content,
+            author: event.author,
+            timestamp: formatTimestamp(event.timestamp)
+          });
+        }
+      }
+    }
+    return response;
+  }
+}
+function getUserKey(appName, userId) {
+  return `${appName}/${userId}`;
+}
+function extractWordsLower(text) {
+  return new Set(
+    [...text.matchAll(/[A-Za-z]+/)].map((match) => match[0].toLowerCase())
+  );
+}
+function formatTimestamp(timestamp) {
+  return new Date(timestamp).toISOString();
+}
+export {
+  InMemoryMemoryService
+};

package/dist/esm/memory/memory_entry.js

@@ -0,0 +1,5 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */

package/dist/esm/models/base_llm.js

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var _a;
+import { getClientLabels } from "../utils/client_labels.js";
+const BASE_MODEL_SYMBOL = Symbol("baseModel");
+function isBaseLlm(obj) {
+  return typeof obj === "object" && obj !== null && BASE_MODEL_SYMBOL in obj && obj[BASE_MODEL_SYMBOL] === true;
+}
+_a = BASE_MODEL_SYMBOL;
+class BaseLlm {
+  /**
+   * Creates an instance of BaseLLM.
+   * @param params The parameters for creating a BaseLlm instance.
+   * @param params.model The name of the LLM, e.g. gemini-1.5-flash or
+   *     gemini-1.5-flash-001.
+   */
+  constructor({ model }) {
+    this[_a] = true;
+    this.model = model;
+  }
+  get trackingHeaders() {
+    const labels = getClientLabels();
+    const headerValue = labels.join(" ");
+    return {
+      "x-goog-api-client": headerValue,
+      "user-agent": headerValue
+    };
+  }
+  /**
+   * Appends a user content, so that model can continue to output.
+   *
+   * @param llmRequest LlmRequest, the request to send to the LLM.
+   */
+  maybeAppendUserContent(llmRequest) {
+    var _a2;
+    if (llmRequest.contents.length === 0) {
+      llmRequest.contents.push({
+        role: "user",
+        parts: [
+          { text: "Handle the requests as specified in the System Instruction." }
+        ]
+      });
+    }
+    if (((_a2 = llmRequest.contents[llmRequest.contents.length - 1]) == null ? void 0 : _a2.role) !== "user") {
+      llmRequest.contents.push({
+        role: "user",
+        parts: [{
+          text: "Continue processing previous requests as instructed. Exit or provide a summary if no more outputs are needed."
+        }]
+      });
+    }
+  }
+}
+/**
+ * List of supported models in regex for LlmRegistry.
+ */
+BaseLlm.supportedModels = [];
+export {
+  BaseLlm,
+  isBaseLlm
+};

package/dist/esm/models/base_llm_connection.js

@@ -0,0 +1,5 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */

package/dist/esm/models/gemini_llm_connection.js

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { logger } from "../utils/logger.js";
+class GeminiLlmConnection {
+  constructor(geminiSession) {
+    this.geminiSession = geminiSession;
+  }
+  /**
+   * Sends the conversation history to the gemini model.
+   *
+   * You call this method right after setting up the model connection.
+   * The model will respond if the last content is from user, otherwise it will
+   * wait for new user input before responding.
+   *
+   * @param history The conversation history to send to the model.
+   */
+  async sendHistory(history) {
+    const contents = history.filter(
+      (content) => {
+        var _a;
+        return content.parts && ((_a = content.parts[0]) == null ? void 0 : _a.text);
+      }
+    );
+    if (contents.length > 0) {
+      this.geminiSession.sendClientContent({
+        turns: contents,
+        turnComplete: contents[contents.length - 1].role === "user"
+      });
+    } else {
+      logger.info("no content is sent");
+    }
+  }
+  /**
+   * Sends a user content to the gemini model.
+   *
+   * The model will respond immediately upon receiving the content.
+   * If you send function responses, all parts in the content should be function
+   * responses.
+   *
+   * @param content The content to send to the model.
+   */
+  async sendContent(content) {
+    if (!content.parts) {
+      throw new Error("Content must have parts.");
+    }
+    if (content.parts[0].functionResponse) {
+      const functionResponses = content.parts.map((part) => part.functionResponse).filter((fr) => !!fr);
+      logger.debug("Sending LLM function response:", functionResponses);
+      this.geminiSession.sendToolResponse({
+        functionResponses
+      });
+    } else {
+      logger.debug("Sending LLM new content", content);
+      this.geminiSession.sendClientContent({
+        turns: [content],
+        turnComplete: true
+      });
+    }
+  }
+  /**
+   * Sends a chunk of audio or a frame of video to the model in realtime.
+   *
+   * @param blob The blob to send to the model.
+   */
+  async sendRealtime(blob) {
+    logger.debug("Sending LLM Blob:", blob);
+    this.geminiSession.sendRealtimeInput({ media: blob });
+  }
+  /**
+   * Builds a full text response.
+   *
+   * The text should not be partial and the returned LlmResponse is not be
+   * partial.
+   *
+   * @param text The text to be included in the response.
+   * @returns An LlmResponse containing the full text.
+   */
+  buildFullTextResponse(text) {
+    return {
+      content: {
+        role: "model",
+        parts: [{ text }]
+      }
+    };
+  }
+  // TODO(b/425992518): GenAI SDK inconsistent API, missing methods.
+  async *receive() {
+    throw new Error("Not Implemented.");
+  }
+  /**
+   * Closes the llm server connection.
+   */
+  async close() {
+    this.geminiSession.close();
+  }
+}
+export {
+  GeminiLlmConnection
+};

package/dist/esm/models/google_llm.js

@@ -0,0 +1,446 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {
+  createPartFromText,
+  FinishReason,
+  GoogleGenAI
+} from "@google/genai";
+import { logger } from "../utils/logger.js";
+import { isGemini3PreviewModel } from "../utils/model_name.js";
+import { GoogleLLMVariant } from "../utils/variant_utils.js";
+import { BaseLlm } from "./base_llm.js";
+import { GeminiLlmConnection } from "./gemini_llm_connection.js";
+import { createLlmResponse } from "./llm_response.js";
+const AGENT_ENGINE_TELEMETRY_TAG = "remote_reasoning_engine";
+const AGENT_ENGINE_TELEMETRY_ENV_VARIABLE_NAME = "GOOGLE_CLOUD_AGENT_ENGINE_ID";
+const GEMINI3_PREVIEW_API_ENDPOINT = "https://aiplatform.googleapis.com/v1/publishers/google";
+class Gemini extends BaseLlm {
+  /**
+   * @param params The parameters for creating a Gemini instance.
+   */
+  constructor({
+    model,
+    apiKey,
+    vertexai,
+    project,
+    location,
+    headers,
+    apiEndpoint
+  }) {
+    if (!model) {
+      model = "gemini-2.5-flash";
+    }
+    super({ model });
+    this.project = project;
+    this.location = location;
+    this.apiKey = apiKey;
+    this.headers = headers;
+    this.isGemini3Preview = isGemini3PreviewModel(model);
+    const canReadEnv = typeof process === "object";
+    this.apiEndpoint = apiEndpoint;
+    if (!this.apiEndpoint && canReadEnv) {
+      this.apiEndpoint = process.env["GEMINI_API_ENDPOINT"];
+    }
+    if (!this.apiEndpoint && this.isGemini3Preview) {
+      this.apiEndpoint = GEMINI3_PREVIEW_API_ENDPOINT;
+      logger.info(`Using Gemini 3 preview endpoint: ${this.apiEndpoint}`);
+    }
+    let useVertexAI = !!vertexai;
+    if (!useVertexAI && canReadEnv) {
+      const vertexAIfromEnv = process.env["GOOGLE_GENAI_USE_VERTEXAI"];
+      if (vertexAIfromEnv) {
+        useVertexAI = vertexAIfromEnv.toLowerCase() === "true" || vertexAIfromEnv === "1";
+      }
+    }
+    if (this.isGemini3Preview && useVertexAI) {
+      const availableApiKey = apiKey || (canReadEnv ? process.env["GOOGLE_GENAI_API_KEY"] || process.env["GEMINI_API_KEY"] : void 0);
+      if (availableApiKey) {
+        logger.info(
+          "Gemini 3 preview detected with Vertex AI mode. Switching to API key mode for correct endpoint handling."
+        );
+        useVertexAI = false;
+        this.apiKey = availableApiKey;
+      } else {
+        logger.warn(
+          "Gemini 3 preview requires API key authentication for correct endpoint handling. Set GEMINI_API_KEY or GOOGLE_GENAI_API_KEY environment variable for best compatibility."
+        );
+      }
+    }
+    this.vertexai = useVertexAI;
+    if (this.vertexai) {
+      if (canReadEnv && !this.project) {
+        this.project = process.env["GOOGLE_CLOUD_PROJECT"];
+      }
+      if (canReadEnv && !this.location) {
+        this.location = process.env["GOOGLE_CLOUD_LOCATION"];
+      }
+      if (!this.project) {
+        throw new Error(
+          "VertexAI project must be provided via constructor or GOOGLE_CLOUD_PROJECT environment variable."
+        );
+      }
+      if (!this.location) {
+        throw new Error(
+          "VertexAI location must be provided via constructor or GOOGLE_CLOUD_LOCATION environment variable."
+        );
+      }
+    } else {
+      if (!this.apiKey && canReadEnv) {
+        this.apiKey = process.env["GOOGLE_GENAI_API_KEY"] || process.env["GEMINI_API_KEY"];
+      }
+      if (!this.apiKey) {
+        throw new Error(
+          "API key must be provided via constructor or GOOGLE_GENAI_API_KEY or GEMINI_API_KEY environment variable."
+        );
+      }
+    }
+  }
+  /**
+   * Sends a request to the Gemini model.
+   *
+   * @param llmRequest LlmRequest, the request to send to the Gemini model.
+   * @param stream bool = false, whether to do streaming call.
+   * @yields LlmResponse: The model response.
+   */
+  async *generateContentAsync(llmRequest, stream = false) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
+    this.preprocessRequest(llmRequest);
+    this.maybeAppendUserContent(llmRequest);
+    logger.info(
+      `Sending out request, model: ${llmRequest.model}, backend: ${this.apiBackend}, stream: ${stream}`
+    );
+    if ((_a = llmRequest.config) == null ? void 0 : _a.httpOptions) {
+      llmRequest.config.httpOptions.headers = {
+        ...llmRequest.config.httpOptions.headers,
+        ...this.trackingHeaders
+      };
+    }
+    if (stream) {
+      const streamResult = await this.apiClient.models.generateContentStream({
+        model: (_b = llmRequest.model) != null ? _b : this.model,
+        contents: llmRequest.contents,
+        config: llmRequest.config
+      });
+      let thoughtText = "";
+      let thoughtSignature;
+      let text = "";
+      let usageMetadata;
+      let lastResponse;
+      for await (const response of streamResult) {
+        lastResponse = response;
+        const llmResponse = createLlmResponse(response);
+        usageMetadata = llmResponse.usageMetadata;
+        const firstPart = (_d = (_c = llmResponse.content) == null ? void 0 : _c.parts) == null ? void 0 : _d[0];
+        const hasFunctionCalls = (_f = (_e = llmResponse.content) == null ? void 0 : _e.parts) == null ? void 0 : _f.some(
+          (part) => part.functionCall
+        );
+        if (this.isGemini3Preview && ((_g = llmResponse.content) == null ? void 0 : _g.parts)) {
+          for (const part of llmResponse.content.parts) {
+            if (part.thoughtSignature && !thoughtSignature) {
+              thoughtSignature = part.thoughtSignature;
+              logger.debug(
+                `[Gemini3] Captured thoughtSignature (length: ${thoughtSignature.length})`
+              );
+              break;
+            }
+          }
+        }
+        if (firstPart == null ? void 0 : firstPart.text) {
+          if ("thought" in firstPart && firstPart.thought) {
+            thoughtText += firstPart.text;
+            if ("thoughtSignature" in firstPart && firstPart.thoughtSignature) {
+              thoughtSignature = firstPart.thoughtSignature;
+            }
+          } else {
+            text += firstPart.text;
+          }
+          llmResponse.partial = true;
+          if (this.isGemini3Preview && hasFunctionCalls) {
+            thoughtText = "";
+            thoughtSignature = void 0;
+            text = "";
+          }
+        } else if ((thoughtText || text) && (!firstPart || !firstPart.inlineData)) {
+          if (this.isGemini3Preview && hasFunctionCalls && llmResponse.content) {
+            const prependParts = [];
+            if (thoughtText) {
+              const thoughtPart = { text: thoughtText, thought: true };
+              if (thoughtSignature) {
+                thoughtPart.thoughtSignature = thoughtSignature;
+              }
+              prependParts.push(thoughtPart);
+            }
+            if (text) {
+              prependParts.push(createPartFromText(text));
+            }
+            if (!thoughtText && thoughtSignature) {
+              for (const part of llmResponse.content.parts || []) {
+                if (part.functionCall && !part.thoughtSignature) {
+                  part.thoughtSignature = thoughtSignature;
+                  break;
+                }
+              }
+            }
+            llmResponse.content.parts = [
+              ...prependParts,
+              ...llmResponse.content.parts || []
+            ];
+            thoughtText = "";
+            thoughtSignature = void 0;
+            text = "";
+          } else {
+            const parts = [];
+            if (thoughtText) {
+              const thoughtPart = { text: thoughtText, thought: true };
+              if (thoughtSignature) {
+                thoughtPart.thoughtSignature = thoughtSignature;
+              }
+              parts.push(thoughtPart);
+            }
+            if (text) {
+              parts.push(createPartFromText(text));
+            }
+            yield {
+              content: {
+                role: "model",
+                parts
+              },
+              usageMetadata: llmResponse.usageMetadata
+            };
+            thoughtText = "";
+            thoughtSignature = void 0;
+            text = "";
+          }
+        }
+        if (this.isGemini3Preview && hasFunctionCalls && ((_h = llmResponse.content) == null ? void 0 : _h.parts)) {
+          const hasExistingSignature = llmResponse.content.parts.some(
+            (p) => p.thoughtSignature
+          );
+          if (!hasExistingSignature && thoughtSignature) {
+            for (const part of llmResponse.content.parts) {
+              if (part.functionCall) {
+                part.thoughtSignature = thoughtSignature;
+                break;
+              }
+            }
+          }
+          const partsWithSig = llmResponse.content.parts.filter(
+            (p) => p.thoughtSignature
+          ).length;
+          if (partsWithSig === 0) {
+            logger.warn(
+              `[Gemini3] No thoughtSignature on function call parts \u2014 may cause 400 on next request`
+            );
+          }
+        }
+        yield llmResponse;
+      }
+      if ((text || thoughtText) && ((_j = (_i = lastResponse == null ? void 0 : lastResponse.candidates) == null ? void 0 : _i[0]) == null ? void 0 : _j.finishReason) === FinishReason.STOP) {
+        const parts = [];
+        if (thoughtText) {
+          const thoughtPart = { text: thoughtText, thought: true };
+          if (thoughtSignature) {
+            thoughtPart.thoughtSignature = thoughtSignature;
+          }
+          parts.push(thoughtPart);
+        }
+        if (text) {
+          parts.push({ text });
+        }
+        yield {
+          content: {
+            role: "model",
+            parts
+          },
+          usageMetadata
+        };
+      }
+    } else {
+      const response = await this.apiClient.models.generateContent({
+        model: (_k = llmRequest.model) != null ? _k : this.model,
+        contents: llmRequest.contents,
+        config: llmRequest.config
+      });
+      const llmResponse = createLlmResponse(response);
+      if (this.isGemini3Preview && ((_l = llmResponse.content) == null ? void 0 : _l.parts)) {
+        let thoughtSig;
+        let hasThoughtPartWithSignature = false;
+        for (const part of llmResponse.content.parts) {
+          if (part.thoughtSignature) {
+            thoughtSig = part.thoughtSignature;
+            if (part.thought) {
+              hasThoughtPartWithSignature = true;
+            }
+            break;
+          }
+        }
+        if (thoughtSig && !hasThoughtPartWithSignature) {
+          for (const part of llmResponse.content.parts) {
+            if (part.functionCall && !part.thoughtSignature) {
+              part.thoughtSignature = thoughtSig;
+              break;
+            }
+          }
+        }
+        const hasFunctionCalls = llmResponse.content.parts.some(
+          (p) => p.functionCall
+        );
+        if (hasFunctionCalls) {
+          const partsWithSig = llmResponse.content.parts.filter(
+            (p) => p.thoughtSignature
+          ).length;
+          if (partsWithSig === 0) {
+            logger.warn(
+              `[Gemini3] No thoughtSignature on function call parts \u2014 may cause 400 on next request`
+            );
+          }
+        }
+      }
+      yield llmResponse;
+    }
+  }
+  get apiClient() {
+    if (this._apiClient) {
+      return this._apiClient;
+    }
+    const combinedHeaders = {
+      ...this.trackingHeaders,
+      ...this.headers
+    };
+    if (this.vertexai) {
+      this._apiClient = new GoogleGenAI({
+        vertexai: this.vertexai,
+        project: this.project,
+        location: this.location,
+        httpOptions: { headers: combinedHeaders }
+      });
+    } else {
+      const httpOptions = { headers: combinedHeaders };
+      if (this.apiEndpoint) {
+        httpOptions.baseUrl = this.apiEndpoint;
+        logger.debug(`Using custom API endpoint: ${this.apiEndpoint}`);
+        if (this.isGemini3Preview) {
+          httpOptions.apiVersion = "";
+          logger.info(
+            `Gemini 3 preview mode: using direct API path without version prefix`
+          );
+        }
+      }
+      this._apiClient = new GoogleGenAI({
+        apiKey: this.apiKey,
+        vertexai: false,
+        httpOptions
+      });
+    }
+    return this._apiClient;
+  }
+  get apiBackend() {
+    if (!this._apiBackend) {
+      this._apiBackend = this.apiClient.vertexai ? GoogleLLMVariant.VERTEX_AI : GoogleLLMVariant.GEMINI_API;
+    }
+    return this._apiBackend;
+  }
+  get liveApiVersion() {
+    if (!this._liveApiVersion) {
+      this._liveApiVersion = this.apiBackend === GoogleLLMVariant.VERTEX_AI ? "v1beta1" : "v1alpha";
+    }
+    return this._liveApiVersion;
+  }
+  get liveApiClient() {
+    if (!this._liveApiClient) {
+      const httpOptions = {
+        headers: this.trackingHeaders,
+        apiVersion: this.liveApiVersion
+      };
+      if (this.apiEndpoint) {
+        httpOptions.baseUrl = this.apiEndpoint;
+        if (this.isGemini3Preview) {
+          httpOptions.apiVersion = "";
+        }
+      }
+      this._liveApiClient = new GoogleGenAI({
+        apiKey: this.apiKey,
+        httpOptions
+      });
+    }
+    return this._liveApiClient;
+  }
+  /**
+   * Connects to the Gemini model and returns an llm connection.
+   *
+   * @param llmRequest LlmRequest, the request to send to the Gemini model.
+   * @returns BaseLlmConnection, the connection to the Gemini model.
+   */
+  async connect(llmRequest) {
+    var _a, _b, _c, _d;
+    if ((_a = llmRequest.liveConnectConfig) == null ? void 0 : _a.httpOptions) {
+      if (!llmRequest.liveConnectConfig.httpOptions.headers) {
+        llmRequest.liveConnectConfig.httpOptions.headers = {};
+      }
+      Object.assign(
+        llmRequest.liveConnectConfig.httpOptions.headers,
+        this.trackingHeaders
+      );
+      llmRequest.liveConnectConfig.httpOptions.apiVersion = this.isGemini3Preview ? "" : this.liveApiVersion;
+    }
+    if ((_b = llmRequest.config) == null ? void 0 : _b.systemInstruction) {
+      llmRequest.liveConnectConfig.systemInstruction = {
+        role: "system",
+        // TODO - b/425992518: validate type casting works well.
+        parts: [
+          createPartFromText(llmRequest.config.systemInstruction)
+        ]
+      };
+    }
+    llmRequest.liveConnectConfig.tools = (_c = llmRequest.config) == null ? void 0 : _c.tools;
+    const liveSession = await this.liveApiClient.live.connect({
+      model: (_d = llmRequest.model) != null ? _d : this.model,
+      config: llmRequest.liveConnectConfig,
+      callbacks: {
+        // TODO - b/425992518: GenAI SDK inconsistent API, missing methods.
+        onmessage: () => {
+        }
+      }
+    });
+    return new GeminiLlmConnection(liveSession);
+  }
+  preprocessRequest(llmRequest) {
+    if (this.apiBackend === GoogleLLMVariant.GEMINI_API) {
+      if (llmRequest.config) {
+        llmRequest.config.labels = void 0;
+      }
+      if (llmRequest.contents) {
+        for (const content of llmRequest.contents) {
+          if (!content.parts) continue;
+          for (const part of content.parts) {
+            removeDisplayNameIfPresent(part.inlineData);
+            removeDisplayNameIfPresent(part.fileData);
+          }
+        }
+      }
+    }
+  }
+}
+/**
+ * A list of model name patterns that are supported by this LLM.
+ *
+ * @returns A list of supported models.
+ */
+Gemini.supportedModels = [
+  /gemini-.*/,
+  // fine-tuned vertex endpoint pattern
+  /projects\/.+\/locations\/.+\/endpoints\/.+/,
+  // vertex gemini long name
+  /projects\/.+\/locations\/.+\/publishers\/google\/models\/gemini.+/
+];
+function removeDisplayNameIfPresent(dataObj) {
+  if (dataObj && dataObj.displayName) {
+    dataObj.displayName = void 0;
+  }
+}
+export {
+  Gemini
+};