@falai/agent 0.6.9 → 0.8.0

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 (242) hide show
  1. package/README.md +78 -82
  2. package/dist/adapters/MemoryAdapter.d.ts +1 -1
  3. package/dist/adapters/MemoryAdapter.js +3 -3
  4. package/dist/adapters/MemoryAdapter.js.map +1 -1
  5. package/dist/adapters/MongoAdapter.d.ts +1 -1
  6. package/dist/adapters/MongoAdapter.js +3 -3
  7. package/dist/adapters/MongoAdapter.js.map +1 -1
  8. package/dist/adapters/OpenSearchAdapter.js +7 -7
  9. package/dist/adapters/OpenSearchAdapter.js.map +1 -1
  10. package/dist/adapters/PostgreSQLAdapter.d.ts +1 -1
  11. package/dist/adapters/PostgreSQLAdapter.js +10 -10
  12. package/dist/adapters/PostgreSQLAdapter.js.map +1 -1
  13. package/dist/adapters/PrismaAdapter.d.ts +1 -1
  14. package/dist/adapters/PrismaAdapter.js +4 -4
  15. package/dist/adapters/PrismaAdapter.js.map +1 -1
  16. package/dist/adapters/RedisAdapter.d.ts +1 -1
  17. package/dist/adapters/RedisAdapter.js +3 -3
  18. package/dist/adapters/RedisAdapter.js.map +1 -1
  19. package/dist/adapters/SQLiteAdapter.d.ts +4 -4
  20. package/dist/adapters/SQLiteAdapter.d.ts.map +1 -1
  21. package/dist/adapters/SQLiteAdapter.js +12 -12
  22. package/dist/adapters/SQLiteAdapter.js.map +1 -1
  23. package/dist/adapters/index.d.ts +1 -1
  24. package/dist/adapters/index.d.ts.map +1 -1
  25. package/dist/cjs/adapters/MemoryAdapter.d.ts +1 -1
  26. package/dist/cjs/adapters/MemoryAdapter.js +3 -3
  27. package/dist/cjs/adapters/MemoryAdapter.js.map +1 -1
  28. package/dist/cjs/adapters/MongoAdapter.d.ts +1 -1
  29. package/dist/cjs/adapters/MongoAdapter.js +3 -3
  30. package/dist/cjs/adapters/MongoAdapter.js.map +1 -1
  31. package/dist/cjs/adapters/OpenSearchAdapter.js +7 -7
  32. package/dist/cjs/adapters/OpenSearchAdapter.js.map +1 -1
  33. package/dist/cjs/adapters/PostgreSQLAdapter.d.ts +1 -1
  34. package/dist/cjs/adapters/PostgreSQLAdapter.js +10 -10
  35. package/dist/cjs/adapters/PostgreSQLAdapter.js.map +1 -1
  36. package/dist/cjs/adapters/PrismaAdapter.d.ts +1 -1
  37. package/dist/cjs/adapters/PrismaAdapter.js +4 -4
  38. package/dist/cjs/adapters/PrismaAdapter.js.map +1 -1
  39. package/dist/cjs/adapters/RedisAdapter.d.ts +1 -1
  40. package/dist/cjs/adapters/RedisAdapter.js +3 -3
  41. package/dist/cjs/adapters/RedisAdapter.js.map +1 -1
  42. package/dist/cjs/adapters/SQLiteAdapter.d.ts +4 -4
  43. package/dist/cjs/adapters/SQLiteAdapter.d.ts.map +1 -1
  44. package/dist/cjs/adapters/SQLiteAdapter.js +12 -12
  45. package/dist/cjs/adapters/SQLiteAdapter.js.map +1 -1
  46. package/dist/cjs/adapters/index.d.ts +1 -1
  47. package/dist/cjs/adapters/index.d.ts.map +1 -1
  48. package/dist/cjs/constants/index.d.ts +4 -4
  49. package/dist/cjs/constants/index.js +5 -5
  50. package/dist/cjs/core/Agent.d.ts +22 -22
  51. package/dist/cjs/core/Agent.d.ts.map +1 -1
  52. package/dist/cjs/core/Agent.js +168 -160
  53. package/dist/cjs/core/Agent.js.map +1 -1
  54. package/dist/cjs/core/Events.d.ts +6 -6
  55. package/dist/cjs/core/Events.d.ts.map +1 -1
  56. package/dist/cjs/core/PersistenceManager.d.ts +13 -13
  57. package/dist/cjs/core/PersistenceManager.d.ts.map +1 -1
  58. package/dist/cjs/core/PersistenceManager.js +24 -24
  59. package/dist/cjs/core/PersistenceManager.js.map +1 -1
  60. package/dist/cjs/core/ResponseEngine.d.ts +3 -8
  61. package/dist/cjs/core/ResponseEngine.d.ts.map +1 -1
  62. package/dist/cjs/core/ResponseEngine.js +8 -8
  63. package/dist/cjs/core/ResponseEngine.js.map +1 -1
  64. package/dist/cjs/core/Route.d.ts +17 -17
  65. package/dist/cjs/core/Route.d.ts.map +1 -1
  66. package/dist/cjs/core/Route.js +33 -33
  67. package/dist/cjs/core/Route.js.map +1 -1
  68. package/dist/cjs/core/RoutingEngine.d.ts +31 -31
  69. package/dist/cjs/core/RoutingEngine.d.ts.map +1 -1
  70. package/dist/cjs/core/RoutingEngine.js +196 -196
  71. package/dist/cjs/core/RoutingEngine.js.map +1 -1
  72. package/dist/cjs/core/Step.d.ts +72 -0
  73. package/dist/cjs/core/Step.d.ts.map +1 -0
  74. package/dist/cjs/core/Step.js +150 -0
  75. package/dist/cjs/core/Step.js.map +1 -0
  76. package/dist/cjs/core/ToolExecutor.d.ts +5 -5
  77. package/dist/cjs/core/ToolExecutor.d.ts.map +1 -1
  78. package/dist/cjs/core/ToolExecutor.js +8 -8
  79. package/dist/cjs/core/ToolExecutor.js.map +1 -1
  80. package/dist/cjs/core/Transition.d.ts +14 -14
  81. package/dist/cjs/core/Transition.d.ts.map +1 -1
  82. package/dist/cjs/core/Transition.js +48 -19
  83. package/dist/cjs/core/Transition.js.map +1 -1
  84. package/dist/cjs/index.d.ts +7 -7
  85. package/dist/cjs/index.d.ts.map +1 -1
  86. package/dist/cjs/index.js +8 -8
  87. package/dist/cjs/index.js.map +1 -1
  88. package/dist/cjs/types/agent.d.ts +9 -9
  89. package/dist/cjs/types/agent.d.ts.map +1 -1
  90. package/dist/cjs/types/ai.d.ts +2 -2
  91. package/dist/cjs/types/ai.d.ts.map +1 -1
  92. package/dist/cjs/types/history.d.ts +3 -3
  93. package/dist/cjs/types/history.d.ts.map +1 -1
  94. package/dist/cjs/types/index.d.ts +1 -1
  95. package/dist/cjs/types/index.d.ts.map +1 -1
  96. package/dist/cjs/types/persistence.d.ts +5 -5
  97. package/dist/cjs/types/persistence.d.ts.map +1 -1
  98. package/dist/cjs/types/route.d.ts +57 -52
  99. package/dist/cjs/types/route.d.ts.map +1 -1
  100. package/dist/cjs/types/session.d.ts +27 -27
  101. package/dist/cjs/types/session.d.ts.map +1 -1
  102. package/dist/cjs/types/session.js +48 -50
  103. package/dist/cjs/types/session.js.map +1 -1
  104. package/dist/cjs/types/tool.d.ts +13 -13
  105. package/dist/cjs/types/tool.d.ts.map +1 -1
  106. package/dist/cjs/utils/id.d.ts +8 -3
  107. package/dist/cjs/utils/id.d.ts.map +1 -1
  108. package/dist/cjs/utils/id.js +16 -7
  109. package/dist/cjs/utils/id.js.map +1 -1
  110. package/dist/constants/index.d.ts +4 -4
  111. package/dist/constants/index.js +4 -4
  112. package/dist/core/Agent.d.ts +22 -22
  113. package/dist/core/Agent.d.ts.map +1 -1
  114. package/dist/core/Agent.js +170 -162
  115. package/dist/core/Agent.js.map +1 -1
  116. package/dist/core/Events.d.ts +6 -6
  117. package/dist/core/Events.d.ts.map +1 -1
  118. package/dist/core/PersistenceManager.d.ts +13 -13
  119. package/dist/core/PersistenceManager.d.ts.map +1 -1
  120. package/dist/core/PersistenceManager.js +25 -25
  121. package/dist/core/PersistenceManager.js.map +1 -1
  122. package/dist/core/ResponseEngine.d.ts +3 -8
  123. package/dist/core/ResponseEngine.d.ts.map +1 -1
  124. package/dist/core/ResponseEngine.js +8 -8
  125. package/dist/core/ResponseEngine.js.map +1 -1
  126. package/dist/core/Route.d.ts +17 -17
  127. package/dist/core/Route.d.ts.map +1 -1
  128. package/dist/core/Route.js +33 -33
  129. package/dist/core/Route.js.map +1 -1
  130. package/dist/core/RoutingEngine.d.ts +31 -31
  131. package/dist/core/RoutingEngine.d.ts.map +1 -1
  132. package/dist/core/RoutingEngine.js +197 -197
  133. package/dist/core/RoutingEngine.js.map +1 -1
  134. package/dist/core/Step.d.ts +72 -0
  135. package/dist/core/Step.d.ts.map +1 -0
  136. package/dist/core/Step.js +146 -0
  137. package/dist/core/Step.js.map +1 -0
  138. package/dist/core/ToolExecutor.d.ts +5 -5
  139. package/dist/core/ToolExecutor.d.ts.map +1 -1
  140. package/dist/core/ToolExecutor.js +8 -8
  141. package/dist/core/ToolExecutor.js.map +1 -1
  142. package/dist/core/Transition.d.ts +14 -14
  143. package/dist/core/Transition.d.ts.map +1 -1
  144. package/dist/core/Transition.js +48 -19
  145. package/dist/core/Transition.js.map +1 -1
  146. package/dist/index.d.ts +7 -7
  147. package/dist/index.d.ts.map +1 -1
  148. package/dist/index.js +4 -4
  149. package/dist/index.js.map +1 -1
  150. package/dist/types/agent.d.ts +9 -9
  151. package/dist/types/agent.d.ts.map +1 -1
  152. package/dist/types/ai.d.ts +2 -2
  153. package/dist/types/ai.d.ts.map +1 -1
  154. package/dist/types/history.d.ts +3 -3
  155. package/dist/types/history.d.ts.map +1 -1
  156. package/dist/types/index.d.ts +1 -1
  157. package/dist/types/index.d.ts.map +1 -1
  158. package/dist/types/persistence.d.ts +5 -5
  159. package/dist/types/persistence.d.ts.map +1 -1
  160. package/dist/types/route.d.ts +57 -52
  161. package/dist/types/route.d.ts.map +1 -1
  162. package/dist/types/session.d.ts +27 -27
  163. package/dist/types/session.d.ts.map +1 -1
  164. package/dist/types/session.js +44 -46
  165. package/dist/types/session.js.map +1 -1
  166. package/dist/types/tool.d.ts +13 -13
  167. package/dist/types/tool.d.ts.map +1 -1
  168. package/dist/utils/id.d.ts +8 -3
  169. package/dist/utils/id.d.ts.map +1 -1
  170. package/dist/utils/id.js +14 -6
  171. package/dist/utils/id.js.map +1 -1
  172. package/docs/ADAPTERS.md +21 -21
  173. package/docs/AGENT.md +63 -61
  174. package/docs/API_REFERENCE.md +218 -220
  175. package/docs/ARCHITECTURE.md +99 -104
  176. package/docs/CONTEXT_MANAGEMENT.md +84 -91
  177. package/docs/CONTRIBUTING.md +3 -3
  178. package/docs/DOCS.md +18 -18
  179. package/docs/DOMAINS.md +18 -18
  180. package/docs/EXAMPLES.md +44 -44
  181. package/docs/GETTING_STARTED.md +63 -66
  182. package/docs/PERSISTENCE.md +70 -74
  183. package/docs/PROVIDERS.md +6 -6
  184. package/docs/README.md +6 -6
  185. package/docs/ROUTES.md +218 -220
  186. package/docs/STEPS.md +883 -0
  187. package/examples/business-onboarding.ts +85 -82
  188. package/examples/company-qna-agent.ts +69 -68
  189. package/examples/custom-database-persistence.ts +89 -91
  190. package/examples/declarative-agent.ts +33 -33
  191. package/examples/domain-scoping.ts +20 -20
  192. package/examples/extracted-data-modification.ts +93 -98
  193. package/examples/healthcare-agent.ts +90 -92
  194. package/examples/openai-agent.ts +30 -33
  195. package/examples/opensearch-persistence.ts +46 -48
  196. package/examples/persistent-onboarding.ts +67 -68
  197. package/examples/prisma-persistence.ts +111 -115
  198. package/examples/prisma-schema.example.prisma +3 -3
  199. package/examples/redis-persistence.ts +70 -76
  200. package/examples/route-transitions.ts +72 -48
  201. package/examples/rules-prohibitions.ts +31 -31
  202. package/examples/streaming-agent.ts +29 -29
  203. package/examples/travel-agent.ts +95 -110
  204. package/package.json +1 -1
  205. package/src/adapters/MemoryAdapter.ts +4 -4
  206. package/src/adapters/MongoAdapter.ts +4 -4
  207. package/src/adapters/OpenSearchAdapter.ts +8 -8
  208. package/src/adapters/PostgreSQLAdapter.ts +11 -11
  209. package/src/adapters/PrismaAdapter.ts +5 -5
  210. package/src/adapters/RedisAdapter.ts +4 -4
  211. package/src/adapters/SQLiteAdapter.ts +16 -16
  212. package/src/adapters/index.ts +1 -1
  213. package/src/constants/index.ts +4 -4
  214. package/src/core/Agent.ts +218 -214
  215. package/src/core/Events.ts +12 -12
  216. package/src/core/PersistenceManager.ts +32 -36
  217. package/src/core/ResponseEngine.ts +11 -17
  218. package/src/core/Route.ts +55 -49
  219. package/src/core/RoutingEngine.ts +252 -258
  220. package/src/core/Step.ts +197 -0
  221. package/src/core/ToolExecutor.ts +11 -11
  222. package/src/core/Transition.ts +72 -26
  223. package/src/index.ts +8 -8
  224. package/src/types/agent.ts +9 -9
  225. package/src/types/ai.ts +2 -2
  226. package/src/types/history.ts +3 -3
  227. package/src/types/index.ts +1 -1
  228. package/src/types/persistence.ts +6 -6
  229. package/src/types/route.ts +77 -61
  230. package/src/types/session.ts +75 -78
  231. package/src/types/tool.ts +17 -17
  232. package/src/utils/id.ts +15 -6
  233. package/dist/cjs/core/State.d.ts +0 -72
  234. package/dist/cjs/core/State.d.ts.map +0 -1
  235. package/dist/cjs/core/State.js +0 -148
  236. package/dist/cjs/core/State.js.map +0 -1
  237. package/dist/core/State.d.ts +0 -72
  238. package/dist/core/State.d.ts.map +0 -1
  239. package/dist/core/State.js +0 -144
  240. package/dist/core/State.js.map +0 -1
  241. package/docs/STATES.md +0 -888
  242. package/src/core/State.ts +0 -212
