@kalenkevich/agent_007 0.0.1

package/src/model/google/gemini_streaming_utils.ts

@@ -0,0 +1,294 @@
+import { GenerateContentResponse, FinishReason } from "@google/genai";
+import { generateClientFunctionCallId } from "../../core/functions.js";
+import type { LlmResponse, UsageMetadata } from "../response.js";
+import {
+  type ContentPart,
+  type PartialArg,
+  type FunctionCallContentPart,
+  isTextContentPart,
+  isThoughtContentPart,
+  isFunctionCallContentPart,
+} from "../../content.js";
+import { createLlmResponse } from "./gemini_response_utils.js";
+
+/**
+ * Aggregates partial streaming responses.
+ *
+ * It aggregates content from partial responses, and generates LlmResponses for
+ * individual (partial) model responses, as well as for aggregated content.
+ */
+export class StreamingResponseAggregator {
+  private usageMetadata?: UsageMetadata;
+  // private groundingMetadata?: GroundingMetadata;
+  // private citationMetadata?: CitationMetadata;
+  private response?: GenerateContentResponse;
+
+  // For progressive SSE streaming mode: accumulate parts in order
+  private partsSequence: ContentPart[] = [];
+  private currentTextBuffer = "";
+  private currentTextIsThought?: boolean;
+  private finishReason?: string;
+
+  // For streaming function call arguments
+  private currentFcName?: string;
+  private currentFcArgs: Record<string, unknown> = {};
+  private currentFcId?: string;
+  private currentThoughtSignature?: string | Uint8Array;
+
+  private flushTextBufferToSequence(): void {
+    if (!this.currentTextBuffer) {
+      return;
+    }
+
+    if (this.currentTextIsThought) {
+      this.partsSequence.push({
+        type: "thought",
+        thought: this.currentTextBuffer,
+      });
+    } else {
+      this.partsSequence.push({
+        type: "text",
+        text: this.currentTextBuffer,
+      });
+    }
+
+    this.currentTextBuffer = "";
+    this.currentTextIsThought = undefined;
+  }
+
+  private getValueFromPartialArg(
+    partialArg: PartialArg,
+    jsonPath: string,
+  ): [unknown, boolean] {
+    let value: unknown = null;
+    let hasValue = false;
+
+    const stringValue = partialArg.stringValue;
+    const numberValue = partialArg.numberValue;
+    const boolValue = partialArg.boolValue;
+    const nullValue = partialArg.nullValue;
+
+    if (stringValue !== undefined) {
+      const stringChunk = stringValue;
+      hasValue = true;
+
+      const pathWithoutPrefix = jsonPath.startsWith("$.")
+        ? jsonPath.slice(2)
+        : jsonPath;
+      const pathParts = pathWithoutPrefix.split(".");
+
+      let existingValue = this.currentFcArgs;
+      for (const part of pathParts) {
+        if (
+          existingValue &&
+          typeof existingValue === "object" &&
+          part in existingValue
+        ) {
+          existingValue = existingValue[part] as Record<string, unknown>;
+        } else {
+          break;
+        }
+      }
+
+      if (typeof existingValue === "string") {
+        value = existingValue + stringChunk;
+      } else {
+        value = stringChunk;
+      }
+    } else if (numberValue !== undefined) {
+      value = numberValue;
+      hasValue = true;
+    } else if (boolValue !== undefined) {
+      value = boolValue;
+      hasValue = true;
+    } else if (nullValue !== undefined) {
+      value = null;
+      hasValue = true;
+    }
+
+    return [value, hasValue];
+  }
+
+  private setValueByJsonPath(jsonPath: string, value: unknown): void {
+    const path = jsonPath.startsWith("$.") ? jsonPath.slice(2) : jsonPath;
+    const pathParts = path.split(".");
+
+    let current = this.currentFcArgs;
+    for (let i = 0; i < pathParts.length - 1; i++) {
+      const part = pathParts[i];
+      if (!(part in current)) {
+        current[part] = {};
+      }
+      current = current[part] as Record<string, unknown>;
+    }
+
+    current[pathParts[pathParts.length - 1]] = value;
+  }
+
+  private flushFunctionCallToSequence(): void {
+    if (this.currentFcName) {
+      const fcPart: FunctionCallContentPart = {
+        type: "function_call",
+        name: this.currentFcName,
+        args: JSON.parse(JSON.stringify(this.currentFcArgs)),
+        id: this.currentFcId ?? generateClientFunctionCallId(),
+      };
+
+      if (this.currentThoughtSignature) {
+        fcPart.thoughtSignature = this.currentThoughtSignature.toString();
+      }
+
+      this.partsSequence.push(fcPart);
+
+      this.currentFcName = undefined;
+      this.currentFcArgs = {};
+      this.currentFcId = undefined;
+      this.currentThoughtSignature = undefined;
+    }
+  }
+
+  private processStreamingFunctionCall(fc: FunctionCallContentPart): void {
+    if (fc.name) {
+      this.currentFcName = fc.name;
+    }
+    if (fc.id) {
+      this.currentFcId = fc.id;
+    }
+
+    for (const partialArg of fc.partialArgs || []) {
+      const jsonPath = partialArg.jsonPath;
+      if (!jsonPath) {
+        continue;
+      }
+
+      const [value, hasValue] = this.getValueFromPartialArg(
+        partialArg,
+        jsonPath,
+      );
+
+      if (hasValue) {
+        this.setValueByJsonPath(jsonPath, value);
+      }
+    }
+
+    if (!fc.willContinue) {
+      this.flushTextBufferToSequence();
+      this.flushFunctionCallToSequence();
+    }
+  }
+
+  private processFunctionCallPart(part: FunctionCallContentPart): void {
+    const fc = part;
+
+    if (fc.partialArgs || fc.willContinue) {
+      if (!fc.id && !this.currentFcId) {
+        fc.id = generateClientFunctionCallId();
+      }
+
+      if (part.thoughtSignature && !this.currentThoughtSignature) {
+        this.currentThoughtSignature = part.thoughtSignature;
+      }
+      this.processStreamingFunctionCall(fc);
+    } else {
+      if (fc.name) {
+        if (!fc.id) {
+          fc.id = generateClientFunctionCallId();
+        }
+        this.flushTextBufferToSequence();
+        this.partsSequence.push(part);
+      }
+    }
+  }
+
+  async *processResponse(
+    response: GenerateContentResponse,
+  ): AsyncGenerator<LlmResponse, void, void> {
+    this.response = response;
+    const llmResponse = createLlmResponse(response);
+    this.usageMetadata = llmResponse.usageMetadata;
+    // if (llmResponse.groundingMetadata) {
+    //   this.groundingMetadata = llmResponse.groundingMetadata;
+    // }
+    // if (llmResponse.citationMetadata) {
+    //   this.citationMetadata = llmResponse.citationMetadata;
+    // }
+
+    if (llmResponse.finishReason) {
+      this.finishReason = llmResponse.finishReason;
+    }
+
+    if (llmResponse.content && llmResponse.content.parts) {
+      for (const part of llmResponse.content.parts) {
+        if (isTextContentPart(part)) {
+          const isThought = false;
+          if (
+            this.currentTextBuffer &&
+            isThought !== this.currentTextIsThought
+          ) {
+            this.flushTextBufferToSequence();
+          }
+
+          if (!this.currentTextBuffer) {
+            this.currentTextIsThought = isThought;
+          }
+          this.currentTextBuffer += part.text;
+        } else if (isThoughtContentPart(part)) {
+          const isThought = true;
+          if (
+            this.currentTextBuffer &&
+            isThought !== this.currentTextIsThought
+          ) {
+            this.flushTextBufferToSequence();
+          }
+
+          if (!this.currentTextBuffer) {
+            this.currentTextIsThought = isThought;
+          }
+          this.currentTextBuffer += part.thought;
+        } else if (isFunctionCallContentPart(part)) {
+          this.processFunctionCallPart(part);
+        } else {
+          this.flushTextBufferToSequence();
+          this.partsSequence.push(part);
+        }
+      }
+    }
+
+    llmResponse.partial = true;
+    yield llmResponse;
+  }
+
+  close(): LlmResponse | undefined {
+    if (!this.response?.candidates || this.response.candidates.length === 0) {
+      return;
+    }
+
+    this.flushTextBufferToSequence();
+    this.flushFunctionCallToSequence();
+
+    const finalParts = this.partsSequence;
+    if (finalParts.length === 0) {
+      return;
+    }
+
+    const candidate = this.response.candidates[0];
+    const finishReason = this.finishReason ?? candidate.finishReason;
+
+    return {
+      content: {
+        role: "agent",
+        parts: finalParts,
+      },
+      // groundingMetadata: this.groundingMetadata,
+      // citationMetadata: this.citationMetadata,
+      errorCode: finishReason === FinishReason.STOP ? undefined : finishReason,
+      errorMessage:
+        finishReason === FinishReason.STOP
+          ? undefined
+          : candidate.finishMessage,
+      usageMetadata: this.usageMetadata,
+      finishReason: finishReason,
+      partial: false,
+    };
+  }
+}

