flowerintelligence.ts

// Copyright 2025 Flower Labs GmbH. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// =============================================================================

import { Engine } from './engines/engine';
import { RemoteEngine } from './engines/remoteEngine';
import { TransformersEngine } from './engines/transformersEngine';
import { ChatOptions, ChatResponseResult, FailureCode, Message, Progress, Result } from './typing';
import { WebllmEngine } from './engines/webllmEngine';
import { DEFAULT_MODEL } from './constants';

/* eslint-disable @typescript-eslint/no-unnecessary-condition */
const isNode = typeof process !== 'undefined' && process.versions.node != null;
/* eslint-enable @typescript-eslint/no-unnecessary-condition */

/**
 * Class representing the core intelligence service for Flower Labs.
 * It facilitates chat, generation, and summarization tasks, with the option of using a
 * local or remote engine based on configurations and availability.
 */
export class FlowerIntelligence {
  static #instance: FlowerIntelligence | null = null;
  static #remoteHandoff = false;
  static #apiKey?: string;

  #remoteEngine?: RemoteEngine;
  #availableLocalEngines: Engine[] = isNode ? [new TransformersEngine()] : [new WebllmEngine()];

  /**
   * Get the initialized FlowerIntelligence instance.
   * Initializes the instance if it doesn't exist.
   * @returns The initialized FlowerIntelligence instance.
   */
  public static get instance(): FlowerIntelligence {
    if (!this.#instance) {
      this.#instance = new FlowerIntelligence();
    }
    return this.#instance;
  }
  /**
   * Sets the remote handoff boolean.
   * @param remoteHandoffValue - If true, the processing might be done on a secure
   remote server instead of locally (if resources are lacking).
   */
  public set remoteHandoff(remoteHandoffValue: boolean) {
    FlowerIntelligence.#remoteHandoff = remoteHandoffValue;
  }

  /**
   * Gets the current remote handoff status.
   * @returns boolean - the value of the remote handoff variable
   */
  public get remoteHandoff() {
    return FlowerIntelligence.#remoteHandoff;
  }

  /**
   * Set apiKey for FlowerIntelligence.
   */
  public set apiKey(apiKey: string) {
    FlowerIntelligence.#apiKey = apiKey;
  }

  /**
   * Downloads and loads a model into memory.
   * @param model Model name to use for the chat.
   * @param callback A callback function taking a {@link Progress} object to handle the loading event.
   * @returns A {@link Result} containing either a {@link Failure} (containing `code: number` and `description: string`) if `ok` is false or a value of `void`, if `ok` is true (meaning the loading was successful).
   */
  async fetchModel(model: string, callback: (progress: Progress) => void): Promise<Result<void>> {
    const engineResult = await this.getEngine(model, false, false);
    if (!engineResult.ok) {
      return engineResult;
    } else {
      return await engineResult.value.fetchModel(model, callback);
    }
  }

  // Overload for string input with an optional options object
  async chat(input: string, options?: ChatOptions): Promise<ChatResponseResult>;

  // Overload for a single object that includes messages along with other options
  async chat(options: ChatOptions & { messages: Message[] }): Promise<ChatResponseResult>;

  /**
   * Conducts a chat interaction using the specified model and options.
   *
   * This method can be invoked in one of two ways:
   *
   * 1. With a string input (plus an optional options object). In this case the string
   *    is automatically wrapped as a single message with role 'user'.
   *
   *    Example:
   *    ```ts
   *    fi.chat("Why is the sky blue?", { temperature: 0.7 });
   *    ```
   *
   * 2. With a single object that includes a {@link Message} array along with additional options.
   *
   *    Example:
   *    ```ts
   *    fi.chat({
   *      messages: [{ role: 'user', content: "Why is the sky blue?" }],
   *      model: "meta/llama3.2-1b"
   *    });
   *    ```
   *
   * @param inputOrOptions - Either a string input or a {@link ChatOptions} object that must include a `messages` array.
   * @param maybeOptions - An optional {@link ChatOptions} object (used only when the first parameter is a string).
   * @returns A Promise that resolves to a {@link ChatResponseResult}. On success, the result contains the
   *          message reply and optionally any tool call details; on failure, it includes an error code and description.
   */
  async chat(
    inputOrOptions: string | (ChatOptions & { messages: Message[] }),
    maybeOptions?: ChatOptions
  ): Promise<ChatResponseResult> {
    const chatResult = await this.internalChat(inputOrOptions, maybeOptions);
    if (!chatResult.ok) {
      if (
        chatResult.failure.code === FailureCode.LocalEngineChatError &&
        this.remoteHandoff &&
        this.apiKey
      ) {
        return await this.internalChat(inputOrOptions, { ...maybeOptions, forceRemote: true });
      }
    }
    return chatResult;
  }

