@falai/agent 0.4.1 → 0.5.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 (285) hide show
  1. package/README.md +21 -74
  2. package/dist/cjs/core/Agent.d.ts +22 -29
  3. package/dist/cjs/core/Agent.d.ts.map +1 -1
  4. package/dist/cjs/core/Agent.js +464 -291
  5. package/dist/cjs/core/Agent.js.map +1 -1
  6. package/dist/cjs/core/Events.d.ts +10 -1
  7. package/dist/cjs/core/Events.d.ts.map +1 -1
  8. package/dist/cjs/core/Events.js +3 -2
  9. package/dist/cjs/core/Events.js.map +1 -1
  10. package/dist/cjs/core/PersistenceManager.d.ts +19 -0
  11. package/dist/cjs/core/PersistenceManager.d.ts.map +1 -1
  12. package/dist/cjs/core/PersistenceManager.js +57 -0
  13. package/dist/cjs/core/PersistenceManager.js.map +1 -1
  14. package/dist/cjs/core/PromptComposer.d.ts +24 -0
  15. package/dist/cjs/core/PromptComposer.d.ts.map +1 -0
  16. package/dist/cjs/core/PromptComposer.js +127 -0
  17. package/dist/cjs/core/PromptComposer.js.map +1 -0
  18. package/dist/cjs/core/ResponseEngine.d.ts +19 -0
  19. package/dist/cjs/core/ResponseEngine.d.ts.map +1 -0
  20. package/dist/cjs/core/ResponseEngine.js +51 -0
  21. package/dist/cjs/core/ResponseEngine.js.map +1 -0
  22. package/dist/cjs/core/Route.d.ts +18 -12
  23. package/dist/cjs/core/Route.d.ts.map +1 -1
  24. package/dist/cjs/core/Route.js +15 -9
  25. package/dist/cjs/core/Route.js.map +1 -1
  26. package/dist/cjs/core/RoutingEngine.d.ts +38 -0
  27. package/dist/cjs/core/RoutingEngine.d.ts.map +1 -0
  28. package/dist/cjs/core/RoutingEngine.js +110 -0
  29. package/dist/cjs/core/RoutingEngine.js.map +1 -0
  30. package/dist/cjs/core/State.d.ts +15 -4
  31. package/dist/cjs/core/State.d.ts.map +1 -1
  32. package/dist/cjs/core/State.js +21 -2
  33. package/dist/cjs/core/State.js.map +1 -1
  34. package/dist/cjs/core/ToolExecutor.d.ts +29 -0
  35. package/dist/cjs/core/ToolExecutor.d.ts.map +1 -0
  36. package/dist/cjs/core/ToolExecutor.js +73 -0
  37. package/dist/cjs/core/ToolExecutor.js.map +1 -0
  38. package/dist/cjs/core/Transition.d.ts +5 -5
  39. package/dist/cjs/core/Transition.d.ts.map +1 -1
  40. package/dist/cjs/core/Transition.js.map +1 -1
  41. package/dist/cjs/index.d.ts +6 -8
  42. package/dist/cjs/index.d.ts.map +1 -1
  43. package/dist/cjs/index.js +8 -10
  44. package/dist/cjs/index.js.map +1 -1
  45. package/dist/cjs/providers/AnthropicProvider.d.ts.map +1 -1
  46. package/dist/cjs/providers/AnthropicProvider.js +10 -13
  47. package/dist/cjs/providers/AnthropicProvider.js.map +1 -1
  48. package/dist/cjs/providers/GeminiProvider.d.ts.map +1 -1
  49. package/dist/cjs/providers/GeminiProvider.js +12 -8
  50. package/dist/cjs/providers/GeminiProvider.js.map +1 -1
  51. package/dist/cjs/providers/OpenAIProvider.d.ts.map +1 -1
  52. package/dist/cjs/providers/OpenAIProvider.js +10 -53
  53. package/dist/cjs/providers/OpenAIProvider.js.map +1 -1
  54. package/dist/cjs/providers/OpenRouterProvider.d.ts.map +1 -1
  55. package/dist/cjs/providers/OpenRouterProvider.js +10 -53
  56. package/dist/cjs/providers/OpenRouterProvider.js.map +1 -1
  57. package/dist/cjs/types/agent.d.ts +13 -12
  58. package/dist/cjs/types/agent.d.ts.map +1 -1
  59. package/dist/cjs/types/ai.d.ts +8 -2
  60. package/dist/cjs/types/ai.d.ts.map +1 -1
  61. package/dist/cjs/types/history.d.ts +8 -0
  62. package/dist/cjs/types/history.d.ts.map +1 -1
  63. package/dist/cjs/types/index.d.ts +0 -3
  64. package/dist/cjs/types/index.d.ts.map +1 -1
  65. package/dist/cjs/types/index.js +1 -3
  66. package/dist/cjs/types/index.js.map +1 -1
  67. package/dist/cjs/types/route.d.ts +39 -4
  68. package/dist/cjs/types/route.d.ts.map +1 -1
  69. package/dist/cjs/types/routing.d.ts +16 -0
  70. package/dist/cjs/types/routing.d.ts.map +1 -0
  71. package/dist/cjs/types/routing.js +3 -0
  72. package/dist/cjs/types/routing.js.map +1 -0
  73. package/dist/cjs/types/schema.d.ts +22 -0
  74. package/dist/cjs/types/schema.d.ts.map +1 -0
  75. package/dist/cjs/types/schema.js +3 -0
  76. package/dist/cjs/types/schema.js.map +1 -0
  77. package/dist/cjs/types/session.d.ts +72 -0
  78. package/dist/cjs/types/session.d.ts.map +1 -0
  79. package/dist/cjs/types/session.js +140 -0
  80. package/dist/cjs/types/session.js.map +1 -0
  81. package/dist/cjs/types/tool.d.ts +11 -5
  82. package/dist/cjs/types/tool.d.ts.map +1 -1
  83. package/dist/cjs/utils/id.d.ts +0 -5
  84. package/dist/cjs/utils/id.d.ts.map +1 -1
  85. package/dist/cjs/utils/id.js +0 -10
  86. package/dist/cjs/utils/id.js.map +1 -1
  87. package/dist/cjs/utils/schema.d.ts +17 -0
  88. package/dist/cjs/utils/schema.d.ts.map +1 -0
  89. package/dist/cjs/utils/schema.js +32 -0
  90. package/dist/cjs/utils/schema.js.map +1 -0
  91. package/dist/core/Agent.d.ts +22 -29
  92. package/dist/core/Agent.d.ts.map +1 -1
  93. package/dist/core/Agent.js +464 -291
  94. package/dist/core/Agent.js.map +1 -1
  95. package/dist/core/Events.d.ts +10 -1
  96. package/dist/core/Events.d.ts.map +1 -1
  97. package/dist/core/Events.js +3 -2
  98. package/dist/core/Events.js.map +1 -1
  99. package/dist/core/PersistenceManager.d.ts +19 -0
  100. package/dist/core/PersistenceManager.d.ts.map +1 -1
  101. package/dist/core/PersistenceManager.js +57 -0
  102. package/dist/core/PersistenceManager.js.map +1 -1
  103. package/dist/core/PromptComposer.d.ts +24 -0
  104. package/dist/core/PromptComposer.d.ts.map +1 -0
  105. package/dist/core/PromptComposer.js +123 -0
  106. package/dist/core/PromptComposer.js.map +1 -0
  107. package/dist/core/ResponseEngine.d.ts +19 -0
  108. package/dist/core/ResponseEngine.d.ts.map +1 -0
  109. package/dist/core/ResponseEngine.js +47 -0
  110. package/dist/core/ResponseEngine.js.map +1 -0
  111. package/dist/core/Route.d.ts +18 -12
  112. package/dist/core/Route.d.ts.map +1 -1
  113. package/dist/core/Route.js +15 -9
  114. package/dist/core/Route.js.map +1 -1
  115. package/dist/core/RoutingEngine.d.ts +38 -0
  116. package/dist/core/RoutingEngine.d.ts.map +1 -0
  117. package/dist/core/RoutingEngine.js +106 -0
  118. package/dist/core/RoutingEngine.js.map +1 -0
  119. package/dist/core/State.d.ts +15 -4
  120. package/dist/core/State.d.ts.map +1 -1
  121. package/dist/core/State.js +21 -2
  122. package/dist/core/State.js.map +1 -1
  123. package/dist/core/ToolExecutor.d.ts +29 -0
  124. package/dist/core/ToolExecutor.d.ts.map +1 -0
  125. package/dist/core/ToolExecutor.js +69 -0
  126. package/dist/core/ToolExecutor.js.map +1 -0
  127. package/dist/core/Transition.d.ts +5 -5
  128. package/dist/core/Transition.d.ts.map +1 -1
  129. package/dist/core/Transition.js.map +1 -1
  130. package/dist/index.d.ts +6 -8
  131. package/dist/index.d.ts.map +1 -1
  132. package/dist/index.js +3 -5
  133. package/dist/index.js.map +1 -1
  134. package/dist/providers/AnthropicProvider.d.ts.map +1 -1
  135. package/dist/providers/AnthropicProvider.js +10 -13
  136. package/dist/providers/AnthropicProvider.js.map +1 -1
  137. package/dist/providers/GeminiProvider.d.ts.map +1 -1
  138. package/dist/providers/GeminiProvider.js +12 -8
  139. package/dist/providers/GeminiProvider.js.map +1 -1
  140. package/dist/providers/OpenAIProvider.d.ts.map +1 -1
  141. package/dist/providers/OpenAIProvider.js +10 -53
  142. package/dist/providers/OpenAIProvider.js.map +1 -1
  143. package/dist/providers/OpenRouterProvider.d.ts.map +1 -1
  144. package/dist/providers/OpenRouterProvider.js +10 -53
  145. package/dist/providers/OpenRouterProvider.js.map +1 -1
  146. package/dist/types/agent.d.ts +13 -12
  147. package/dist/types/agent.d.ts.map +1 -1
  148. package/dist/types/ai.d.ts +8 -2
  149. package/dist/types/ai.d.ts.map +1 -1
  150. package/dist/types/history.d.ts +8 -0
  151. package/dist/types/history.d.ts.map +1 -1
  152. package/dist/types/index.d.ts +0 -3
  153. package/dist/types/index.d.ts.map +1 -1
  154. package/dist/types/index.js +0 -1
  155. package/dist/types/index.js.map +1 -1
  156. package/dist/types/route.d.ts +39 -4
  157. package/dist/types/route.d.ts.map +1 -1
  158. package/dist/types/routing.d.ts +16 -0
  159. package/dist/types/routing.d.ts.map +1 -0
  160. package/dist/types/routing.js +2 -0
  161. package/dist/types/routing.js.map +1 -0
  162. package/dist/types/schema.d.ts +22 -0
  163. package/dist/types/schema.d.ts.map +1 -0
  164. package/dist/types/schema.js +2 -0
  165. package/dist/types/schema.js.map +1 -0
  166. package/dist/types/session.d.ts +72 -0
  167. package/dist/types/session.d.ts.map +1 -0
  168. package/dist/types/session.js +132 -0
  169. package/dist/types/session.js.map +1 -0
  170. package/dist/types/tool.d.ts +11 -5
  171. package/dist/types/tool.d.ts.map +1 -1
  172. package/dist/utils/id.d.ts +0 -5
  173. package/dist/utils/id.d.ts.map +1 -1
  174. package/dist/utils/id.js +0 -9
  175. package/dist/utils/id.js.map +1 -1
  176. package/dist/utils/schema.d.ts +17 -0
  177. package/dist/utils/schema.d.ts.map +1 -0
  178. package/dist/utils/schema.js +27 -0
  179. package/dist/utils/schema.js.map +1 -0
  180. package/docs/ADAPTERS.md +83 -3
  181. package/docs/API_REFERENCE.md +95 -104
  182. package/docs/ARCHITECTURE.md +284 -286
  183. package/docs/CONSTRUCTOR_OPTIONS.md +192 -135
  184. package/docs/CONTEXT_MANAGEMENT.md +311 -28
  185. package/docs/CONTRIBUTING.md +1 -1
  186. package/docs/DOMAINS.md +61 -0
  187. package/docs/GETTING_STARTED.md +177 -88
  188. package/docs/PERSISTENCE.md +170 -23
  189. package/docs/README.md +7 -10
  190. package/examples/business-onboarding.ts +21 -9
  191. package/examples/company-qna-agent.ts +508 -0
  192. package/examples/declarative-agent.ts +143 -26
  193. package/examples/domain-scoping.ts +31 -10
  194. package/examples/extracted-data-modification.ts +415 -0
  195. package/examples/healthcare-agent.ts +194 -90
  196. package/examples/openai-agent.ts +67 -25
  197. package/examples/opensearch-persistence.ts +455 -151
  198. package/examples/persistent-onboarding.ts +162 -96
  199. package/examples/prisma-persistence.ts +371 -125
  200. package/examples/redis-persistence.ts +393 -23
  201. package/examples/rules-prohibitions.ts +32 -11
  202. package/examples/streaming-agent.ts +61 -13
  203. package/examples/travel-agent.ts +266 -133
  204. package/package.json +1 -1
  205. package/src/core/Agent.ts +674 -356
  206. package/src/core/Events.ts +12 -2
  207. package/src/core/PersistenceManager.ts +83 -0
  208. package/src/core/PromptComposer.ts +143 -0
  209. package/src/core/ResponseEngine.ts +82 -0
  210. package/src/core/Route.ts +32 -17
  211. package/src/core/RoutingEngine.ts +165 -0
  212. package/src/core/State.ts +55 -15
  213. package/src/core/ToolExecutor.ts +117 -0
  214. package/src/core/Transition.ts +5 -5
  215. package/src/index.ts +12 -21
  216. package/src/providers/AnthropicProvider.ts +10 -13
  217. package/src/providers/GeminiProvider.ts +12 -8
  218. package/src/providers/OpenAIProvider.ts +10 -56
  219. package/src/providers/OpenRouterProvider.ts +10 -56
  220. package/src/types/agent.ts +16 -13
  221. package/src/types/ai.ts +6 -2
  222. package/src/types/history.ts +8 -0
  223. package/src/types/index.ts +0 -11
  224. package/src/types/route.ts +41 -5
  225. package/src/types/routing.ts +18 -0
  226. package/src/types/schema.ts +23 -0
  227. package/src/types/session.ts +207 -0
  228. package/src/types/tool.ts +29 -7
  229. package/src/utils/id.ts +0 -10
  230. package/src/utils/schema.ts +32 -0
  231. package/dist/cjs/core/ConditionEvaluator.d.ts +0 -72
  232. package/dist/cjs/core/ConditionEvaluator.d.ts.map +0 -1
  233. package/dist/cjs/core/ConditionEvaluator.js +0 -272
  234. package/dist/cjs/core/ConditionEvaluator.js.map +0 -1
  235. package/dist/cjs/core/Observation.d.ts +0 -24
  236. package/dist/cjs/core/Observation.d.ts.map +0 -1
  237. package/dist/cjs/core/Observation.js +0 -39
  238. package/dist/cjs/core/Observation.js.map +0 -1
  239. package/dist/cjs/core/PreparationEngine.d.ts +0 -116
  240. package/dist/cjs/core/PreparationEngine.d.ts.map +0 -1
  241. package/dist/cjs/core/PreparationEngine.js +0 -353
  242. package/dist/cjs/core/PreparationEngine.js.map +0 -1
  243. package/dist/cjs/core/PromptBuilder.d.ts +0 -136
  244. package/dist/cjs/core/PromptBuilder.d.ts.map +0 -1
  245. package/dist/cjs/core/PromptBuilder.js +0 -421
  246. package/dist/cjs/core/PromptBuilder.js.map +0 -1
  247. package/dist/cjs/types/observation.d.ts +0 -27
  248. package/dist/cjs/types/observation.d.ts.map +0 -1
  249. package/dist/cjs/types/observation.js +0 -6
  250. package/dist/cjs/types/observation.js.map +0 -1
  251. package/dist/cjs/types/prompt.d.ts +0 -46
  252. package/dist/cjs/types/prompt.d.ts.map +0 -1
  253. package/dist/cjs/types/prompt.js +0 -19
  254. package/dist/cjs/types/prompt.js.map +0 -1
  255. package/dist/core/ConditionEvaluator.d.ts +0 -72
  256. package/dist/core/ConditionEvaluator.d.ts.map +0 -1
  257. package/dist/core/ConditionEvaluator.js +0 -268
  258. package/dist/core/ConditionEvaluator.js.map +0 -1
  259. package/dist/core/Observation.d.ts +0 -24
  260. package/dist/core/Observation.d.ts.map +0 -1
  261. package/dist/core/Observation.js +0 -35
  262. package/dist/core/Observation.js.map +0 -1
  263. package/dist/core/PreparationEngine.d.ts +0 -116
  264. package/dist/core/PreparationEngine.d.ts.map +0 -1
  265. package/dist/core/PreparationEngine.js +0 -349
  266. package/dist/core/PreparationEngine.js.map +0 -1
  267. package/dist/core/PromptBuilder.d.ts +0 -136
  268. package/dist/core/PromptBuilder.d.ts.map +0 -1
  269. package/dist/core/PromptBuilder.js +0 -417
  270. package/dist/core/PromptBuilder.js.map +0 -1
  271. package/dist/types/observation.d.ts +0 -27
  272. package/dist/types/observation.d.ts.map +0 -1
  273. package/dist/types/observation.js +0 -5
  274. package/dist/types/observation.js.map +0 -1
  275. package/dist/types/prompt.d.ts +0 -46
  276. package/dist/types/prompt.d.ts.map +0 -1
  277. package/dist/types/prompt.js +0 -16
  278. package/dist/types/prompt.js.map +0 -1
  279. package/docs/STRUCTURE.md +0 -58
  280. package/src/core/ConditionEvaluator.ts +0 -381
  281. package/src/core/Observation.ts +0 -47
  282. package/src/core/PreparationEngine.ts +0 -561
  283. package/src/core/PromptBuilder.ts +0 -617
  284. package/src/types/observation.ts +0 -29
  285. package/src/types/prompt.ts +0 -49
