@codebolt/agent 1.1.0 → 2.2.2

package/README.md

@@ -1,101 +1,177 @@
-# CodeBolt Agent Utils
+# CodeBolt Agent Package
 
-A TypeScript library providing utilities for building and managing AI agents with CodeBolt. This package extracts the agent functionality from the main CodeBolt library into a focused, reusable package.
+A comprehensive TypeScript framework for building and managing AI agents with CodeBolt. This package provides multiple architectural patterns and utilities to meet different development needs, from simple composable agents to complex multi-step workflows.
 
-## Features
+## 🚀 Quick Start
 
-- **Agent Class**: Core agent functionality for managing conversations with LLMs
-- **Message Builders**: Utilities for building user messages, system prompts, and task instructions
-- **Prompt Management**: Advanced prompt building and management capabilities
-- **LLM Output Handling**: Processing and managing LLM responses and tool executions
-- **Follow-up Questions**: Generate contextual follow-up questions for conversations
+```typescript
+import { ComposableAgent, createTool } from '@codebolt/agent/composable';
+import { z } from 'zod';
+
+// Create a simple weather tool
+const weatherTool = createTool({
+  id: 'get-weather',
+  description: 'Get current weather for a location',
+  inputSchema: z.object({ location: z.string() }),
+  outputSchema: z.object({ temperature: z.number(), conditions: z.string() }),
+  execute: async ({ context }) => {
+    return await getWeatherAPI(context.location);
+  },
+});
+
+// Create and run agent
+const agent = new ComposableAgent({
+  name: 'Weather Agent',
+  instructions: 'You are a helpful weather assistant.',
+  model: 'gpt-4o-mini',
+  tools: { weatherTool },
+  memory: createCodeBoltAgentMemory('weather_agent')
+});
+
+const result = await agent.execute('What is the weather in New York?');
+```
+
+## ✨ Key Features
+
+- **Multiple Patterns**: Choose between Composable, Builder, and Processor patterns
+- **Type Safety**: Full TypeScript support with Zod validation
+- **Memory Management**: Persistent conversation storage with CodeBolt integration
+- **Tool System**: Extensible tool framework with validation
+- **Workflow Orchestration**: Multi-step agent processes with conditional logic
+- **Model Agnostic**: Support for OpenAI, Anthropic, Ollama, and more
+- **Stream Support**: Real-time streaming responses
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install @codebolt/agent
 ```
 
-## Usage
+## 📖 Documentation
 
-### Basic Agent Setup
+**📚 [View Complete Documentation](./DOCUMENTATION.md)** - Comprehensive guide with examples, API reference, and best practices
 
-```typescript
-import { Agent, SystemPrompt, TaskInstruction } from '@codebolt/agent';
+### Quick Links
+- [Architectural Patterns](./DOCUMENTATION.md#architectural-patterns) - Choose the right pattern for your use case
+- [API Reference](./API_REFERENCE.md) - Complete API documentation  
+- [Examples](./EXAMPLES.md) - Real-world usage examples and tutorials
+- [Best Practices](./DOCUMENTATION.md#best-practices) - Tips for optimal agent development
+- [Migration Guide](./DOCUMENTATION.md#migration-guide) - Upgrading from previous versions
+
+## 🎯 Architecture Patterns
 
-// Create a system prompt
-const systemPrompt = new SystemPrompt();
-await systemPrompt.loadPrompt('./prompts/system.yaml');
+### Composable Pattern (Recommended)
+**Best for**: Rapid prototyping, simple agents, beginners
 
-// Create a task instruction
-const taskInstruction = new TaskInstruction();
-await taskInstruction.loadInstruction('./tasks/coding-task.yaml');
+```typescript
+import { ComposableAgent, createTool, createCodeBoltAgentMemory } from '@codebolt/agent/composable';
 
-// Initialize agent
-const agent = new Agent([], systemPrompt);
+const agent = new ComposableAgent({
+  name: 'My Agent',
+  instructions: 'You are a helpful assistant.',
+  model: 'gpt-4o-mini',
+  tools: { myTool },
+  memory: createCodeBoltAgentMemory('agent_id')
+});
 
-// Run the agent on a task
-const result = await agent.runAgent(taskInstruction);
+const result = await agent.execute('Help me with this task');
 ```
 
-### Building User Messages
+### Builder Pattern
+**Best for**: Complex workflows, fine-grained control
 
 ```typescript
-import { UserMessage } from '@codebolt/agent-utils';
+import { Agent, InitialPromptBuilder, LLMOutputHandler } from '@codebolt/agent/builder';
 
-const userMessage = new UserMessage();
-await userMessage.addMessage("Please help me with my code");
-await userMessage.addFileContent("./src/main.ts");
+const promptBuilder = new InitialPromptBuilder(userMessage)
+  .addSystemInstructions("You are a coding assistant")
+  .addFile("./src/main.ts")
+  .addTaskDetails("Fix compilation errors");
+
+const prompt = await promptBuilder.build();
+const agent = new Agent(tools, systemPrompt);
+const result = await agent.runAgent(prompt);
 ```
 
-### Advanced Prompt Building
+### Processor Pattern
+**Best for**: Advanced customization, specialized requirements
 
 ```typescript
-import { InitialPromptBuilder } from '@codebolt/agent';
-
-const promptBuilder = new InitialPromptBuilder("Fix the bug in my application");
-promptBuilder
-  .addSystemInstructions("You are a helpful coding assistant")
-  .addFile("./src/problematic-file.ts")
-  .addTaskDetails("Find and fix the TypeScript compilation errors");
+import { BaseProcessor, AgentStep } from '@codebolt/agent/processor';
 
-const prompt = await promptBuilder.build();
+class CustomProcessor extends BaseProcessor {
+  async process(messages: any[]): Promise<any> {
+    return this.executeCustomFlow(messages);
+  }
+}
 ```
 
-### LLM Output Handling
+## 🛠️ Available Exports
+
+### Composable Pattern
+```typescript
+import { 
+  ComposableAgent, createTool, createWorkflow,
+  Memory, createCodeBoltAgentMemory, MDocument 
+} from '@codebolt/agent/composable';
+```
 
+### Builder Pattern  
 ```typescript
-import { LLMOutputHandler } from '@codebolt/agent';
+import { 
+  Agent, InitialPromptBuilder, LLMOutputHandler,
+  SystemPrompt, TaskInstruction, UserMessage 
+} from '@codebolt/agent/builder';
+```
 
-const outputHandler = new LLMOutputHandler();
-const result = await outputHandler.processLLMResponse(llmResponse, tools);
+### Processor Pattern
+```typescript
+import { 
+  BaseProcessor, AgentStep, BaseTool,
+  ChatCompressionProcessor, LoopDetectionProcessor 
+} from '@codebolt/agent/processor';
 ```
 
-## API Reference
+## 🏗️ Workflow System
 
-### Classes
+Create complex multi-agent workflows:
 
-- `Agent` - Core agent for managing LLM conversations and tool executions
-- `UserMessage` - Builder for user messages with file content support
-- `SystemPrompt` - Management of system prompts from YAML files
-- `TaskInstruction` - Handling of task instructions and metadata
-- `InitialPromptBuilder` - Fluent interface for building complex prompts
-- `FollowUpPromptBuilder` - Generate follow-up questions for conversations
-- `LLMOutputHandler` - Process LLM responses and handle tool executions
+```typescript
+const workflow = createWorkflow({
+  name: 'Content Pipeline',
+  steps: [
+    createAgentStep({
+      id: 'research', 
+      agent: researchAgent,
+      messageTemplate: 'Research: {{topic}}'
+    }),
+    createAgentStep({
+      id: 'write',
+      agent: writingAgent, 
+      messageTemplate: 'Write article: {{researchData}}'
+    })
+  ]
+});
+
+const result = await workflow.execute({ topic: 'AI Ethics' });
+```
 
-### Types
+## 🧠 Memory & Storage
 
-The package exports comprehensive TypeScript types for all interfaces, including:
-- `Message`, `ToolResult`, `ToolDetails`
-- `OpenAIMessage`, `OpenAITool`, `ConversationEntry`
-- `UserMessageContent`, `CodeboltAPI`
-- `MCPTool`, `InitialUserMessage`
+Integrated with CodeBolt's storage system:
 
-## Dependencies
+```typescript
+// Agent-scoped persistent storage
+const agentMemory = createCodeBoltAgentMemory('my_agent');
 
-This package depends on `@codebolt/codeboltjs` for core functionality like file system operations, LLM communication, and tool execution.
+// Project-scoped storage
+const projectMemory = createCodeBoltProjectMemory('project_agent');
 
-## Development
+// Fast access memory database  
+const dbMemory = createCodeBoltDbMemory('cache_agent');
+```
+
+## 🔧 Development
 
 ```bash
 # Install dependencies
@@ -104,17 +180,32 @@ npm install
 # Build the project
 npm run build
 
-# Run in development mode
+# Development mode
 npm run dev
 
-# Clean build artifacts
-npm run clean
+# Run tests
+npm run test
+
+# Lint code
+npm run lint
 ```
 
-## License
+## 📋 Pattern Comparison
+
+| Pattern | Complexity | Use Case | Learning Curve |
+|---------|------------|----------|----------------|
+| **Composable** | Low | Rapid prototyping, simple agents | Low |
+| **Builder** | Medium | Complex workflows, custom logic | Medium |
+| **Processor** | High | Advanced customization | High |
+
+## 🤝 Contributing
+
+See our [Contributing Guide](./DOCUMENTATION.md#contributing) for development setup, coding standards, and submission guidelines.
+
+## 📄 License
 
-MIT
+MIT - See the main CodeBolt repository for details.
 
-## Contributing
+---
 
-Please see the main CodeBolt repository for contribution guidelines.
+**📚 [Complete Documentation](./DOCUMENTATION.md)** | **🐛 [Report Issues](https://github.com/codeboltai/codeboltjs/issues)** | **💬 [Join Community](https://discord.gg/codebolt)**

package/dist/builderpattern/agent.d.ts

@@ -0,0 +1,86 @@
+import { SystemPrompt } from "./systemprompt";
+import { TaskInstruction } from "./taskInstruction";
+/**
+ * Agent class that manages conversations with LLMs and tool executions.
+ * Handles the conversation flow, tool calls, and task completions.
+ */
+declare class Agent {
+    /** Available tools for the agent to use */
+    private tools;
+    /** Full conversation history for API calls */
+    private apiConversationHistory;
+    /** Maximum number of conversation turns (0 means unlimited) */
+    private maxRun;
+    /** System prompt that provides instructions to the model */
+    private systemPrompt;
+    /** Messages from the user */
+    private userMessage;
+    /** The next user message to be added to the conversation */
+    private nextUserMessage;
+    /**
+     * Creates a new Agent instance.
+     *
+     * @param tools - The tools available to the agent
+     * @param systemPrompt - The system prompt providing instructions to the LLM
+     * @param maxRun - Maximum number of conversation turns (0 means unlimited)
+     */
+    constructor(tools: any | undefined, systemPrompt: SystemPrompt, maxRun?: number);
+    /**
+     * Runs the agent on a specific task until completion or max runs reached.
+     *
+     * @param task - The task instruction to be executed
+     * @param successCondition - Optional function to determine if the task is successful
+     * @returns Promise with success status, error (if any), and the last assistant message
+     */
+    run(task: TaskInstruction, successCondition?: () => boolean): Promise<{
+        success: boolean;
+        error: string | null;
+        message: string | null;
+    }>;
+    /**
+     * Attempts to make a request to the LLM with conversation history and tools.
+     *
+     * @param apiConversationHistory - The current conversation history
+     * @param tools - The tools available to the LLM
+     * @returns Promise with the LLM response
+     */
+    private attemptLlmRequest;
+    /**
+     * Executes a tool with given name and input.
+     *
+     * @param toolName - The name of the tool to execute
+     * @param toolInput - The input parameters for the tool
+     * @returns Promise with tuple [userRejected, result]
+     */
+    private executeTool;
+    /**
+     * Starts a sub-agent to handle a specific task.
+     *
+     * @param agentName - The name of the sub-agent to start
+     * @param params - Parameters for the sub-agent
+     * @returns Promise with tuple [userRejected, result]
+     */
+    private startSubAgent;
+    /**
+     * Extracts tool details from a tool call object.
+     *
+     * @param tool - The tool call object from the LLM response
+     * @returns ToolDetails object with name, input, and ID
+     */
+    private getToolDetail;
+    /**
+     * Creates a tool result object from the tool execution response.
+     *
+     * @param tool_call_id - The ID of the tool call
+     * @param content - The content returned by the tool
+     * @returns ToolResult object
+     */
+    private getToolResult;
+    /**
+     * Fallback method for API requests in case of failures.
+     *
+     * @throws Error API request fallback not implemented
+     */
+    private attemptApiRequest;
+}
+export { Agent };