overai 1.4.0

package/README.md

@@ -0,0 +1,248 @@
+# OverAI TypeScript Node.js AI Agents Framework
+
+OverAI is a production-ready Multi AI Agents framework, designed to create AI Agents to automate and solve problems ranging from simple tasks to complex challenges. It provides a low-code solution to streamline the building and management of multi-agent LLM systems, emphasising simplicity, customisation, and effective human-agent collaboration.
+
+## Installation
+
+```bash
+npm install overai
+```
+
+## Development Setup
+
+1. Clone the repository:
+```bash
+git clone https://github.com/MervinPraison/PraisonAI.git
+cd src/praisonai-ts
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Build the package:
+```bash
+npm run build
+```
+
+## Usage
+
+Here are examples of different ways to use OverAI:
+
+### 1. Single Agent Example
+
+```typescript
+import { Agent, PraisonAIAgents } from 'overai';
+
+async function main() {
+    // Create a simple agent (no task specified)
+    const agent = new Agent({
+        name: "BiologyExpert",
+        instructions: "Explain the process of photosynthesis in detail.",
+        verbose: true
+    });
+
+    // Run the agent
+    const praisonAI = new PraisonAIAgents({
+        agents: [agent],
+        tasks: ["Explain the process of photosynthesis in detail."],
+        verbose: true
+    });
+
+    try {
+        console.log('Starting single agent example...');
+        const results = await praisonAI.start();
+        console.log('\nFinal Results:', results);
+    } catch (error) {
+        console.error('Error:', error);
+    }
+}
+
+main();
+```
+
+### 2. Multi-Agent Example
+
+```typescript
+import { Agent, PraisonAIAgents } from 'overai';
+
+async function main() {
+    // Create multiple agents with different roles
+    const researchAgent = new Agent({
+        name: "ResearchAgent",
+        instructions: "Research and provide detailed information about renewable energy sources.",
+        verbose: true
+    });
+
+    const summaryAgent = new Agent({
+        name: "SummaryAgent",
+        instructions: "Create a concise summary of the research findings about renewable energy sources. Use {previous_result} as input.",
+        verbose: true
+    });
+
+    const recommendationAgent = new Agent({
+        name: "RecommendationAgent",
+        instructions: "Based on the summary in {previous_result}, provide specific recommendations for implementing renewable energy solutions.",
+        verbose: true
+    });
+
+    // Run the agents in sequence
+    const praisonAI = new PraisonAIAgents({
+        agents: [researchAgent, summaryAgent, recommendationAgent],
+        tasks: [
+            "Research and analyze current renewable energy technologies and their implementation.",
+            "Summarize the key findings from the research.",
+            "Provide actionable recommendations based on the summary."
+        ],
+        verbose: true
+    });
+
+    try {
+        console.log('Starting multi-agent example...');
+        const results = await praisonAI.start();
+        console.log('\nFinal Results:', results);
+    } catch (error) {
+        console.error('Error:', error);
+    }
+}
+
+main();
+```
+
+### 3. Task-Based Agent Example
+
+```typescript
+import { Agent, Task, PraisonAIAgents } from 'overai';
+
+async function main() {
+    // Create agents first
+    const dietAgent = new Agent({
+        name: "DietAgent",
+        role: "Nutrition Expert",
+        goal: "Create healthy and delicious recipes",
+        backstory: "You are a certified nutritionist with years of experience in creating balanced meal plans.",
+        verbose: true,  // Enable streaming output
+        instructions: `You are a professional chef and nutritionist. Create 5 healthy food recipes that are both nutritious and delicious.
+Each recipe should include:
+1. Recipe name
+2. List of ingredients with quantities
+3. Step-by-step cooking instructions
+4. Nutritional information
+5. Health benefits
+
+Format your response in markdown.`
+    });
+
+    const blogAgent = new Agent({
+        name: "BlogAgent",
+        role: "Food Blogger",
+        goal: "Write engaging blog posts about food and recipes",
+        backstory: "You are a successful food blogger known for your ability to make recipes sound delicious and approachable.",
+        verbose: true,  // Enable streaming output
+        instructions: `You are a food and health blogger. Write an engaging blog post about the provided recipes.
+The blog post should:
+1. Have an engaging title
+2. Include an introduction about healthy eating`
+    });
+
+    // Create tasks
+    const createRecipesTask = new Task({
+        name: "Create Recipes",
+        description: "Create 5 healthy and delicious recipes",
+        agent: dietAgent
+    });
+
+    const writeBlogTask = new Task({
+        name: "Write Blog",
+        description: "Write a blog post about the recipes",
+        agent: blogAgent,
+        dependencies: [createRecipesTask]  // This task depends on the recipes being created first
+    });
+
+    // Run the tasks
+    const praisonAI = new PraisonAIAgents({
+        tasks: [createRecipesTask, writeBlogTask],
+        verbose: true
+    });
+
+    try {
+        console.log('Starting task-based example...');
+        const results = await praisonAI.start();
+        console.log('\nFinal Results:', results);
+    } catch (error) {
+        console.error('Error:', error);
+    }
+}
+
+main();
+```
+
+### Running the Examples
+
+1. First, set up your environment variables:
+```bash
+export OPENAI_API_KEY='your-api-key'
+```
+
+2. Create a new TypeScript file (e.g., `example.ts`) with any of the above examples.
+
+3. Run the example:
+```bash
+npx ts-node example.ts
+```
+
+For more examples, check out the `examples/concepts/` directory in the repository.
+
+## Package Structure
+
+```
+src/
+├── agent/         # Agent-related interfaces and implementations
+├── agents/        # Multi-agent system management
+├── knowledge/     # Knowledge base and management
+├── llm/          # Language Model interfaces
+├── memory/       # Memory management systems
+├── process/      # Process management
+├── task/         # Task management
+└── tools/        # Various utility tools
+    ├── arxivTools.ts
+    └── ... (other tools)
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+MIT License - see the LICENSE file for details
+
+## Testing
+
+### Manual Testing
+
+```bash
+export OPENAI_API_KEY='your-api-key'
+npx ts-node tests/development/simple/single-agent.ts
+npx ts-node tests/development/simple/multi-agent.ts
+npx ts-node tests/development/simple/multi-agents-simple.js
+```
+
+## Examples Testing
+
+```bash
+export OPENAI_API_KEY='your-api-key'
+npx ts-node examples/simple/single-agent.ts
+npx ts-node examples/simple/multi-agent.ts
+```
+
+### Automated Testing (WIP)
+
+```bash
+npm run test
+```

