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

package/docs/platform/pii-masking.md

@@ -0,0 +1,220 @@
+# PII Masking
+
+## Overview
+
+The Minded platform provides built-in protection for Personally Identifiable Information (PII) through an advanced masking mechanism. This feature ensures that sensitive data remains secure throughout your application's lifecycle while preserving the contextual integrity of your business logic.
+
+<figure><img src="../.gitbook/assets/PII-masking.png" alt="PII Masking Flow Diagram"></figure>
+
+## How to Use PII Masking
+
+### Step 1: Configure PII Masking in the Minded Platform
+
+To enable PII masking, go to the agent configuration panel and toggle **"Enable PII Masking"**. Then, configure the masking behavior according to your needs by specifying:
+
+- **Entity Types**: Define which data entities should be treated as PII. Any entity that requires masking must be explicitly listed.
+- **Detection Model**: By default, Minded uses OpenAI's GPT-4.1-mini for PII detection. Optionally, you can provide a custom Azure OpenAI deployment. Be sure to include the corresponding API key in the environment's secrets.
+- **TTL Settings**: TTL (Time-to-Live) determines how long masked data is stored for a specific `sessionId`. The default TTL is 14 hours.
+- **Trigger SessionId Field**: Specify the property name in your incoming webhook payload that contains the session ID. This field is used to identify and group PII data per session. It must be a single word with no special characters (only letters, numbers, and underscores allowed).
+
+Once enabled, PII masking is automatically applied at critical points within the platform:
+
+- All webhook payloads are masked upon receipt.
+- App integrations undergo automatic unmasking before requests and re-masking after responses.
+
+### Step 2: Use PII Masking via the Minded SDK
+
+Minded provides automatic PII masking capabilities for HTTP requests within your agent workflows. When a trigger is received with a sessionId, the PII masking functionality is automatically initialized and made available to your custom code through the agent's PII gateway.
+
+#### PII Gateway for HTTP Requests
+
+The PII gateway enables secure HTTP communication by automatically handling PII masking/unmasking for your API calls. It provides a complete HTTP client interface similar to popular libraries like Axios, supporting all common HTTP methods.
+
+The PII masking gateway ensures:
+
+- **Automatic Unmasking**: Requests are automatically unmasked before being sent to external APIs
+- **Secure Routing**: All requests are routed through Minded's secure gateway infrastructure
+- **Response Masking**: API responses are automatically masked before being returned to your agent
+- **Session Isolation**: PII data is properly isolated per session using the sessionId
+- **Error Handling**: Comprehensive error handling for network issues and API failures
+
+> **Note:** API error responses are **not** masked. The PII gateway requires a valid sessionId to function properly.
+
+#### Available HTTP Methods
+
+The PII gateway supports all standard HTTP methods:
+
+```ts
+// GET request
+const userData = await agent.piiGateway.get(sessionId, 'https://api.example.com/user/123');
+
+// POST request
+const createResult = await agent.piiGateway.post(sessionId, 'https://api.example.com/users', {
+  name: 'John Doe',
+  email: 'john@example.com',
+});
+
+// PUT request
+const updateResult = await agent.piiGateway.put(sessionId, 'https://api.example.com/user/123', {
+  email: 'newemail@example.com',
+});
+
+// DELETE request
+const deleteResult = await agent.piiGateway.delete(sessionId, 'https://api.example.com/user/123');
+
+// PATCH request
+const patchResult = await agent.piiGateway.patch(sessionId, 'https://api.example.com/user/123', {
+  email: 'updated@example.com',
+});
+```
+
+#### Example Usage in Tools
+
+```ts
+// POST request example - within a custom tool
+import { Tool } from '@minded-ai/mindedjs';
+import { logger } from '@minded-ai/mindedjs';
+
+const modelParams = z.object({
+  prev: z.string().describe('The email to update'),
+  new: z.string().describe('The new email address'),
+});
+
+const updateEmailTool: Tool<any, any> = {
+  name: 'updateEmail',
+  description: 'Update the email',
+  input: modelParams,
+  execute: async ({ input, state, agent }) => {
+    try {
+      logger.info('Updating email via PII gateway', {
+        sessionId: state.sessionId,
+      });
+
+      const response = await agent.piiGateway.post(state.sessionId, 'https://www.acme.com/update_email', {
+        oldEmail: input.prev,
+        newEmail: input.new,
+      });
+
+      logger.info('Email update successful', {
+        sessionId: state.sessionId,
+        status: response.status,
+      });
+
+      return {
+        result: 'Email updated successfully',
+        state: {
+          memory: {
+            emailUpdated: true,
+            lastEmailUpdate: new Date().toISOString(),
+          },
+        },
+      };
+    } catch (error) {
+      logger.error('Email update failed', {
+        sessionId: state.sessionId,
+        error: error.message,
+      });
+      throw error;
+    }
+  },
+};
+```
+
+#### Request Configuration
+
+You can also pass additional configuration options:
+
+```ts
+const response = await agent.piiGateway.post(
+  sessionId,
+  'https://api.example.com/data',
+  { data: 'example' },
+  {
+    headers: {
+      Authorization: 'Bearer token',
+      'Content-Type': 'application/json',
+    },
+    params: {
+      version: 'v1',
+      format: 'json',
+    },
+  },
+);
+```
+
+#### How It Works
+
+1. **Trigger Received**: When your agent receives a trigger with a sessionId, the PII masking gateway is automatically initialized and available via `agent.piiGateway`
+2. **Session Binding**: The PII gateway is bound to the specific session context, ensuring proper PII isolation
+3. **Request Processing**: When you make HTTP requests through the gateway:
+   - Request data is automatically unmasked using session-specific mappings
+   - The request is sent to the target API with real, unmasked data
+   - The response is received and automatically masked before being returned
+4. **Error Handling**: Network errors and API errors are properly handled and logged
+
+## How PII Masking Works
+
+### Input Processing
+
+The masking workflow begins as data enters the Minded platform:
+
+1. The platform receives input (e.g. JSON object or string) tagged with a unique `sessionId`.
+
+2. PII entities are identified using the configured detection model.
+
+3. Detected entities are replaced with structured placeholders such as:
+
+   - `<PERSON1>`, `<PERSON2>` for names
+   - `<PHONE1>` for phone numbers
+   - `<ADDRESS1>`, `<ADDRESS2>` for addresses
+   - Other entity types as defined in your configuration
+
+4. A secure internal PII database (PII-DB) manages the mapping:
+
+   - Each `sessionId` has its own isolated mapping store
+   - Example mapping:
+
+     ```
+     "Kate" → <PERSON1>
+     "Josh Wildon" → <PERSON2>
+     ```
+
+   - Consistent masking/unmasking is maintained throughout the session
+   - Data is automatically purged from the PII-DB based on TTL settings
+
+### Session ID Configuration
+
+The **Trigger SessionId Field** setting in the UI specifies which field in your webhook payload contains the session identifier:
+
+- **Field Name**: Must be a valid property name (letters, numbers, underscores only)
+- **Examples**: `sessionId`, `session_id`, `conversationId`, `userId`
+- **Purpose**: Groups all PII data for a specific user session together
+- **Requirements**:
+  - Single word identifier
+  - No special characters except underscores
+  - Must exist in every webhook payload
+
+Example webhook payload where we set **Trigger SessionId Field** to **webhookId**:
+
+```json
+{
+  "webhookId": "user_12345_conversation_67890",
+  "customerName": "John Doe",
+  "email": "john.doe@example.com",
+  "orderDetails": "Need help with order #ABC123"
+}
+```
+
+### Mask Consistency
+
+The platform guarantees deterministic masking within a session:
+
+- Each unique entity always receives the same placeholder
+- New placeholders are generated only for previously unseen entities
+- Cross-reference logic maintains consistent relationships between data
+- TTL should be aligned with your agent's session lifecycle for optimal performance
+
+### Logging and Storage
+
+- All logs within the platform are written **only with masked data**
+- Raw, unmasked data is **never** logged