package/README.md CHANGED
@@ -43,21 +43,22 @@
43
43
  <tr>
44
44
  <td width="50%">
45
45
 
46
- ### 🛤️ **Conversation Flows**
46
+ ### 🛤️ **Data-Driven Conversations**
47
47
 
48
- - **Route DSL** - Declarative state machines for conversations
49
- - **Smart Transitions** - Conditional flows with `transitionTo`
50
- - **Disambiguation** - Observations for handling ambiguous intent
48
+ - **Schema-First Extraction** - Define data contracts with JSON Schema
49
+ - **Session State Management** - Track conversation progress across turns
50
+ - **Code-Based Logic** - Deterministic state progression with `skipIf`
51
+ - **Always-On Routing** - Context-aware routing respects user intent changes
51
52
 
52
53
  </td>
53
54
  <td width="50%">
54
55
 
55
- ### 🔧 **Tools & Domains**
56
+ ### 🔧 **Tools & Data Integration**
56
57
 
58
+ - **Data-Aware Tools** - Tools access extracted data directly via `extracted` context
59
+ - **Enrichment Hooks** - Tools can modify extracted data with `extractedUpdate`
60
+ - **Action Flags** - Tools set flags for conditional execution
57
61
  - **Type-Safe Tools** - Define tools with full type inference