package/dist/agent/context.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Context Agent - Agent with enhanced context management
+ */
+import { KnowledgeBase, type SearchResult } from '../knowledge/rag';
+export interface ContextAgentConfig {
+    name?: string;
+    instructions: string;
+    llm?: string;
+    knowledgeBase?: KnowledgeBase;
+    contextWindow?: number;
+    maxContextTokens?: number;
+    verbose?: boolean;
+}
+export interface ContextMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+    timestamp: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Context Agent - Agent with RAG and context management
+ */
+export declare class ContextAgent {
+    readonly name: string;
+    readonly instructions: string;
+    private provider;
+    private providerPromise;
+    private llmModel;
+    private knowledgeBase?;
+    private contextWindow;
+    private maxContextTokens;
+    private messages;
+    private verbose;
+    constructor(config: ContextAgentConfig);
+    /**
+     * Get the LLM provider (lazy initialization with AI SDK backend)
+     */
+    private getProvider;
+    /**
+     * Chat with context awareness
+     */
+    chat(prompt: string): Promise<{
+        text: string;
+        context?: SearchResult[];
+    }>;
+    /**
+     * Get recent messages within context window
+     */
+    private getRecentMessages;
+    /**
+     * Add document to knowledge base
+     */
+    addDocument(id: string, content: string, metadata?: Record<string, any>): Promise<void>;
+    /**
+     * Search knowledge base
+     */
+    searchKnowledge(query: string, limit?: number): Promise<SearchResult[]>;
+    /**
+     * Clear conversation history
+     */
+    clearHistory(): void;
+    /**
+     * Get conversation history
+     */
+    getHistory(): ContextMessage[];
+    /**
+     * Set knowledge base
+     */
+    setKnowledgeBase(kb: KnowledgeBase): void;
+}
+/**
+ * Create a context agent
+ */
+export declare function createContextAgent(config: ContextAgentConfig): ContextAgent;

