@minded-ai/mindedjs 1.0.19

package/docs/getting-started/quick-start.md

@@ -0,0 +1,264 @@
+# Quick Start
+
+Build your first MindedJS agent in minutes! We'll create a customer support agent that can process refunds.
+
+## What You'll Build
+
+A customer support agent for an ecommerce store:
+
+* Greets customers and asks for order details
+* Intelligently routes to refund processing when appropriate
+* Processes refunds with business logic
+* Maintains conversation state throughout
+
+## Project Setup
+
+First, create the necessary files in your project:
+
+### 1. Agent Configuration
+
+Create `minded.json` in your project root:
+
+```json
+{
+  "flows": [
+    "./flows"
+  ],
+  "llm": {
+    "name": "ChatOpenAI",
+    "properties": {
+      "model": "gpt-4o"
+    }
+  }
+}
+```
+
+### 2. Flow Definition
+
+Create `flows/refundFlow.yaml`:
+
+```yaml
+name: 'Order Refund Flow'
+nodes:
+  - type: 'trigger'
+    triggerType: 'manual'
+    name: 'CLI Trigger'
+  - type: 'promptNode'
+    name: 'Support Agent'
+    prompt: "Hello! I'm your customer support agent. I can help you with refunds. Please provide your name, order ID, and describe your issue."
+  - type: 'tool'
+    name: 'Process Refund'
+    toolName: 'processRefund'
+edges:
+  - source: 'CLI Trigger'
+    target: 'Support Agent'
+    type: 'stepForward'
+  - source: 'Support Agent'
+    target: 'Process Refund'
+    type: 'promptCondition'
+    prompt: 'The user is asking for a refund and provided their order details'
+```
+
+### 3. Memory Schema
+
+Create `schema.ts`:
+
+```ts
+import { z } from 'zod';
+
+export default z.object({
+  customerName: z.string().optional(),
+  orderId: z.string().optional(),
+  issue: z.string().optional(),
+});
+```
+
+### 4. Tools
+
+Create `tools/processRefund.ts`:
+
+```ts
+import { z } from 'zod';
+import { Tool } from 'mindedjs/src/types/Tools.types';
+import memorySchema from '../schema';
+
+type Memory = z.infer<typeof memorySchema>;
+
+const schema = z.object({
+  orderId: z.string(),
+  customerName: z.string(),
+  reason: z.string(),
+});
+
+const processRefundTool: Tool<typeof schema, Memory> = {
+  name: 'processRefund',
+  description: 'Process a refund for the customer order',
+  input: schema,
+  execute: async ({ input, memory }) => {
+    console.log('*Action: Processing refund*');
+    console.log(`Refunding order ${input.orderId} for ${input.customerName}`);
+    console.log(`Reason: ${input.reason}`);
+    
+    // Simulate refund processing
+    const refundAmount = Math.floor(Math.random() * 100) + 20; // Random amount between $20-$120
+    console.log(`Refund of $${memory.orderAmount} has been processed successfully!`);
+    
+    return {
+      memory: {
+        customerName: input.customerName,
+        orderId: input.orderId,
+        issue: `Refund processed - $${refundAmount}`,
+      },
+    };
+  },
+};
+
+export default processRefundTool;
+```
+
+Create `tools/index.ts`:
+
+```ts
+import processRefundTool from './processRefund';
+
+export default [processRefundTool];
+```
+
+### 5. Main Agent
+
+Create `agent.ts`:
+
+```ts
+import { Agent } from 'mindedjs/src/agent';
+import { HumanMessage } from '@langchain/core/messages';
+import { events } from 'mindedjs/src/index';
+import * as readline from 'readline';
+import memorySchema from './schema';
+import tools from './tools';
+import config from './minded.json';
+
+// 1. Create readline interface for interactive chat
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+// 2. Create the agent with config from minded.json
+const agent = new Agent({
+  memorySchema,
+  config,
+  tools,
+});
+
+// 3. Listen for AI messages
+agent.on(events.AI_MESSAGE, async ({ message }) => {
+  console.log('AI:', message);
+  promptUser(); // Continue the conversation
+});
+
+// 4. Handle trigger events
+agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody }) => {
+  if (triggerName === 'CLI Trigger') {
+    return {
+      memory: {},
+      messages: [new HumanMessage(triggerBody)],
+    };
+  }
+});
+
+// 5. Function to prompt user for input
+const promptUser = () => {
+  rl.question('You: ', async (input) => {
+    if (input.toLowerCase() === 'exit' || input.toLowerCase() === 'quit') {
+      console.log('Goodbye!');
+      rl.close();
+      return;
+    }
+
+    console.log(); // Add spacing for readability
+    
+    // Send user message to agent
+    await agent.invoke({ 
+      triggerBody: input, 
+      triggerName: 'CLI Trigger' 
+    });
+  });
+};
+
+// 6. Start the interactive session
+console.log('🤖 Customer Support Agent is ready!');
+console.log('Type your message below (or "exit" to quit):\n');
+promptUser();
+```
+
+## Project Structure
+
+Your project should look like this:
+
+```
+your-project/
+├── minded.json          # Agent configuration
+├── schema.ts           # Memory schema definition
+├── agent.ts            # Main agent file
+├── flows/              # Flow definitions
+│   └── refundFlow.yaml  # Individual flow files
+└── tools/              # Tools directory
+    ├── processRefund.ts # Refund processing tool
+    └── index.ts        # Export your tools
+```
+
+## Run Your Agent
+
+Start the interactive chat session:
+
+```bash
+npx ts-node agent.ts
+```
+
+This will start an interactive conversation where you can chat with your agent:
+
+```
+🤖 Customer Support Agent is ready!
+Type your message below (or "exit" to quit):
+
+You: Hi, I want to refund my order #1234. I received the wrong item.
+
+AI: Hello! I'm your customer support agent. I can help you with refunds. Please provide your name, order ID, and describe your issue.
+
+You: My name is John Smith, order ID is 1234, and I received the wrong size shoes.
+
+*Action: Processing refund*
+Refunding order 1234 for John Smith
+Reason: received the wrong size shoes
+Refund of $87 has been processed successfully!
+
+You: Thank you!
+
+AI: You're welcome! Your refund has been processed successfully. Is there anything else I can help you with?
+
+You: exit
+Goodbye!
+```
+
+**Tips:**
+
+* Type `exit` or `quit` to end the conversation
+* Each message maintains conversation context and memory
+* The agent will intelligently route to refund processing when appropriate
+
+## What Happens
+
+1. **Trigger Activation**: The manual trigger receives your input message
+2. **Support Agent**: The prompt node greets the customer and asks for details
+3. **Intelligent Routing**: If the customer mentions refunds and provides order details, the flow routes to the refund tool
+4. **Refund Processing**: The tool processes the refund and updates memory
+5. **State Management**: Memory persists customer information throughout the conversation
+
+## Next Steps
+
+Now that you have a working agent, explore:
+
+* [**Core Concepts**](../core-concepts/flows.md) - Understand how flows, nodes, and edges work
+* [**Node Types**](../core-concepts/nodes.md) - Learn about all available node types
+* [**Edge Types**](../core-concepts/edges.md) - Learn about all available edge types
+* [**Tools**](../core-concepts/tools.md) - Learn about all available tools

