@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.
Files changed (79) hide show
  1. package/.mocharc.json +1 -2
  2. package/README.md +123 -178
  3. package/dist/graph/controller.js +29 -6
  4. package/dist/graph/index.js +302 -62
  5. package/dist/index.js +21 -6
  6. package/dist/interfaces/index.js +15 -0
  7. package/dist/modules/agenda/adapters/node-cron/index.js +29 -0
  8. package/dist/modules/agenda/index.js +140 -0
  9. package/dist/{services/embedding.js → modules/embedding/adapters/ai/index.js} +24 -7
  10. package/dist/modules/embedding/index.js +59 -0
  11. package/dist/modules/memory/adapters/in-memory/index.js +210 -0
  12. package/dist/{memory → modules/memory}/adapters/meilisearch/index.js +97 -2
  13. package/dist/{memory → modules/memory}/adapters/redis/index.js +77 -15
  14. package/dist/modules/memory/index.js +103 -0
  15. package/dist/utils/{stringifiy-zod-schema.js → generate-action-schema.js} +5 -5
  16. package/graph/controller.ts +46 -35
  17. package/graph/index.ts +534 -102
  18. package/graph.ts +74 -0
  19. package/index.ts +25 -7
  20. package/interfaces/index.ts +353 -27
  21. package/modules/agenda/adapters/node-cron/index.ts +25 -0
  22. package/modules/agenda/index.ts +159 -0
  23. package/modules/embedding/adapters/ai/index.ts +42 -0
  24. package/modules/embedding/index.ts +45 -0
  25. package/modules/memory/adapters/in-memory/index.ts +203 -0
  26. package/{memory → modules/memory}/adapters/meilisearch/index.ts +114 -12
  27. package/modules/memory/adapters/redis/index.ts +164 -0
  28. package/modules/memory/index.ts +93 -0
  29. package/package.json +3 -1
  30. package/test/graph/index.test.ts +578 -0
  31. package/test/modules/agenda/node-cron.test.ts +286 -0
  32. package/test/modules/embedding/ai.test.ts +78 -0
  33. package/test/modules/memory/adapters/in-memory.test.ts +153 -0
  34. package/test/{memory → modules/memory}/adapters/meilisearch.test.ts +79 -75
  35. package/test/modules/memory/adapters/redis.test.ts +169 -0
  36. package/test/modules/memory/base.test.ts +230 -0
  37. package/test/services/agenda.test.ts +279 -280
  38. package/types/index.ts +93 -202
  39. package/utils/{stringifiy-zod-schema.ts → generate-action-schema.ts} +3 -3
  40. package/app/README.md +0 -36
  41. package/app/app/favicon.ico +0 -0
  42. package/app/app/globals.css +0 -21
  43. package/app/app/gun.ts +0 -0
  44. package/app/app/layout.tsx +0 -18
  45. package/app/app/page.tsx +0 -321
  46. package/app/eslint.config.mjs +0 -16
  47. package/app/next.config.ts +0 -7
  48. package/app/package-lock.json +0 -5912
  49. package/app/package.json +0 -31
  50. package/app/pnpm-lock.yaml +0 -4031
  51. package/app/postcss.config.mjs +0 -8
  52. package/app/public/file.svg +0 -1
  53. package/app/public/globe.svg +0 -1
  54. package/app/public/next.svg +0 -1
  55. package/app/public/vercel.svg +0 -1
  56. package/app/public/window.svg +0 -1
  57. package/app/tailwind.config.ts +0 -18
  58. package/app/tsconfig.json +0 -27
  59. package/dist/memory/index.js +0 -9
  60. package/dist/services/agenda.js +0 -115
  61. package/dist/services/queue.js +0 -142
  62. package/dist/utils/experimental-graph-rag.js +0 -152
  63. package/dist/utils/generate-object.js +0 -111
  64. package/dist/utils/inject-actions.js +0 -16
  65. package/dist/utils/queue-item-transformer.js +0 -24
  66. package/dist/utils/sanitize-results.js +0 -60
  67. package/memory/adapters/redis/index.ts +0 -103
  68. package/memory/index.ts +0 -22
  69. package/services/agenda.ts +0 -118
  70. package/services/embedding.ts +0 -26
  71. package/services/queue.ts +0 -145
  72. package/test/memory/adapters/redis.test.ts +0 -159
  73. package/test/memory/base.test.ts +0 -225
  74. package/test/services/queue.test.ts +0 -286
  75. package/utils/experimental-graph-rag.ts +0 -170
  76. package/utils/generate-object.ts +0 -117
  77. package/utils/inject-actions.ts +0 -19
  78. package/utils/queue-item-transformer.ts +0 -38
  79. package/utils/sanitize-results.ts +0 -66
