@minded-ai/mindedjs 1.0.89 → 1.0.91-beta-1

package/docs/getting-started/project-configuration.md

@@ -0,0 +1,206 @@
+# Project Configuration
+
+Configure your MindedJS agent using the `minded.json` file to define how your agent operates, which flows to use, and deployment settings.
+
+## minded.json Overview
+
+The `minded.json` file is the central configuration file for your MindedJS agent. It defines:
+
+* **Flows**: Paths to your flow definition files
+* **Tools**: Paths to your tool implementations (optional)
+* **LLM Configuration**: Which language model to use and its settings
+* **Agent Path**: Where your agent is exported (for deployment only)
+
+This file should be placed in your project root directory.
+
+## Configuration Structure
+
+```json
+{
+  "flows": ["./flows"],
+  "tools": ["./tools"],
+  "agent": "./agent.ts",
+  "llm": {
+    "name": "ChatOpenAI",
+    "properties": {
+      "model": "gpt-4o",
+      "temperature": 0.7
+    }
+  }
+}
+```
+
+## Configuration Fields
+
+### flows (required)
+
+An array of paths to directories containing your flow YAML files.
+
+```json
+{
+  "flows": ["./flows", "./custom-flows"]
+}
+```
+
+The agent will load all `.yaml` and `.yml` files from these directories.
+
+### tools (optional)
+
+An array of paths to directories containing your tool implementations.
+
+```json
+{
+  "tools": ["./tools"]
+}
+```
+
+If not specified, tools should be passed directly to the Agent constructor.
+
+### agent (deployment only)
+
+The path to your main agent file where the agent is exported as default. This field is used by the Minded platform during deployment and is not required for local development.
+
+```json
+{
+  "agent": "./agent.ts"
+}
+```
+
+{% hint style="info" %}
+The `agent` field is only used during deployment to the Minded platform. It tells the platform where to find your agent's default export. This field is not used by the Agent class at runtime.
+{% endhint %}
+
+### llm (required)
+
+Configures the language model for your agent.
+
+```json
+{
+  "llm": {
+    "name": "ChatOpenAI",
+    "properties": {
+      "model": "gpt-4o",
+      "temperature": 0.7,
+      "maxTokens": 2000
+    }
+  }
+}
+```
+
+#### Supported LLM Providers
+
+**ChatOpenAI**
+
+```json
+{
+  "llm": {
+    "name": "ChatOpenAI",
+    "properties": {
+      "model": "gpt-4o",
+      "temperature": 0.7
+    }
+  }
+}
+```
+
+**AzureChatOpenAI**
+
+```json
+{
+  "llm": {
+    "name": "AzureChatOpenAI",
+    "properties": {
+      "model": "gpt-4o",
+      "temperature": 0.7
+    }
+  }
+}
+```
+
+## Usage in Your Agent
+
+The `minded.json` configuration is passed directly to your Agent constructor:
+
+```typescript
+import { Agent } from '@minded-ai/mindedjs';
+import memorySchema from './schema';
+import tools from './tools';
+import mindedConfig from './minded.json';
+
+const agent = new Agent({
+  memorySchema,
+  config: mindedConfig,
+  tools, // Optional if specified in minded.json
+});
+```
+
+## Complete Example
+
+Here's a full example of a `minded.json` file for a customer support agent:
+
+```json
+{
+  "flows": ["./flows"],
+  "tools": ["./tools"],
+  "agent": "./customerSupportAgent.ts",
+  "llm": {
+    "name": "ChatOpenAI",
+    "properties": {
+      "model": "gpt-4o",
+      "temperature": 0.7,
+      "maxTokens": 1000,
+      "topP": 0.9
+    }
+  }
+}
+```
+
+Corresponding project structure:
+
+```
+your-project/
+├── minded.json              # Agent configuration
+├── customerSupportAgent.ts  # Main agent file (default export)
+├── schema.ts               # Memory schema
+├── flows/                  # Flow definitions
+│   ├── mainFlow.yaml
+│   └── escalationFlow.yaml
+└── tools/                  # Tool implementations
+    ├── lookupOrder.ts
+    ├── processRefund.ts
+    └── index.ts
+```
+
+## Environment-Specific Configuration
+
+You can create environment-specific configurations:
+
+```
+your-project/
+├── minded.json              # Default configuration
+├── minded.development.json  # Development overrides
+├── minded.production.json   # Production settings
+└── minded.staging.json      # Staging configuration
+```
+
+Load the appropriate configuration based on your environment:
+
+```typescript
+const env = process.env.NODE_ENV || 'development';
+const configPath = env === 'production' ? './minded.production.json' : './minded.json';
+const mindedConfig = require(configPath);
+
+const agent = new Agent({
+  memorySchema,
+  config: mindedConfig,
+  tools,
+});
+```
+
+## Next Steps
+
+With your `minded.json` configured, you're ready to:
+
+1. [Build your first agent](quick-start.md) - Follow the quick start guide
+2. [Define your flows](../low-code-editor/flows.md) - Learn about flow structure
+3. [Deploy to Minded platform](../platform/deployment.md) - Deploy your agent

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

@@ -0,0 +1,262 @@
+# 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 (see [Project Configuration](project-configuration.md) for detailed documentation):
+
+```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**](../low-code-editor/flows.md) - Understand how flows, nodes, and edges work
+* [**Node Types**](../low-code-editor/nodes.md) - Learn about all available node types
+* [**Edge Types**](../low-code-editor/edges.md) - Learn about all available edge types
+* [**Tools**](../low-code-editor/tools.md) - Learn about all available tools