stamp: improved error handling

- Applying 'pattern matching' and 'Result pattern' to improve error
handling. It enforces that users must first check for errors before
consuming the message

Author: kallebysantos

ext/ai/js/ai.ts

@@ -10,6 +10,9 @@ import {
 // @ts-ignore deno_core environment
 const core = globalThis.Deno.core;
 
+// TODO: extract to utils file
+export type Result<T, E> = [T, undefined] | [undefined, E];
+
 // NOTE:(kallebysantos) do we still need gte-small? Or maybe add another type 'embeddings' with custom model opt.
 export type SessionType = LLMProviderName | "gte-small";
 
@@ -47,6 +50,16 @@ export type SessionOutput<T extends SessionType, O> = T extends "gte-small"
     : LLMProviderInstance<T>["output"]
   : never;
 
+export type SessionError<T = object | string> = {
+  message: string;
+  inner: T;
+};
+
+export type SessionOutputError<T extends SessionType> = T extends "gte-small"
+  ? SessionError<Error>
+  : T extends LLMProviderName ? SessionError<LLMProviderInstance<T>["error"]>
+  : any;
+
 export class Session<T extends SessionType> {
   #model?: string;
   #init?: Promise<void>;
@@ -87,42 +100,58 @@ export class Session<T extends SessionType> {
   async run<O extends SessionInputOptions<T>>(
     input: SessionInput<T>,
     options: O,
-  ): Promise<SessionOutput<T, O>> {
-    if (this.isLLMType()) {
-      const opts = options as LLMInputOptions;
-      const stream = opts.stream ?? false;
-
-      const llmSession = LLMSession.fromProvider(this.type, {
-        // safety: We did check `options` during construction
-        baseURL: this.options!.baseURL,
-        model: this.options!.model,
-        ...this.options, // allows custom provider initialization like 'apiKey'
-      });
-
-      return await llmSession.run(input, {
-        stream,
-        signal: opts.signal,
-        timeout: opts.timeout,
-      }) as SessionOutput<T, typeof options>;
-    }
+  ): Promise<
+    [SessionOutput<T, O>, undefined] | [undefined, SessionOutputError<T>]
+  > {
+    try {
+      if (this.isLLMType()) {
+        const opts = options as LLMInputOptions;
+        const stream = opts.stream ?? false;
+
+        const llmSession = LLMSession.fromProvider(this.type, {
+          // safety: We did check `options` during construction
+          baseURL: this.options!.baseURL,
+          model: this.options!.model,
+          ...this.options, // allows custom provider initialization like 'apiKey'
+        });
+
+        const [output, error] = await llmSession.run(input, {
+          stream,
+          signal: opts.signal,
+          timeout: opts.timeout,
+        });
+        if (error) {
+          return [undefined, error as SessionOutputError<T>];
+        }
+
+        return [output as SessionOutput<T, typeof options>, undefined];
+      }
 
-    if (this.#init) {
-      await this.#init;
-    }
+      if (this.#init) {
+        await this.#init;
+      }
 
-    const opts = options as EmbeddingInputOptions;
+      const opts = options as EmbeddingInputOptions;
 
-    const mean_pool = opts.mean_pool ?? true;
-    const normalize = opts.normalize ?? true;
+      const mean_pool = opts.mean_pool ?? true;
+      const normalize = opts.normalize ?? true;
 
-    const result = await core.ops.op_ai_run_model(
-      this.#model,
-      prompt,
-      mean_pool,
-      normalize,
-    );
+      const result = await core.ops.op_ai_run_model(
+        this.#model,
+        prompt,
+        mean_pool,
+        normalize,
+      ) as SessionOutput<T, typeof options>;
 
-    return result;
+      return [result, undefined];
+    } catch (e: any) {
+      const error = (e instanceof Error) ? e : new Error(e);
+
+      return [
+        undefined,
+        { inner: error, message: error.message } as SessionOutputError<T>,
+      ];
+    }
   }
 
   private isEmbeddingType(

ext/ai/js/llm/llm_session.ts

@@ -1,3 +1,4 @@
+import { Result, SessionError } from "../ai.ts";
 import { OllamaLLMSession } from "./providers/ollama.ts";
 import { OpenAILLMSession } from "./providers/openai.ts";
 
@@ -20,6 +21,7 @@ export type LLMRunInput = {
 export interface ILLMProviderMeta {
   input: ILLMProviderInput;
   output: unknown;
+  error: unknown;
   options: ILLMProviderOptions;
 }
 
@@ -41,15 +43,23 @@ export interface ILLMProviderOutput<T = object> {
   inner: T;
 }
 
+export interface ILLMProviderError<T = object> extends SessionError<T> {
+}
+
 export interface ILLMProvider {
   getStream(
     input: ILLMProviderInput,
     signal: AbortSignal,
-  ): Promise<AsyncIterable<ILLMProviderOutput>>;
+  ): Promise<
+    Result<
+      AsyncIterable<Result<ILLMProviderOutput, ILLMProviderError>>,
+      ILLMProviderError
+    >
+  >;
   getText(
     input: ILLMProviderInput,
     signal: AbortSignal,
-  ): Promise<ILLMProviderOutput>;
+  ): Promise<Result<ILLMProviderOutput, ILLMProviderError>>;
 }
 
 export const providers = {
@@ -81,6 +91,10 @@ export type LLMSessionRunInputOptions = {
   signal?: AbortSignal;
 };
 
+export type LLMSessionOutput =
+  | AsyncIterable<Result<ILLMProviderOutput, ILLMProviderError>>
+  | ILLMProviderOutput;
+
 export class LLMSession {
   #inner: ILLMProvider;
 
@@ -97,10 +111,10 @@ export class LLMSession {
     return new LLMSession(provider);
   }
 
-  run(
+  async run(
     input: ILLMProviderInput,
     opts: LLMSessionRunInputOptions,
-  ): Promise<AsyncIterable<ILLMProviderOutput>> | Promise<ILLMProviderOutput> {
+  ): Promise<Result<LLMSessionOutput, ILLMProviderError>> {
     const isStream = opts.stream ?? false;
 
     const timeoutSeconds = typeof opts.timeout === "number" ? opts.timeout : 60;
@@ -112,7 +126,15 @@ export class LLMSession {
     const signal = AbortSignal.any(abortSignals);
 
     if (isStream) {
-      return this.#inner.getStream(input, signal);
+      const [stream, getStreamError] = await this.#inner.getStream(
+        input,
+        signal,
+      );
+      if (getStreamError) {
+        return [undefined, getStreamError];
+      }
+
+      return [stream, undefined];
     }
 
     return this.#inner.getText(input, signal);