praisonai 1.2.4 → 1.3.1

package/dist/agent/index.d.ts

@@ -1,6 +1,19 @@
+/**
+ * Agent Module - Core agent classes for PraisonAI
+ *
+ * The primary exports are:
+ * - Agent: Single agent with instructions, tools, and optional persistence
+ * - Agents: Multi-agent orchestration (alias for PraisonAIAgents)
+ * - Router: Simplified keyword/pattern-based routing
+ * - Workflow: Step-based workflow execution (from workflows module)
+ */
+export { Agent, PraisonAIAgents, Agents } from './simple';
+export type { SimpleAgentConfig, PraisonAIAgentsConfig } from './simple';
+export { Router, RouterAgent, createRouter, routeConditions } from './router';
+export type { RouterConfig, RouteConfig, RouteContext, SimpleRouterConfig, SimpleRouteConfig } from './router';
+export { Task } from './types';
+export type { TaskConfig, AgentConfig as TaskAgentConfig } from './types';
+/**
+ * @deprecated Task mode is no longer needed. Use Agent with role/goal/backstory instead.
+ */
 export declare function setTaskMode(enabled: boolean): void;
-export { Agent, PraisonAIAgents, Task } from './proxy';
-export type { ProxyAgentConfig } from './proxy';
-export type { AgentConfig } from './types';
-export type { TaskConfig } from './types';
-export type { PraisonAIAgentsConfig, SimpleAgentConfig } from './simple';

package/dist/agent/index.js

@@ -1,13 +1,38 @@
 "use strict";
+/**
+ * Agent Module - Core agent classes for PraisonAI
+ *
+ * The primary exports are:
+ * - Agent: Single agent with instructions, tools, and optional persistence
+ * - Agents: Multi-agent orchestration (alias for PraisonAIAgents)
+ * - Router: Simplified keyword/pattern-based routing
+ * - Workflow: Step-based workflow execution (from workflows module)
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Task = exports.PraisonAIAgents = exports.Agent = void 0;
+exports.Task = exports.routeConditions = exports.createRouter = exports.RouterAgent = exports.Router = exports.Agents = exports.PraisonAIAgents = exports.Agent = void 0;
 exports.setTaskMode = setTaskMode;
-// Export implementation based on mode
+// Core exports - the main API surface
+var simple_1 = require("./simple");
+Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return simple_1.Agent; } });
+Object.defineProperty(exports, "PraisonAIAgents", { enumerable: true, get: function () { return simple_1.PraisonAIAgents; } });
+Object.defineProperty(exports, "Agents", { enumerable: true, get: function () { return simple_1.Agents; } });
+// Router exports
+var router_1 = require("./router");
+Object.defineProperty(exports, "Router", { enumerable: true, get: function () { return router_1.Router; } });
+Object.defineProperty(exports, "RouterAgent", { enumerable: true, get: function () { return router_1.RouterAgent; } });
+Object.defineProperty(exports, "createRouter", { enumerable: true, get: function () { return router_1.createRouter; } });
+Object.defineProperty(exports, "routeConditions", { enumerable: true, get: function () { return router_1.routeConditions; } });
+// Task support (for advanced use cases)
+var types_1 = require("./types");
+Object.defineProperty(exports, "Task", { enumerable: true, get: function () { return types_1.Task; } });
+// Legacy compatibility - setTaskMode is deprecated but kept for backward compat
 let useTaskMode = false;
+/**
+ * @deprecated Task mode is no longer needed. Use Agent with role/goal/backstory instead.
+ */
 function setTaskMode(enabled) {
+    if (enabled) {
+        console.warn('setTaskMode() is deprecated. Use Agent({ role, goal, backstory }) instead of task mode.');
+    }
     useTaskMode = enabled;
 }
