.cursorrules

Below is an example **TypeScript/Node.js** folder structure replicating the Python package's layout. Each subfolder matches the Python counterpart (`agent`, `agents`, `knowledge`, etc.). All "LLM" or "litellm" references are replaced by **`aisdk`** usage.

Feel free to rename or restructure to suit your project's Node.js conventions.

---

## Folder Structure

```
praisonai-ts/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts
│   ├── main.ts
│   ├── agent/
│   │   └── agent.ts
│   ├── agents/
│   │   ├── agents.ts
│   │   └── autoagents.ts
│   ├── knowledge/
│   │   ├── chunking.ts
│   │   └── knowledge.ts
│   ├── llm/
│   │   └── llm.ts
│   ├── memory/
│   │   └── memory.ts
│   ├── process/
│   │   └── process.ts
│   ├── task/
│   │   └── task.ts
│   └── tools/
│       ├── README.md
│       ├── index.ts
│       ├── test.ts
│       ├── arxivTools.ts
│       ├── calculatorTools.ts
│       ├── csvTools.ts
│       ├── duckdbTools.ts
│       ├── duckduckgoTools.ts
│       ├── excelTools.ts
│       ├── fileTools.ts
│       ├── jsonTools.ts
│       ├── newspaperTools.ts
│       ├── pandasTools.ts
│       ├── pythonTools.ts
│       ├── shellTools.ts
│       ├── spiderTools.ts
│       ├── tools.ts
│       ├── wikipediaTools.ts
│       ├── xmlTools.ts
│       ├── yamlTools.ts
│       └── yfinanceTools.ts
└── ...
```

Below is a **high-level table** describing the main files/folders, the classes or functions inside them, their parameters, and return values.

---

