@kernl-sdk/protocol 0.1.1

package/src/language-model/stream.ts

@@ -0,0 +1,251 @@
+import { SharedProviderMetadata } from "@/provider";
+
+import type {
+  LanguageModelFinishReason,
+  LanguageModelUsage,
+  LanguageModelWarning,
+} from "./model";
+import type { ToolCallState } from "./item";
+
+/**
+ * Union of all possible language model stream events.
+ */
+export type LanguageModelStreamEvent =
+  | TextStartEvent
+  | TextEndEvent
+  | TextDeltaEvent
+  | ReasoningStartEvent
+  | ReasoningEndEvent
+  | ReasoningDeltaEvent
+  | ToolInputStartEvent
+  | ToolInputEndEvent
+  | ToolInputDeltaEvent
+  | ToolCallEvent
+  | ToolResultEvent
+  | StartEvent
+  | FinishEvent
+  | AbortEvent
+  | ErrorEvent
+  | RawEvent;
+
+/**
+ * Base interface for all stream events.
+ */
+export interface StreamEventBase {
+  /**
+   * The ID associated with this stream event.
+   */
+  id?: string;
+
+  /**
+   * Additional provider-specific metadata for the event.
+   */
+  providerMetadata?: SharedProviderMetadata;
+}
+
+/**
+ * Stream event indicating the start of a text output.
+ */
+export interface TextStartEvent extends StreamEventBase {
+  readonly kind: "text-start";
+  id: string;
+}
+
+/**
+ * Stream event indicating the end of a text output.
+ */
+export interface TextEndEvent extends StreamEventBase {
+  readonly kind: "text-end";
+  id: string;
+}
+
+/**
+ * Stream event containing a delta (chunk) of text output.
+ */
+export interface TextDeltaEvent extends StreamEventBase {
+  readonly kind: "text-delta";
+  id: string;
+
+  /**
+   * The incremental text chunk.
+   */
+  text: string;
+}
+
+/**
+ * Stream event indicating the start of reasoning output.
+ */
+export interface ReasoningStartEvent extends StreamEventBase {
+  readonly kind: "reasoning-start";
+  id: string;
+}
+
+/**
+ * Stream event indicating the end of reasoning output.
+ */
+export interface ReasoningEndEvent extends StreamEventBase {
+  readonly kind: "reasoning-end";
+  id: string;
+}
+
+/**
+ * Stream event containing a delta (chunk) of reasoning output.
+ */
+export interface ReasoningDeltaEvent extends StreamEventBase {
+  readonly kind: "reasoning-delta";
+  id: string;
+
+  /**
+   * The incremental reasoning text chunk.
+   */
+  text: string;
+}
+
+/**
+ * Stream event indicating the start of tool input generation.
+ */
+export interface ToolInputStartEvent extends StreamEventBase {
+  readonly kind: "tool-input-start";
+  id: string;
+
+  /**
+   * The name of the tool being called.
+   */
+  toolName: string;
+
+  /**
+   * Optional title for the tool call.
+   */
+  title?: string;
+}
+
+/**
+ * Stream event indicating the end of tool input generation.
+ */
+export interface ToolInputEndEvent extends StreamEventBase {
+  readonly kind: "tool-input-end";
+  id: string;
+}
+
+/**
+ * Stream event containing a delta (chunk) of tool input.
+ */
+export interface ToolInputDeltaEvent extends StreamEventBase {
+  readonly kind: "tool-input-delta";
+  id: string;
+
+  /**
+   * The incremental tool input chunk.
+   */
+  delta: string;
+}
+
+/**
+ * Stream event containing a complete tool call.
+ */
+export interface ToolCallEvent extends StreamEventBase {
+  readonly kind: "tool-call";
+  id: string;
+
+  /**
+   * The name of the tool being called.
+   */
+  toolName: string;
+
+  /**
+   * The arguments for the tool call as a JSON string.
+   */
+  arguments: string;
+}
+
+/**
+ * Stream event containing a tool result from a provider-executed tool.
+ */
+export interface ToolResultEvent extends StreamEventBase {
+  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 value.
+   */
+  result: unknown;
+
+  /**
+   * Error message if the tool call failed.
+   */
+  error: string | null;
+}
+
+/**
+ * Stream event indicating the start of agent execution.
+ */
+export interface StartEvent extends StreamEventBase {
+  readonly kind: "stream-start";
+
+  /**
+   * Warnings for the call (e.g., unsupported settings).
+   */
+  warnings?: LanguageModelWarning[];
+}
+
+/**
+ * Stream event indicating the completion of agent execution.
+ */
+export interface FinishEvent extends StreamEventBase {
+  readonly kind: "finish";
+
+  /**
+   * The reason for completion.
+   */
+  finishReason: LanguageModelFinishReason;
+
+  /**
+   * Total usage data for the execution.
+   */
+  usage: LanguageModelUsage;
+}
+
+/**
+ * Stream event indicating the agent execution was aborted.
+ */
+export interface AbortEvent extends StreamEventBase {
+  readonly kind: "abort";
+}
+
+/**
+ * Stream event indicating an error occurred during execution.
+ */
+export interface ErrorEvent extends StreamEventBase {
+  readonly kind: "error";
+
+  /**
+   * The error that occurred.
+   */
+  error: unknown;
+}
+
+/**
+ * Stream event containing raw provider-specific data.
+ */
+export interface RawEvent extends StreamEventBase {
+  readonly kind: "raw";
+
+  /**
+   * The raw value from the provider.
+   */
+  rawValue: unknown;
+}