package/src/model/google/gen_ai_convert_utils.ts

@@ -0,0 +1,149 @@
+import {
+  type Content,
+  type ContentPart,
+  isTextContentPart,
+  isThoughtContentPart,
+  isMediaContentPart,
+  isFunctionCallContentPart,
+  isFunctionResponseContentPart,
+} from "../../content.js";
+import type {
+  Part as GenAIContentPart,
+  Content as GenAIContent,
+} from "@google/genai";
+
+export function contentToGenAIContent(content: Content): GenAIContent {
+  return {
+    parts: content.parts.map((part) => contentPartToGenAIContentPart(part)),
+    role: content.role === "user" ? "user" : "model",
+  };
+}
+
+export function contentPartToGenAIContentPart(
+  part: ContentPart,
+): GenAIContentPart {
+  if (isTextContentPart(part)) {
+    return {
+      text: part.text,
+    };
+  }
+
+  if (isThoughtContentPart(part)) {
+    return {
+      text: part.thought,
+      thought: true,
+    };
+  }
+
+  if (isMediaContentPart(part) && part.data) {
+    return {
+      inlineData: {
+        data: part.data,
+        mimeType: part.mimeType,
+      },
+    };
+  }
+
+  if (isMediaContentPart(part) && part.uri) {
+    return {
+      fileData: {
+        fileUri: part.uri,
+        mimeType: part.mimeType,
+      },
+    };
+  }
+
+  if (isFunctionCallContentPart(part)) {
+    return {
+      functionCall: {
+        id: part.id,
+        name: part.name,
+        args: part.args,
+        partialArgs: part.partialArgs,
+        willContinue: part.willContinue,
+      },
+      thoughtSignature: part.thoughtSignature,
+    };
+  }
+
+  if (isFunctionResponseContentPart(part)) {
+    return {
+      functionResponse: {
+        id: part.id,
+        name: part.name,
+        response: part.response,
+        willContinue: part.willContinue,
+      },
+      thoughtSignature: part.thoughtSignature,
+    };
+  }
+
+  throw new Error(`Unsupported content type: ${part.type}`);
+}
+
+export function genAIContentToContent(genAIContent: GenAIContent): Content {
+  return {
+    role: genAIContent.role === "user" ? "user" : "agent",
+    parts: (genAIContent.parts || []).map((p) =>
+      genAIContentPartToContentPart(p),
+    ),
+  };
+}
+
+export function genAIContentPartToContentPart(
+  part: GenAIContentPart,
+): ContentPart {
+  if (part.text !== undefined) {
+    if ((part as any).thought) {
+      return {
+        type: "thought",
+        thought: part.text,
+      };
+    }
+    return {
+      type: "text",
+      text: part.text,
+    };
+  }
+
+  if (part.inlineData) {
+    return {
+      type: "media",
+      data: part.inlineData.data,
+      mimeType: part.inlineData.mimeType,
+    };
+  }
+
+  if (part.fileData) {
+    return {
+      type: "media",
+      uri: part.fileData.fileUri,
+      mimeType: part.fileData.mimeType,
+    };
+  }
+
+  if (part.functionCall) {
+    return {
+      type: "function_call",
+      id: part.functionCall.id,
+      name: part.functionCall.name,
+      args: part.functionCall.args,
+      partialArgs: part.functionCall.partialArgs,
+      willContinue: part.functionCall.willContinue,
+      thoughtSignature: part.thoughtSignature,
+    };
+  }
+
+  if (part.functionResponse) {
+    return {
+      type: "function_response",
+      id: part.functionResponse.id,
+      name: part.functionResponse.name,
+      response: part.functionResponse.response,
+      willContinue: part.functionResponse.willContinue,
+      thoughtSignature: part.thoughtSignature,
+    };
+  }
+
+  throw new Error(`Unsupported GenAI content part`);
+}

