booths 0.0.3 → 0.0.6

package/README.md

@@ -4,60 +4,11 @@ The Core Booth system is a modular and extensible framework for building and man
 
 The system is designed around a central `CoreBooth` class that orchestrates interactions between users and the Large Language Model (LLM), leveraging a system of registries and plugins to manage the conversational state and capabilities.
 
-## How It Works
-
-The Core Booth system is comprised of several key components that work together to process user input and generate contextual responses.
-
-### 1. Registries
-
-- **`BoothRegistry`**: Manages the collection of `BoothConfig` objects. Each booth represents a specialized agent with a specific role, description, and set of tools. It also keeps track of the "current context booth" to ensure the conversation stays on topic.
-- **`ToolRegistry`**: Manages the tools that can be made available to the LLM. Tools are functions that the AI can decide to call to perform actions or retrieve information.
-- **`BoothPluginRegistry`**: Manages plugins that hook into the interaction lifecycle. This allows for modular and reusable functionality to be added to the system.
-
-### 2. Plugins
-
-Plugins are classes that implement the `BoothPlugin` interface. They can execute logic at different stages of the conversation:
-
-- `onBeforeInteractionLoopStart`: Before the main loop begins.
-- `onBeforeMessageSend`: Before a message is sent to the LLM.
-- `onResponseReceived`: After a response is received from the LLM.
-- `onBeforeToolCall`: Before each individual tool call is executed _(allows modification of tool parameters, validation, and logging)_.
-- `onAfterToolCall`: After each individual tool call is successfully executed _(allows result processing, caching, and transformation)_.
-- `onToolCallError`: When a tool call encounters an error _(allows custom error handling and recovery)_.
-- `shouldEndInteractionLoop`: To determine if the conversation turn is over.
-- `onAfterInteractionLoopEnd`: After the main loop has finished.
-
-The system includes several core plugins by default:
-
-- `ConversationHistoryPlugin`: Maintains the history of the conversation.
-- `ContextProviderPlugin`: Provides the LLM with the context of the current booth.
-- `ToolProviderPlugin`: Provides the LLM with the available tools for the current booth.
-- `ToolExecutorPlugin`: Executes tool calls requested by the LLM with granular hook support for individual tool call interception.
-- `FinishTurnPlugin`: Determines when the LLM's turn is finished and it's waiting for user input.
-
-#### Enhanced Tool Call Management
-
-The plugin system now provides granular control over individual tool executions through three new hooks:
-
-- **`onBeforeToolCall`**: Intercept and modify tool calls before execution (parameter validation, authorization, logging)
-- **`onAfterToolCall`**: Process and transform tool results after successful execution (caching, metadata addition, data transformation)
-- **`onToolCallError`**: Handle tool execution errors with custom recovery logic (fallback responses, error logging, graceful degradation)
-
-This enables sophisticated tool management patterns like authentication, caching, audit logging, and error recovery at the individual tool level.
-
-### 3. Interaction Processor
-
-The `InteractionProcessor` is the engine of the system. It manages the interaction loop with the LLM:
+## Installation
 
-1. It takes user input.
-2. Runs the `onBefore...` plugin hooks.
-3. Sends the payload to the LLM.
-4. Receives the response.
-5. Runs the `onResponseReceived` plugin hooks to process the response (e.g., execute tools).
-6. Repeats this loop until a plugin's `shouldEndInteractionLoop` returns `true`.
-7. Runs the `onAfter...` plugin hooks for cleanup.
-
----
+```bash
+npm install booths
+```
 
 ## Quick Start Example
 
@@ -69,7 +20,7 @@ First, define your booth configurations and any custom tools you need.
 
 ```typescript
 // in my-booths.ts
-import type { BoothConfig } from './types/booths.types'
+import type { BoothConfig } from 'booths';
 
 export const customerSupportBooth: BoothConfig = {
   id: 'customer-support',
@@ -77,10 +28,12 @@ export const customerSupportBooth: BoothConfig = {
   description: 'You are a helpful customer support assistant for a SaaS company.',
   tools: ['get_user_account_details'],
   examples: ["I'm having trouble with my account.", 'I want to upgrade my subscription.'],
-}
+};
+```
 
