booths 0.0.0

package/README.md

@@ -0,0 +1,135 @@
+# Core Booth System
+
+The Core Booth system is a modular and extensible framework for building and managing conversational AI agents, referred to as "Booths." It provides a structured way to define the capabilities, context, and tools for different AI-powered conversational flows.
+
+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:
+
+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.
+
+---
+
+## Quick Start Example
+
+Here is a lightweight example of how to set up and use the Core Booth system.
+
+### 1. Define Booths and Tools
+
+First, define your booth configurations and any custom tools you need.
+
+```typescript
+// in my-booths.ts
+import type { BoothConfig } from './types/booths.types'
+
+export const customerSupportBooth: BoothConfig = {
+  id: 'customer-support',
+  role: 'Customer Support Assistant',
+  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.'],
+}
+
+// in my-tools.ts
+import type { ToolModule } from './types/tools.types'
+
+export const getUserAccountDetailsTool: ToolModule = {
+  type: 'function',
+  name: 'get_user_account_details',
+  description: 'Gets the account details for the current user.',
+  parameters: { type: 'object', properties: {} },
+  execute: async () => {
+    // In a real app, you would fetch this from an API
+    return { accountId: '123', plan: 'Pro' }
+  },
+}
+```
+
+### 2. 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'
+
+// 1. Create instances of the registries
+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)
+
+// 3. Set a starting context for the conversation
+boothRegistry.setCurrentContextId('customer-support')
+
+// 4. Create the CoreBooth instance
+const coreBooth = new CoreBooth({
+  booths: boothRegistry,
+  tools: toolRegistry,
+  boothPlugins: boothPluginRegistry,
+})
+
+// 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)
+
+  console.log(response.output_text)
+  // Expected output might be something like: "You are currently on the Pro plan."
+}
+
+haveConversation()
+```