@minded-ai/mindedjs 3.1.31 → 3.1.32

package/docs/platform/knowledge-bases.md

@@ -0,0 +1,191 @@
+# Knowledge Bases
+
+Knowledge bases let you upload documents (with metadata), keep them synced per environment, and query them at runtime from your agent.
+
+## Concepts
+
+- **Knowledge base**: A named container of documents that belongs to a specific agent.
+- **Document**: A file (PDF, TXT, DOCX, etc.) plus optional metadata used for filtering.
+- **Environment**: Separate datasets per environment: `development`, `staging`, `production`.
+
+## Manage knowledge bases in the platform (UI)
+
+### Create a knowledge base
+
+1. Open your agent in the Minded dashboard
+2. Navigate to **Knowledge Bases**
+3. Click **Create knowledge base**
+4. Set a **name** (and optional description) and save
+
+### Update a knowledge base
+
+You can update a knowledge base’s **name** and **description** from the knowledge base settings/details view.
+
+### Delete a knowledge base
+
+Deleting a knowledge base removes it from the agent and triggers cleanup of its documents across environments.
+
+## Upload and manage documents (UI)
+
+From the knowledge base view, you can upload documents and set metadata for filtering.
+
+Typical flow:
+
+- Upload a document (and optionally add metadata)
+- Wait for ingestion/sync to complete
+- Use the platform “Query” / “Generate” actions to test retrieval and citations
+
+## Manage documents via API
+
+For programmatic document management (upload, update, metadata, delete), use the Knowledge API:
+
+- Base URL: `https://api.minded.com/api/v1`
+- Scope required: `knowledge-management`
+
+See the full reference in [Knowledge API](../api/knowledge.md).
+
+## Platform knowledge APIs (advanced)
+
+These endpoints are used by the Minded dashboard. They are helpful for internal automation and debugging.
+
+> **Note:** The dashboard APIs are not the same as the customer-facing `/api/v1/*` APIs. They require dashboard authentication and are mounted under the dashboard service.
+
+### Knowledge base CRUD
+
+All routes are scoped to an agent via `:agentId`.
+
+- **List knowledge bases**
+  - **GET** `/dashboard/agents/:agentId/knowledge/bases`
+- **Create a knowledge base**
+  - **POST** `/dashboard/agents/:agentId/knowledge/bases`
+  - Body:
+    ```json
+    {
+      "name": "Support KB",
+      "description": "Policies and FAQs"
+    }
+    ```
+- **Get a knowledge base**
+  - **GET** `/dashboard/agents/:agentId/knowledge/bases/:knowledgeBaseId`
+- **Update a knowledge base**
+  - **PATCH** `/dashboard/agents/:agentId/knowledge/bases/:knowledgeBaseId`
+  - Body:
+    ```json
+    {
+      "name": "Support KB (v2)",
+      "description": "Updated description"
+    }
+    ```
+- **Delete a knowledge base**
+  - **DELETE** `/dashboard/agents/:agentId/knowledge/bases/:knowledgeBaseId`
+
+### Query and generate (platform testing endpoints)
+
+These endpoints are commonly used by the dashboard UI to test retrieval and “retrieve + generate”.
+
+- **Retrieve only**
+  - **POST** `/dashboard/agents/:agentId/knowledge/:environment/kb/:knowledgeBaseId/query`
+  - Body:
+    ```json
+    {
+      "query": "What is the refund policy?",
+      "numberOfResults": 5
+    }
+    ```
+
+- **Retrieve and generate (with citations)**
+  - **POST** `/dashboard/agents/:agentId/knowledge/:environment/kb/:knowledgeBaseId/generate`
+  - Body:
+    ```json
+    {
+      "query": "Summarize the refund policy",
+      "numberOfResults": 5,
+      "modelArn": "optional-model-identifier",
+      "filters": {
+        "equals": { "key": "category", "value": "policy" }
+      }
+    }
+    ```
+
+If you want to query from agent code (recommended for runtime usage), use the SDK methods documented in [Knowledge Base RAG API](../sdk/knowledge-base-rag.md).
+
+## Enable knowledge base usage in an agent
+
+There are two common patterns: **automatic default retrieval** configured from the platform, and **manual retrieval** from code.
+
+### Option A: Automatic default retrieval (platform configuration)
+
+The platform can configure “RAG defaults” for your agent. When enabled, MindedJS will:
+
+- Run retrieval automatically **after `TRIGGER_EVENT`**
+- Retrieve from one or more configured knowledge bases
+- Filter by `minScore` (if provided)
+- Inject the retrieved context into the conversation as a **system message**
+
+#### Default retrieval settings
+
+Default retrieval is configured **per environment** (`development`, `staging`, `production`). Each environment can include:
+
+- `enabled`: turn default retrieval on/off
+- `knowledgeBases`: list of knowledge bases to query on every trigger
+  - `knowledgeBaseId`: the KB ID to query
+  - `environment` (optional): override which KB environment to query (defaults to the current environment)
+  - `numberOfResults` (optional): how many chunks to retrieve
+  - `minScore` (optional): discard results below this similarity score threshold
+  - `filters` (optional): metadata filters applied to retrieval
+
+#### Filter operators and templating
+
+Default retrieval filters support these operators:
+
+- `equals`
+- `notEquals`
+- `greaterThan`
+- `lessThan`
+
+Filter values can be either:
+
+- A **plain string** (example: `"policy"`)
+- A **memory chip pattern** in the exact form: `{state.memory.<path>}`
+  - Example: `{state.memory.language}`
+  - Nested values are supported with dot notation: `{state.memory.user.locale}`
+  - If the memory value is missing (`null`/`undefined`), that filter entry is **skipped**
+
+Multiple filter entries are combined with **AND** semantics.
+
+#### Example default retrieval configuration
+
+This is an example of the underlying shape (shown here for clarity; in practice it’s configured via the platform UI):
+
+```json
+{
+  "production": {
+    "enabled": true,
+    "knowledgeBases": [
+      {
+        "knowledgeBaseId": "kb-abc123",
+        "numberOfResults": 5,
+        "minScore": 0.6,
+        "filters": [
+          { "key": "category", "operator": "equals", "value": "policy" },
+          { "key": "language", "operator": "equals", "value": "{state.memory.language}" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Option B: Manual retrieval from code (e.g., in `TRIGGER_EVENT`)
+
+If you need full control over _when_ retrieval happens and _how_ results are applied, you can:
+
+Import directly from the SDK:
+
+- `retrieveFromKnowledgeBase(...)`
+- `retrieveAndGenerateFromKnowledgeBase(...)`
+
+See:
+
+- [Knowledge Base RAG API](../sdk/knowledge-base-rag.md)
+- [Events → TRIGGER_EVENT](../sdk/events.md#trigger_event) (includes an example of querying a knowledge base during trigger qualification)

package/docs/platform/security-architecture.md

@@ -316,7 +316,6 @@ For more information on related security and operational topics, see:
 - **[Secrets Management](secrets.md)** - Detailed guide on storing and managing credentials securely
 - **[Operator Documentation](operator.md)** - Operational procedures and best practices for running agents
 - **[On-Premise Deployment](on-prem.md)** - Security considerations for self-hosted Minded installations
-- **[Browser Task (RPA)](browserTask.md)** - Technical details on RPA capabilities and configurations
 
 ---
 

package/docs/sdk/agent-api.md

@@ -218,6 +218,18 @@ await agent.compiledGraph.updateState(agent.getLangraphConfig(sessionId), {
 });
 ```
 