| **File / Folder**                 | **Contents**                                                                                                                                                                                                                                                 | **Functions / Classes**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | **Parameters**                                                                                                                                                                                                                                                                                                                                       | **Return**                                                                     | **Purpose**                                                                                                                                                                                                                                                           |
|-----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **src/index.ts**                  | Main entry point that re-exports key classes/functions                                                                                                                                                                                                       | - Typically re-exports `Agent`, `Agents`, `Task`, etc.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | -                                                                                                                                                                                                                                                                                                                                                     | -                                                                              | Provides a simple import path for consumers.                                                                                                                                                                                                                           |
| **src/main.ts**                   | Equivalent of `main.py`, sets up logging, callbacks, registers display callbacks, and integrates with `aisdk` if needed                                                                                                                                       | - `registerDisplayCallback(type: string, callbackFn, isAsync: boolean): void`<br/>- `executeCallback(type: string, ...args): Promise<void>`<br/>- `displayInteraction(...)`, `displayError(...)`, etc. <br/>- Possibly some global logs array or error logs.                                                                                                                                                                                                                                                                           | Depending on the function, e.g. `registerDisplayCallback` → `(type, fn, isAsync)`                                                                                                                                                                                                                                                                     | Varies by function type. Typically `void` or `Promise<void>`                                                   | Central place for logging and "display callbacks," mirroring the Python approach (prints, error logs, etc.). Uses or references `aisdk` for generating text if needed.                                                                                                 |
| **src/agent/agent.ts**            | Contains `Agent` class, mirroring `agent.py`. Handles single-agent logic, possible references to LLM calls via `aisdk`.                                                                                                                                       | - `class Agent`<br/>   - constructor(name: string, role: string, goal: string, ...)<br/>   - `chat(...)`: main method for handling "chat" or LLM calls<br/>   - `achat(...)`: async method, if needed                                                                                                                                                                                                                                                                                         | **constructor**: `(name, role, goal, tools, ... )` etc. <br/>**chat**: `(prompt: string, ...)` <br/>**achat**: `(prompt: string, ...)`                                                                                                                                                                                                                 | `Promise<string>` or `string` for the chat methods.                                                          | Encapsulates a single agent's role, name, and the methods for calling the LLM using `aisdk`. Also may manage context, tools, roles, etc.                                                                                                                               |
| **src/agents/agents.ts**          | Contains `PraisonAIAgents` (like `agents.py`). Manages multiple agents, tasks, memory, process type, etc.                                                                                                                                                     | - `class PraisonAIAgents`<br/>   - constructor(agents: Agent[], tasks?: Task[], ...)<br/>   - `addTask(task: Task)`: number<br/>   - `executeTask(taskId: number)`: TaskOutput<br/>   - `runTask(taskId: number)`: void<br/>   - `runAllTasks()`: void<br/>   - `start(...)`: starts them all<br/>   - `getTaskResult(...)`                                                                                                                                         | The constructor takes arrays of `Agent`, optional tasks, manager config, memory config, etc. Other methods take Task IDs.                                                                                                                                                                                                                             | Most methods return `void`, or a `Promise<void>`, or a custom object.                                          | Coordinates multiple agents and tasks in a "manager" style. The top-level orchestrator for tasks and agent interactions.                                                                                                                                               |
| **src/agents/autoagents.ts**      | The `AutoAgents` class, an advanced manager that can auto-create tasks/agents from instructions. Uses `aisdk` to parse config.                                                                                                                               | - `class AutoAgents extends PraisonAIAgents`<br/>   - constructor(instructions: string, tools?: any[], ...)<br/>   - `_generateConfig(...)`<br/>   - `_createAgentsAndTasks(...)`<br/>   - `start()`: overrides the parent to handle auto generation<br/>   - etc.                                                                                                                                                                                                                              | Takes user instructions, tools, config (like memory usage, manager LLM, etc.).                                                                                                                                                                                                                                                                       | Typically `Promise<object>` or `void` for the `start()` method.                                               | High-level convenience for automatically generating agent/task configuration from user instructions.                                                                                                                              |
| **src/knowledge/chunking.ts**     | `Chunking` class for text chunking. Similar logic to the Python version.                                                                                                                                                                                     | - `class Chunking`<br/>   - constructor(chunkerType: string, ... )<br/>   - `chunk(text: string | string[], addContext: boolean, contextParams: any): Chunk[]`<br/>   - Possibly `_get_overlap_refinery(...)`, etc.                                                                                                                                                                                                                                                                     | Similar to Python (chunkerType, chunkSize, etc.).                                                                                                                                                                                                                                                                                                     | Returns an array of chunked text or objects describing the chunk.                                             | Manages chunking text for memory or knowledge base usage (like large documents).                                                                                                                                               |
| **src/knowledge/knowledge.ts**    | `Knowledge` class for storing & retrieving data from memory, chunking, vector DB, etc.                                                                                                                                                                       | - `class Knowledge`<br/>   - constructor(config: any, verbose?: number)<br/>   - `store(content: string, userId?: string, ...): any`<br/>   - `search(query: string, ...): any`<br/>   - `deleteAll(...)`: etc.                                                                                                                                                                                                                                                                                 | Takes a config object for local or external DB. Methods get or store docs, do RAG searching, etc.                                                                                                                                                                                                                                                    | Return types typically objects or arrays.                                                                     | Central interface to handle knowledge storage, chunking, retrieval, e.g. vector store, RAG.                                                                                                                                      |
| **src/llm/llm.ts**                | `LLM` class referencing **`aisdk`** instead of `litellm`. Basic usage of `generateText` or `streamText`.                                                                                                                                                       | - `class LLM`<br/>   - constructor(options: { model: string, apiKey?: string, ... })<br/>   - `response(prompt: string, ...): Promise<string>` (calls `aisdk.generateText`)<br/>   - possibly `streamResponse(...)` if needed                                                                                                                              | `model, prompt, temperature, ...`                                                                                                                                                                                                                                                                                                                  | `Promise<string>` for final text.                                                                             | The bridging layer between your code and `aisdk`, so `Agent` can call `LLM.response(...)`.                                                                                                                                      |
| **src/memory/memory.ts**          | `Memory` class for short-term or long-term memory references, entity memory, user memory, etc.                                                                                                                                                              | - `class Memory`<br/>   - constructor(config: MemoryConfig, verbose?: number)<br/>   - `storeShortTerm(...)`, `storeLongTerm(...)`, `searchShortTerm(...)`, etc.<br/>   - `buildContextForTask(...)`                                                                                                                                                                                                                                                    | Varies, e.g. `(text: string, metadata?: any)`                                                                                                                                                                                                                                                                                                       | Typically `void` or some object referencing stored docs.                                                      | Takes a config describing how/where memory is stored: local DB, RAG, or `aisdk` embeddings.                                                                                                                                     |
| **src/process/process.ts**        | `Process` class that handles sequential or workflow processes between tasks.                                                                                                                                                                                | - `class Process`<br/>   - constructor(tasks: Map<number, Task>, agents: Agent[], ... )<br/>   - `sequential()`, `workflow()`, `hierarchical()`, etc.                                                                                                                                                                                                                                                                                                     | Receives tasks, agents, process type.                                                                                                                                                                                                                                                                                                               | Returns an iterator or array describing the next tasks to run.                                               | Logic for ordering tasks in "sequential", "hierarchical", or "workflow" modes.                                                                                                                                                   |
| **src/task/task.ts**              | `Task` class for describing a single piece of work, the agent assigned, context, etc.                                                                                                                                                                       | - `class Task`<br/>   - constructor(description: string, expectedOutput?: string, ... )<br/>   - `executeCallback(taskOutput: TaskOutput)`, `storeInMemory(...)`, etc.                                                                                                                                                                                                                                                                                  | The constructor has many options: `(description, expectedOutput, agent, tools, ...)`.                                                                                                                                                                                                                                                                 | Methods return `void`, or custom objects.                                                                     | Encapsulates a single unit of work, references an agent, has optional callback, memory usage, etc.                                                                                                                               |
| **src/tools/README.md**           | Short README describing how to write "tools" in JS/TS.                                                                                                                                                                                                      | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | -                                                                                                                                                                                                                                                                                                                                                     | -                                                                              | Provides docs for tool developers.                                                                                                                                                                                                                                      |
| **src/tools/index.ts**            | Entry point that re-exports tool functions (like `internetSearch`, `getArxivPaper`, etc.)                                                                                                                        | - Possibly a map of `functionName -> import`<br/> - `import * as calculatorTools from './calculatorTools'`, etc.                                                                                                                                                                                                                                                                                                                                    | -                                                                                                                                                                                                                                                                                                                                                     | -                                                                              | Simplifies import of tools (e.g. `import { getArticle } from "praisonai/tools"`).                                                                                                                                               |
| **src/tools/test.ts**             | Script for running each tool's internal test or example.                                                                                                                                                                                                   | - Typically a script that `import ... from './someTool.ts'` then tries them.                                                                                                                                                                                                                                                                                                                                                                                                                 | -                                                                                                                                                                                                                                                                                                                                                     | -                                                                              | Quick local tests.                                                                                                                                                                                                                                                      |
| **src/tools/arxivTools.ts**       | Example "arxiv_tools.py" logic in TS. Searching arXiv, returning results.                                                                                                                                                                                   | - `function searchArxiv(query: string, ...): Promise<any[]>`<br/> - `function getArxivPaper(id: string): Promise<any>` etc.                                                                                                                                                                                                                                                                                                                                                                   | `(query, maxResults=10, ... )`                                                                                                                                                                                                                                                                                                                     | `Promise<ArxivPaper[]>` or something like that.                                                               | Tools for searching and retrieving from arXiv.                                                                                                                                                                                                                          |