package/docs-structure.md

@@ -0,0 +1,144 @@
+# GitBook Documentation Structure
+
+## Recommended File Organization
+
+```
+docs/
+├── README.md                    # Introduction & Why MindedJS
+├── getting-started/
+│   ├── installation.md          # Installation instructions
+│   ├── quick-start.md           # Quick start example
+│   └── project-setup.md         # Project structure & configuration
+├── core-concepts/
+│   ├── memory-types.md          # Memory type system
+│   ├── flows.md                 # Flow overview
+│   ├── nodes.md                 # Node types overview
+│   ├── edges.md                 # Edge types overview
+│   ├── tools.md                 # Tools system
+│   └── events.md                # Event system
+├── node-types/
+│   ├── trigger-nodes.md         # TRIGGER nodes
+│   ├── prompt-nodes.md          # PROMPT_NODE nodes
+│   ├── tool-nodes.md            # TOOL nodes
+│   ├── app-tool-nodes.md        # APP_TOOL nodes
+│   └── junction-nodes.md        # JUNCTION nodes
+├── edge-types/
+│   ├── step-forward.md          # STEP_FORWARD edges
+│   ├── prompt-condition.md      # PROMPT_CONDITION edges
+│   └── logical-condition.md     # LOGICAL_CONDITION edges
+├── implementation-examples/
+│   ├── node-examples.md         # All node implementation examples
+│   ├── edge-examples.md         # All edge implementation examples
+│   └── complete-flows.md        # Full flow examples
+├── how-to-guides/
+│   ├── add-new-tool.md          # Adding tools
+│   ├── listen-for-events.md     # Event handling
+│   ├── persist-memory.md        # Memory persistence
+│   └── run-from-cli.md          # CLI execution
+├── api-reference/
+│   ├── agent-class.md           # Agent class reference
+│   ├── tool-interface.md        # Tool interface
+│   ├── flow-schema.md           # Flow YAML schema
+│   └── event-types.md           # Event type definitions
+└── examples/
+    ├── order-refund-flow.md     # Order refund example
+    ├── customer-support.md      # Customer support example
+    └── e-commerce-agent.md      # E-commerce example
+```
+
+## SUMMARY.md Structure
+
+```markdown
+# Table of contents
+
+* [Introduction](README.md)
+
+## Getting Started
+* [Installation](getting-started/installation.md)
+* [Quick Start](getting-started/quick-start.md)
+* [Project Setup](getting-started/project-setup.md)
+
+## Core Concepts
+* [Memory Types](core-concepts/memory-types.md)
+* [Flows](core-concepts/flows.md)
+* [Nodes](core-concepts/nodes.md)
+* [Edges](core-concepts/edges.md)
+* [Tools](core-concepts/tools.md)
+* [Events](core-concepts/events.md)
+
+## Node Types
+* [Trigger Nodes](node-types/trigger-nodes.md)
+* [Prompt Nodes](node-types/prompt-nodes.md)
+* [Tool Nodes](node-types/tool-nodes.md)
+* [App Tool Nodes](node-types/app-tool-nodes.md)
+* [Junction Nodes](node-types/junction-nodes.md)
+
+## Edge Types
+* [Step Forward](edge-types/step-forward.md)
+* [Prompt Condition](edge-types/prompt-condition.md)
+* [Logical Condition](edge-types/logical-condition.md)
+
+## Implementation Examples
+* [Node Examples](implementation-examples/node-examples.md)
+* [Edge Examples](implementation-examples/edge-examples.md)
+* [Complete Flows](implementation-examples/complete-flows.md)
+
+## How-to Guides
+* [Add a New Tool](how-to-guides/add-new-tool.md)
+* [Listen for Events](how-to-guides/listen-for-events.md)
+* [Persist Memory](how-to-guides/persist-memory.md)
+* [Run from CLI](how-to-guides/run-from-cli.md)
+
+## API Reference
+* [Agent Class](api-reference/agent-class.md)
+* [Tool Interface](api-reference/tool-interface.md)
+* [Flow Schema](api-reference/flow-schema.md)
+* [Event Types](api-reference/event-types.md)
+
+## Examples
+* [Order Refund Flow](examples/order-refund-flow.md)
+* [Customer Support](examples/customer-support.md)
+* [E-commerce Agent](examples/e-commerce-agent.md)
+```
+
+## Content Distribution Guide
+
+### README.md (Introduction)
+- Why MindedJS section
+- Key features/benefits
+- Brief overview
+- Link to getting started
+
+### getting-started/quick-start.md
+- The current quick start example
+- Basic project setup
+- First flow creation
+
+### core-concepts/
+- Split the "Core Concepts" section into individual files
+- Each concept gets detailed explanation
+- Keep tables and type definitions here
+
+### node-types/ & edge-types/
+- Detailed documentation for each type
+- Implementation details
+- Advanced configuration options
+- Best practices for each type
+
+### implementation-examples/
+- All the practical examples
+- Code snippets
+- Real-world use cases
+
+### api-reference/
+- Complete API documentation
+- Method signatures
+- Parameter details
+- Return types
+
+This structure provides:
+1. **Progressive disclosure** - readers can dive deeper as needed
+2. **Easy navigation** - logical grouping of related content
+3. **Searchability** - specific topics in dedicated files
+4. **Maintainability** - easier to update specific sections
+5. **Cross-references** - ability to link between related concepts 