package/docs/platform/secrets.md

@@ -0,0 +1,99 @@
+# Secrets
+
+Secrets allow you to securely store sensitive configuration data like API keys and database credentials in your deployed MindedJS agents.
+
+## Overview
+
+Secrets are configured through the platform dashboard and automatically injected into `process.env` when your agent is deployed. They are only available in deployed agents, not during local development.
+
+**Key Features:**
+- Secure storage on the platform backend
+- Automatic injection into `process.env` for deployed agents
+- Environment-specific configuration (dev/staging/production)
+- Deploy-time access only
+
+## Usage
+
+### Basic Access
+
+```typescript
+// Access secrets via process.env in deployed agents
+const apiKey = process.env.OPENAI_API_KEY;
+const databaseUrl = process.env.DATABASE_URL;
+
+// Always validate required secrets
+if (!apiKey) {
+  throw new Error('OPENAI_API_KEY secret not configured');
+}
+```
+
+### In Tools
+
+```typescript
+import { Tool } from 'mindedjs';
+
+const weatherTool: Tool<{ city: string }, any> = {
+  name: 'getWeather',
+  description: 'Get weather information for a city',
+  parameters: {
+    type: 'object',
+    properties: {
+      city: { type: 'string', description: 'The city to get weather for' }
+    },
+    required: ['city']
+  },
+  handler: async ({ city }) => {
+    const apiKey = process.env.WEATHER_API_KEY;
+    
+    if (!apiKey) {
+      throw new Error('WEATHER_API_KEY secret not configured');
+    }
+    
+    const response = await fetch(`https://api.weather.com/v1/current?key=${apiKey}&q=${city}`);
+    return await response.json();
+  }
+};
+```
+
+## Configuration
+
+### Platform Management
+
+Configure secrets in the MindedJS platform dashboard:
+- Navigate to your agent's settings
+- Use the secrets management interface to add/edit secrets
+- Configure different values per environment
+- Changes require redeployment to take effect
+
+### Naming Conventions
+
+Use `UPPER_SNAKE_CASE` with descriptive names:
+- `OPENAI_API_KEY`
+- `DATABASE_URL`
+- `WEBHOOK_SECRET`
+- `JWT_SIGNING_KEY`
+
+## Local Development
+
+When developing locally, you can use the `.env` file (in the root of your project) to set the secrets or environment variables.
+
+```bash
+# .env file
+MINDED_CONNECTION_TOKEN=abc
+API_KEY=xyz
+```
+
+## Best Practices
+
+- **Always validate** that required secrets exist before use
+- **Never log** secret values in console output or logs
+- **Use descriptive names** for clarity
+- **Separate environments** with different secret values
+- **Never commit** `.env` files or hardcode secrets
+- **Regular rotation** of secrets through the platform
+
+## Troubleshooting
+
+- **Secret not available**: Verify it's configured in platform dashboard with exact name (case-sensitive) and agent is deployed
+- **Local development**: Remember secrets only work in deployed agents - use `.env` files or fallbacks locally
+- **Changes not applied**: Secret changes require redeployment to take effect 

package/docs/resources/your-first-eval.md

@@ -0,0 +1,108 @@
+# Your First Eval
+
+At Minded, we strong believe in the [Agent Development Lifecycle (ADLC)](https://www.minded.com/blog/adlc-loop), our agentic take on the Software Development Lifecycle (SDLC), a.k.a. how to ship reliable agents fast.
+
+In this guide we’ll vibe-code an agent that sets the stage for the last-mile prompt engineering needed to go live to production - you’ll get a fresh from the oven agent
+
+## The ADLC flow
+
+Here’s how an [Agent Squad](https://www.minded.com/blog/agent-squad) team up from 0 to 1
+
+<figure><img src="../getting-started/.gitbook/assets/ADLC.png" alt=""><figcaption></figcaption></figure>
+
+## Step by Step
+
+### Define Minimum Viable Agent (MVA)
+
+**Owner: Agent Product Manager**
+
+Define the absolute minimum the agent needs to do before going live.
+
+For the most part that means answering the following questions
+
+If possible handoff to human reps anything that’s outside of that scope.
+
+| Aspect                  | Example response for an ecommerce support agent            |
+| ----------------------- | ---------------------------------------------------------- |
+| Initial use case        | Order status                                               |
+| Interface               | Zendesk messaging                                          |
+| How to interact with it | sending SMS to the support number                          |
+| Handoff mechanism       | Assign CS Human tag on Zendesk upon escalation             |
+| Metric                  | Deflection rate - % of support tickets solved by the agent |
+
+### Prepare E2E evals of real world cases
+
+**Owner: Domain Expert**
+
+Prepare end-to-end examples of how humans solve real world cases, each example should ideally include:
+
+1. Screen recording of the different apps operated throughout the resolution
+2. Explanation of the decision making process behind the resolution
+3. If you’re using a knowledge base, then list all the relevant articles from it that are used for this resolution
+4. List all other data sources used throughout the resolution (such as admin panels)
+
+### Identify data sources per each eval
+
+**Owner: Agent Engineer**
+
+This step is critical to build agents that take actions and make decisions:
+
+1. Identify the data sources available to the AI Agent to be able to reproduce the decision making process and/or actions of the end-to-end evals of the previous step. The most obvious data source are the interface (often that’s the customer support CRM such as Zendesk), and the admin panel (often that’s the human operator dashboard, such as Retool), however often these data sources can get tricky from 3rd party
+2. Map each data source into an API endpoint and ensure the relevant fields are available from the API
+3. When an API is not available consider alternatives such as Computer Use, and make sure the authentication could be enabled for an AI Agent.
+
+### Run the agent locally
+
+**Owner: Agent Engineer**
+
+Now is the time to make sure all the tools and knowledge are accessible for the agent
+
+1. Setup the local development environment (see getting started guide)
+2. Add tools per each data source
+3. Add knowledge per each knowledge source
+4. Add a prompt node to the agent that uses each of the above tools and knowledge bases and make sure that each of them are being called by the agent
+
+### Prompt Engineering
+
+**Owner: Agent Engineer**
+
+Next you’re going to solve each of the above evals by retrying again and again.
+
+You are probably going to run a similar process to each of the eval examples:
+
+1. Invoke the trigger - ideally in a way that lets the agent actually pull the data it needs for the example
+2. Run the scenario in a step by step manner, whenever you run into an issue troubleshoot, solve it, and retry
+   1. Evaluate the steps, normally evaluation covers:
+      1. Agent tone of voice
+      2. Tools accuracy - are the input parameters configured correctly?
+      3. Did the agent invoke the right tool at the right time? with the right parameters?
+      4. Did the agent take necessary actions?
+      5. Did it retrieve the right knowledge base articles? Did it parse them correctly?
+   2. If there were any issues there are usually two ways to go about it - solve it with code, or solve it with prompt (see our prompt engineering best practices)
+   3. After you’ve applied a fix - retry the last step, until you’re able to reach the desired state
+   4. If you weren’t able to solve it - consider escalating similar cases in the future, to let humans take care of cases where the agent is not perfect yet
+   5. Repeat until the example reaches its final step successfully
+3. Now that the example run fully it is time to review post-run logs, actions and analytics
+
+### Agent Warm up
+
+**Owner: Agent Engineer**
+
+**Warm up** is everything that happens from the moment the agent wakes up to the first node execution. This is the window where we inject critical context, like `user_id` , or qualifying triggers to ensure the agent is laser-focused on the task it needs to resolve.
+
+1. Qualify the trigger - review the data schema of the trigger and make your mind if some of those data points should indicate the agent is not qualified for certain scenarios. Remember it’s usually best to launch a reliable agent at small scale (see MVA above).
+2. Enrich context - some context should or could be introduced to the agent upfront. It could be parameters `user_id` , or some tools (for example pulling order details for an ecommerce support agent)
+
+### QA
+
+**Owner: Domain Expert**
+
+This is the final OK before going live. This is where the expert “stress test” the agent for more edge cases, and evaluates the results.
+
+If the agent is good enough - then awesome time to deploy. Otherwise, it’s time for more evals 💪🏻
+
+### Publish
+
+**Owner: Agent Engineer**
+
+Hit deploy on the platform and follow our deployment instructions for more details.

package/docs-structure.md

@@ -0,0 +1,141 @@
+# 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.md                # Memory 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.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
+* [API Reference](https://minded-ai.github.io/mindedjs-api-referance)
+
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minded-ai/mindedjs",
-  "version": "1.0.89",
+  "version": "1.0.91-beta-1",
   "description": "MindedJS is a TypeScript library for building agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,9 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "docs",
+    "docs-structure.md"
   ],
   "scripts": {
     "build": "tsc && npm run copy-templates",
@@ -64,4 +66,4 @@
     "uuid": "^11.1.0",
     "ws": "^8.15.1"
   }
-}
+}