---

### Notes on `aisdk` Integration

1. In the Python code, many calls like `litellm` or `OpenAI(api_key=...)` appear. In **Node**, replace that with something like:
   ```ts
   import { generateText } from "aisdk";

   async function callLLM(prompt: string) {
     const { text } = await generateText({
       model: "gpt-4o-mini",
       prompt,
       // other config like temperature, maxTokens, etc.
     });
     return text;
   }
   ```
2. The `LLM` class in `llm.ts` can wrap `generateText` calls:
   ```ts
   import { generateText } from "aisdk";

   export class LLM {
     model: string;

     constructor(model: string) {
       this.model = model;
     }

     async response(prompt: string, temperature=0.7): Promise<string> {
       const { text } = await generateText({
         model: this.model,
         prompt,
         temperature
       });
       return text;
     }
   }
   ```

3. Agents or tasks can reference the `LLM` instance or call `aisdk` directly.

---

### Summary

- **Each folder** in `praisonaiagents/` is mapped to a corresponding **subfolder in TypeScript**.
- **Classes** or **functions** mirror the Python classes, with the same constructor parameters and method signatures in a TypeScript style.
- **Return types** are changed from Python style (`dict`, `list`) to TypeScript style (`object`, `Record<string,any>`, `Promise<void>`, etc.).
- **Use `aisdk`** in place of `litellm` / `openai`.
- **Tool files** replicate exactly what the Python code does, but in TypeScript (e.g., `arxivTools.ts`, `calculatorTools.ts`, etc.).
- **Add any third-party TS libs** needed (`node-fetch`, `cheerio`, `duckdb`, `yaml`, `xml2js`, etc.).