package/eslint.config.js

@@ -0,0 +1,68 @@
+const js = require('@eslint/js');
+const tseslint = require('typescript-eslint');
+const globals = require('globals');
+
+module.exports = tseslint.config(
+  {
+    // Only apply to TypeScript files in src directory
+    files: ['src/**/*.ts', 'src/**/*.tsx'],
+    extends: [
+      js.configs.recommended,
+      ...tseslint.configs.recommended,
+    ],
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+      parser: tseslint.parser,
+      parserOptions: {
+        project: './tsconfig.json',
+        tsconfigRootDir: __dirname,
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off',
+    },
+  },
+  {
+    // Allow require() in config files at root level
+    files: ['*.config.js', 'eslint.config.js'],
+    extends: [js.configs.recommended],
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-require-imports': 'off',
+    },
+  },
+  {
+    // Relax TypeScript project rules for test and example files
+    files: ['test/**/*.ts', 'examples/**/*.ts'],
+    extends: [
+      js.configs.recommended,
+      ...tseslint.configs.recommended,
+    ],
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+      parser: tseslint.parser,
+      parserOptions: {
+        project: false,
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off',
+    },
+  },
+  {
+    ignores: [
+      'dist/**/*', 
+      'node_modules/**/*', 
+      'docs/**/*',  // Ignore generated documentation
+      '*.d.ts'      // Ignore type declaration files
+    ],
+  }
+); 

