@falai/agent 0.6.3 → 0.6.4

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 (128) hide show
  1. package/README.md +89 -29
  2. package/dist/cjs/constants/index.d.ts +6 -1
  3. package/dist/cjs/constants/index.d.ts.map +1 -1
  4. package/dist/cjs/constants/index.js +8 -3
  5. package/dist/cjs/constants/index.js.map +1 -1
  6. package/dist/cjs/core/Agent.d.ts +22 -0
  7. package/dist/cjs/core/Agent.d.ts.map +1 -1
  8. package/dist/cjs/core/Agent.js +108 -21
  9. package/dist/cjs/core/Agent.js.map +1 -1
  10. package/dist/cjs/core/Events.d.ts +13 -0
  11. package/dist/cjs/core/Events.d.ts.map +1 -1
  12. package/dist/cjs/core/Events.js +28 -14
  13. package/dist/cjs/core/Events.js.map +1 -1
  14. package/dist/cjs/core/Route.d.ts.map +1 -1
  15. package/dist/cjs/core/Route.js +4 -4
  16. package/dist/cjs/core/Route.js.map +1 -1
  17. package/dist/cjs/core/RoutingEngine.d.ts +6 -1
  18. package/dist/cjs/core/RoutingEngine.d.ts.map +1 -1
  19. package/dist/cjs/core/RoutingEngine.js +112 -37
  20. package/dist/cjs/core/RoutingEngine.js.map +1 -1
  21. package/dist/cjs/core/State.d.ts +15 -5
  22. package/dist/cjs/core/State.d.ts.map +1 -1
  23. package/dist/cjs/core/State.js +24 -5
  24. package/dist/cjs/core/State.js.map +1 -1
  25. package/dist/cjs/core/Tool.d.ts +8 -1
  26. package/dist/cjs/core/Tool.d.ts.map +1 -1
  27. package/dist/cjs/core/Tool.js +25 -28
  28. package/dist/cjs/core/Tool.js.map +1 -1
  29. package/dist/cjs/core/Transition.js +1 -1
  30. package/dist/cjs/index.d.ts +1 -1
  31. package/dist/cjs/index.d.ts.map +1 -1
  32. package/dist/cjs/index.js +3 -2
  33. package/dist/cjs/index.js.map +1 -1
  34. package/dist/cjs/types/agent.d.ts +5 -0
  35. package/dist/cjs/types/agent.d.ts.map +1 -1
  36. package/dist/cjs/types/agent.js.map +1 -1
  37. package/dist/cjs/types/route.d.ts +7 -1
  38. package/dist/cjs/types/route.d.ts.map +1 -1
  39. package/dist/cjs/types/session.d.ts +12 -1
  40. package/dist/cjs/types/session.d.ts.map +1 -1
  41. package/dist/cjs/types/session.js +26 -5
  42. package/dist/cjs/types/session.js.map +1 -1
  43. package/dist/cjs/utils/logger.d.ts +10 -0
  44. package/dist/cjs/utils/logger.d.ts.map +1 -0
  45. package/dist/cjs/utils/logger.js +23 -0
  46. package/dist/cjs/utils/logger.js.map +1 -0
  47. package/dist/constants/index.d.ts +6 -1
  48. package/dist/constants/index.d.ts.map +1 -1
  49. package/dist/constants/index.js +6 -1
  50. package/dist/constants/index.js.map +1 -1
  51. package/dist/core/Agent.d.ts +22 -0
  52. package/dist/core/Agent.d.ts.map +1 -1
  53. package/dist/core/Agent.js +108 -21
  54. package/dist/core/Agent.js.map +1 -1
  55. package/dist/core/Events.d.ts +13 -0
  56. package/dist/core/Events.d.ts.map +1 -1
  57. package/dist/core/Events.js +28 -14
  58. package/dist/core/Events.js.map +1 -1
  59. package/dist/core/Route.d.ts.map +1 -1
  60. package/dist/core/Route.js +4 -4
  61. package/dist/core/Route.js.map +1 -1
  62. package/dist/core/RoutingEngine.d.ts +6 -1
  63. package/dist/core/RoutingEngine.d.ts.map +1 -1
  64. package/dist/core/RoutingEngine.js +112 -37
  65. package/dist/core/RoutingEngine.js.map +1 -1
  66. package/dist/core/State.d.ts +15 -5
  67. package/dist/core/State.d.ts.map +1 -1
  68. package/dist/core/State.js +25 -6
  69. package/dist/core/State.js.map +1 -1
  70. package/dist/core/Tool.d.ts +8 -1
  71. package/dist/core/Tool.d.ts.map +1 -1
  72. package/dist/core/Tool.js +25 -28
  73. package/dist/core/Tool.js.map +1 -1
  74. package/dist/core/Transition.js +1 -1
  75. package/dist/index.d.ts +1 -1
  76. package/dist/index.d.ts.map +1 -1
  77. package/dist/index.js +1 -1
  78. package/dist/index.js.map +1 -1
  79. package/dist/types/agent.d.ts +5 -0
  80. package/dist/types/agent.d.ts.map +1 -1
  81. package/dist/types/agent.js.map +1 -1
  82. package/dist/types/route.d.ts +7 -1
  83. package/dist/types/route.d.ts.map +1 -1
  84. package/dist/types/session.d.ts +12 -1
  85. package/dist/types/session.d.ts.map +1 -1
  86. package/dist/types/session.js +26 -5
  87. package/dist/types/session.js.map +1 -1
  88. package/dist/utils/logger.d.ts +10 -0
  89. package/dist/utils/logger.d.ts.map +1 -0
  90. package/dist/utils/logger.js +17 -0
  91. package/dist/utils/logger.js.map +1 -0
  92. package/docs/{CONSTRUCTOR_OPTIONS.md → AGENT.md} +79 -7
  93. package/docs/API_REFERENCE.md +309 -18
  94. package/docs/ARCHITECTURE.md +1 -1
  95. package/docs/DOCS.md +46 -22
  96. package/docs/GETTING_STARTED.md +1 -1
  97. package/docs/README.md +13 -5
  98. package/docs/ROUTES.md +743 -0
  99. package/docs/STATES.md +798 -0
  100. package/examples/business-onboarding.ts +46 -5
  101. package/examples/company-qna-agent.ts +107 -1
  102. package/examples/custom-database-persistence.ts +44 -1
  103. package/examples/declarative-agent.ts +80 -37
  104. package/examples/domain-scoping.ts +91 -21
  105. package/examples/extracted-data-modification.ts +64 -2
  106. package/examples/healthcare-agent.ts +61 -4
  107. package/examples/openai-agent.ts +24 -2
  108. package/examples/opensearch-persistence.ts +26 -1
  109. package/examples/persistent-onboarding.ts +84 -18
  110. package/examples/prisma-persistence.ts +90 -16
  111. package/examples/redis-persistence.ts +89 -17
  112. package/examples/rules-prohibitions.ts +300 -139
  113. package/examples/streaming-agent.ts +60 -0
  114. package/examples/travel-agent.ts +66 -24
  115. package/package.json +3 -2
  116. package/src/constants/index.ts +6 -1
  117. package/src/core/Agent.ts +135 -21
  118. package/src/core/Events.ts +73 -10
  119. package/src/core/Route.ts +8 -4
  120. package/src/core/RoutingEngine.ts +150 -39
  121. package/src/core/State.ts +35 -10
  122. package/src/core/Tool.ts +67 -10
  123. package/src/core/Transition.ts +1 -1
  124. package/src/index.ts +1 -1
  125. package/src/types/agent.ts +5 -0
  126. package/src/types/route.ts +10 -1
  127. package/src/types/session.ts +42 -6
  128. package/src/utils/logger.ts +19 -0
