booths 0.1.3 → 1.1.0

package/README.md

@@ -10,12 +10,11 @@ The Booths framework is built around a few key concepts that work together to cr
 
 ```mermaid
 graph TD
-    subgraph User Interface
-        A[Vue.js Component]
+    subgraph Application Layer
+        A[Your Application]
     end
 
     subgraph Booth Service Layer
-        B(useLLMService)
         C(CoreBooth)
     end
 
@@ -26,8 +25,7 @@ graph TD
         G[Plugins]
     end
 
-    A -- "sends user input" --> B
-    B -- "initializes and calls" --> C
+    A -- "initializes and calls" --> C
     C -- "delegates to" --> D
     D -- "uses" --> E
     D -- "uses" --> F
@@ -38,57 +36,47 @@ graph TD
     F -- "manages" --> K{Plugins}
     G -- "hook into" --> D
 
-    style B fill:#f9f,stroke:#333,stroke-width:2px
     style C fill:#f9f,stroke:#333,stroke-width:2px
 ```
 
-1.  **User Interface**: A frontend application (e.g., a Vue component) captures user input and displays the conversation.
-2.  **Service Layer (`useLLMService.ts`)**: This layer acts as a bridge between the UI and the Booths engine. It initializes the `CoreBooth`, manages the conversational state, and exposes methods for sending messages.
-3.  **`CoreBooth`**: The central orchestrator of the system. It is configured with an `LLMAdapter`, and a set of registries for booths, tools, and plugins.
-4.  **`InteractionProcessor`**: The engine that drives the conversation. It takes user input, runs it through the plugin lifecycle, sends it to the LLM (via the adapter), and processes the response.
-5.  **`LLMAdapter`**: A component that handles communication with the specific LLM provider (e.g., OpenAI). It translates requests and responses between the Booths system and the LLM's API.
-6.  **Registries**: These are responsible for managing the different components of the system:
+1.  **Application Layer**: Your application integrates the Booths framework to handle conversational AI interactions.
+2.  **`CoreBooth`**: The framework foundation that provides global functionality, instructions, and infrastructure that applies to all booths. It manages the overall system configuration and coordinates the interaction flow.
+3.  **`InteractionProcessor`**: The engine that drives the conversation. It takes user input, runs it through the plugin lifecycle, sends it to the LLM (via the adapter), and processes the response.
+4.  **`LLMAdapter`**: A component that handles communication with the specific LLM provider (e.g., OpenAI). It translates requests and responses between the Booths system and the LLM's API.
+5.  **Registries**: These are responsible for managing the different components of the system:
     *   `BoothRegistry`: Manages `BoothConfig` objects that define the behavior of different AI agents.
     *   `ToolRegistry`: Manages the tools (functions) that booths can use.
     *   `BoothPluginRegistry`: Manages the plugins that hook into the conversational lifecycle.
-7.  **Plugins**: These are modules that add functionality to the system by hooking into the `InteractionProcessor`'s lifecycle (e.g., managing conversation history, providing context to the LLM, executing tools).
+6.  **Plugins**: These are modules that add functionality to the system by hooking into the `InteractionProcessor`'s lifecycle (e.g., managing conversation history, providing context to the LLM, executing tools).
 
-## Running the Examples
+## Getting Started
 
-The best way to understand the Booths framework is to run the example application provided in the `src/examples` directory.
+The Booths framework is designed as a TypeScript library for building conversational AI systems. This repository contains the core framework implementation.
 
-### Prerequisites
+### Installation
 
--   Node.js and npm installed.
--   An OpenAI API key.
+```bash
+npm install booths
+```
 
-### Setup
+### Prerequisites
 
-1.  **Clone the repository:**
-    ```bash
-    git clone <repository-url>
-    cd booths
-    ```
+-   Node.js and npm installed
+-   An LLM provider API key (e.g., OpenAI)
 
-2.  **Install dependencies:**
-    ```bash
-    npm install
-    ```
+### Development
 
-3.  **Set up your environment variables:**
-    Create a `.env.local` file in the root of the project and add your OpenAI API key:
-    ```
-    VITE_OPENAI_API_KEY=your-openai-api-key
-    ```
+To build the library:
 