58
- - **Domain Registry** - Optional security & organization by domain
59
- - **Context Awareness** - Tools receive typed context automatically
60
- - **Automatic Execution** - Tools run based on state machine, not AI
61
62
 
62
63
  </td>
63
64
  </tr>
@@ -66,19 +67,22 @@
66
67
 
67
68
  ### 💾 **Optional Persistence**
68
69
 
70
+ - **Session State Integration** - Automatic saving of extracted data & conversation progress
69
71
  - **Provider Pattern** - Simple API like AI providers
70
- - **Prisma Ready** - Built-in ORM adapter
71
- - **Auto-save** - Automatic session & message persistence
72
+ - **Multiple Adapters** - Prisma, Redis, MongoDB, PostgreSQL, SQLite, OpenSearch, Memory
73
+ - **Auto-save** - Automatic session state & message persistence
74
+ - **Type-Safe** - Full TypeScript support with generics
72
75
  - **Extensible** - Create adapters for any database
73
76
 
74
77
  </td>
75
78
  <td width="50%">
76
79
 
77
- ### 🎯 **Smart Routing**
80
+ ### 🎯 **Session-Aware Routing**
78
81
 
82
+ - **Always-On Routing** - Users can change their mind mid-conversation
83
+ - **Context Awareness** - Router sees current progress and extracted data
84
+ - **Session State** - Track conversation progress across turns
79
85
  - **Deterministic IDs** - Consistent identifiers across restarts