-var proxy_1 = require("./proxy");
-Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return proxy_1.Agent; } });
-Object.defineProperty(exports, "PraisonAIAgents", { enumerable: true, get: function () { return proxy_1.PraisonAIAgents; } });
-Object.defineProperty(exports, "Task", { enumerable: true, get: function () { return proxy_1.Task; } });

package/dist/agent/router.d.ts

@@ -1,12 +1,32 @@
 /**
  * Router Agent - Route requests to specialized agents
+ *
+ * @example Simple usage (5 lines)
+ * ```typescript
+ * import { Agent, Router } from 'praisonai';
+ *
+ * const router = new Router({
+ *   math: { agent: new Agent({ instructions: 'Math expert' }), keywords: ['calculate', 'math'] },
+ *   code: { agent: new Agent({ instructions: 'Code expert' }), keywords: ['code', 'program'] }
+ * });
+ * await router.chat('Calculate 2+2');  // Routes to math agent
+ * ```
  */
 import type { EnhancedAgent } from './enhanced';
+import { Agent } from './simple';
+type AnyAgent = Agent | EnhancedAgent;
 export interface RouteConfig {
-    agent: EnhancedAgent;
+    agent: AnyAgent;
     condition: (input: string, context?: RouteContext) => boolean | Promise<boolean>;
     priority?: number;
 }