package/src/model/model.ts

@@ -0,0 +1,18 @@
+import type { LlmRequest } from "./request.js";
+import type { LlmResponse } from "./response.js";
+
+export interface LlmModelConfig {
+  stream?: boolean;
+  abortSignal?: AbortSignal;
+}
+
+export interface LlmModel {
+  modelName: string;
+
+  run(
+    request: LlmRequest,
+    config?: LlmModelConfig,
+  ): AsyncGenerator<LlmResponse, void, unknown>;
+
+  countTokens(request: LlmRequest): Promise<number>;
+}

package/src/model/registry.ts

@@ -0,0 +1,61 @@
+import type { LlmModel } from "./model.js";
+import { Gemini } from "./google/gemini_model.js";
+
+type LlmModelClass = {
+  new (params: { modelName: string; apiKey: string }): LlmModel;
+};
+
+export enum ModelType {
+  LITE = "lite",
+  FAST = "fast",
+  PRO = "pro",
+}
+
+export interface ModelInfo {
+  name: string;
+  type: ModelType;
+  klass: LlmModelClass;
+}
+
+const MODEL_REGISTRY: Record<string, ModelInfo> = {
+  "gemini-3.1-pro-preview": {
+    name: "gemini-3.1-pro-preview",
+    type: ModelType.PRO,
+    klass: Gemini,
+  },
+  "gemini-3-flash-preview": {
+    name: "gemini-3-flash-preview",
+    type: ModelType.FAST,
+    klass: Gemini,
+  },
+  "gemini-3.1-flash-lite-preview": {
+    name: "gemini-3.1-flash-lite-preview",
+    type: ModelType.LITE,
+    klass: Gemini,
+  },
+  "gemini-2.5-pro": {
+    name: "gemini-2.5-pro",
+    type: ModelType.PRO,
+    klass: Gemini,
+  },
+  "gemini-2.5-flash": {
+    name: "gemini-2.5-flash",
+    type: ModelType.FAST,
+    klass: Gemini,
+  },
+  "gemini-2.5-flash-lite": {
+    name: "gemini-2.5-flash-lite",
+    type: ModelType.LITE,
+    klass: Gemini,
+  },
+};
+
+export function resolveLlmModel(modelName: string): LlmModelClass {
+  const modelInfo = MODEL_REGISTRY[modelName];
+
+  if (!modelInfo) {
+    throw new Error(`Model ${modelName} not found`);
+  }
+
+  return modelInfo.klass;
+}

