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

package/docs/sdk/memory.md

@@ -0,0 +1,271 @@
+# Memory Types
+
+Memory in MindedJS allows agents to persist and share data across conversation turns and flow executions. It acts as the agent's working memory, storing context, user information, conversation state, and any other data your agent needs to remember.
+
+## What is Memory?
+
+Memory is a structured data store that:
+
+- Persists throughout an agent session
+- Is accessible to all nodes in your flows
+- Gets automatically merged when updated
+- Is validated against a schema you define
+- Can store any JSON-serializable data
+
+## Defining Memory Schema
+
+Memory schemas are defined using [Zod](https://zod.dev/) for type safety and runtime validation.
+
+```typescript
+import { z } from 'zod';
+
+const memorySchema = z.object({
+  user: z.object({
+    id: z.string(),
+    name: z.string(),
+    preferences: z.object({
+      language: z.string().default('en'),
+      timezone: z.string().default('UTC'),
+    }),
+  }),
+  conversation: z.object({
+    topic: z.string().optional(),
+    urgency: z.enum(['low', 'medium', 'high']).default('medium'),
+  }),
+  order: z
+    .object({
+      id: z.string(),
+      status: z.string(),
+      total: z.number(),
+    })
+    .optional(),
+});
+
+type Memory = z.infer<typeof memorySchema>;
+```
+
+## Using Memory in Your Agent
+
+### 1. Configure Memory Schema
+
+```typescript
+import { Agent } from 'mindedjs';
+
+const agent = new Agent({
+  memorySchema,
+  config,
+  tools,
+});
+```
+
+### 2. Initialize Memory
+
+Memory is typically initialized when a trigger event occurs:
+
+```typescript
+import { events } from 'mindedjs';
+
+agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody, state }) => {
+  if (triggerName === 'new_order_issue') {
+    // Update state directly by reference (v2.0 change)
+    if (state) {
+      state.memory.user = { id: triggerBody.userId, name: triggerBody.userName };
+      state.memory.order = { id: triggerBody.orderId, status: 'pending' };
+    }
+
+    return {
+      isQualified: true,
+    };
+  }
+});
+```
+
+### 3. Access Memory in Tools
+
+Tools can read from and write to memory:
+
+```typescript
+const updateOrderStatus = {
+  name: 'updateOrderStatus',
+  description: 'Updates the order status in memory',
+  inputSchema: z.object({
+    newStatus: z.string(),
+  }),
+  execute: async ({ input, state }) => {
+    // Read from memory
+    const currentOrder = state.memory.order;
+
+    // Update state directly by reference (v2.0 change)
+    state.memory.order = {
+      ...currentOrder,
+      status: input.newStatus,
+      lastUpdated: new Date().toISOString(),
+    };
+
+    return {
+      result: `Order status updated to ${input.newStatus}`,
+    };
+  },
+};
+```
+
+## Memory Lifecycle
+
+1. **Initialization**: Memory starts empty `{}` and gets populated during trigger events
+2. **Persistence**: Automatically persisted between conversation turns
+3. **Updates**: Memory is updated by reference in tools and event handlers (v2.0 change)
+4. **Validation**: All updates are validated against your schema
+
+```typescript
+// Current memory: { userId: "123", userName: "John" }
+// Tool updates state directly:
+//   state.memory.userName = "John Doe";
+//   state.memory.email = "john@example.com";
+// Result: { userId: "123", userName: "John Doe", email: "john@example.com" }
+```
+
+## Best Practices
+
+### 1. Keep It Focused
+
+Only store data relevant to your agent's functionality:
+
+```typescript
+// Good: Focused schema
+const memorySchema = z.object({
+  customerId: z.string(),
+  currentIssue: z.string(),
+  resolutionSteps: z.array(z.string()),
+});
+```
+
+### 2. Use Optional Fields and Defaults
+
+```typescript
+const memorySchema = z.object({
+  userId: z.string(),
+  orderId: z.string().optional(), // Not all conversations involve orders
+  conversationState: z.enum(['started', 'in_progress', 'resolved']).default('started'),
+  attemptCount: z.number().default(0),
+});
+```
+
+### 3. Structure Related Data
+
+Group related fields into objects:
+
+```typescript
+const memorySchema = z.object({
+  customer: z.object({
+    id: z.string(),
+    name: z.string(),
+    tier: z.enum(['bronze', 'silver', 'gold']),
+  }),
+  session: z.object({
+    startTime: z.string(),
+    channel: z.enum(['chat', 'email', 'phone']),
+  }),
+});
+```
+
+## Common Patterns
+
+### User Context Pattern
+
+```typescript
+const memorySchema = z.object({
+  user: z.object({
+    id: z.string(),
+    profile: z.object({
+      name: z.string(),
+      email: z.string(),
+      preferences: z.record(z.unknown()),
+    }),
+  }),
+});
+```
+
+### Conversation State Pattern
+
+```typescript
+const memorySchema = z.object({
+  conversation: z.object({
+    phase: z.enum(['greeting', 'information_gathering', 'processing', 'resolution']),
+    data: z.record(z.unknown()),
+  }),
+});
+```
+
+## Memory vs Messages vs History
+
+- **Memory**: Structured data representing current state and context
+- **Messages**: Conversation messages (AI, Human, Tool call, System etc.)
+- **History**: Flow execution tracking with details about node visits, triggers, and tool calls
+
+```typescript
+// Memory: Current state
+{
+  orderId: "ORD-123",
+  status: "processing",
+  customer: { name: "John", tier: "gold" }
+}
+
+// Messages: Conversation messages
+[
+  { role: "human", content: "I need help with my order" },
+  { role: "ai", content: "I'd be happy to help!" },
+]
+
+
+```
+
+All three work together to provide complete context to your agent.
+
+## Updating Memory Outside Agent Lifecycle
+
+Sometimes you need to update the agent's memory from outside the normal agent flow - for example, when external events occur or when you need to programmatically modify the session state. MindedJS provides the `updateMemory` method for this purpose.
+
+### Using updateMemory
+
+The `updateMemory` method allows you to update the memory for a specific session:
+
+```typescript
+await agent.updateMemory(sessionId, memoryUpdate);
+```
+
+### Parameters
+
+- `sessionId` (string): The unique identifier of the session whose memory you want to update
+- `memoryUpdate` (Partial<Memory>): A partial memory object containing only the fields you want to update
+
+### Example Usage
+
+```typescript
+// Update a single field
+await agent.updateMemory('session-123', {
+  order: {
+    status: 'shipped',
+    trackingNumber: 'TRK-456789',
+  },
+});
+
+// Update multiple fields
+await agent.updateMemory('session-123', {
+  user: {
+    preferences: {
+      language: 'es',
+      timezone: 'America/Mexico_City',
+    },
+  },
+  conversation: {
+    urgency: 'high',
+  },
+});
+```
+
+### Important Notes
+
+1. **Partial Updates**: The memory update is merged with existing memory, so you only need to provide the fields you want to change
+2. **Validation**: Updates are validated against your memory schema - invalid updates will throw an error
+3. **Session Must Exist**: The session ID must correspond to an active session
+4. **Asynchronous**: The method returns a Promise, so make sure to await it

package/docs/sdk/parallel-llm.md

@@ -0,0 +1,242 @@
+# Parallel LLM Requests
+
+Parallel LLM requests can significantly reduce latency by sending multiple identical requests and using the fastest response. This feature can reduce response times by 30-50% in scenarios with variable network conditions.
+
+## Quick Start
+
+The easiest way to enable parallel requests is through your `minded.json` configuration:
+
+```json
+{
+  "flows": ["./src/flows"],
+  "tools": ["./src/tools"],
+  "agent": "./src/agent.ts",
+  "llm": {
+    "name": "MindedChatOpenAI",
+    "properties": {
+      "model": "gpt-4o",
+      "numParallelRequests": 3,
+      "logTimings": true
+    }
+  }
+}
+```
+
+Your agent will automatically use parallel requests for all LLM calls:
+
+```typescript
+import { Agent } from '@minded-ai/mindedjs';
+import memorySchema from './agentMemorySchema';
+import config from '../minded.json';
+import tools from './tools';
+
+const agent = new Agent({
+  memorySchema,
+  config, // Parallel configuration is automatically applied
+  tools,
+});
+```
+
+## Configuration Options
+
+### MindedChatOpenAI (Recommended)
+
+For agents running on the Minded platform, use `MindedChatOpenAI` with parallel configuration:
+
+```json
+{
+  "llm": {
+    "name": "MindedChatOpenAI",
+    "properties": {
+      "model": "gpt-4o",
+      "numParallelRequests": 3,
+      "logTimings": true,
+      "temperature": 0.7
+    }
+  }
+}
+```
+
+### AzureChatOpenAI
+
+For Azure OpenAI deployments:
+
+```json
+{
+  "llm": {
+    "name": "AzureChatOpenAI",
+    "properties": {
+      "model": "gpt-4o",
+      "numParallelRequests": 3,
+      "logTimings": true,
+      "azureOpenAIApiVersion": "2024-02-01"
+    }
+  }
+}
+```
+
+Required environment variables:
+
+```env
+AZURE_OPENAI_API_KEY=your_azure_key
+AZURE_OPENAI_API_INSTANCE_NAME=your_instance_name
+AZURE_OPENAI_API_DEPLOYMENT_NAME=your_deployment_name
+```
+
+### ChatOpenAI
+
+For standard OpenAI API:
+
+```json
+{
+  "llm": {
+    "name": "ChatOpenAI",
+    "properties": {
+      "model": "gpt-4o",
+      "numParallelRequests": 3,
+      "logTimings": true,
+      "openAIApiKey": "${OPENAI_API_KEY}"
+    }
+  }
+}
+```
+
+## Configuration Parameters
+
+| Parameter             | Type    | Default | Description                                   |
+| --------------------- | ------- | ------- | --------------------------------------------- |
+| `numParallelRequests` | number  | 1       | Number of parallel requests (2-5 recommended) |
+| `logTimings`          | boolean | false   | Enable detailed timing logs                   |
+
+## Performance Notes
+
+- **Optimal Range**: 2-3 parallel requests usually provide the best latency/cost balance
+- **Cost Impact**: You pay for all parallel requests made
+- **Best Use Cases**: Variable network conditions, consistency requirements
+- **Latency Reduction**: Typically 30-50% faster response times
+
+## Monitoring Performance
+
+When `logTimings: true` is enabled, you'll see detailed performance logs:
+
+```
+[Model] Fastest request completed { requestTime: 1.234, numParallelRequests: 3 }
+[Model] Time saved using parallel requests {
+  fastestRequestTime: 1.234,
+  secondFastestRequestTime: 1.567,
+  allFinishTime: 2.345,
+  timeSaved: 1.111,
+  timeSavedFromSecond: 0.333
+}
+```
+
+## Advanced Usage
+
+### Dynamic Configuration
+
+You can adjust parallel requests based on environment:
+
+```json
+{
+  "llm": {
+    "name": "MindedChatOpenAI",
+    "properties": {
+      "model": "gpt-4o",
+      "numParallelRequests": "${NODE_ENV === 'production' ? 3 : 1}",
+      "logTimings": "${NODE_ENV === 'development'}"
+    }
+  }
+}
+```
+
+### Manual Instantiation with createParallelWrapper
+
+For advanced use cases where you need direct control over the LLM instance, you can manually apply parallel wrapping:
+
+```typescript
+import { createParallelWrapper } from '@minded-ai/mindedjs';
+import { ChatOpenAI, AzureChatOpenAI } from '@langchain/openai';
+
+// Manual wrapping for ChatOpenAI
+const parallelOpenAI = createParallelWrapper(
+  new ChatOpenAI({
+    openAIApiKey: process.env.OPENAI_API_KEY,
+    model: 'gpt-4o',
+    temperature: 0.7,
+  }),
+  {
+    numParallelRequests: 3,
+    logTimings: true,
+  },
+);
+
+// Manual wrapping for AzureChatOpenAI
+const parallelAzure = createParallelWrapper(
+  new AzureChatOpenAI({
+    azureOpenAIApiKey: process.env.AZURE_OPENAI_API_KEY,
+    azureOpenAIApiInstanceName: process.env.AZURE_OPENAI_INSTANCE!,
+    azureOpenAIApiDeploymentName: process.env.AZURE_OPENAI_DEPLOYMENT!,
+    azureOpenAIApiVersion: '2024-02-01',
+  }),
+  {
+    numParallelRequests: 2,
+    logTimings: false,
+  },
+);
+
+// Use directly with Agent (bypassing configuration)
+const agent = new Agent({
+  memorySchema,
+  config: {
+    flows: ['./flows'],
+    tools: [],
+    llm: parallelOpenAI as any, // Direct LLM instance
+  },
+  tools: [],
+});
+```
+
+**Note**: The configuration-based approach is recommended for most use cases as it's simpler and more maintainable. Use manual instantiation only when you need specific control over LLM creation or are integrating with existing LangChain workflows.
+
+## How It Works
+
+### MindedChatOpenAI (Backend Processing)
+
+- Parallel requests are handled on the Minded platform backend
+- Multiple requests sent to Azure OpenAI from the backend
+- Fastest response returned to your agent
+- Optimal for production deployments
+
+### Other LLM Providers (Client-Side Processing)
+
+- Parallel requests handled in your application
+- Multiple requests sent directly to the LLM provider
+- Good for development and custom deployments
+
+## Best Practices
+
+1. **Start Small**: Begin with 2-3 parallel requests
+2. **Monitor Costs**: Each parallel request counts toward your usage
+3. **Enable Logging**: Use `logTimings: true` during development to measure improvements
+4. **Environment-Specific**: Use fewer parallel requests in development
+5. **Configuration Over Code**: Prefer `minded.json` configuration over manual instantiation
+
+## Troubleshooting
+
+### No Performance Improvement
+
+- Check network latency variability
+- Ensure `numParallelRequests > 1`
+- Verify timing logs are showing multiple requests
+
+### Increased Costs
+
+- Reduce `numParallelRequests`
+- Consider cost vs. latency trade-offs
+- Monitor usage patterns
+
+### Rate Limiting
+
+- Lower `numParallelRequests`
+- Implement backoff strategies
+- Contact provider about rate limits

package/docs/sdk/vectorstore-query.md

@@ -0,0 +1,60 @@
+# Vector Store Query API
+
+Query indexed document collections directly from your agent code to retrieve relevant documents from knowledge bases.
+
+## Method Signature
+
+```typescript
+agent.getDocumentsFromDB(
+  collectionName: string,
+  query: string,
+  options?: {
+    filter?: any;
+    numChunks?: number;
+    minScore?: number;
+  },
+  timeoutMs?: number
+): Promise<Document[]>
+```
+
+## Parameters
+
+| Parameter           | Type   | Required | Description                          |
+| ------------------- | ------ | -------- | ------------------------------------ |
+| `collectionName`    | string | ✓        | Name of the vectore store collection |
+| `query`             | string | ✓        | Search query string                  |
+| `options`           | object |          | Query options                        |
+| `options.filter`    | any    |          | MongoDB-style filter                 |
+| `options.numChunks` | number |          | Number of chunks to return           |
+| `options.minScore`  | number |          | Minimum similarity score (0-1)       |
+| `timeoutMs`         | number |          | Query timeout (default: 30000ms)     |
+
+## Return Value
+
+Returns `Promise<Document[]>` where each document contains:
+
+- `pageContent`: Text content of the document chunk
+- `metadata`: Associated metadata as key-value pairs
+
+## Examples
+
+### Basic Query
+
+```typescript
+const documents = await agent.getDocumentsFromDB('knowledge_base', 'How to handle refunds?');
+```
+
+### Query with Options
+
+```typescript
+const documents = await agent.getDocumentsFromDB(
+  'products',
+  'laptop specifications',
+  {
+    numChunks: 5, // Top 5 results
+    minScore: 0.7, // >70% similarity
+    filter: { category: 'electronics' },
+  },
+  10000, // 10 second timeout
+);
+```