+### Knowledge Base RAG
+
+You can query knowledge bases directly from code by importing the RAG utilities:
+
+```typescript
+import { retrieveFromKnowledgeBase, retrieveAndGenerateFromKnowledgeBase } from '@minded-ai/mindedjs';
+```
+
+These functions are useful when you want full control over retrieval timing (for example in `TRIGGER_EVENT`) and how the retrieved context is applied.
+
+See [Knowledge Base RAG API](./knowledge-base-rag.md) for function signatures, filtering, and citations.
+
 ## State Management Best Practices
 
 ### 1. Partial Updates

package/docs/sdk/events.md

@@ -16,6 +16,7 @@ All events provide access to `state.history`, an array of `HistoryStep` objects
 - `messageIds`: Associated message IDs
 
 Additional fields:
+
 - `APP_TRIGGER_NODE`: `appName` identifies source application
 - `TOOL_NODE`: Contains tool input/output information
 
@@ -23,9 +24,7 @@ Additional fields:
 
 ```typescript
 agent.on(events.AI_MESSAGE, async ({ state }) => {
-  const triggerStep = state.history.find((step) => 
-    step.type === 'TRIGGER_NODE' || step.type === 'APP_TRIGGER_NODE'
-  );
+  const triggerStep = state.history.find((step) => step.type === 'TRIGGER_NODE' || step.type === 'APP_TRIGGER_NODE');
   const toolSteps = state.history.filter((step) => step.type === 'TOOL_NODE');
   console.log(`Trigger: ${triggerStep?.nodeDisplayName}, Tools used: ${toolSteps.length}`);
 });
@@ -36,6 +35,7 @@ agent.on(events.AI_MESSAGE, async ({ state }) => {
 Emitted when agent's graph state is initialized (new session begins).
 
 **Input:**
+
 ```typescript
 {
   state: {
@@ -51,6 +51,7 @@ Emitted when agent's graph state is initialized (new session begins).
 **Return:** `void` (handlers for side effects only)
 
 **Example:**
+
 ```typescript
 agent.on(events.INIT, async ({ state }) => {
   await initializeSessionResources(state.sessionId);
@@ -68,6 +69,7 @@ agent.on(events.INIT, async ({ state }) => {
 Emitted when AI generates a message for the user.
 
 **Input:**
+
 ```typescript
 {
   message: string;
@@ -83,14 +85,17 @@ Emitted when AI generates a message for the user.
 **Return:** `void` (handlers for side effects only)
 
 **Example:**
+
 ```typescript
 agent.on(events.AI_MESSAGE, async ({ message, state }) => {
   await sendMessageToUser(message, state.sessionId);
-  await websocket.send(JSON.stringify({
-    type: 'ai_message',
-    content: message,
-    sessionId: state.sessionId
-  }));
+  await websocket.send(
+    JSON.stringify({
+      type: 'ai_message',
+      content: message,
+      sessionId: state.sessionId,
+    }),
+  );
 });
 ```
 
@@ -101,11 +106,12 @@ agent.on(events.AI_MESSAGE, async ({ message, state }) => {
 Emitted when a trigger node is executed. Allows qualifying triggers and modifying state before processing.
 
 **Input:**
+
 ```typescript
 {
   triggerName: string;
   triggerBody: any;
-  state: State<Memory>;  // Current state (can be modified by reference)
+  state: State<Memory>; // Current state (can be modified by reference)
 }
 ```
 
@@ -114,6 +120,7 @@ Emitted when a trigger node is executed. Allows qualifying triggers and modifyin
 **Important:** State is modified by reference (v2.0). Modify `state` directly, don't return state updates.
 
 **Return patterns:**
+
 ```typescript
 // Qualify
 return { isQualified: true };
@@ -136,6 +143,43 @@ agent.on(events.TRIGGER_EVENT, async ({ triggerBody, state }) => {
 });
 ```
 
+```typescript
+// Query a knowledge base during trigger qualification
+//
+// Use this pattern when you want full control over *when* retrieval happens
+// and *how* the retrieved context is applied to the conversation.
+import { SystemMessage } from '@langchain/core/messages';
+import { v4 as uuidv4 } from 'uuid';
+import { retrieveFromKnowledgeBase } from '@minded-ai/mindedjs';
+
+agent.on(events.TRIGGER_EVENT, async ({ triggerBody, state }) => {
+  const query = typeof triggerBody?.content === 'string' ? triggerBody.content : JSON.stringify(triggerBody);
+
+  // knowledgeBaseId is optional - backend auto-selects if agent has exactly 1 KB
+  // Pass knowledgeBaseId explicitly if you have multiple KBs
+  const { retrievalResults } = await retrieveFromKnowledgeBase({
+    environment: 'production',
+    query,
+    numberOfResults: 5,
+  });
+
+  if (retrievalResults.length > 0) {
+    const context = retrievalResults.map((r) => `#### ${r.location.s3Location.uri}\n${r.content.text}`).join('\n\n');
+
+    state.messages.push(
+      new SystemMessage({
+        id: uuidv4(),
+        content: `### Knowledge Base Context\n\n${context}`,
+      }),
+    );
+  }
+
+  return { isQualified: true };
+});
+```
+
+> **Tip:** If you want retrieval to happen automatically after `TRIGGER_EVENT`, enable “default retrieval” from the platform. See [Knowledge Bases](../platform/knowledge-bases.md#enable-knowledge-base-usage-in-an-agent).
+
 > **Note:** `goto` jump occurs after current invocation completes.
 
 **Use cases:** Input validation, data transformation, context setting, access control, routing logic
@@ -145,6 +189,7 @@ agent.on(events.TRIGGER_EVENT, async ({ triggerBody, state }) => {
 Emitted when an error occurs during execution. Control whether error is thrown or caught.
 
 **Input:**
+
 ```typescript
 {
   error: Error;
@@ -153,21 +198,23 @@ Emitted when an error occurs during execution. Control whether error is thrown o
 ```
 
 **Return:**
+
 ```typescript
 {
-  throwError: boolean;  // true = throw error and stop, false = catch and continue
+  throwError: boolean; // true = throw error and stop, false = catch and continue
 }
 ```
 
 **Important:** State is modified by reference (v2.0).
 
 **Example:**
+
 ```typescript
 agent.on(events.ERROR, async ({ error, state }) => {
   await logger.error({
     message: 'Agent execution error',
     error: error.message,
-    sessionId: state.sessionId
+    sessionId: state.sessionId,
   });
 
   if (error.message.includes('rate limit')) {
@@ -191,6 +238,7 @@ agent.on(events.ERROR, async ({ error, state }) => {
 Emitted before evaluating a logical condition on an edge.
 
 **Input:**
+
 ```typescript
 {
   edge: LogicalConditionEdge;
@@ -202,13 +250,14 @@ Emitted before evaluating a logical condition on an edge.
 **Return:** `void` (handlers for debugging/logging only)
 
 **Example:**
+
 ```typescript
 agent.on(events.ON_LOGICAL_CONDITION, async ({ edge, condition, state }) => {
   await logger.debug({
     event: 'condition_evaluation_start',
     condition,
     edge: { source: edge.source, target: edge.target },
-    sessionId: state.sessionId
+    sessionId: state.sessionId,
   });
 });
 ```
@@ -220,6 +269,7 @@ agent.on(events.ON_LOGICAL_CONDITION, async ({ edge, condition, state }) => {
 Emitted after a logical condition is evaluated, providing result and execution metrics.
 
 **Input:**
+
 ```typescript
 {
   edge: LogicalConditionEdge;
@@ -234,6 +284,7 @@ Emitted after a logical condition is evaluated, providing result and execution m
 **Return:** `void` (handlers for logging/monitoring only)
 
 **Example:**
+
 ```typescript
 agent.on(events.ON_LOGICAL_CONDITION_RESULT, async ({ condition, result, executionTimeMs, error }) => {
   if (error) {
@@ -255,15 +306,13 @@ agent.on(events.ON_LOGICAL_CONDITION_RESULT, async ({ condition, result, executi
 Emitted when you call `trackAnalyticsEvent()` to send custom analytics data.
 
 **Function signature:**
+
 ```typescript
-async function trackAnalyticsEvent(
-  eventName: string,
-  payload: Record<string, any>,
-  sessionId: string
-): Promise<void>;
+async function trackAnalyticsEvent(eventName: string, payload: Record<string, any>, sessionId: string): Promise<void>;
 ```
 
 **Handler input:**
+
 ```typescript
 {
   eventName: string;
@@ -275,6 +324,7 @@ async function trackAnalyticsEvent(
 **Return:** `void`
 
 **Example:**
+
 ```typescript
 import { trackAnalyticsEvent } from '@minded-ai/mindedjs';
 
@@ -285,9 +335,9 @@ agent.on(events.AI_MESSAGE, async ({ state }) => {
       'booking_completed',
       {
         bookingId: state.memory.bookingId,
-        amount: state.memory.totalAmount
+        amount: state.memory.totalAmount,
       },
-      state.sessionId
+      state.sessionId,
     );
   }
 });
@@ -298,13 +348,14 @@ agent.on(events.ANALYTICS_EVENT, async ({ eventName, payload, sessionId }) => {
 });
 ```
 
-**Query analytics:** Use the [REST API](../platform/api.md)
+**Query analytics:** Use the [Analytics API](../api/analytics.md)
 
 ## TURN_END
 
 Emitted when a trigger invocation completes, just before returning the result. Allows customizing the return value.
 
 **Input:**
+
 ```typescript
 {
   state: State<Memory>;
@@ -312,13 +363,15 @@ Emitted when a trigger invocation completes, just before returning the result. A
 ```
 
 **Return:**
+
 ```typescript
 {
-  returnValue: any;  // Custom return value (optional)
+  returnValue: any; // Custom return value (optional)
 }
 ```
 
 **Example:**
+
 ```typescript
 agent.on(events.TURN_END, async ({ state }) => {
   return {
@@ -328,9 +381,9 @@ agent.on(events.TURN_END, async ({ state }) => {
       message: 'Operation completed',
       metadata: {
         executionTime: state.memory.executionTime,
-        stepsExecuted: state.history.length
-      }
-    }
+        stepsExecuted: state.history.length,
+      },
+    },
   };
 });
 ```