package/src/language-model/tool.ts

@@ -0,0 +1,56 @@
+import type { JSONSchema7 } from "json-schema";
+import type { SharedProviderOptions } from "@/provider";
+
+/**
+ * A tool has a name, a description, and a set of parameters.
+ *
+ * Note: this is **not** the user-facing tool definition. The AI SDK methods will
+ * map the user-facing tool definitions to this format.
+ */
+export type LanguageModelFunctionTool = {
+  readonly kind: "function";
+
+  /**
+   * The name of the tool. Unique within this model call.
+   */
+  name: string;
+
+  /**
+   * A description of the tool. The language model uses this to understand the
+   * tool's purpose and to provide better completion suggestions.
+   */
+  description?: string;
+
+  /**
+   * The parameters that the tool expects. The language model uses this to
+   * understand the tool's input requirements and to provide matching suggestions.
+   */
+  parameters: JSONSchema7;
+
+  /**
+   * The provider-specific options for the tool.
+   */
+  providerOptions?: SharedProviderOptions;
+};
+
+/**
+ * The configuration of a tool that is defined by the provider.
+ */
+export type LanguageModelProviderTool = {
+  readonly kind: "provider-defined";
+
+  /**
+   * The ID of the tool. Should follow the format `<provider-id>.<unique-tool-name>`.
+   */
+  id: `${string}.${string}`;
+
+  /**
+   * The name of the tool that the user must use in the tool set.
+   */
+  name: string;
+
+  /**
+   * The arguments for configuring the tool. Must match the expected arguments defined by the provider for this tool.
+   */
+  args: Record<string, unknown>;
+};

package/src/provider/index.ts

@@ -0,0 +1 @@
+export * from "./provider";

package/src/provider/provider.ts

@@ -0,0 +1,79 @@
+import { EmbeddingModel } from "@/embedding-model";
+import { LanguageModel } from "@/language-model";
+import { JSONObject } from "@/json";
+
+/**
+ * Provider for language, text embedding, and image generation models.
+ */
+export interface Provider {
+  readonly spec: "1.0";
+
+  /**
+   * Returns the language model with the given id.
+   *
+   * @throws {NoSuchModelError} If no such model exists.
+   */
+  languageModel(modelId: string): LanguageModel;
+
+  /**
+   * Returns the text embedding model with the given id.
+   *
+   * @throws {NoSuchModelError} If no such model exists.
+   */
+  textEmbeddingModel(modelId: string): EmbeddingModel<string>;
+
+  // /**
+  //  * Returns the image model with the given id.
+  //  *
+  //  * @param modelId - The id of the model to return.
+  //  * @returns The image model associated with the id.
+  //  */
+  // imageModel(modelId: string): ImageModelV3;
+
+  // /**
+  //  * Returns the transcription model with the given id.
+  //  *
+  //  * @param modelId - The id of the model to return.
+  //  * @returns The transcription model associated with the id.
+  //  */
+  // transcriptionModel?(modelId: string): TranscriptionModelV3;
+
+  // /**
+  //  * Returns the speech model with the given id.
+  //  *
+  //  * @param modelId - The id of the model to return.
+  //  * @returns The speech model associated with the id.
+  //  */
+  // speechModel?(modelId: string): SpeechModelV3;
+
+  // /**
+  //  * Returns the reranking model with the given id.
+  //  *
+  //  * @param modelId - The id of the model to return.
+  //  * @returns The reranking model associated with the id.
+  //  * @throws {NoSuchModelError} If no such model exists.
+  //  */
+  // rerankingModel?(modelId: string): RerankingModelV3;
+}
+
+/**
+ * Additional provider-specific metadata.
+ *
+ * They are passed through to the provider from the AI SDK
+ * and enable provider-specific functionality
+ * that can be fully encapsulated in the provider.
+ *
+ * The outer record is keyed by the provider name, and the inner
+ * record is keyed by the provider-specific metadata key.
+ *
+ * ```ts
+ * {
+ *   "anthropic": {
+ *     "cacheControl": { "type": "ephemeral" }
+ *   }
+ * }
+ * ```
+ */
+export type SharedProviderMetadata = Record<string, JSONObject>;
+
+export type SharedProviderOptions = Record<string, JSONObject>;

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}