package/.mocharc.json CHANGED
@@ -1,5 +1,4 @@
1
1
  {
2
2
  "extension": ["ts"],
3
- "spec": "test/**/*.test.ts",
4
- "require": ["ts-node/register", "tsconfig-paths/register"]
3
+ "require": ["ts-node/register"]
5
4
  }
package/README.md CHANGED
@@ -1,247 +1,192 @@
1
- # @ai.ntellect/core
1
+ # **@ai.ntellect/core Documentation**
2
2
 
3
- A powerful framework for building AI-powered applications with graph-based workflows, memory management, and embedding services.
3
+ ## **1. Introduction**
4
4
 
5
- ## Features
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
- - 🔄 **Graph-based workflow engine**: Build complex, type-safe workflows with retry mechanisms and error handling
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
- ## Installation
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
- ```bash
15
- npm install @ai.ntellect/core
16
- ```
18
+ ### **Common Use Cases**
17
19
 
18
- ## Core components
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
- The Graph system is the heart of the framework, enabling dynamic and highly flexible workflows.
27
+ ## **2. Core Concepts**
21
28
 
22
- ### Basic graph structure
29
+ ### **2.1 Graph Theory Foundation**
23
30
 
24
- ```typescript
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
- ## Advanced graph features
33
+ - **V**: Set of nodes (vertices)
34
+ - **E**: Set of directed edges
78
35
 
79
- ### 1. Nodes with conditions
36
+ Each node represents an executable action, and edges represent conditional transitions between actions.
80
37
 
81
- Add sophisticated conditions for node execution:
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
- ### 2. Error handling
48
+ #### **Basic Node**
95
49
 
96
50
  ```typescript
97
- {
98
- name: "unreliableOperation",
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
- // Potentially unstable operation
54
+ // Process data
107
55
  },
108
- // Node-specific error handler
109
- onError: (error) => {
110
- console.warn("Node error:", error);
111
- }
112
- }
56
+ next: ["saveResult"],
57
+ };
113
58
  ```
114
59
 
115
- ### 3. Dynamic and parallel execution
60
+ #### **Conditional Node**
116
61
 
117
62
  ```typescript