This gives a **1-to-1** replication of the Python package's structure, now in a Node/TypeScript environment with **aisdk** for large language model calls.


Let me provide a detailed breakdown of the PraisonAI Agents python library based on the code.
Need to build the same for TypeScript.

# 1. Directory Structure Overview

```
praisonai-python/
├── __init__.py           # Package initialization, exports main components
├── main.py              # Core functionality, display handlers
├── agent/               # Individual agent functionality
├── agents/              # Multi-agent management
├── knowledge/           # Knowledge base and chunking
├── llm/                # Language model interface
├── memory/             # Memory management
├── process/            # Process execution handling
├── task/              # Task definition and handling
└── tools/             # Various utility tools
```

# 2. Main Components

## a. Core Agent Classes
- `Agent`: Individual AI agent with specific capabilities
- `PraisonAIAgents`: Manager class for multiple agents
- `AutoAgents`: Automatic agent creation and management
- `Task`: Task definition and execution
- `Tools`: Utility functions and capabilities

## b. Key Functionalities
1. Task Management
2. Memory Management
3. Knowledge Base
4. LLM Integration
5. Process Control
6. Tool Integration

# 3. Key Classes & Functions

## 3.1 PraisonAIAgents Class
Main class for managing multiple agents.

```python
class PraisonAIAgents:
    def __init__(self, 
        agents,               # List of agents
        tasks=None,          # List of tasks
        verbose=0,           # Verbosity level
        completion_checker=None, # Custom completion checker
        max_retries=5,       # Maximum retry attempts
        process="sequential", # Process type
        manager_llm=None,    # LLM model for management
        memory=False,        # Enable memory
        memory_config=None,  # Memory configuration
        embedder=None,       # Custom embedder
        user_id=None,        # User identifier
        max_iter=10          # Maximum iterations
    )
```

## 3.2 Task Class
Defines individual tasks for agents.