package/examples/orderRefundAgent/flows/orderRefundFlow.yaml

@@ -0,0 +1,32 @@
+name: 'Order refund flow'
+nodes:
+  - type: 'trigger'
+    triggerType: 'manual'
+    name: 'CLI Trigger'
+  - type: 'tool'
+    name: 'Refund order'
+    toolName: 'refundOrder'
+  - type: 'tool'
+    name: 'Escalate conversation'
+    toolName: 'escalateConversation'
+  - type: 'promptNode'
+    name: 'Prompt'
+    humanInTheLoop: true
+    canStayOnNode: true
+    prompt: "You are a customer support agent (Alex) tasked with identifying the issue and escalating it if necessary. Introduce yourself and make sure to collect the customer's name, the issue they are having, and the order id they are referring to. make sure you got all the details you need before continue with the flow. You don't need to further help the customer."
+    llmConfig:
+      name: 'ChatOpenAI'
+      properties:
+        model: 'o3'
+edges:
+  - source: 'CLI Trigger'
+    target: 'Prompt'
+    type: 'stepForward'
+  - source: 'Prompt'
+    target: 'Refund order'
+    type: 'promptCondition'
+    prompt: 'The user is asking for a refund'
+  - source: 'Prompt'
+    target: 'Escalate conversation'
+    type: 'promptCondition'
+    prompt: 'if user does not want refund but says what they need help with and user provided all the details you need'

package/examples/orderRefundAgent/minded.json

@@ -0,0 +1,14 @@
+{
+  "flows": [
+    "./flows"
+  ],
+  "tools": [
+    "./tools"
+  ],
+  "llm": {
+    "name": "ChatOpenAI",
+    "properties": {
+      "model": "gpt-4o"
+    }
+  }
+}

package/examples/orderRefundAgent/orderRefundAgent.ts

@@ -0,0 +1,58 @@
+import { Agent } from '../../src/agent';
+import readline from 'readline';
+import memorySchema from './schema';
+import tools from './tools';
+import { HumanMessage } from '@langchain/core/messages';
+import { events } from '../../src/index';
+import mindedConfig from './minded.json';
+
+const agent = new Agent({
+  memorySchema,
+  config: mindedConfig,
+  tools,
+});
+
+agent.on(events.AI_MESSAGE, async ({ message }) => {
+  await sendMessage(message);
+});
+
+agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody }) => {
+  if (triggerName === 'CLI Trigger') {
+    return {
+      memory: {},
+      messages: [new HumanMessage(triggerBody)],
+    };
+  }
+});
+
+const sendMessage = async (message: string) => {
+  console.log('AI:', message);
+};
+
+if (process.env.NO_PLATFORM_CONNECT === 'true') {
+  // Simple CLI interface
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: 'You: ',
+  });
+
+  console.log('Type your message and press Enter (type "exit" to quit)');
+  rl.prompt();
+
+  rl.on('line', async (line) => {
+    const userInput = line.trim();
+    if (userInput.toLowerCase() === 'exit') {
+      rl.close();
+      process.exit(0);
+    }
+
+    await agent.invoke({
+      triggerBody: userInput,
+      triggerName: 'CLI Trigger',
+      sessionId: 'cli-session',
+    });
+
+    rl.prompt();
+  });
+}