118
- // Execute multiple graphs in parallel
119
- const results = await GraphController.executeParallel(
120
- [graph1, graph2, graph3],
121
- ["startNode1", "startNode2", "startNode3"],
122
- [context1, context2, context3],
123
- undefined, // parameters
124
- 3 // concurrency limit
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
- ### 4. Events
73
+ ## **3. Advanced Features**
129
74
 
130
- ```typescript
131
- workflow.on("nodeCompleted", (data) => {
132
- console.log(`Node ${data.nodeName} completed`);
133
- });
75
+ ### **3.1 Event-Driven Execution**
134
76
 
135
- // Emit custom events
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
- // Dynamically add nodes
145
- workflow.addNode({
146
- name: "newNode",
80
+ const eventNode: Node<ContextType> = {
81
+ name: "handleUserInput",
82
+ events: ["userSubmitted"],
147
83
  execute: async (context) => {
148
- // New logic
84
+ // Handle user input
149
85
  },
150
- });
151
-
152
- // Remove nodes
153
- workflow.removeNode("obsoleteNode");
86
+ };
154
87
  ```
155
88
 
156
- ### 6. Context validation with Zod
89
+ ### **3.2 Retry Mechanisms**
157
90
 
158
- Use Zod for runtime context validation:
91
+ Built-in retry support for handling transient failures:
159
92
 
160
93
  ```typescript
161
- const strictContextSchema = z.object({
162
- // Define precise rules
163
- input: z.string().min(3).max(100),
164
- result: z.number().positive(),
165
- timestamp: z.date(),
166
- });
167
-
168
- const workflow = new Graph("strictWorkflow", {
169
- // The validator will check each context modification
170
- validator: strictContextSchema,
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
- ## Complete example: Data processing workflow
106
+ ## **4. Real-World Examples**
107
+
108
+ ### **4.1 AI Agent Workflow**
175
109
 
176
110
  ```typescript
177
- const dataProcessingWorkflow = new Graph("dataProcessor", {
111
+ const aiAgentGraph = new Graph<AIContextType>("AIAgent", {
178
112
  nodes: [
179
113
  {
180
- name: "dataFetch",
114
+ name: "analyzeInput",
181
115
  execute: async (context) => {
182
- context.rawData = await fetchData();
116
+ context.intent = await analyzeUserIntent(context.input);
183
117
  },
184
- next: ["dataValidation"],
118
+ next: ["selectAction"],
185
119
  },
186
120
  {
187
- name: "dataValidation",
188
- condition: (context) => context.rawData.length > 0,
121
+ name: "selectAction",
189
122
  execute: async (context) => {
190
- context.validatedData = validateData(context.rawData);
123
+ context.selectedAction = determineNextAction(context.intent);
191
124
  },
192
- next: ["dataTransformation"],
125
+ next: ["validateResponse"],
193
126
  },
194
127
  {
195
- name: "dataTransformation",
128
+ name: "generateResponse",
196
129
  execute: async (context) => {
197
- context.processedData = transformData(context.validatedData);
130
+ context.response = await generateAIResponse(context);
198
131
  },
199
- next: ["dataStorage"],
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: "dataStorage",
151
+ name: "processPayment",
152
+ retry: {
153
+ maxAttempts: 3,
154
+ delay: 1000,
155
+ },
156
+ condition: (context) => context.hasSufficientFunds,
203
157
  execute: async (context) => {
204
- await storeData(context.processedData);
158
+ await processPayment(context.transactionData);
205
159
  },
160
+ next: ["notifyUser"],
206
161
  },
207
162
  ],
208
163
  });
209
164
  ```
210
165
 
211
- ## Key points
166
+ ## **5. Event Listeners**
212
167
 
213
- - **Total flexibility**: Create complex workflows with great freedom
214
- - **Type safety**: Runtime context and parameter validation
215
- - **Dynamic management**: Modify graphs during execution
216
- - **Resilience**: Integrated retry and error handling mechanisms
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
- ### Sequential execution
173
+ graph.on("nodeCompleted", ({ name, context }) => {
174
+ console.log(`Node ${name} completed with context:`, context);
175
+ });
221
176
 
222
- ```typescript
223
- const sequentialResults = await GraphController.executeSequential(
224
- [graph1, graph2],
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
- ### Parallel execution with concurrency control
182
+ ## **6. Future Developments**
231
183
 
232
- ```typescript
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
- ## Performance considerations
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
- - Use `executeParallel` for independent workflows
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.
@@ -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
- static executeParallel(graphs, startNodes, inputContexts, inputParams, concurrencyLimit) {
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 (inputParams) {
31
- inputParams = inputParams.map((params) => params || {});
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.slice(i, i + concurrencyLimit).map((graph, index) => graph.execute(startNodes[i + index], (inputContexts === null || inputContexts === void 0 ? void 0 : inputContexts[i + index]) || {}, (inputParams === null || inputParams === void 0 ? void 0 : inputParams[i + index]) || {} // ✅ Passe bien les paramètres
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]) || {}, (inputParams === null || inputParams === void 0 ? void 0 : inputParams[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
  });