-4.  **Run the application:**
-    ```bash
-    npm run dev
-    ```
+```bash
+npm run build
+```
 
-This will start a local development server. Open your browser to the specified address (usually `http://localhost:5173`) to see the chat application in action.
+To check types:
 
-The example application features a collection of pirate-themed booths that demonstrate how to create and manage different conversational agents. You can interact with a "Sea Lore" booth, a "Shipwright" booth, and even a "Duel" booth.
+```bash
+npm run typecheck
+```
 
 ## Quick Start Guide
 
@@ -135,18 +123,18 @@ export const tellPirateJokeTool: ToolModule = {
 The `CoreBooth` requires an `LLMAdapter` to communicate with your chosen language model. Here is a minimal example for OpenAI.
 
 ```typescript
-// in openAIAdapter.ts
+// in OpenAIAdapter.ts
 import type { LLMAdapter, ResponseCreateParamsNonStreaming, Response } from 'booths';
-import openai from 'openai';
+import OpenAI from 'openai';
 
-export class OpenAIAdapter implements LLMAdapter<any> {
-  openai: openai;
+export class OpenAIAdapter implements LLMAdapter<Response> {
+  private openai: OpenAI;
 
   constructor(apiKey: string) {
-    this.openai = new openai({ apiKey, dangerouslyAllowBrowser: true });
+    this.openai = new OpenAI({ apiKey });
   }
 
-  invoke(params: ResponseCreateParamsNonStreaming) {
+  async invoke(params: ResponseCreateParamsNonStreaming): Promise<Response> {
     return this.openai.responses.create({ ...params, model: 'gpt-4o' });
   }
 

package/dist/index.d.ts

@@ -13,6 +13,7 @@ import { ResponseFunctionWebSearch } from 'openai/resources/responses/responses'
 import { ResponseIncludable } from 'openai/resources/responses/responses';
 import { ResponseInput } from 'openai/resources/responses/responses';
 import { ResponseInputItem } from 'openai/resources/responses/responses';
+import { ResponseOutputItem } from 'openai/resources/responses/responses';
 import { ResponseOutputMessage } from 'openai/resources/responses/responses';
 import { ResponsePrompt } from 'openai/resources/responses/responses';
 import { ResponseReasoningItem } from 'openai/resources/responses/responses';
@@ -85,7 +86,7 @@ export declare interface BoothPlugin {
      * @param responseParams - The initial parameters for the response creation.
      * @returns The potentially modified response parameters.
      */
-    onBeforeInteractionLoopStart?: (prepareInitialMessagesArgs: RepositoryUtilities, responseParams: ResponseCreateParamsNonStreaming, initialInput: string) => Promise<ResponseCreateParamsNonStreaming>;
+    onBeforeInteractionLoopStart?: (prepareInitialMessagesArgs: RepositoryUtilities, responseParams: ResponseCreateParamsNonStreaming, initialInput: string | ResponseInput) => Promise<ResponseCreateParamsNonStreaming>;
     /**
      * Called before a message is sent to the AI. This allows for modification
      * of the message or its parameters.
@@ -207,7 +208,7 @@ export declare class BoothPluginRegistry {
      * @param initialInput
      * @returns Modified response parameters after all plugins have processed them
      */
-    runBeforeInteractionLoopStart(prepareArgs: RepositoryUtilities, initialParams: ResponseCreateParamsNonStreaming, initialInput: string): Promise<ResponseCreateParamsNonStreaming>;
+    runBeforeInteractionLoopStart(prepareArgs: RepositoryUtilities, initialParams: ResponseCreateParamsNonStreaming, initialInput: string | ResponseInput): Promise<ResponseCreateParamsNonStreaming>;
     /**
      * Sequentially invokes every plugin's onBeforeMessageSend hook.
      * This is called immediately before sending a message to the LLM,
@@ -304,6 +305,23 @@ export declare class BoothRegistry {
      * @private
      */
     private currentContextId;
+    /**
+     * Tracks whether the orchestrator booth is currently registered.
+     * @private
+     */
+    private hasOrchestrator;
+    /**
+     * Optional callback function that gets called when multi-booth mode is enabled.
+     * Used to coordinate external actions like tool registration.
+     * @private
+     */
+    private onMultiBoothModeEnabled?;
+    /**
+     * Optional callback function that gets called when multi-booth mode is disabled.
+     * Used to coordinate external actions like tool unregistration.
+     * @private
+     */
+    private onMultiBoothModeDisabled?;
     /**
      * Creates a new booth registry with a specified base booth configuration.
      *
@@ -372,10 +390,25 @@ export declare class BoothRegistry {
      * @returns Record of all booth configurations indexed by their IDs
      */
     getAllBooths(): Record<string, BoothConfig>;
+    toArray(): BoothConfig[];
     /**
-     * Checks if the registry is operating in a multi-booth configuration.
-     * @returns {boolean} `true` if there is more than one booth registered, otherwise `false`.
+     * Enables multi-booth mode by registering the orchestrator and setting it as current context.
+     * @private
      */
+    private enableMultiBoothMode;
+    /**
+     * Disables multi-booth mode by unregistering the orchestrator and resetting context to base booth.
+     * @private
+     */
+    private disableMultiBoothMode;
+    /**
+     * Sets callback functions for when multi-booth mode is enabled/disabled.
+     * Used to coordinate external actions like tool registration/unregistration.
+     *
+     * @param onEnabled - Callback for when multi-booth mode is enabled
+     * @param onDisabled - Callback for when multi-booth mode is disabled
+     */
+    setMultiBoothModeCallbacks(onEnabled?: () => void, onDisabled?: () => void): void;
     get isMultiBoothMode(): boolean;
     /**
      * Removes a booth configuration from the registry by its ID.
@@ -386,6 +419,12 @@ export declare class BoothRegistry {
     unregisterBooth(boothId: string): void;
 }
 
+export declare type BoothResponseInput = BoothResponseInputItem[];
+
+export declare type BoothResponseInputItem = (ResponseInputItem & {
+    bmId: string;
+}) | string;
+
 /**
  * The ContextProviderPlugin provides contextual information to booths during interaction loops.
  *
@@ -447,6 +486,11 @@ export declare class ContextProviderPlugin implements BoothPlugin {
  * interaction has access to the full conversation history, enabling contextual responses.
  */
 export declare class ConversationHistoryPlugin implements BoothPlugin {
+    /**
+     * The sessionHistory variable stores the conversation history between the user and the booth system.
+     * It is initialized as an empty array and will be populated with messages exchanged during the interaction.
+     */
+    private sessionHistory;
     /**
      * Unique identifier for this plugin instance.
      * @private
@@ -462,7 +506,30 @@ export declare class ConversationHistoryPlugin implements BoothPlugin {
      * @private
      */
     private readonly plugin_description;
+    /**
+     * Checks if the given response contains a booth change.
+     *
+     * A booth change is determined by examining the response's output for a specific tool call to 'route_to_booth'.
+     * The output can either include a direct function call object or a message containing a list of tool calls.
+     *
+     * @param response - The response objects to be checked. It is expected to contain an `output` property.
+     * @return A boolean indicating whether a booth change is present in the response.
+     */
     private responseContainsBoothChange;
+    /**
+     * Constructs a new instance with an optional session history.
+     *
+     * @param {ResponseInput[]} [sessionHistory=[]] - An array representing the session history. Defaults to an empty array if not provided.
+     */
+    constructor(sessionHistory?: ResponseInput);
+    /**
+     * Retrieves the session history.
+     *
+     * @return {Array} The history of the current session.
+     */
+    get history(): (ResponseInputItem & {
+        bmId?: string;
+    })[];
     /**
      * Returns the plugin's unique identifier.
      */
@@ -488,13 +555,13 @@ export declare class ConversationHistoryPlugin implements BoothPlugin {
      * Executes after receiving a response from the LLM, adding the response content
      * to the conversation history for future reference.
      *
-     * @param _
+     * @param utilities
      * @param responseParams - Current parameters for the LLM response creation
      * @param response
      * @returns Unmodified response parameters
      */
     onResponseReceived(utilities: RepositoryUtilities, responseParams: ResponseCreateParamsNonStreaming, response: Response_2): Promise<{
-        input: ( ResponseFunctionToolCall | EasyInputMessage | ResponseOutputMessage | ResponseFileSearchToolCall | ResponseComputerToolCall | ResponseInputItem.ComputerCallOutput | ResponseFunctionWebSearch | ResponseInputItem.FunctionCallOutput | ResponseReasoningItem | ResponseInputItem.ImageGenerationCall | ResponseCodeInterpreterToolCall | ResponseInputItem.LocalShellCall | ResponseInputItem.LocalShellCallOutput | ResponseInputItem.McpListTools | ResponseInputItem.McpApprovalRequest | ResponseInputItem.McpApprovalResponse | ResponseInputItem.McpCall | ResponseInputItem.ItemReference)[];
+        input: ( EasyInputMessage | ResponseOutputMessage | ResponseFileSearchToolCall | ResponseComputerToolCall | ResponseInputItem.ComputerCallOutput | ResponseFunctionWebSearch | ResponseFunctionToolCall | ResponseInputItem.FunctionCallOutput | ResponseReasoningItem | ResponseInputItem.ImageGenerationCall | ResponseCodeInterpreterToolCall | ResponseInputItem.LocalShellCall | ResponseInputItem.LocalShellCallOutput | ResponseInputItem.McpListTools | ResponseInputItem.McpApprovalRequest | ResponseInputItem.McpApprovalResponse | ResponseInputItem.McpCall | ResponseInputItem.ItemReference)[];
         stream?: false | null;
         background?: boolean | null;
         include?: Array< ResponseIncludable> | null;
@@ -585,10 +652,11 @@ export declare class CoreBooth<T> {
      * @param {ToolRegistry} options.tools - Registry containing tool configurations
      */
     constructor(options: {
-        boothPlugins: BoothPluginRegistry;
+        boothPlugins?: BoothPluginRegistry;
         booths: BoothRegistry;
-        tools: ToolRegistry;
+        tools?: ToolRegistry;
         llmAdapter: LLMAdapter<T>;
+        sessionHistory?: ResponseInput;
     });
 }
 
@@ -717,10 +785,10 @@ export declare class InteractionProcessor<T> {
      * @param input The input message to send.
      * @returns The processed response from the LLM.
      */
-    send(input: string): Promise<Response_2>;
+    send(input: string | ResponseInput): Promise<Response_2>;
 }
 
-export declare interface LLMAdapter<LLMResponse> {
+export declare interface LLMAdapter<LLMResponse = any> {
     invoke: (responseParams: ResponseCreateParamsNonStreaming) => Promise<LLMResponse>;
     interpret: (response: LLMResponse) => Promise<Response_2>;
 }
@@ -799,6 +867,7 @@ export declare class ToolExecutorPlugin implements BoothPlugin {
      * @private
      */
     private executeToolCall;
+    static extractFunctionCalls(output: ResponseOutputItem[]): ResponseFunctionToolCall[];
     /**
      * After a response is received from the LLM, this hook checks for tool calls. If any are found,
      * it executes them using the `toolRegistry` and appends their outputs to the response parameters'
@@ -827,7 +896,8 @@ export declare type ToolModule = FunctionTool & {
      * @param input - The input parameters for the tool, typically parsed from a JSON string.
      * @returns A promise that resolves with the result of the tool's execution.
      */
-    execute: (input: any) => Promise<any>;
+    execute?: (input?: any) => Promise<any>;
+    global?: boolean;
 };
 
 /**
@@ -916,12 +986,26 @@ export declare class ToolRegistry {
      * @returns The tool instance if found, undefined otherwise
      */
     getTool(toolName: string): ToolModule;
+    getGlobalTools(): ToolModule[];
     /**
      * Returns all registered tools as an array.
      *
      * @returns Array of all registered Tool instances
      */
-    getAllTools(): ToolModule[];
+    getServerTools(): ToolModule[];
+    /**
+     * Returns local tools. Local tools are distinguished by not having the execute method.
+     */
+    getLocalTools(): ToolModule[];
+    /**
+     * Determines if the specified tool is a local tool.
+     *
+     * A local tool is identified by the `execute` property being undefined.
+     *
+     * @param {string} toolName - The name of the tool to be checked.
+     * @return {boolean} - Returns true if the specified tool is a local tool, false otherwise.
+     */
+    isLocalTool(toolName: string): boolean;
     /**
      * Removes a tool from the registry by its ID.
      * Throws an error if the tool doesn't exist.