  private async internalChat(
    inputOrOptions: string | (ChatOptions & { messages: Message[] }),
    maybeOptions?: ChatOptions
  ): Promise<ChatResponseResult> {
    let options: ChatOptions;
    let messages: Message[];

    if (typeof inputOrOptions === 'string') {
      options = maybeOptions ?? {};
      messages = [{ role: 'user', content: inputOrOptions }];
    } else {
      ({ messages, ...options } = inputOrOptions);
    }

    const model = options.model ?? DEFAULT_MODEL;
    const engineResult = await this.getEngine(
      model,
      options.forceRemote ?? false,
      options.forceLocal ?? false
    );

    if (!engineResult.ok) {
      return engineResult;
    }

    return await engineResult.value.chat(
      messages,
      model,
      options.temperature,
      options.maxCompletionTokens,
      options.stream,
      options.onStreamEvent,
      options.tools,
      options.encrypt
    );
  }

  private async getEngine(
    modelId: string,
    forceRemote: boolean,
    forceLocal: boolean
  ): Promise<Result<Engine>> {
    const argsResult = this.validateArgs(forceRemote, forceLocal);
    if (!argsResult.ok) {
      return argsResult;
    }

    if (forceRemote) {
      return this.getOrCreateRemoteEngine();
    }

    const localEngineResult = await this.chooseLocalEngine(modelId);
    if (localEngineResult.ok) {
      return localEngineResult;
    }

    return this.getOrCreateRemoteEngine(localEngineResult);
  }

  private async chooseLocalEngine(modelId: string): Promise<Result<Engine>> {
    const compatibleEngines = (
      await Promise.all(
        this.#availableLocalEngines.map(async (engine) => {
          return (await engine.isSupported(modelId)) ? engine : null;
        })
      )
    ).filter((item): item is Engine => item !== null);

    if (compatibleEngines.length > 0) {
      // Currently we just select the first compatible localEngine without further check
      return { ok: true, value: compatibleEngines[0] };
    } else {
      return {
        ok: false,
        failure: {
          code: FailureCode.NoLocalProviderError,
          description: `No available local engine for ${modelId}.`,
        },
      };
    }
  }

  private getOrCreateRemoteEngine(localFailure?: Result<Engine>): Result<Engine> {
    if (localFailure && !FlowerIntelligence.#remoteHandoff && !FlowerIntelligence.#apiKey) {
      return localFailure;
    }
    if (!FlowerIntelligence.#remoteHandoff) {
      return {
        ok: false,
        failure: {
          description: 'To use remote inference, remote handoff must be allowed.',
          code: FailureCode.InvalidRemoteConfigError,
        },
      };
    }
    if (!FlowerIntelligence.#apiKey) {
      return {
        ok: false,
        failure: {
          description: 'To use remote inference, a valid API key must be set.',
          code: FailureCode.InvalidRemoteConfigError,
        },
      };
    }
    this.#remoteEngine = this.#remoteEngine ?? new RemoteEngine(FlowerIntelligence.#apiKey);
    return { ok: true, value: this.#remoteEngine };
  }

  private validateArgs(forceRemote: boolean, forceLocal: boolean): Result<void> {
    if (forceLocal && forceRemote) {
      return {
        ok: false,
        failure: {
          description:
            'The `forceLocal` and `forceRemote` options cannot be true at the same time.',
          code: FailureCode.InvalidArgumentsError,
        },
      };
    }
    return { ok: true, value: undefined };
  }
}