+```typescript
 // in my-tools.ts
-import type { ToolModule } from './types/tools.types'
+import type { ToolModule } from 'booths';
 
 export const getUserAccountDetailsTool: ToolModule = {
   type: 'function',
@@ -89,47 +42,154 @@ export const getUserAccountDetailsTool: ToolModule = {
   parameters: { type: 'object', properties: {} },
   execute: async () => {
     // In a real app, you would fetch this from an API
-    return { accountId: '123', plan: 'Pro' }
+    return { accountId: '123', plan: 'Pro' };
   },
+};
+```
+
+### 2. Implement the LLM Adapter
+
+The `CoreBooth` requires an `LLMAdapter` to communicate with your chosen language model. Here is a minimal example of what that adapter could look like.
+
+```typescript
+// in MyLLMAdapter.ts
+import type { LLMAdapter, ResponseCreateParamsNonStreaming } from 'booths';
+
+class MyLLMAdapter implements LLMAdapter<any> {
+    async createResponse(params: ResponseCreateParamsNonStreaming) {
+        // This is a mock implementation.
+        // In a real application, you would make a call to an LLM API (e.g., OpenAI, Anthropic).
+        console.log('Sending to LLM:', params.messages);
+        
+        const lastMessage = params.messages[params.messages.length - 1];
+
+        if (lastMessage.content?.includes("check my account plan")) {
+             return {
+                id: 'fake-response-id',
+                choices: [{
+                    message: {
+                        role: 'assistant',
+                        content: null,
+                        tool_calls: [{
+                            id: 'tool-call-1',
+                            type: 'function',
+                            function: {
+                                name: 'get_user_account_details',
+                                arguments: '{}'
+                            }
+                        }]
+                    }
+                }]
+             }
+        }
+        
+        return {
+            id: 'fake-response-id',
+            choices: [{
+                message: {
+                    role: 'assistant',
+                    content: "I am on the Pro plan.",
+                }
+            }]
+        };
+    }
 }
+
+export default MyLLMAdapter;
 ```
 
-### 2. Initialize the CoreBooth
+### 3. Initialize the CoreBooth
 
 Next, instantiate the registries and the `CoreBooth` itself.
 
 ```typescript
-import { CoreBooth, BoothRegistry, ToolRegistry, BoothPluginRegistry } from './index'
-import { customerSupportBooth } from './my-booths'
-import { getUserAccountDetailsTool } from './my-tools'
+// in main.ts
+import { CoreBooth, BoothRegistry, ToolRegistry, BoothPluginRegistry } from 'booths';
+import { customerSupportBooth } from './my-booths';
+import { getUserAccountDetailsTool } from './my-tools';
+import MyLLMAdapter from './MyLLMAdapter';
 
 // 1. Create instances of the registries
-const boothRegistry = new BoothRegistry()
-const toolRegistry = new ToolRegistry()
-const boothPluginRegistry = new BoothPluginRegistry() // For custom user plugins
+const boothRegistry = new BoothRegistry();
+const toolRegistry = new ToolRegistry();
+const boothPluginRegistry = new BoothPluginRegistry(); // For custom user plugins
 
 // 2. Register your booths and tools
-boothRegistry.registerBooth(customerSupportBooth)
-toolRegistry.registerTool(getUserAccountDetailsTool)
+boothRegistry.registerBooths([customerSupportBooth]);
+toolRegistry.registerTools([getUserAccountDetailsTool]);
 
 // 3. Set a starting context for the conversation
-boothRegistry.setCurrentContextId('customer-support')
+boothRegistry.setCurrentContextId('customer-support');
 
-// 4. Create the CoreBooth instance
+// 4. Create the CoreBooth instance with the adapter
 const coreBooth = new CoreBooth({
   booths: boothRegistry,
   tools: toolRegistry,
   boothPlugins: boothPluginRegistry,
-})
+  llmAdapter: new MyLLMAdapter(),
+});
 
 // 5. Send a message and get a response
 async function haveConversation() {
-  const userInput = 'Can you check my account plan?'
-  const response = await coreBooth.callProcessor.send(userInput)
+  const userInput = 'Can you check my account plan?';
+  const response = await coreBooth.callProcessor.send(userInput);
 
-  console.log(response.output_text)
+  console.log(response.output_text);
   // Expected output might be something like: "You are currently on the Pro plan."
 }
 
-haveConversation()
+haveConversation();
 ```