package/examples/orderRefundAgent/schema.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+
+export default z.object({
+  orderId: z.string(),
+  customerName: z.string(),
+  issue: z.string(),
+});

package/examples/orderRefundAgent/tools/escalateConversation.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import memorySchema from '../schema';
+import { Tool } from '../../../src/types/Tools.types';
+type Memory = z.infer<typeof memorySchema>;
+
+const schema = z.object({
+  issue: z.string(),
+  orderId: z.string(),
+  customerName: z.string(),
+});
+
+const escalateConversationTool: Tool<typeof schema, Memory> = {
+  name: 'escalateConversation',
+  description: 'Escalate conversation',
+  input: schema,
+  execute: async ({ input }) => {
+    console.log('*Action: Escalate conversation to a human*');
+    return {
+      memory: {
+        issue: input.issue,
+        orderId: input.orderId,
+        customerName: input.customerName,
+      },
+    };
+  },
+};
+
+export default escalateConversationTool;

package/examples/orderRefundAgent/tools/index.ts

@@ -0,0 +1,4 @@
+import refundOrderTool from './refundOrder';
+import escalateConversationTool from './escalateConversation';
+
+export default [refundOrderTool, escalateConversationTool];

package/examples/orderRefundAgent/tools/refundOrder.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { Tool } from '../../../src/types/Tools.types';
+import memorySchema from '../schema';
+type Memory = z.infer<typeof memorySchema>;
+
+const schema = z.object({
+  orderId: z.string(),
+  customerName: z.string(),
+});
+
+const refundOrderTool: Tool<typeof schema, Memory> = {
+  name: 'refundOrder',
+  description: 'Refund order',
+  input: schema,
+  execute: async ({ input }) => {
+    console.log('*Action: Refund order*');
+    return {
+      memory: {
+        orderId: input.orderId,
+        customerName: input.customerName,
+        issue: 'Refund',
+      },
+    };
+  },
+};
+
+export default refundOrderTool;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@minded-ai/mindedjs",
+  "version": "1.0.19",
+  "description": "",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "test": "NODE_ENV=test mocha --parallel --jobs auto --retries 1 -r ts-node/register -r ./test/setup.ts \"test/**/*.test.ts\"",
+    "testFile": "NODE_ENV=test mocha -r ts-node/register -r ./test/setup.ts",
+    "order-refund": "cd examples/orderRefundAgent && nodemon --watch '**/*.ts' --exec 'ts-node' orderRefundAgent.ts",
+    "lint": "eslint .",
+    "lintFix": "eslint --fix .",
+    "generateApiDocs": "typedoc src --out docs/api-reference ./src"
+  },
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@eslint/js": "^9.27.0",
+    "@types/chai": "^4.3.11",
+    "@types/mocha": "^10.0.6",
+    "@types/node": "^20.11.19",
+    "chai": "^4.3.10",
+    "dotenv": "^16.4.5",
+    "eslint": "^9.27.0",
+    "globals": "^16.2.0",
+    "mocha": "^10.3.0",
+    "nodemon": "^3.1.10",
+    "ts-node": "^10.9.2",
+    "typedoc": "^0.28.5",
+    "typescript": "^5.3.3",
+    "typescript-eslint": "^8.32.1"
+  },
+  "dependencies": {
+    "@langchain/core": "^0.3.55",
+    "@langchain/langgraph": "^0.2.72",
+    "@types/js-yaml": "^4.0.9",
+    "axios": "^1.9.0",
+    "js-yaml": "^4.1.0",
+    "langchain": "^0.3.25",
+    "socket.io-client": "^4.8.1",
+    "uuid": "^11.1.0",
+    "zod": "^3.24.4"
+  }
+}