80
- - **Route Scoping** - Control tool access per route
81
- - **Rules & Prohibitions** - Fine-grained behavior control
82
86
 
83
87
  </td>
84
88
  </tr>
@@ -343,7 +347,6 @@ onboardingRoute.initialState
343
347
  - **[Context Management](./docs/CONTEXT_MANAGEMENT.md)** - Persistent conversations & state management
344
348
  - **[Persistence](./docs/PERSISTENCE.md)** - Optional database persistence with Prisma **(NEW!)**
345
349
  - **[API Reference](./docs/API_REFERENCE.md)** - Complete API documentation
346
- - **[Package Structure](./docs/STRUCTURE.md)** - Package structure and design principles
347
350
 
348
351
  ### 💡 Key Concepts
349
352
 
@@ -598,57 +601,6 @@ agent.createRoute({
598
601
  - 📋 Clear documentation of route capabilities
599
602
  - 🛡️ Security by design
600
603
 
601
- ### 🔀 Disambiguation with Observations
602
-
603
- Handle ambiguous user intent gracefully - declaratively or programmatically:
604
-
605
- ```typescript
606
- // Option A: Declarative (reference routes by title)
607
- const agent = new Agent({
608
- name: "HealthBot",
609
- ai: provider,
610
- routes: [
611
- {
612
- id: "route_schedule", // Custom ID
613
- title: "Schedule Appointment",
614
- conditions: ["User wants to schedule"],
615
- },
616
- {
617
- id: "route_reschedule", // Custom ID
618
- title: "Reschedule Appointment",
619
- conditions: ["User wants to reschedule"],
620
- },
621
- ],
622
- observations: [
623
- {
624
- id: "obs_appointment_intent", // Custom ID for tracking
625
- description: "User mentions appointment but intent is unclear",
626
- routeRefs: ["Schedule Appointment", "Reschedule Appointment"], // By title
627
- },
628
- ],
629
- });
630
-
631
- // Option B: Programmatic
632
- const scheduleRoute = agent.createRoute({
633
- id: "route_schedule", // Custom ID
634
- title: "Schedule Appointment",
635
- conditions: ["User wants to schedule"],
636
- });
637
-
638
- const rescheduleRoute = agent.createRoute({
639
- id: "route_reschedule", // Custom ID
640
- title: "Reschedule Appointment",
641
- conditions: ["User wants to reschedule"],
642
- });
643
-
644
- const appointmentInquiry = agent.createObservation(
645
- "User mentions appointment but intent is unclear"
646
- );
647
-
648
- // Agent will ask user to clarify between these routes
649
- appointmentInquiry.disambiguate([scheduleRoute, rescheduleRoute]);
650
- ```
651
-
652
604
  ### 🎨 Context Override
653
605
 
654
606
  Dynamically update context per request:
@@ -792,14 +744,10 @@ agent
792
744
 
793
745
  ### 🆔 Deterministic IDs & Persistence
794
746
 
795
- All entities (routes, states, observations, tools) have **deterministic IDs** by default, ensuring consistency across server restarts:
747
+ All entities (routes, states, tools) have **deterministic IDs** by default, ensuring consistency across server restarts:
796
748
 
797
749
  ```typescript
798
- import {
799
- generateRouteId,
800
- generateToolId,
801
- generateObservationId,
802
- } from "@falai/agent";
750
+ import { generateRouteId, generateToolId } from "@falai/agent";
803
751
 
804
752
  // Auto-generated deterministic IDs (recommended)
805
753
  const route = agent.createRoute({
@@ -904,8 +852,7 @@ const openrouterProvider = new OpenRouterProvider({
904
852
  **Comprehensive declarative configuration example:**
905
853
 
906
854
  - 📦 Everything configured in constructor
907
- - 📚 Terms, guidelines, capabilities, routes, observations
908
- - 🔗 Route references by title in observations
855
+ - 📚 Terms, guidelines, capabilities, routes
909
856
  - ➕ Dynamic additions after construction
910
857
 
911
858
  ### ⚡ [Streaming Responses](./examples/streaming-agent.ts) **(NEW!)**
@@ -965,7 +912,7 @@ Healthcare-focused agent demonstrating:
965
912
 
966
913
  - 🩺 Appointment scheduling with alternatives
967
914
  - 🔬 Lab results retrieval
968
- - 🤔 Observation-based disambiguation
915
+ - 🤔 Route-based disambiguation with conditions
969
916
  - 🔐 Sensitive data handling
970
917
  - ⚠️ Urgent case prioritization
971
918
 
@@ -4,9 +4,9 @@
4
4
  import type { AgentOptions, Term, Guideline, Capability } from "../types/agent";
5
5
  import type { Event, StateRef } from "../types/index";
6
6
  import type { RouteOptions } from "../types/route";
7
+ import type { SessionState } from "../types/session";
7
8
  import { Route } from "./Route";
8
9
  import { DomainRegistry } from "./DomainRegistry";
9
- import { Observation } from "./Observation";
10
10
  import { PersistenceManager } from "./PersistenceManager";
11
11
  /**
12
12
  * Main Agent class with generic context support
@@ -17,11 +17,11 @@ export declare class Agent<TContext = unknown> {
17
17
  private guidelines;
18
18
  private capabilities;
19
19
  private routes;
20
- private observations;
21
20
  private domainRegistry;
22
21
  private context;
23
22
  private persistenceManager;
24
- private preparationEngine;
23
+ private routingEngine;
24
+ private responseEngine;
25
25
  /**
26
26
  * Dynamic domain property - populated via addDomain
27
27
  */
@@ -41,8 +41,9 @@ export declare class Agent<TContext = unknown> {
41
41
  get goal(): string | undefined;
42
42
  /**
43
43
  * Create a new route (journey)
44
+ * @template TExtracted - Type of data extracted throughout the route
44
45
  */
45
- createRoute(options: RouteOptions): Route<TContext>;
46
+ createRoute<TExtracted = unknown>(options: RouteOptions<TExtracted>): Route<TContext, TExtracted>;
46
47
  /**
47
48
  * Create a domain term for the glossary
48
49
  */
@@ -55,12 +56,9 @@ export declare class Agent<TContext = unknown> {
55
56
  * Add a capability
56
57
  */
57
58
  createCapability(capability: Capability): this;
58
- /**
59
- * Create an observation for disambiguation
60
- */
61
- createObservation(description: string): Observation;
62
59
  /**
63
60
  * Add a domain with its tools/methods
61
+ * Automatically tags all ToolRef objects with their domain name for security enforcement
64
62
  */
65
63
  addDomain<TName extends string, TDomain extends Record<string, unknown>>(name: TName, domainObject: TDomain): void;
66
64
  /**
@@ -68,31 +66,36 @@ export declare class Agent<TContext = unknown> {
68
66
  * Triggers the onContextUpdate lifecycle hook if configured
69
67
  */
70
68
  updateContext(updates: Partial<TContext>): Promise<void>;
69
+ /**
70
+ * Update extracted data in session with lifecycle hook support
71
+ * Triggers the onExtractedUpdate lifecycle hook if configured
72
+ * @internal
73
+ */
74
+ private updateExtracted;
71
75
  /**
72
76
  * Get current context (fetches from provider if configured)
73
77
  * @internal
74
78
  */
75
79
  private getContext;
80
+ /**
81
+ * Determine the next state in a route based on extracted data
82
+ * @internal
83
+ */
84
+ private getNextState;
76
85
  /**
77
86
  * Generate a response based on history and context as a stream
78
87
  */
79
88
  respondStream(params: {
80
89
  history: Event[];
81
90
  state?: StateRef;
91
+ session?: SessionState;
82
92
  contextOverride?: Partial<TContext>;
83
93
  signal?: AbortSignal;
84
94
  }): AsyncGenerator<{
85
95
  delta: string;
86
96
  accumulated: string;
87
97
  done: boolean;
88
- route?: {
89
- id: string;
90
- title: string;
91
- } | null;
92
- state?: {
93
- id: string;
94
- description?: string;
95
- } | null;
98
+ session?: SessionState;
96
99
  toolCalls?: Array<{
97
100
  toolName: string;
98
101
  arguments: Record<string, unknown>;
@@ -104,18 +107,12 @@ export declare class Agent<TContext = unknown> {
104
107
  respond(params: {
105
108
  history: Event[];
106
109
  state?: StateRef;
110
+ session?: SessionState;
107
111
  contextOverride?: Partial<TContext>;
108
112
  signal?: AbortSignal;
109
113
  }): Promise<{
110
114
  message: string;
111
- route?: {
112
- id: string;
113
- title: string;
114
- } | null;
115
- state?: {
116
- id: string;
117
- description?: string;
118
- } | null;
115
+ session?: SessionState;
119
116
  toolCalls?: Array<{
120
117
  toolName: string;
121
118
  arguments: Record<string, unknown>;
@@ -124,7 +121,7 @@ export declare class Agent<TContext = unknown> {
124
121
  /**
125
122
  * Get all routes
126
123
  */
127
- getRoutes(): Route<TContext>[];
124
+ getRoutes(): Route<TContext, unknown>[];
128
125
  /**
129
126
  * Get all terms
130
127
  */
@@ -137,10 +134,6 @@ export declare class Agent<TContext = unknown> {
137
134
  * Get all capabilities
138
135
  */
139
136
  getCapabilities(): Capability[];
140
- /**
141
- * Get all observations
142
- */
143
- getObservations(): Observation[];
144
137
  /**
145
138
  * Get the domain registry
146
139
  */
@@ -1 +1 @@
1
- {"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"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"}