package/dist/agent/context.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * Context Agent - Agent with enhanced context management
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextAgent = void 0;
+exports.createContextAgent = createContextAgent;
+const backend_resolver_1 = require("../llm/backend-resolver");
+/**
+ * Context Agent - Agent with RAG and context management
+ */
+class ContextAgent {
+    constructor(config) {
+        this.provider = null;
+        this.providerPromise = null;
+        this.messages = [];
+        this.name = config.name || `ContextAgent_${Math.random().toString(36).substr(2, 9)}`;
+        this.instructions = config.instructions;
+        this.llmModel = config.llm || 'openai/gpt-4o-mini';
+        this.knowledgeBase = config.knowledgeBase;
+        this.contextWindow = config.contextWindow ?? 10;
+        this.maxContextTokens = config.maxContextTokens ?? 4000;
+        this.verbose = config.verbose ?? false;
+    }
+    /**
+     * Get the LLM provider (lazy initialization with AI SDK backend)
+     */
+    async getProvider() {
+        if (this.provider) {
+            return this.provider;
+        }
+        if (!this.providerPromise) {
+            this.providerPromise = (async () => {
+                const result = await (0, backend_resolver_1.resolveBackend)(this.llmModel, {
+                    attribution: { agentId: this.name },
+                });
+                this.provider = result.provider;
+                return result.provider;
+            })();
+        }
+        return this.providerPromise;
+    }
+    /**
+     * Chat with context awareness
+     */
+    async chat(prompt) {
+        // Add user message
+        this.messages.push({
+            role: 'user',
+            content: prompt,
+            timestamp: Date.now()
+        });
+        // Build context from knowledge base
+        let ragContext = [];
+        let contextString = '';
+        if (this.knowledgeBase) {
+            ragContext = await this.knowledgeBase.search(prompt);
+            if (ragContext.length > 0) {
+                contextString = this.knowledgeBase.buildContext(ragContext);
+                if (this.verbose) {
+                    console.log(`[ContextAgent] Found ${ragContext.length} relevant documents`);
+                }
+            }
+        }
+        // Build messages array with context
+        const systemPrompt = contextString
+            ? `${this.instructions}\n\nRelevant context:\n${contextString}`
+            : this.instructions;
+        const messages = [
+            { role: 'system', content: systemPrompt },
+            ...this.getRecentMessages()
+        ];
+        // Generate response
+        const provider = await this.getProvider();
+        const result = await provider.generateText({ messages });
+        // Add assistant message
+        this.messages.push({
+            role: 'assistant',
+            content: result.text,
+            timestamp: Date.now()
+        });
+        return {
+            text: result.text,
+            context: ragContext.length > 0 ? ragContext : undefined
+        };
+    }
+    /**
+     * Get recent messages within context window
+     */
+    getRecentMessages() {
+        const recent = this.messages.slice(-this.contextWindow);
+        return recent.map(m => ({
+            role: m.role,
+            content: m.content
+        }));
+    }
+    /**
+     * Add document to knowledge base
+     */
+    async addDocument(id, content, metadata) {
+        if (!this.knowledgeBase) {
+            throw new Error('No knowledge base configured');
+        }
+        await this.knowledgeBase.add({ id, content, metadata });
+    }
+    /**
+     * Search knowledge base
+     */
+    async searchKnowledge(query, limit) {
+        if (!this.knowledgeBase) {
+            return [];
+        }
+        return this.knowledgeBase.search(query, limit);
+    }
+    /**
+     * Clear conversation history
+     */
+    clearHistory() {
+        this.messages = [];
+    }
+    /**
+     * Get conversation history
+     */
+    getHistory() {
+        return [...this.messages];
+    }
+    /**
+     * Set knowledge base
+     */
+    setKnowledgeBase(kb) {
+        this.knowledgeBase = kb;
+    }
+}
+exports.ContextAgent = ContextAgent;
+/**
+ * Create a context agent
+ */
+function createContextAgent(config) {
+    return new ContextAgent(config);
+}

package/dist/agent/enhanced.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Enhanced Agent - Agent with session management, provider abstraction, and tool support
+ */
+import { type ToolCall } from '../llm/providers';
+import { Session } from '../session';
+import { FunctionTool } from '../tools/decorator';
+export interface EnhancedAgentConfig {
+    name?: string;
+    instructions: string;
+    llm?: string;
+    tools?: Array<FunctionTool | Function | {
+        name: string;
+        description?: string;
+        parameters?: any;
+        execute: Function;
+    }>;
+    session?: Session;
+    sessionId?: string;
+    verbose?: boolean;
+    stream?: boolean;
+    maxToolCalls?: number;
+    temperature?: number;
+    maxTokens?: number;
+    outputSchema?: any;
+}
+export interface ChatOptions {
+    stream?: boolean;
+    temperature?: number;
+    maxTokens?: number;
+    outputSchema?: any;
+    onToken?: (token: string) => void;
+}
+export interface ChatResult {
+    text: string;
+    structured?: any;
+    toolCalls?: ToolCall[];
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    runId: string;
+    sessionId: string;
+}
+/**
+ * Enhanced Agent with full feature support
+ */
+export declare class EnhancedAgent {
+    readonly name: string;
+    readonly instructions: string;
+    readonly sessionId: string;
+    private provider;
+    private providerPromise;
+    private llmModel;
+    private session;
+    private toolRegistry;
+    private verbose;
+    private stream;
+    private maxToolCalls;
+    private temperature;
+    private maxTokens?;
+    private outputSchema?;
+    constructor(config: EnhancedAgentConfig);
+    /**
+     * Get the LLM provider (lazy initialization with AI SDK backend)
+     */
+    private getProvider;
+    private registerTools;
+    /**
+     * Add a tool to the agent
+     */
+    addTool(t: FunctionTool | {
+        name: string;
+        description?: string;
+        parameters?: any;
+        execute: Function;
+    }): this;
+    /**
+     * Get all registered tools
+     */
+    getTools(): FunctionTool[];
+    /**
+     * Chat with the agent
+     */
+    chat(prompt: string, options?: ChatOptions): Promise<ChatResult>;
+    /**
+     * Start method for compatibility
+     */
+    start(prompt: string, options?: ChatOptions): Promise<string>;
+    /**
+     * Get the session
+     */
+    getSession(): Session;
+    /**
+     * Clear conversation history
+     */
+    clearHistory(): void;
+}