+
+## How It Works
+
+The Core Booth system is comprised of several key components that work together to process user input and generate contextual responses.
+
+### 1. Registries
+
+- **`BoothRegistry`**: Manages the collection of `BoothConfig` objects. Each booth represents a specialized agent with a specific role, description, and set of tools. It also keeps track of the "current context booth" to ensure the conversation stays on topic.
+- **`ToolRegistry`**: Manages the tools that can be made available to the LLM. Tools are functions that the AI can decide to call to perform actions or retrieve information.
+- **`BoothPluginRegistry`**: Manages plugins that hook into the interaction lifecycle. This allows for modular and reusable functionality to be added to the system.
+
+### 2. Plugins
+
+Plugins are classes that implement the `BoothPlugin` interface. They can execute logic at different stages of the conversation:
+
+- `onBeforeInteractionLoopStart`: Before the main loop begins.
+- `onBeforeMessageSend`: Before a message is sent to the LLM.
+- `onResponseReceived`: After a response is received from the LLM.
+- `onBeforeToolCall`: Before each individual tool call is executed _(allows modification of tool parameters, validation, and logging)_.
+- `onAfterToolCall`: After each individual tool call is successfully executed _(allows result processing, caching, and transformation)_.
+- `onToolCallError`: When a tool call encounters an error _(allows custom error handling and recovery)_.
+- `shouldEndInteractionLoop`: To determine if the conversation turn is over.
+- `onAfterInteractionLoopEnd`: After the main loop has finished.
+
+The system includes several core plugins by default:
+
+- `ConversationHistoryPlugin`: Maintains the history of the conversation.
+- `ContextProviderPlugin`: Provides the LLM with the context of the current booth.
+- `ToolProviderPlugin`: Provides the LLM with the available tools for the current booth.
+- `ToolExecutorPlugin`: Executes tool calls requested by the LLM with granular hook support for individual tool call interception.
+- `FinishTurnPlugin`: Determines when the LLM's turn is finished and it's waiting for user input.
+
+#### Enhanced Tool Call Management
+
+The plugin system now provides granular control over individual tool executions through three new hooks:
+
+- **`onBeforeToolCall`**: Intercept and modify tool calls before execution (parameter validation, authorization, logging)
+- **`onAfterToolCall`**: Process and transform tool results after successful execution (caching, metadata addition, data transformation)
+- **`onToolCallError`**: Handle tool execution errors with custom recovery logic (fallback responses, error logging, graceful degradation)
+
+This enables sophisticated tool management patterns like authentication, caching, audit logging, and error recovery at the individual tool level.
+
+### 3. Interaction Processor
+
+The `InteractionProcessor` is the engine of the system. It manages the interaction loop with the LLM:
+
+1. It takes user input.
+2. Runs the `onBefore...` plugin hooks.
+3. Sends the payload to the LLM.
+4. Receives the response.
+5. Runs the `onResponseReceived` plugin hooks to process the response (e.g., execute tools).
+6. Repeats this loop until a plugin's `shouldEndInteractionLoop` returns `true`.
+7. Runs the `onAfter...` plugin hooks for cleanup.

package/dist/index.js

@@ -827,7 +827,12 @@ class R {
     return e += `
     
 
- Once a user response is expected, at the end of your message, add "__awaiting_user_response__" to your message.`, {
+ 
+    [MUST]
+    - Add the marker "__awaiting_user_response__" to the end of your response when you expect a user response.
+    - This marker indicates that the interaction loop should end and the system should wait for user input
+    - If the marker is not present, the system will continue to process the response as usual.
+    `, {
       ...o,
       instructions: e
     };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "booths",
   "private": false,
-  "version": "0.0.3",
+  "version": "0.0.6",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",