package/src/model/request.ts

@@ -0,0 +1,15 @@
+import type { Content } from "../content.js";
+import type { FunctionDeclaration } from "../tools/tool.js";
+
+export interface LlmRequest {
+  model?: string;
+  contents: Content[];
+  systemInstructions?: string;
+  tools?: FunctionDeclaration[];
+  thinkingConfig?: ThinkingConfig;
+}
+
+export interface ThinkingConfig {
+  enabled: boolean;
+  level?: "low" | "medium" | "high" | "auto";
+}

package/src/model/request_builder_utils.ts

@@ -0,0 +1,79 @@
+import type { LlmRequest, ThinkingConfig } from "./request.js";
+import type { Content } from "../content.js";
+import type { Tool, FunctionDeclaration } from "../tools/tool.js";
+import { type Skill, toFunctionDeclaration } from "../skills/skill.js";
+
+interface BuildLlmRequestOptions {
+  agentName: string;
+  content: Content;
+  historyContent: Content[];
+  tools?: Tool[];
+  skills?: Skill[];
+  description?: string;
+  instructions: string;
+  thinkingConfig?: ThinkingConfig;
+}
+
+export function buildLlmRequest(options: BuildLlmRequestOptions): LlmRequest {
+  const {
+    agentName,
+    content,
+    historyContent,
+    tools,
+    skills,
+    description,
+    instructions,
+    thinkingConfig,
+  } = options;
+
+  return {
+    contents: mergeAdjacentContents([...historyContent, content]),
+    tools: [...buildTools(tools), ...buildSkillsTools(skills)],
+    systemInstructions: buildSystemInstruction(
+      agentName,
+      description,
+      instructions,
+    ),
+    thinkingConfig,
+  };
+}
+
+function mergeAdjacentContents(contents: Content[]): Content[] {
+  const result: Content[] = [];
+  for (const content of contents) {
+    const last = result[result.length - 1];
+    if (last && last.role === content.role) {
+      last.parts.push(...content.parts);
+    } else {
+      result.push({ ...content, parts: [...content.parts] });
+    }
+  }
+
+  return result;
+}
+
+export function buildTools(tools?: Tool[]): FunctionDeclaration[] {
+  if (!tools) return [];
+
+  return tools.map((t) => t.toFunctionDeclaration());
+}
+
+export function buildSkillsTools(skills?: Skill[]): FunctionDeclaration[] {
+  if (!skills) return [];
+
+  return skills.map((skill) => toFunctionDeclaration(skill));
+}
+
+export function buildSystemInstruction(
+  name: string,
+  description: string | undefined,
+  instructions: string,
+): string {
+  return [
+    `You are an agent. Your internal name is "${name}".`,
+    description ? `The description about you is "${description}"` : "",
+    instructions,
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}

package/src/model/response.ts

@@ -0,0 +1,66 @@
+import type { Content } from "../content.js";
+
+export interface UsageMetadata {
+  inputTokens?: number;
+  outputTokens?: number;
+  cachedTokens?: number;
+  cost?: { amount: number; currency?: string };
+}
+
+export type FinishReason = string;
+
+/**
+ * LLM response class that provides the first candidate response from the
+ * model if available. Otherwise, returns error code and message.
+ */
+export interface LlmResponse {
+  /**
+   * The content of the response.
+   */
+  content?: Content;
+
+  /**
+   * Indicates whether the text content is part of a unfinished text stream.
+   * Only used for streaming mode and when the content is plain text.
+   */
+  partial?: boolean;
+
+  /**
+   * Indicates whether the response from the model is complete.
+   * Only used for streaming mode.
+   */
+  turnComplete?: boolean;
+
+  /**
+   * Error code if the response is an error. Code varies by model.
+   */
+  errorCode?: string;
+
+  /**
+   * Error message if the response is an error.
+   */
+  errorMessage?: string;
+
+  /**
+   * Flag indicating that LLM was interrupted when generating the content.
+   * Usually it's due to user interruption during a bidi streaming.
+   */
+  interrupted?: boolean;
+
+  /**
+   * The custom metadata of the LlmResponse.
+   * An optional key-value pair to label an LlmResponse.
+   * NOTE: the entire object must be JSON serializable.
+   */
+  customMetadata?: { [key: string]: unknown };
+
+  /**
+   * The finish reason of the response.
+   */
+  finishReason?: FinishReason;
+
+  /**
+   * The usage metadata of the LlmResponse.
+   */
+  usageMetadata?: UsageMetadata;
+}