```python
class Task:
    def __init__(self,
        description: str,    # Task description
        expected_output: str = None,  # Expected output
        agent: Agent = None,  # Assigned agent
        name: str = None,    # Task name
        tools: List = None,  # Available tools
        context: List = None,  # Task context
        async_execution: bool = False,  # Async execution
        config: Dict = None,  # Configuration
        output_file: str = None,  # Output file path
        output_json: bool = False,  # JSON output flag
        output_pydantic: bool = False,  # Pydantic output flag
        callback: Callable = None,  # Callback function
        status: str = "not started",  # Task status
        result: TaskOutput = None,  # Task result
        create_directory: bool = False,  # Create output directory
        id: int = None,      # Task ID
        images: List[str] = None,  # Image paths
        next_tasks: List[str] = None,  # Next tasks
        task_type: str = "task",  # Task type
        condition: Dict = None,  # Task conditions
        is_start: bool = False,  # Start task flag
        loop_state: Dict = None,  # Loop state
        memory=None,         # Memory instance
        quality_check: bool = True,  # Enable quality check
        input_file: str = None,  # Input file path
        rerun: bool = False  # Allow task rerun
    )
```

## 3.3 Memory Management

```python
class Memory:
    def __init__(self, 
        config: Dict[str, Any],  # Memory configuration
        verbose: int = 0         # Verbosity level
    )

    def store_long_term(self,
        text: str,              # Text to store
        metadata: Dict = None,   # Additional metadata
        completeness: float = None,  # Completeness score
        relevance: float = None,     # Relevance score
        clarity: float = None,       # Clarity score
        accuracy: float = None,      # Accuracy score
        weights: Dict = None,        # Score weights
        evaluator_quality: float = None  # Overall quality
    )
```

# 4. Tools Library

## 4.1 Available Tools Categories

1. **File Operations**
   - CSV Tools
   - Excel Tools
   - JSON Tools
   - YAML Tools
   - XML Tools
   - File Tools

2. **Web & Data**
   - ArXiv Tools
   - Wikipedia Tools
   - DuckDuckGo Tools
   - Spider Tools
   - Newspaper Tools

3. **Data Analysis**
   - Pandas Tools
   - DuckDB Tools
   - Calculator Tools

4. **System & Development**
   - Shell Tools
   - Python Tools

5. **Financial**
   - YFinance Tools

## 4.2 Example Tool Class (YFinanceTools)

```python
class YFinanceTools:
    def get_stock_price(self, symbol: str) -> Dict[str, float]:
        """Get current stock price and metrics"""
        
    def get_stock_info(self, symbol: str) -> Dict:
        """Get detailed stock information"""
        
    def get_historical_data(self,
        symbol: str,
        period: str = "1y",
        interval: str = "1d",
        start: Optional[datetime] = None,
        end: Optional[datetime] = None
    ) -> List[Dict[str, Any]]:
        """Get historical price data"""
```

# 5. Configuration

## 5.1 Memory Configuration Example
```python
memory_config = {
    "provider": "rag",     # Memory provider type
    "use_embedding": True,  # Use embeddings
    "storage": {
        "type": "sqlite",
        "path": "./.praison/memory.db"
    },
    "rag_db_path": "./.praison/chroma_db"
}
```

## 5.2 Process Types
- "sequential": Tasks execute in sequence
- "workflow": Tasks execute based on workflow rules
- "hierarchical": Tasks execute in hierarchical order

# 6. Output Formats

## 6.1 TaskOutput
```python
class TaskOutput(BaseModel):
    description: str
    summary: Optional[str]
    raw: str
    pydantic: Optional[BaseModel]
    json_dict: Optional[Dict[str, Any]]
    agent: str
    output_format: Literal["RAW", "JSON", "Pydantic"]
```

# 7. Task Types
1. Regular Task
2. Decision Task
3. Loop Task
4. Workflow Task

Each task type has specific behaviors and attributes for different use cases.

# 8. Error Handling

The library includes comprehensive error handling with:
- Error logging
- Retry mechanisms
- Fallback strategies
- Error display functions

# 9. Display Functions

```python
def display_interaction(message, response, markdown=True)
def display_self_reflection(message: str)
def display_instruction(message: str)
def display_tool_call(message: str)
def display_error(message: str)
def display_generating(content: str)
```