@kernl-sdk/protocol 0.1.1

package/src/json.ts

@@ -0,0 +1,17 @@
+/**
+ * A JSON value can be a string, number, boolean, object, array, or null.
+ * JSON values can be serialized and deserialized by the JSON.stringify and JSON.parse methods.
+ */
+export type JSONValue =
+  | null
+  | string
+  | number
+  | boolean
+  | JSONObject
+  | JSONArray;
+
+export type JSONObject = {
+  [key: string]: JSONValue | undefined;
+};
+
+export type JSONArray = JSONValue[];

package/src/language-model/index.ts

@@ -0,0 +1,5 @@
+export * from "./item";
+export * from "./model";
+export * from "./request";
+export * from "./stream";
+export * from "./tool";

package/src/language-model/item.ts

@@ -0,0 +1,251 @@
+import { SharedProviderMetadata } from "@/provider";
+import { JSONValue } from "@/json";
+import {
+  IN_PROGRESS,
+  COMPLETED,
+  FAILED,
+  INTERRUPTIBLE,
+  UNINTERRUPTIBLE,
+} from "@/constants";
+
+export type LanguageModelItem =
+  | Message
+  | Reasoning
+  | ToolCall
+  | ToolResult
+  | Unknown;
+
+/**
+ * A subset of LanguageModelItem that excludes items that wouldn't
+ * make sense for a model to generate (e.g. system/user messages, tool results).
+ */
+export type LanguageModelResponseItem =
+  | AssistantMessage
+  | Reasoning
+  | ToolCall
+  | Unknown;
+
+export interface SharedBase {
+  /**
+   * Optional provider-specific metadata for the text part.
+   */
+  providerMetadata?: SharedProviderMetadata;
+}
+
+/**
+ * Shared base for language model items.
+ */
+export interface LanguageModelItemBase extends SharedBase {
+  /**
+   * A unique identifier for the item. Optional by default.
+   */
+  id?: string;
+}
+
+// ----------------------------
+// Content types
+// ----------------------------
+
+/**
+ * Defines base properties common to all message or artifact parts.
+ */
+export interface PartBase extends SharedBase {
+  /** Optional metadata associated with this part. */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Text that the model has generated.
+ */
+export interface TextPart extends PartBase {
+  readonly kind: "text";
+
+  /**
+   * The text content.
+   */
+  text: string;
+}
+
+/**
+ * A file that has been generated by the model.
+ *
+ * May be base64 encoded strings or binary data.
+ */
+export interface FilePart extends PartBase {
+  readonly kind: "file";
+
+  /**
+   * The IANA media type of the file, e.g. `image/png` or `audio/mp3`.
+   *
+   * @see https://www.iana.org/assignments/media-types/media-types.xhtml
+   */
+  mimeType: string;
+
+  /**
+   * Generated file data as base64 encoded strings or binary data.
+   */
+  data: string | Uint8Array;
+
+  /**
+   * Optional filename for the file
+   */
+  filename?: string;
+}
+
+/**
+ * Represents a structured data segment (e.g., JSON) within a message or artifact.
+ */
+export interface DataPart extends PartBase {
+  readonly kind: "data";
+
+  /**
+   * The structured data content.
+   */
+  data: Record<string, unknown>;
+}
+
+export type MessagePart = TextPart | FilePart | DataPart;
+
+/**
+ * Reasoning that the model has generated.
+ */
+export interface Reasoning extends LanguageModelItemBase {
+  readonly kind: "reasoning";
+
+  /**
+   * The reasoning content
+   */
+  text: string;
+}
+
+/**
+ * This is a catch all for events that are not part of the protocol.
+ *
+ * For example, a model might return an event that is not part of the protocol using this type.
+ *
+ * In that case everything returned from the model should be passed in the `providerMetadata` field.
+ *
+ * This enables new features to be added to be added by a model provider without breaking the protocol.
+ */
+export interface Unknown extends LanguageModelItemBase {
+  readonly kind: "unknown";
+}
+
+// ----------------------------
+// Message types
+// ----------------------------
+
+export interface MessageBase extends SharedBase {
+  readonly kind: "message";
+
+  /**
+   * The unique identifier for the message.
+   */
+  id: string;
+
+  /**
+   * The content parts of the message.
+   */
+  content: MessagePart[];
+
+  /**
+   * Optional additional metadata for the message
+   */
+  metadata?: Record<string, unknown>;
+}
+
+export interface SystemMessage extends MessageBase {
+  /**
+   * Representing a system message to the user
+   */
+  readonly role: "system";
+}
+
+export interface AssistantMessage extends MessageBase {
+  /**
+   * Representing a message from the assistant
+   */
+  readonly role: "assistant";
+}
+
+export interface UserMessage extends MessageBase {
+  /**
+   * Representing a message from the user
+   */
+  readonly role: "user";
+}
+
+export type Message = SystemMessage | AssistantMessage | UserMessage;
+
+// ----------------------------
+// Tool call types
+// ----------------------------
+
+/**
+ * Tool calls that the model has generated.
+ */
+export interface ToolCall extends LanguageModelItemBase {
+  readonly kind: "tool-call";
+
+  /**
+   * The identifier of the tool call. It must be unique across all tool calls.
+   */
+  callId: string;
+
+  /**
+   * The id of the tool that should be called.
+   */
+  toolId: string;
+
+  /**
+   * The state of the tool call.
+   */
+  state: ToolCallState;
+
+  /**
+   * The stringified JSON object with the arguments of the tool call.
+   */
+  arguments: string;
+}
+
+/**
+ * Result of a tool call that has been executed by the provider.
+ */
+export interface ToolResult extends LanguageModelItemBase {
+  readonly kind: "tool-result";
+
+  /**
+   * The ID of the tool call that this result is associated with.
+   */
+  callId: string;
+
+  /**
+   * Name of the tool that generated this result.
+   */
+  toolId: string;
+
+  /**
+   * The state of the tool call.
+   */
+  state: ToolCallState;
+
+  /**
+   * Result of the tool call. This is a JSON-serializable object.
+   */
+  result: NonNullable<JSONValue>;
+
+  /**
+   * Error message if the tool call failed
+   */
+  error: string | null;
+}
+
+/**
+ * State of a tool call execution.
+ */
+export type ToolCallState =
+  | typeof IN_PROGRESS /* tool is actively executing */
+  | typeof COMPLETED /* finished successfully */
+  | typeof FAILED /* failed with error */
+  | typeof INTERRUPTIBLE /* tool is blocked/waiting and CAN be interrupted  */
+  | typeof UNINTERRUPTIBLE; /* tool is blocked/waiting and CANNOT be interrupted (e.g. critical I/O, API call, ..) */

package/src/language-model/model.ts

@@ -0,0 +1,161 @@
+import { SharedProviderMetadata } from "@/provider";
+
+import { LanguageModelResponseItem } from "./item";
+import { LanguageModelRequest } from "./request";
+import { LanguageModelStreamEvent } from "./stream";
+import { LanguageModelFunctionTool, LanguageModelProviderTool } from "./tool";
+
+/**
+ * Defines the standard interface for language model providers in kernl.
+ */
+export interface LanguageModel {
+  /**
+   * The language model must specify which language model interface version it implements.
+   */
+  readonly spec: "1.0";
+
+  /**
+   * Provider ID.
+   */
+  readonly provider: string;
+
+  /**
+   * Provider-specific model ID.
+   */
+  readonly modelId: string;
+
+  /**
+   * Get a response from the model.
+   *
+   * @param request - The request to get a response for.
+   */
+  generate(request: LanguageModelRequest): Promise<LanguageModelResponse>;
+
+  /**
+   * Get a streamed response from the model.
+   *
+   * @param request - The request to get a response for.
+   */
+  stream(
+    request: LanguageModelRequest,
+  ): AsyncIterable<LanguageModelStreamEvent>;
+
+  // /**
+  //  * Supported URL patterns by media type for the provider.
+  //  *
+  //  * The keys are media type patterns or full media types (e.g. `*\/*` for everything, `audio/*`, `video/*`, or `application/pdf`).
+  //  * and the values are arrays of regular expressions that match the URL paths.
+  //  *
+  //  * The matching should be against lower-case URLs.
+  //  *
+  //  * Matched URLs are supported natively by the model and are not downloaded.
+  //  *
+  //  * @returns A map of supported URL patterns by media type (as a promise or a plain object).
+  //  */
+  // supportedUrls:
+  //   | PromiseLike<Record<string, RegExp[]>>
+  //   | Record<string, RegExp[]>;
+}
+
+/**
+ * The base response interface for a language model.
+ */
+export interface LanguageModelResponse {
+  // /**
+  //  * An ID for the response which can be used to refer to the response in subsequent calls to the
+  //  * model. Not supported by all model providers.
+  //  */
+  // responseId?: string;
+
+  /**
+   * The ordered list of content items generated by the model.
+   */
+  content: LanguageModelResponseItem[];
+
+  /**
+   * Finish reason.
+   */
+  finishReason: LanguageModelFinishReason;
+
+  /**
+   * The usage information for response.
+   */
+  usage: LanguageModelUsage;
+
+  /**
+   * Warnings for the call, e.g. unsupported settings.
+   */
+  warnings: LanguageModelWarning[];
+
+  /**
+   * Raw response data from the underlying model provider.
+   */
+  providerMetadata?: SharedProviderMetadata;
+}
+
+/**
+ * Reason why a language model finished generating a response.
+ */
+export type LanguageModelFinishReason =
+  | "stop" /* model generated stop sequence */
+  | "length" /* model generated maximum number of tokens */
+  | "content-filter" /* content filter violation stopped the model */
+  | "tool-calls" /* model triggered tool calls */
+  | "error" /* model stopped because of an error */
+  | "other" /* model stopped for other reasons */
+  | "unknown"; /* the model has not transmitted a finish reason */
+
+/**
+ * Usage information for a language model call.
+ *
+ * If your API return additional usage information, you can add it to the
+ * provider metadata under your provider's key.
+ */
+export interface LanguageModelUsage {
+  /**
+   * The number of input (prompt) tokens used.
+   */
+  inputTokens: number | undefined;
+
+  /**
+   * The number of output (completion) tokens used.
+   */
+  outputTokens: number | undefined;
+
+  /**
+   * The total number of tokens as reported by the provider.
+   * This number might be different from the sum of `inputTokens` and `outputTokens`
+   * and e.g. include reasoning tokens or other overhead.
+   */
+  totalTokens: number | undefined;
+
+  /**
+   * The number of reasoning tokens used.
+   */
+  reasoningTokens?: number | undefined;
+
+  /**
+   * The number of cached input tokens.
+   */
+  cachedInputTokens?: number | undefined;
+}
+
+/**
+ * Warning from the model provider for this call. The call will proceed, but e.g.
+ * some settings might not be supported, which can lead to suboptimal results.
+ */
+export type LanguageModelWarning =
+  | {
+      type: "unsupported-setting";
+      setting: Omit<keyof LanguageModelRequest, "input">; // (TODO): allow string
+      details?: string;
+    }
+  | {
+      type: "unsupported-tool";
+      tool: LanguageModelFunctionTool | LanguageModelProviderTool;
+      details?: string;
+    }
+  | {
+      type: "other";
+      message: string;
+    };

package/src/language-model/request.ts

@@ -0,0 +1,210 @@
+import type { JSONSchema7 } from "json-schema";
+
+import { SharedProviderOptions } from "@/provider";
+
+import { LanguageModelItem } from "./item";
+import { LanguageModelFunctionTool, LanguageModelProviderTool } from "./tool";
+
+export type LanguageModelTool =
+  | LanguageModelFunctionTool
+  | LanguageModelProviderTool;
+
+/**
+ * A request to a large language model.
+ */
+export interface LanguageModelRequest {
+  /**
+   * The input to the model.
+   */
+  input: LanguageModelItem[];
+
+  /**
+   * The model settings to use for the request.
+   */
+  settings: LanguageModelRequestSettings;
+
+  /**
+   * Response format. The output can either be text or JSON. Default is text.
+   *
+   * If JSON is selected, a schema can optionally be provided to guide the LLM.
+   */
+  responseType?: LanguageModelResponseType;
+
+  /**
+   * The tools that are available for the model.
+   */
+  tools?: LanguageModelTool[];
+
+  /**
+Include raw chunks in the stream. Only applicable for streaming calls.
+ */
+  includeRawChunks?: boolean;
+
+  /**
+   * Abort signal for cancelling the operation.
+   */
+  abort?: AbortSignal;
+}
+
+/**
+ * Response format specification for language model output.
+ *
+ * The output can either be text or JSON. Default is text.
+ * If JSON is selected, a schema can optionally be provided to guide the LLM.
+ */
+export type LanguageModelResponseType =
+  | LanguageModelResponseText
+  | LanguageModelResponseJSON;
+
+/**
+ * Text response format.
+ */
+export interface LanguageModelResponseText {
+  readonly kind: "text";
+}
+
+/**
+ * JSON response format.
+ */
+export interface LanguageModelResponseJSON {
+  readonly kind: "json";
+
+  /**
+   * JSON schema that the generated output should conform to.
+   */
+  schema?: JSONSchema7;
+
+  /**
+   * Name of output that should be generated. Used by some providers for additional LLM guidance.
+   */
+  name?: string;
+
+  /**
+   * Description of the output that should be generated. Used by some providers for additional LLM guidance.
+   */
+  description?: string;
+}
+
+/**
+ * Settings to use when calling an LLM.
+ *
+ * This class holds optional model configuration parameters (e.g. temperature,
+ * topP, penalties, truncation, etc.).
+ *
+ * Not all models/providers support all of these parameters, so please check the API documentation
+ * for the specific model and provider you are using.
+ */
+export interface LanguageModelRequestSettings {
+  /**
+   * The temperature to use when calling the model.
+   */
+  temperature?: number;
+
+  /**
+   * The topP to use when calling the model.
+   */
+  topP?: number;
+
+  /**
+   * The frequency penalty to use when calling the model.
+   */
+  frequencyPenalty?: number;
+
+  /**
+   * The presence penalty to use when calling the model.
+   */
+  presencePenalty?: number;
+
+  /**
+   * The tool choice to use when calling the model.
+   */
+  toolChoice?: LanguageModelToolChoice;
+
+  /**
+   * Whether to use parallel tool calls when calling the model.
+   * Defaults to false if not provided.
+   */
+  parallelToolCalls?: boolean;
+
+  /**
+   * The truncation strategy to use when calling the model.
+   */
+  truncation?: "auto" | "disabled";
+
+  /**
+   * The maximum number of output tokens to generate.
+   */
+  maxTokens?: number;
+
+  /**
+   * Whether to store the generated model response for later retrieval.
+   * Defaults to true if not provided.
+   */
+  store?: boolean;
+
+  /**
+   * The reasoning settings to use when calling the model.
+   */
+  reasoning?: ModelSettingsReasoning;
+
+  /**
+   * The text settings to use when calling the model.
+   */
+  text?: ModelSettingsText;
+
+  /**
+   * Additional provider specific metadata to be passed directly to the model
+   * request.
+   */
+  providerOptions?: SharedProviderOptions;
+}
+
+export type LanguageModelToolChoice =
+  | { kind: "auto" } /* the tool selection is automatic (can be no tool) */
+  | { kind: "none" } /* no tool must be selected */
+  | { kind: "required" } /* one of the available tools must be selected */
+  | { kind: "tool"; toolId: string }; /* a specific tool must be selected: */
+
+/**
+ * Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning).
+ *
+ * Supported for providers:
+ *
+ *  - OpenAI
+ *  - ... ?
+ */
+export type ModelSettingsReasoningEffort =
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | null;
+
+/**
+ * Configuration options for model reasoning
+ */
+export type ModelSettingsReasoning = {
+  /**
+   * Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning).
+   */
+  effort?: ModelSettingsReasoningEffort | null;
+
+  /**
+   * A summary of the reasoning performed by the model.
+   * This can be useful for debugging and understanding the model's reasoning process.
+   * One of `auto`, `concise`, or `detailed`.
+   */
+  summary?: "auto" | "concise" | "detailed" | null;
+};
+
+export interface ModelSettingsText {
+  /**
+   * Constrains the verbosity of the model's response.
+   *
+   * Supported for providers:
+   *
+   *  - OpenAI
+   *  - ... ?
+   */
+  verbosity?: "low" | "medium" | "high" | null;
+}