@minded-ai/mindedjs 1.0.0-ec2-beta-1

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

@@ -0,0 +1,158 @@
+# Environment Configuration
+
+Configure your environment variables to customize MindedJS behavior and connect to external services.
+
+## Environment Variables
+
+Create a `.env` file in your project root to configure MindedJS:
+
+```bash
+# .env file
+```
+
+### Core Configuration
+
+#### `RUN_LOCALLY`
+
+Controls whether the agent runs fully local in memory or connects to the Minded platform.
+
+```bash
+RUN_LOCALLY=true
+```
+
+- **`true`**: Agent runs fully local in memory without external connections
+- **`false`** (default): Agent connects to the Minded platform
+
+
+#### `BROWSER_TASK_MODE`
+
+Controls the mode in which the browser task runs.
+
+```bash
+BROWSER_TASK_MODE=cloud
+```
+
+
+- **`onPrem`**: Browser task runs on the customer's own infrastructure with a remotely installed on-premise kit.
+- **`localRun`**: Browser task runs locally where the SDK is running. Requires configuring a UV project and installing dependencies.
+- **`cloud`**: Browser task runs on the Minded platform. This is the default mode.
+
+
+### Chat Model Credentials
+
+MindedJS currently supports OpenAI and Azure OpenAI chat models. Under the hood, these are implemented using LangChain chat models. If you want to use a chat model that is not currently supported, please reach out to us.
+
+#### Supported Chat Model Configurations
+
+**OpenAI**
+
+```bash
+OPENAI_API_KEY=your-openai-api-key
+```
+
+**Azure OpenAI**
+
+```bash
+AZURE_OPENAI_API_KEY=your-azure-openai-api-key
+AZURE_OPENAI_ENDPOINT=your-azure-openai-endpoint
+AZURE_OPENAI_API_DEPLOYMENT_NAME=your-deployment-name
+AZURE_OPENAI_API_VERSION=your-api-version
+```
+
+{% hint style="info" %}
+If you need support for additional chat models, please contact us and we'll work on adding support for your preferred provider.
+{% endhint %}
+
+### Platform Connection
+
+#### `MINDED_CONNECTION_TOKEN`
+
+Required to connect to the Minded platform for advanced features and monitoring. Each token is specific to the agent you are working on.
+
+```bash
+MINDED_CONNECTION_TOKEN=your-minded-connection-token
+```
+
+{% hint style="info" %}
+Your connection token is available on the [Minded platform](https://app.minded.com) in the agent page within the GitHub integration popup. You can also use the npx command provided there to automatically set the minded token.
+{% endhint %}
+
+## Example .env File
+
+Here's a complete example of a `.env` file:
+
+```bash
+# Core Configuration
+RUN_LOCALLY=false
+
+# Chat Model (OpenAI example)
+OPENAI_API_KEY=sk-your-openai-api-key-here
+
+# Platform Connection
+MINDED_CONNECTION_TOKEN=your-minded-connection-token-here
+```
+
+## Loading Environment Variables
+
+MindedJS automatically loads environment variables from your `.env` file. Make sure to:
+
+1. Create the `.env` file in your project root
+2. Add `.env` to your `.gitignore` file to keep credentials secure
+3. Never commit your `.env` file to version control
+
+```bash
+# Add to .gitignore
+.env
+```
+
+## Runtime Environment Detection
+
+MindedJS uses specific environment variables to determine the runtime environment and adjust behavior accordingly.
+
+### Environment Variables
+
+| Environment        | NODE_ENV      | MINDED_CLOUD | Description                          |
+| ------------------ | ------------- | ------------ | ------------------------------------ |
+| Local Development  | `development` | `false`      | Running locally on developer machine |
+| Minded Platform    | `development` | `true`       | Running in Minded platform sandbox   |
+| Staging Service    | `staging`     | `true`       | Agent deployed as staging service    |
+| Production Service | `production`  | `true`       | Agent deployed as production service |
+
+### Usage in Code
+
+```typescript
+// Check if running on Minded Cloud
+if (process.env.MINDED_CLOUD === 'true') {
+  // Running on Minded infrastructure (dev/staging/prod)
+  logger.info({ message: 'Running on Minded Cloud' });
+}
+
+// Check specific environment
+if (process.env.NODE_ENV === 'production' && process.env.MINDED_CLOUD === 'true') {
+  // Production environment on Minded Cloud
+  logger.info({ message: 'Production mode' });
+}
+```
+
+### Environment-Specific Behavior
+
+```typescript
+const isDevelopment = process.env.NODE_ENV === 'development';
+const isMindedCloud = process.env.MINDED_CLOUD === 'true';
+
+// Enable debug features only in development
+if (isDevelopment) {
+  // Enable verbose logging
+  logger.setLevel('debug');
+}
+
+// Use different endpoints based on environment
+const apiEndpoint = isMindedCloud ? 'https://api.minded.com' : 'http://localhost:3000';
+```
+
+## Next Steps
+
+With your environment configured, continue to:
+
+1. [Project Configuration](project-configuration.md) - Set up your `minded.json` file
+2. [Quick Start](quick-start.md) - Build your first agent

package/docs/getting-started/installation.md

@@ -0,0 +1,44 @@
+# Installation
+
+Get MindedJS up and running in your project.
+
+## Requirements
+
+- Node.js 18 or later
+- npm, yarn, or pnpm
+
+## Install MindedJS
+
+{% tabs %}
+{% tab title="npm" %}
+
+```bash
+npm i @minded-ai/mindedjs langchain
+```
+
+{% endtab %}
+
+{% tab title="yarn" %}
+
+```bash
+yarn add @minded-ai/mindedjs langchain
+```
+
+{% endtab %}
+
+{% tab title="pnpm" %}
+
+```bash
+pnpm add @minded-ai/mindedjs langchain
+```
+
+{% endtab %}
+{% endtabs %}
+
+## Next Steps
+
+Now that MindedJS is installed:
+
+1. Configure your environment variables in the [Environment Configuration](environment-configuration.md) guide
+2. Set up your project with `minded.json` in the [Project Configuration](project-configuration.md) guide
+3. Build your first agent with the [Quick Start](quick-start.md) guide!

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