@@ -64,7 +64,7 @@ export interface RedisAdapterOptions {
64
64
  *
65
65
  * const agent = new Agent({
66
66
  * name: "My Agent",
67
- * ai: provider,
67
+ * provider: provider,
68
68
  * persistence: {
69
69
  * adapter: new RedisAdapter({ redis }),
70
70
  * userId: "user_123",
@@ -223,12 +223,12 @@ class RedisSessionRepository implements SessionRepository {
223
223
  return this.update(id, { collectedData });
224
224
  }
225
225
 
226
- async updateRouteState(
226
+ async updateRouteStep(
227
227
  id: string,
228
228
  route?: string,
229
- state?: string
229
+ step?: string
230
230
  ): Promise<SessionData | null> {
231
- return this.update(id, { currentRoute: route, currentState: state });
231
+ return this.update(id, { currentRoute: route, currentStep: step });
232
232
  }
233
233
 
234
234
  async incrementMessageCount(id: string): Promise<SessionData | null> {
@@ -16,15 +16,15 @@ import type {
16
16
  * SQLite database interface - matches better-sqlite3
17
17
  */
18
18
  export interface SqliteDatabase {
19
- prepare(sql: string): SqliteStatement;
19
+ prepare(sql: string): SqliteStepment;
20
20
  exec(sql: string): void;
21
21
  close(): void;
22
22
  }
23
23
 
24
24
  /**
25
- * SQLite statement interface
25
+ * SQLite stepment interface
26
26
  */
27
- export interface SqliteStatement {
27
+ export interface SqliteStepment {
28
28
  run(...params: unknown[]): { changes: number; lastInsertRowid: number };
29
29
  get(...params: unknown[]): Record<string, unknown> | undefined;
30
30
  all(...params: unknown[]): Array<Record<string, unknown>>;
@@ -60,7 +60,7 @@ export interface SQLiteAdapterOptions {
60
60
  *
61
61
  * const agent = new Agent({
62
62
  * name: "My Agent",
63
- * ai: provider,
63
+ * provider: provider,
64
64
  * persistence: {
65
65
  * adapter: new SQLiteAdapter({ db }),
66
66
  * userId: "user_123",
@@ -95,7 +95,7 @@ export class SQLiteAdapter implements PersistenceAdapter {
95
95
  agent_name TEXT,
96
96
  status TEXT DEFAULT 'active',
97
97
  current_route TEXT,
98
- current_state TEXT,
98
+ current_step TEXT,
99
99
  collected_data TEXT,
100
100
  message_count INTEGER DEFAULT 0,
101
101
  last_message_at TEXT,
@@ -120,7 +120,7 @@ export class SQLiteAdapter implements PersistenceAdapter {
120
120
  role TEXT NOT NULL,
121
121
  content TEXT NOT NULL,
122
122
  route TEXT,
123
- state TEXT,
123
+ step TEXT,
124
124
  tool_calls TEXT,
125
125
  event TEXT,
126
126
  created_at TEXT NOT NULL,
@@ -232,9 +232,9 @@ class SQLiteSessionRepository implements SessionRepository {
232
232
  fields.push("current_route = ?");
233
233
  values.push(data.currentRoute);
234
234
  }
235
- if (data.currentState !== undefined) {
236
- fields.push("current_state = ?");
237
- values.push(data.currentState);
235
+ if (data.currentStep !== undefined) {
236
+ fields.push("current_step = ?");
237
+ values.push(data.currentStep);
238
238
  }
239
239
  if (data.messageCount !== undefined) {
240
240
  fields.push("message_count = ?");
@@ -281,14 +281,14 @@ class SQLiteSessionRepository implements SessionRepository {
281
281
  return await this.update(id, { collectedData });
282
282
  }
283
283
 
284
- async updateRouteState(
284
+ async updateRouteStep(
285
285
  id: string,
286
286
  route?: string,
287
- state?: string
287
+ step?: string
288
288
  ): Promise<SessionData | null> {
289
289
  return await this.update(id, {
290
290
  currentRoute: route,
291
- currentState: state,
291
+ currentStep: step,
292
292
  });
293
293
  }
294
294
 
@@ -321,7 +321,7 @@ class SQLiteSessionRepository implements SessionRepository {
321
321
  agentName: (row.agent_name as string) || undefined,
322
322
  status: row.status as SessionStatus,
323
323
  currentRoute: (row.current_route as string) || undefined,
324
- currentState: (row.current_state as string) || undefined,
324
+ currentStep: (row.current_step as string) || undefined,
325
325
  collectedData: row.collected_data
326
326
  ? (JSON.parse(row.collected_data as string) as Record<string, unknown>)
327
327
  : undefined,
@@ -356,7 +356,7 @@ class SQLiteMessageRepository implements MessageRepository {
356
356
 
357
357
  const stmt = this.db.prepare(`
358
358
  INSERT INTO ${this.tableName}
359
- (id, session_id, user_id, role, content, route, state, tool_calls, event, created_at)
359
+ (id, session_id, user_id, role, content, route, step, tool_calls, event, created_at)
360
360
  VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
361
361
  `);
362
362
 
@@ -367,7 +367,7 @@ class SQLiteMessageRepository implements MessageRepository {
367
367
  data.role,
368
368
  data.content,
369
369
  data.route || null,
370
- data.state || null,
370
+ data.step || null,
371
371
  JSON.stringify(data.toolCalls || null),
372
372
  JSON.stringify(data.event || null),
373
373
  now.toISOString()
@@ -436,7 +436,7 @@ class SQLiteMessageRepository implements MessageRepository {
436
436
  role: row.role as MessageData["role"],
437
437
  content: row.content as string,
438
438
  route: (row.route as string) || undefined,
439
- state: (row.state as string) || undefined,
439
+ step: (row.step as string) || undefined,
440
440
  toolCalls: row.tool_calls
441
441
  ? (JSON.parse(row.tool_calls as string) as MessageData["toolCalls"])
442
442
  : undefined,
@@ -30,7 +30,7 @@ export type {
30
30
  export { SQLiteAdapter } from "./SQLiteAdapter";
31
31
  export type {
32
32
  SqliteDatabase,
33
- SqliteStatement,
33
+ SqliteStepment,
34
34
  SQLiteAdapterOptions,
35
35
  } from "./SQLiteAdapter";
36
36
 
@@ -1,10 +1,10 @@
1
1
  /**
2
2
  * Special marker to end a route/journey
3
3
  */
4
- export const END_STATE = Symbol("END_STATE");
4
+ export const END_ROUTE = Symbol("END_ROUTE");
5
5
 
6
6
  /**
7
- * String constant for END_STATE comparisons
8
- * Use this when checking if currentState.id has reached END_STATE
7
+ * String constant for END_ROUTE comparisons
8
+ * Use this when checking if currentStep.id has reached END_ROUTE
9
9
  */
10
- export const END_STATE_ID = "END_STATE";
10
+ export const END_ROUTE_ID = "END_ROUTE";