+/** Simplified route definition */
+export interface SimpleRouteConfig {
+    agent: AnyAgent;
+    keywords?: string[];
+    pattern?: RegExp;
+    priority?: number;
+}
 export interface RouteContext {
     history?: string[];
     metadata?: Record<string, any>;
@@ -14,9 +34,11 @@ export interface RouteContext {
 export interface RouterConfig {
     name?: string;
     routes: RouteConfig[];
-    defaultAgent?: EnhancedAgent;
+    defaultAgent?: AnyAgent;
     verbose?: boolean;
 }
+/** Simplified router config - just a map of route name to config */
+export type SimpleRouterConfig = Record<string, SimpleRouteConfig>;
 /**
  * Router Agent - Routes requests to the most appropriate agent
  */
@@ -30,9 +52,13 @@ export declare class RouterAgent {
      * Route a request to the appropriate agent
      */
     route(input: string, context?: RouteContext): Promise<{
-        agent: EnhancedAgent;
+        agent: AnyAgent;
         response: string;
     } | null>;
+    /**
+     * Simplified chat method - routes and returns just the response
+     */
+    chat(input: string, context?: RouteContext): Promise<string>;
     /**
      * Add a route
      */
@@ -72,6 +98,44 @@ export declare const routeConditions: {
     or: (...conditions: Array<(input: string, context?: RouteContext) => boolean>) => (input: string, context?: RouteContext) => boolean;
 };
 /**
- * Create a router agent
+ * Create a router agent (legacy API)
  */
 export declare function createRouter(config: RouterConfig): RouterAgent;
+/**
+ * Simplified Router class - uses keyword/pattern-based routing
+ *
+ * @example Simple usage (5 lines)
+ * ```typescript
+ * import { Agent, Router } from 'praisonai';
+ *
+ * const router = new Router({
+ *   math: { agent: new Agent({ instructions: 'Math expert' }), keywords: ['calculate', 'math'] },
+ *   code: { agent: new Agent({ instructions: 'Code expert' }), keywords: ['code', 'program'] }
+ * });
+ * await router.chat('Calculate 2+2');  // Routes to math agent
+ * ```
+ */
+export declare class Router {
+    private routerAgent;
+    private agentMap;
+    constructor(config: SimpleRouterConfig, options?: {
+        default?: string;
+        verbose?: boolean;
+    });
+    /**
+     * Route and get response
+     */
+    chat(input: string): Promise<string>;
+    /**
+     * Route and get full result with agent info
+     */
+    route(input: string): Promise<{
+        agent: AnyAgent;
+        response: string;
+    } | null>;
+    /**
+     * Get agent by name
+     */
+    getAgent(name: string): AnyAgent | undefined;
+}
+export {};

package/dist/agent/router.js

@@ -1,9 +1,20 @@
 "use strict";
 /**
  * Router Agent - Route requests to specialized agents
+ *
+ * @example Simple usage (5 lines)
+ * ```typescript
+ * import { Agent, Router } from 'praisonai';
+ *
+ * const router = new Router({
+ *   math: { agent: new Agent({ instructions: 'Math expert' }), keywords: ['calculate', 'math'] },
+ *   code: { agent: new Agent({ instructions: 'Code expert' }), keywords: ['code', 'program'] }
+ * });
+ * await router.chat('Calculate 2+2');  // Routes to math agent
+ * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.routeConditions = exports.RouterAgent = void 0;
+exports.Router = exports.routeConditions = exports.RouterAgent = void 0;
 exports.createRouter = createRouter;
 /**
  * Router Agent - Routes requests to the most appropriate agent
@@ -26,7 +37,9 @@ class RouterAgent {
                     console.log(`[Router] Routing to: ${route.agent.name}`);
                 }
                 const response = await route.agent.chat(input);
-                return { agent: route.agent, response: response.text };
+                // Handle both Agent (returns string) and EnhancedAgent (returns ChatResult)
+                const responseText = typeof response === 'string' ? response : response.text;
+                return { agent: route.agent, response: responseText };
             }
         }
         if (this.defaultAgent) {
@@ -34,10 +47,21 @@ class RouterAgent {
                 console.log(`[Router] Using default agent: ${this.defaultAgent.name}`);
             }
             const response = await this.defaultAgent.chat(input);
-            return { agent: this.defaultAgent, response: response.text };
+            const responseText = typeof response === 'string' ? response : response.text;
+            return { agent: this.defaultAgent, response: responseText };
         }
         return null;
     }
+    /**
+     * Simplified chat method - routes and returns just the response
+     */
+    async chat(input, context) {
+        const result = await this.route(input, context);
+        if (!result) {
+            throw new Error('No matching route found and no default agent configured');
+        }
+        return result.response;
+    }
     /**
      * Add a route
      */
@@ -106,8 +130,80 @@ exports.routeConditions = {
     }
 };
 /**
- * Create a router agent
+ * Create a router agent (legacy API)
  */
 function createRouter(config) {
     return new RouterAgent(config);
 }
+/**
+ * Simplified Router class - uses keyword/pattern-based routing
+ *
+ * @example Simple usage (5 lines)
+ * ```typescript
+ * import { Agent, Router } from 'praisonai';
+ *
+ * const router = new Router({
+ *   math: { agent: new Agent({ instructions: 'Math expert' }), keywords: ['calculate', 'math'] },
+ *   code: { agent: new Agent({ instructions: 'Code expert' }), keywords: ['code', 'program'] }
+ * });
+ * await router.chat('Calculate 2+2');  // Routes to math agent
+ * ```
+ */
+class Router {
+    constructor(config, options) {
+        this.agentMap = new Map();
+        const routes = [];
+        let defaultAgent;
+        for (const [name, routeConfig] of Object.entries(config)) {
+            this.agentMap.set(name, routeConfig.agent);
+            // Build condition from keywords or pattern
+            let condition;
+            if (routeConfig.keywords) {
+                condition = exports.routeConditions.keywords(routeConfig.keywords);
+            }
+            else if (routeConfig.pattern) {
+                condition = exports.routeConditions.pattern(routeConfig.pattern);
+            }
+            else {
+                condition = exports.routeConditions.always();
+            }
+            routes.push({
+                agent: routeConfig.agent,
+                condition,
+                priority: routeConfig.priority
+            });
+            // Set default agent
+            if (options?.default === name) {
+                defaultAgent = routeConfig.agent;
+            }
+        }
+        // If no default specified, use first agent
+        if (!defaultAgent && routes.length > 0) {
+            defaultAgent = routes[0].agent;
+        }
+        this.routerAgent = new RouterAgent({
+            routes,
+            defaultAgent,
+            verbose: options?.verbose
+        });
+    }
+    /**
+     * Route and get response
+     */
+    async chat(input) {
+        return this.routerAgent.chat(input);
+    }
+    /**
+     * Route and get full result with agent info
+     */
+    async route(input) {
+        return this.routerAgent.route(input);
+    }
+    /**
+     * Get agent by name
+     */
+    getAgent(name) {
+        return this.agentMap.get(name);
+    }
+}
+exports.Router = Router;

package/dist/agent/simple.d.ts

@@ -1,13 +1,89 @@
+import type { DbAdapter } from '../db/types';
+/**
+ * Agent Configuration
+ *
+ * The Agent class is the primary entry point for PraisonAI.
+ * It supports both simple instruction-based agents and advanced configurations.
+ *
+ * @example Simple usage (3 lines)
+ * ```typescript
+ * import { Agent } from 'praisonai';
+ * const agent = new Agent({ instructions: "You are helpful" });
+ * await agent.chat("Hello!");
+ * ```
+ *
+ * @example With tools (5 lines)
+ * ```typescript
+ * const getWeather = (city: string) => `Weather in ${city}: 20°C`;
+ * const agent = new Agent({
+ *   instructions: "You provide weather info",
+ *   tools: [getWeather]
+ * });
+ * await agent.chat("Weather in Paris?");
+ * ```
+ *
+ * @example With persistence (4 lines)
+ * ```typescript
+ * import { Agent, db } from 'praisonai';
+ * const agent = new Agent({
+ *   instructions: "You are helpful",
+ *   db: db("sqlite:./data.db"),
+ *   sessionId: "my-session"
+ * });
+ * await agent.chat("Hello!");
+ * ```
+ */
 export interface SimpleAgentConfig {
+    /** Agent instructions/system prompt (required) */
     instructions: string;
+    /** Agent name (auto-generated if not provided) */
     name?: string;
+    /** Enable verbose logging (default: true) */
     verbose?: boolean;
+    /** Enable pretty output formatting */
     pretty?: boolean;
+    /**
+     * LLM model to use. Accepts:
+     * - Model name: "gpt-4o-mini", "claude-3-sonnet"
+     * - Provider/model: "openai/gpt-4o", "anthropic/claude-3"
+     * Default: "gpt-4o-mini"
+     */
     llm?: string;
+    /** Enable markdown formatting in responses */
     markdown?: boolean;
+    /** Enable streaming responses (default: true) */
     stream?: boolean;
+    /**
+     * Tools available to the agent.
+     * Can be plain functions (auto-schema) or OpenAI tool definitions.
+     */
     tools?: any[] | Function[];
+    /** Map of tool function implementations */
     toolFunctions?: Record<string, Function>;
+    /** Database adapter for persistence */
+    db?: DbAdapter;
+    /** Session ID for conversation persistence (auto-generated if not provided) */
+    sessionId?: string;
+    /** Run ID for tracing (auto-generated if not provided) */
+    runId?: string;
+    /** Max messages to restore from history (default: 100) */
+    historyLimit?: number;
+    /** Auto-restore conversation history from db (default: true) */
+    autoRestore?: boolean;
+    /** Auto-persist messages to db (default: true) */
+    autoPersist?: boolean;
+    /** Enable caching of responses */
+    cache?: boolean;
+    /** Cache TTL in seconds (default: 3600) */
+    cacheTTL?: number;
+    /** Enable telemetry tracking (default: false, opt-in) */
+    telemetry?: boolean;
+    /** Agent role (advanced mode) */
+    role?: string;
+    /** Agent goal (advanced mode) */
+    goal?: string;
+    /** Agent backstory (advanced mode) */
+    backstory?: string;
 }
 export declare class Agent {
     private instructions;
@@ -20,7 +96,35 @@ export declare class Agent {
     private llmService;
     private tools?;
     private toolFunctions;
+    private dbAdapter?;
+    private sessionId;
+    private runId;
+    private messages;
+    private dbInitialized;
+    private historyLimit;
+    private autoRestore;
+    private autoPersist;
+    private cache;
+    private cacheTTL;
+    private responseCache;
+    private telemetryEnabled;
     constructor(config: SimpleAgentConfig);
+    /**
+     * Generate a session ID based on current hour and agent name (like Python SDK)
+     */
+    private generateSessionId;
+    /**
+     * Initialize DB session - restore history on first chat (lazy)
+     */
+    private initDbSession;
+    /**
+     * Get cached response if available and not expired
+     */
+    private getCachedResponse;
+    /**
+     * Cache a response
+     */
+    private cacheResponse;
     private createSystemPrompt;
     /**
      * Register a tool function that can be called by the model
@@ -49,9 +153,39 @@ export declare class Agent {
     start(prompt: string, previousResult?: string): Promise<string>;
     chat(prompt: string, previousResult?: string): Promise<string>;
     execute(previousResult?: string): Promise<string>;
+    /**
+     * Persist a message to the database
+     */
+    private persistMessage;
+    /**
+     * Get the session ID for this agent
+     */
+    getSessionId(): string;
+    /**
+     * Get the run ID for this agent
+     */
+    getRunId(): string;
     getResult(): string | null;
     getInstructions(): string;
+    /**
+     * Get conversation history
+     */
+    getHistory(): Array<{
+        role: string;
+        content: string | null;
+    }>;
+    /**
+     * Clear conversation history (in memory and optionally in DB)
+     */
+    clearHistory(clearDb?: boolean): Promise<void>;
+    /**
+     * Clear response cache
+     */
+    clearCache(): void;
 }
+/**
+ * Configuration for multi-agent orchestration
+ */
 export interface PraisonAIAgentsConfig {
     agents: Agent[];
     tasks?: string[];
@@ -59,15 +193,59 @@ export interface PraisonAIAgentsConfig {
     pretty?: boolean;
     process?: 'sequential' | 'parallel';
 }
+/**
+ * Multi-agent orchestration class
+ *
+ * @example Simple array syntax
+ * ```typescript
+ * import { Agent, Agents } from 'praisonai';
+ *
+ * const researcher = new Agent({ instructions: "Research the topic" });
+ * const writer = new Agent({ instructions: "Write based on research" });
+ *
+ * const agents = new Agents([researcher, writer]);
+ * await agents.start();
+ * ```
+ *
+ * @example Config object syntax
+ * ```typescript
+ * const agents = new Agents({
+ *   agents: [researcher, writer],
+ *   process: 'parallel'
+ * });
+ * ```
+ */
 export declare class PraisonAIAgents {
     private agents;
     private tasks;
     private verbose;
     private pretty;
     private process;
-    constructor(config: PraisonAIAgentsConfig);
+    /**
+     * Create a multi-agent orchestration
+     * @param configOrAgents - Either an array of agents or a config object
+     */
+    constructor(configOrAgents: PraisonAIAgentsConfig | Agent[]);
     private generateTasks;
     private executeSequential;
     start(): Promise<string[]>;
     chat(): Promise<string[]>;
 }
+/**
+ * Agents - Alias for PraisonAIAgents
+ *
+ * This is the recommended class name for multi-agent orchestration.
+ * PraisonAIAgents is kept for backward compatibility.
+ *
+ * @example
+ * ```typescript
+ * import { Agent, Agents } from 'praisonai';
+ *
+ * const agents = new Agents([
+ *   new Agent({ instructions: "Research the topic" }),
+ *   new Agent({ instructions: "Write based on research" })
+ * ]);
+ * await agents.start();
+ * ```
+ */
+export declare const Agents: typeof PraisonAIAgents;