windsurfrules

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- executeCallback(type: string, ...args): Promise<void>- displayInteraction(...), displayError(...), etc. - 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 - constructor(name: string, role: string, goal: string, ...) - chat(...): main method for handling "chat" or LLM calls - achat(...): async method, if needed	constructor: (name, role, goal, tools, ... ) etc. chat: (prompt: string, ...) 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 - constructor(agents: Agent[], tasks?: Task[], ...) - addTask(task: Task): number - executeTask(taskId: number): TaskOutput - runTask(taskId: number): void - runAllTasks(): void - start(...): starts them all - 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 - constructor(instructions: string, tools?: any[], ...) - _generateConfig(...) - _createAgentsAndTasks(...) - start(): overrides the parent to handle auto generation - 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 - constructor(chunkerType: string, ... ) - `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.
src/knowledge/knowledge.ts	Knowledge class for storing & retrieving data from memory, chunking, vector DB, etc.	- class Knowledge - constructor(config: any, verbose?: number) - store(content: string, userId?: string, ...): any - search(query: string, ...): any - 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 - constructor(options: { model: string, apiKey?: string, ... }) - response(prompt: string, ...): Promise<string> (calls aisdk.generateText) - 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 - constructor(config: MemoryConfig, verbose?: number) - storeShortTerm(...), storeLongTerm(...), searchShortTerm(...), etc. - 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 - constructor(tasks: Map<number, Task>, agents: Agent[], ... ) - 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 - constructor(description: string, expectedOutput?: string, ... ) - 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 - 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[]> - function getArxivPaper(id: string): Promise<any> etc.	(query, maxResults=10, ... )	Promise<ArxivPaper[]> or something like that.	Tools for searching and retrieving from arXiv.