@@ -24,9 +24,19 @@ export interface SessionState<TExtracted = Record<string, unknown>> {
24
24
  enteredAt: Date;
25
25
  };
26
26
 
27
- /** Data extracted during the current route */
27
+ /**
28
+ * Data extracted during the current route
29
+ * This is a convenience reference to extractedByRoute[currentRoute.id]
30
+ */
28
31
  extracted: Partial<TExtracted>;
29
32
 
33
+ /**
34
+ * Extracted data organized by route ID
35
+ * Preserves data when switching between routes
36
+ * Format: { "routeId": { ...extractedData } }
37
+ */
38
+ extractedByRoute: Record<string, Partial<unknown>>;
39
+
30
40
  /** History of routes visited in this session */
31
41
  routeHistory: Array<{
32
42
  routeId: string;
@@ -55,6 +65,7 @@ export function createSession<TExtracted = Record<string, unknown>>(
55
65
  return {
56
66
  id: sessionId,
57
67
  extracted: {},
68
+ extractedByRoute: {},
58
69
  routeHistory: [],
59
70
  metadata: {
60
71
  ...metadata,
@@ -66,12 +77,19 @@ export function createSession<TExtracted = Record<string, unknown>>(
66
77
 
67
78
  /**
68
79
  * Helper to update session with new route
80
+ * Preserves extracted data per route in extractedByRoute map
69
81
  */
70
82
  export function enterRoute<TExtracted = Record<string, unknown>>(
71
83
  session: SessionState<TExtracted>,
72
84
  routeId: string,
73
85
  routeTitle: string
74
86
  ): SessionState<TExtracted> {
87
+ // Save current route's extracted data before switching
88
+ const extractedByRoute = { ...session.extractedByRoute };
89
+ if (session.currentRoute && Object.keys(session.extracted).length > 0) {
90
+ extractedByRoute[session.currentRoute.id] = session.extracted;
91
+ }
92
+
75
93
  // Exit current route if exists
76
94
  const routeHistory = [...session.routeHistory];
77
95
  if (session.currentRoute) {
@@ -83,6 +101,9 @@ export function enterRoute<TExtracted = Record<string, unknown>>(
83
101
  }
84
102
  }
85
103
 
104
+ // Load extracted data for new route (if resuming) or start fresh
105
+ const newExtracted = (extractedByRoute[routeId] as Partial<TExtracted>) || {};
106
+
86
107
  // Enter new route
87
108
  const now = new Date();
88
109
  return {
@@ -93,7 +114,8 @@ export function enterRoute<TExtracted = Record<string, unknown>>(
93
114
  enteredAt: now,
94
115
  },
95
116
  currentState: undefined,
96
- extracted: {}, // Reset extracted data for new route
117
+ extracted: newExtracted, // Load route's data or start fresh
118
+ extractedByRoute,
97
119
  routeHistory: [
98
120
  ...routeHistory,
99
121
  {
@@ -133,17 +155,27 @@ export function enterState<TExtracted = Record<string, unknown>>(
133
155
 
134
156
  /**
135
157
  * Helper to merge extracted data into session
158
+ * Updates both the extracted field and the extractedByRoute map
136
159
  */
137
160
  export function mergeExtracted<TExtracted = Record<string, unknown>>(
138
161
  session: SessionState<TExtracted>,
139
162
  extracted: Partial<TExtracted>
140
163
  ): SessionState<TExtracted> {
164
+ const newExtracted = {
165
+ ...session.extracted,
166
+ ...extracted,
167
+ };
168
+
169
+ // Also update the extractedByRoute map for the current route
170
+ const extractedByRoute = { ...session.extractedByRoute };
171
+ if (session.currentRoute) {
172
+ extractedByRoute[session.currentRoute.id] = newExtracted;
173
+ }
174
+
141
175
  return {
142
176
  ...session,
143
- extracted: {
144
- ...session.extracted,
145
- ...extracted,
146
- },
177
+ extracted: newExtracted,
178
+ extractedByRoute,
147
179
  metadata: {
148
180
  ...session.metadata,
149
181
  lastUpdatedAt: new Date(),
@@ -167,6 +199,7 @@ export function sessionStateToData<TExtracted = Record<string, unknown>>(
167
199
  currentState: session.currentState?.id,
168
200
  collectedData: {
169
201
  extracted: session.extracted,
202
+ extractedByRoute: session.extractedByRoute, // Include per-route data
170
203
  routeHistory: session.routeHistory,
171
204
  currentRouteTitle: session.currentRoute?.title,
172
205
  currentStateDescription: session.currentState?.description,
@@ -210,6 +243,9 @@ export function sessionDataToState<TExtracted = Record<string, unknown>>(
210
243
  }
211
244
  : undefined,
212
245
  extracted: (collectedData.extracted as Partial<TExtracted>) || {},
246
+ extractedByRoute:
247
+ (collectedData.extractedByRoute as Record<string, Partial<unknown>>) ||
248
+ {}, // Restore per-route data
213
249
  routeHistory:
214
250
  (collectedData.routeHistory as SessionState<TExtracted>["routeHistory"]) ||
215
251
  [],
@@ -0,0 +1,19 @@
1
+ import log from "loglevel";
2
+
3
+ export enum LoggerLevel {
4
+ DEBUG = "debug",
5
+ INFO = "info",
6
+ WARN = "warn",
7
+ ERROR = "error",
8
+ SILENT = "silent",
9
+ }
10
+
11
+ /**
12
+ * Default log level
13
+ */
14
+ const DEFAULT_LOG_LEVEL = LoggerLevel.SILENT;
15
+
16
+ // Initialize logger
17
+ log.setLevel(DEFAULT_LOG_LEVEL);
18
+
19
+ export const logger = log;