@ai.ntellect/core 0.6.17 → 0.6.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.mocharc.json +1 -2
- package/README.md +123 -178
- package/dist/graph/controller.js +29 -6
- package/dist/graph/index.js +302 -62
- package/dist/index.js +21 -6
- package/dist/interfaces/index.js +15 -0
- package/dist/modules/agenda/adapters/node-cron/index.js +29 -0
- package/dist/modules/agenda/index.js +140 -0
- package/dist/{services/embedding.js → modules/embedding/adapters/ai/index.js} +24 -7
- package/dist/modules/embedding/index.js +59 -0
- package/dist/modules/memory/adapters/in-memory/index.js +210 -0
- package/dist/{memory → modules/memory}/adapters/meilisearch/index.js +97 -2
- package/dist/{memory → modules/memory}/adapters/redis/index.js +77 -15
- package/dist/modules/memory/index.js +103 -0
- package/dist/utils/{stringifiy-zod-schema.js → generate-action-schema.js} +5 -5
- package/graph/controller.ts +46 -35
- package/graph/index.ts +534 -102
- package/graph.ts +74 -0
- package/index.ts +25 -7
- package/interfaces/index.ts +353 -27
- package/modules/agenda/adapters/node-cron/index.ts +25 -0
- package/modules/agenda/index.ts +159 -0
- package/modules/embedding/adapters/ai/index.ts +42 -0
- package/modules/embedding/index.ts +45 -0
- package/modules/memory/adapters/in-memory/index.ts +203 -0
- package/{memory → modules/memory}/adapters/meilisearch/index.ts +114 -12
- package/modules/memory/adapters/redis/index.ts +164 -0
- package/modules/memory/index.ts +93 -0
- package/package.json +3 -1
- package/test/graph/index.test.ts +578 -0
- package/test/modules/agenda/node-cron.test.ts +286 -0
- package/test/modules/embedding/ai.test.ts +78 -0
- package/test/modules/memory/adapters/in-memory.test.ts +153 -0
- package/test/{memory → modules/memory}/adapters/meilisearch.test.ts +79 -75
- package/test/modules/memory/adapters/redis.test.ts +169 -0
- package/test/modules/memory/base.test.ts +230 -0
- package/test/services/agenda.test.ts +279 -280
- package/types/index.ts +93 -202
- package/utils/{stringifiy-zod-schema.ts → generate-action-schema.ts} +3 -3
- package/app/README.md +0 -36
- package/app/app/favicon.ico +0 -0
- package/app/app/globals.css +0 -21
- package/app/app/gun.ts +0 -0
- package/app/app/layout.tsx +0 -18
- package/app/app/page.tsx +0 -321
- package/app/eslint.config.mjs +0 -16
- package/app/next.config.ts +0 -7
- package/app/package-lock.json +0 -5912
- package/app/package.json +0 -31
- package/app/pnpm-lock.yaml +0 -4031
- package/app/postcss.config.mjs +0 -8
- package/app/public/file.svg +0 -1
- package/app/public/globe.svg +0 -1
- package/app/public/next.svg +0 -1
- package/app/public/vercel.svg +0 -1
- package/app/public/window.svg +0 -1
- package/app/tailwind.config.ts +0 -18
- package/app/tsconfig.json +0 -27
- package/dist/memory/index.js +0 -9
- package/dist/services/agenda.js +0 -115
- package/dist/services/queue.js +0 -142
- package/dist/utils/experimental-graph-rag.js +0 -152
- package/dist/utils/generate-object.js +0 -111
- package/dist/utils/inject-actions.js +0 -16
- package/dist/utils/queue-item-transformer.js +0 -24
- package/dist/utils/sanitize-results.js +0 -60
- package/memory/adapters/redis/index.ts +0 -103
- package/memory/index.ts +0 -22
- package/services/agenda.ts +0 -118
- package/services/embedding.ts +0 -26
- package/services/queue.ts +0 -145
- package/test/memory/adapters/redis.test.ts +0 -159
- package/test/memory/base.test.ts +0 -225
- package/test/services/queue.test.ts +0 -286
- package/utils/experimental-graph-rag.ts +0 -170
- package/utils/generate-object.ts +0 -117
- package/utils/inject-actions.ts +0 -19
- package/utils/queue-item-transformer.ts +0 -38
- package/utils/sanitize-results.ts +0 -66
package/.mocharc.json
CHANGED
package/README.md
CHANGED
@@ -1,247 +1,192 @@
|
|
1
|
-
#
|
1
|
+
# **@ai.ntellect/core Documentation**
|
2
2
|
|
3
|
-
|
3
|
+
## **1. Introduction**
|
4
4
|
|
5
|
-
|
5
|
+
The **`@ai.ntellect/core`** framework is a powerful tool designed to **model, execute, and manage dynamic interaction flows** using **graph structures**. Unlike traditional **Directed Acyclic Graphs (DAGs)**, this framework supports cycles, enabling nodes to be executed multiple times and allowing for loop-based workflows.
|
6
6
|
|
7
|
-
|
8
|
-
- 🧠 **Memory management**: Store and retrieve AI-related data with multiple storage adapters (Meilisearch, Redis)
|
9
|
-
- 🔍 **Embedding services**: Generate and compare text embeddings for semantic search and similarity matching
|
10
|
-
- ⏰ **Task scheduling**: Schedule and manage recurring tasks with cron expressions
|
7
|
+
### **Key Features**
|
11
8
|
|
12
|
-
|
9
|
+
- Dynamic workflow execution
|
10
|
+
- Cyclic and acyclic graph support
|
11
|
+
- Strong typing with Zod validation
|
12
|
+
- Event-driven architecture
|
13
|
+
- Built-in error handling and retries
|
14
|
+
- Conditional execution paths
|
15
|
+
- Parameter validation
|
16
|
+
- State management
|
13
17
|
|
14
|
-
|
15
|
-
npm install @ai.ntellect/core
|
16
|
-
```
|
18
|
+
### **Common Use Cases**
|
17
19
|
|
18
|
-
|
20
|
+
- **AI Agents**: Building conversational AI systems that can maintain context and make decisions
|
21
|
+
- **Transaction Processing**: Managing complex financial workflows with validation chains
|
22
|
+
- **Task Orchestration**: Coordinating multiple dependent operations
|
23
|
+
- **Decision Trees**: Implementing complex business logic with multiple branches
|
24
|
+
- **State Machines**: Managing application state transitions
|
25
|
+
- **Event Processing**: Handling and responding to system events
|
19
26
|
|
20
|
-
|
27
|
+
## **2. Core Concepts**
|
21
28
|
|
22
|
-
###
|
29
|
+
### **2.1 Graph Theory Foundation**
|
23
30
|
|
24
|
-
|
25
|
-
import { Graph, GraphContext } from "@ai.ntellect/core";
|
26
|
-
import { z } from "zod";
|
27
|
-
|
28
|
-
// Context Schema Definition
|
29
|
-
const contextSchema = z.object({
|
30
|
-
input: z.string(),
|
31
|
-
result: z.number().optional(),
|
32
|
-
error: z.string().optional(),
|
33
|
-
});
|
34
|
-
|
35
|
-
// Graph Creation
|
36
|
-
const workflow = new Graph("processWorkflow", {
|
37
|
-
name: "workflow",
|
38
|
-
nodes: [
|
39
|
-
{
|
40
|
-
name: "inputValidation",
|
41
|
-
execute: async (context) => {
|
42
|
-
if (context.input.length < 3) {
|
43
|
-
context.error = "Input too short";
|
44
|
-
}
|
45
|
-
},
|
46
|
-
next: ["processing"],
|
47
|
-
},
|
48
|
-
{
|
49
|
-
name: "processing",
|
50
|
-
condition: (context) => !context.error,
|
51
|
-
execute: async (context) => {
|
52
|
-
context.result = context.input.length;
|
53
|
-
},
|
54
|
-
next: ["finalValidation"],
|
55
|
-
},
|
56
|
-
{
|
57
|
-
name: "finalValidation",
|
58
|
-
execute: async (context) => {
|
59
|
-
if (context.result && context.result < 10) {
|
60
|
-
context.error = "Result too small";
|
61
|
-
}
|
62
|
-
},
|
63
|
-
},
|
64
|
-
],
|
65
|
-
initialContext: {
|
66
|
-
input: "",
|
67
|
-
result: undefined,
|
68
|
-
error: undefined,
|
69
|
-
},
|
70
|
-
validator: contextSchema,
|
71
|
-
globalErrorHandler: (error, context) => {
|
72
|
-
console.error("Global error:", error);
|
73
|
-
},
|
74
|
-
});
|
75
|
-
```
|
31
|
+
A directed graph in our framework is defined as **G = (V, E)** where:
|
76
32
|
|
77
|
-
|
33
|
+
- **V**: Set of nodes (vertices)
|
34
|
+
- **E**: Set of directed edges
|
78
35
|
|
79
|
-
|
36
|
+
Each node represents an executable action, and edges represent conditional transitions between actions.
|
80
37
|
|
81
|
-
|
38
|
+
#### Example Graph Structure:
|
82
39
|
|
83
|
-
```typescript
|
84
|
-
{
|
85
|
-
name: "conditionalNode",
|
86
|
-
// Execute the node only if the condition is met
|
87
|
-
condition: (context) => context.result > 10,
|
88
|
-
execute: async (context) => {
|
89
|
-
// Conditional logic
|
90
|
-
}
|
91
|
-
}
|
92
40
|
```
|
41
|
+
(ValidateInput) → (ProcessData) → (SaveResult)
|
42
|
+
↓ ↑
|
43
|
+
(RetryInput) ──────────────────────
|
44
|
+
```
|
45
|
+
|
46
|
+
### **2.2 Node Types**
|
93
47
|
|
94
|
-
|
48
|
+
#### **Basic Node**
|
95
49
|
|
96
50
|
```typescript
|
97
|
-
{
|
98
|
-
name: "
|
99
|
-
retry: {
|
100
|
-
// Maximum number of attempts
|
101
|
-
maxAttempts: 3,
|
102
|
-
// Delay between attempts
|
103
|
-
delay: 1000 // 1 second
|
104
|
-
},
|
51
|
+
const basicNode: Node<ContextType> = {
|
52
|
+
name: "processData",
|
105
53
|
execute: async (context) => {
|
106
|
-
//
|
54
|
+
// Process data
|
107
55
|
},
|
108
|
-
|
109
|
-
|
110
|
-
console.warn("Node error:", error);
|
111
|
-
}
|
112
|
-
}
|
56
|
+
next: ["saveResult"],
|
57
|
+
};
|
113
58
|
```
|
114
59
|
|
115
|
-
|
60
|
+
#### **Conditional Node**
|
116
61
|
|
117
62
|
```typescript
|
118
|
-
|
119
|
-
|
120
|
-
|
121
|
-
|
122
|
-
|
123
|
-
|
124
|
-
|
125
|
-
|
63
|
+
const conditionalNode: Node<ContextType> = {
|
64
|
+
name: "validateInput",
|
65
|
+
condition: (context) => context.isValid,
|
66
|
+
execute: async (context) => {
|
67
|
+
// Validation logic
|
68
|
+
},
|
69
|
+
next: ["processData"],
|
70
|
+
};
|
126
71
|
```
|
127
72
|
|
128
|
-
|
73
|
+
## **3. Advanced Features**
|
129
74
|
|
130
|
-
|
131
|
-
workflow.on("nodeCompleted", (data) => {
|
132
|
-
console.log(`Node ${data.nodeName} completed`);
|
133
|
-
});
|
75
|
+
### **3.1 Event-Driven Execution**
|
134
76
|
|
135
|
-
|
136
|
-
await workflow.emit("customEvent", {
|
137
|
-
additionalData: "value",
|
138
|
-
});
|
139
|
-
```
|
140
|
-
|
141
|
-
### 5. Dynamic graph modification
|
77
|
+
Nodes can respond to system events:
|
142
78
|
|
143
79
|
```typescript
|
144
|
-
|
145
|
-
|
146
|
-
|
80
|
+
const eventNode: Node<ContextType> = {
|
81
|
+
name: "handleUserInput",
|
82
|
+
events: ["userSubmitted"],
|
147
83
|
execute: async (context) => {
|
148
|
-
//
|
84
|
+
// Handle user input
|
149
85
|
},
|
150
|
-
}
|
151
|
-
|
152
|
-
// Remove nodes
|
153
|
-
workflow.removeNode("obsoleteNode");
|
86
|
+
};
|
154
87
|
```
|
155
88
|
|
156
|
-
###
|
89
|
+
### **3.2 Retry Mechanisms**
|
157
90
|
|
158
|
-
|
91
|
+
Built-in retry support for handling transient failures:
|
159
92
|
|
160
93
|
```typescript
|
161
|
-
const
|
162
|
-
|
163
|
-
|
164
|
-
|
165
|
-
|
166
|
-
}
|
167
|
-
|
168
|
-
|
169
|
-
|
170
|
-
|
171
|
-
});
|
94
|
+
const retryableNode: Node<ContextType> = {
|
95
|
+
name: "apiCall",
|
96
|
+
retry: {
|
97
|
+
maxAttempts: 3,
|
98
|
+
delay: 1000, // ms
|
99
|
+
},
|
100
|
+
execute: async (context) => {
|
101
|
+
// API call logic
|
102
|
+
},
|
103
|
+
};
|
172
104
|
```
|
173
105
|
|
174
|
-
##
|
106
|
+
## **4. Real-World Examples**
|
107
|
+
|
108
|
+
### **4.1 AI Agent Workflow**
|
175
109
|
|
176
110
|
```typescript
|
177
|
-
const
|
111
|
+
const aiAgentGraph = new Graph<AIContextType>("AIAgent", {
|
178
112
|
nodes: [
|
179
113
|
{
|
180
|
-
name: "
|
114
|
+
name: "analyzeInput",
|
181
115
|
execute: async (context) => {
|
182
|
-
context.
|
116
|
+
context.intent = await analyzeUserIntent(context.input);
|
183
117
|
},
|
184
|
-
next: ["
|
118
|
+
next: ["selectAction"],
|
185
119
|
},
|
186
120
|
{
|
187
|
-
name: "
|
188
|
-
condition: (context) => context.rawData.length > 0,
|
121
|
+
name: "selectAction",
|
189
122
|
execute: async (context) => {
|
190
|
-
context.
|
123
|
+
context.selectedAction = determineNextAction(context.intent);
|
191
124
|
},
|
192
|
-
next: ["
|
125
|
+
next: ["validateResponse"],
|
193
126
|
},
|
194
127
|
{
|
195
|
-
name: "
|
128
|
+
name: "generateResponse",
|
196
129
|
execute: async (context) => {
|
197
|
-
context.
|
130
|
+
context.response = await generateAIResponse(context);
|
198
131
|
},
|
199
|
-
next: ["
|
132
|
+
next: ["validateResponse"],
|
133
|
+
},
|
134
|
+
],
|
135
|
+
});
|
136
|
+
```
|
137
|
+
|
138
|
+
### **4.2 Transaction Processing**
|
139
|
+
|
140
|
+
```typescript
|
141
|
+
const transactionGraph = new Graph<TransactionContext>("TransactionProcessor", {
|
142
|
+
nodes: [
|
143
|
+
{
|
144
|
+
name: "validateFunds",
|
145
|
+
execute: async (context) => {
|
146
|
+
context.hasSufficientFunds = await checkBalance(context.amount);
|
147
|
+
},
|
148
|
+
next: ["processPayment"],
|
200
149
|
},
|
201
150
|
{
|
202
|
-
name: "
|
151
|
+
name: "processPayment",
|
152
|
+
retry: {
|
153
|
+
maxAttempts: 3,
|
154
|
+
delay: 1000,
|
155
|
+
},
|
156
|
+
condition: (context) => context.hasSufficientFunds,
|
203
157
|
execute: async (context) => {
|
204
|
-
await
|
158
|
+
await processPayment(context.transactionData);
|
205
159
|
},
|
160
|
+
next: ["notifyUser"],
|
206
161
|
},
|
207
162
|
],
|
208
163
|
});
|
209
164
|
```
|
210
165
|
|
211
|
-
##
|
166
|
+
## **5. Event Listeners**
|
212
167
|
|
213
|
-
|
214
|
-
|
215
|
-
|
216
|
-
|
217
|
-
|
218
|
-
## GraphController: Advanced execution strategies
|
168
|
+
```typescript
|
169
|
+
graph.on("nodeStarted", ({ name, context }) => {
|
170
|
+
console.log(`Node ${name} started with context:`, context);
|
171
|
+
});
|
219
172
|
|
220
|
-
|
173
|
+
graph.on("nodeCompleted", ({ name, context }) => {
|
174
|
+
console.log(`Node ${name} completed with context:`, context);
|
175
|
+
});
|
221
176
|
|
222
|
-
|
223
|
-
|
224
|
-
|
225
|
-
["startNode1", "startNode2"],
|
226
|
-
[context1, context2]
|
227
|
-
);
|
177
|
+
graph.on("nodeError", ({ name, error }) => {
|
178
|
+
console.error(`Error in node ${name}:`, error);
|
179
|
+
});
|
228
180
|
```
|
229
181
|
|
230
|
-
|
182
|
+
## **6. Future Developments**
|
231
183
|
|
232
|
-
|
233
|
-
const parallelResults = await GraphController.executeParallel(
|
234
|
-
multipleGraphs,
|
235
|
-
startNodes,
|
236
|
-
inputContexts,
|
237
|
-
inputParams,
|
238
|
-
3 // Maximum 3 graphs executing simultaneously
|
239
|
-
);
|
240
|
-
```
|
184
|
+
Planned features include:
|
241
185
|
|
242
|
-
|
186
|
+
- Advanced memory management for AI agents
|
187
|
+
- Graph composition and nesting
|
188
|
+
- Real-time monitoring dashboard
|
189
|
+
- Performance analytics
|
190
|
+
- Distributed execution support
|
243
191
|
|
244
|
-
|
245
|
-
- Implement appropriate concurrency limits
|
246
|
-
- Monitor context size and complexity
|
247
|
-
- Leverage Zod for efficient runtime validation
|
192
|
+
For more information and updates, visit the official documentation or join our community discussions.
|
package/dist/graph/controller.js
CHANGED
@@ -10,7 +10,19 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
|
|
10
10
|
};
|
11
11
|
Object.defineProperty(exports, "__esModule", { value: true });
|
12
12
|
exports.GraphController = void 0;
|
13
|
+
/**
|
14
|
+
* Controller class for managing the execution of graph flows
|
15
|
+
* Handles both sequential and parallel execution of multiple graphs
|
16
|
+
*/
|
13
17
|
class GraphController {
|
18
|
+
/**
|
19
|
+
* Executes multiple graphs sequentially
|
20
|
+
* @param graphs - Array of GraphFlow instances to execute
|
21
|
+
* @param startNodes - Array of starting node identifiers for each graph
|
22
|
+
* @param inputContexts - Optional array of initial contexts for each graph
|
23
|
+
* @returns Map containing results of each graph execution, keyed by graph name and index
|
24
|
+
* @template T - Zod schema type for graph context validation
|
25
|
+
*/
|
14
26
|
static executeSequential(graphs, startNodes, inputContexts) {
|
15
27
|
return __awaiter(this, void 0, void 0, function* () {
|
16
28
|
const results = new Map();
|
@@ -21,26 +33,37 @@ class GraphController {
|
|
21
33
|
return results;
|
22
34
|
});
|
23
35
|
}
|
24
|
-
|
36
|
+
/**
|
37
|
+
* Executes multiple graphs in parallel with optional concurrency control
|
38
|
+
* @param graphs - Array of GraphFlow instances to execute
|
39
|
+
* @param startNodes - Array of starting node identifiers for each graph
|
40
|
+
* @param inputContexts - Optional array of initial contexts for each graph
|
41
|
+
* @param inputs - Optional array of additional inputs for each graph
|
42
|
+
* @param concurrencyLimit - Optional limit on number of concurrent graph executions
|
43
|
+
* @returns Map containing results of each graph execution, keyed by graph name
|
44
|
+
* @template T - Zod schema type for graph context validation
|
45
|
+
*/
|
46
|
+
static executeParallel(graphs, startNodes, inputContexts, inputs, concurrencyLimit) {
|
25
47
|
return __awaiter(this, void 0, void 0, function* () {
|
26
48
|
const results = new Map();
|
27
49
|
if (inputContexts) {
|
28
50
|
inputContexts = inputContexts.map((ctx) => ctx || {});
|
29
51
|
}
|
30
|
-
if (
|
31
|
-
|
52
|
+
if (inputs) {
|
53
|
+
inputs = inputs.map((input) => input || {});
|
32
54
|
}
|
33
55
|
if (concurrencyLimit) {
|
34
56
|
for (let i = 0; i < graphs.length; i += concurrencyLimit) {
|
35
|
-
const batchResults = yield Promise.all(graphs
|
36
|
-
|
57
|
+
const batchResults = yield Promise.all(graphs
|
58
|
+
.slice(i, i + concurrencyLimit)
|
59
|
+
.map((graph, index) => graph.execute(startNodes[i + index], (inputContexts === null || inputContexts === void 0 ? void 0 : inputContexts[i + index]) || {}, inputs === null || inputs === void 0 ? void 0 : inputs[i + index])));
|
37
60
|
batchResults.forEach((result, index) => {
|
38
61
|
results.set(`${graphs[i + index].name}`, result);
|
39
62
|
});
|
40
63
|
}
|
41
64
|
}
|
42
65
|
else {
|
43
|
-
const allResults = yield Promise.all(graphs.map((graph, index) => graph.execute(startNodes[index], (inputContexts === null || inputContexts === void 0 ? void 0 : inputContexts[index]) || {}, (
|
66
|
+
const allResults = yield Promise.all(graphs.map((graph, index) => graph.execute(startNodes[index], (inputContexts === null || inputContexts === void 0 ? void 0 : inputContexts[index]) || {}, (inputs === null || inputs === void 0 ? void 0 : inputs[index]) || {})));
|
44
67
|
allResults.forEach((result, index) => {
|
45
68
|
results.set(`${graphs[index].name}`, result);
|
46
69
|
});
|