@xynehq/jaf 0.1.2

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 (279) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +596 -0
  3. package/dist/a2a/agent-card.d.ts +28 -0
  4. package/dist/a2a/agent-card.d.ts.map +1 -0
  5. package/dist/a2a/agent-card.js +250 -0
  6. package/dist/a2a/agent-card.js.map +1 -0
  7. package/dist/a2a/agent.d.ts +38 -0
  8. package/dist/a2a/agent.d.ts.map +1 -0
  9. package/dist/a2a/agent.js +223 -0
  10. package/dist/a2a/agent.js.map +1 -0
  11. package/dist/a2a/client.d.ts +35 -0
  12. package/dist/a2a/client.d.ts.map +1 -0
  13. package/dist/a2a/client.js +337 -0
  14. package/dist/a2a/client.js.map +1 -0
  15. package/dist/a2a/examples/client-example.d.ts +104 -0
  16. package/dist/a2a/examples/client-example.d.ts.map +1 -0
  17. package/dist/a2a/examples/client-example.js +232 -0
  18. package/dist/a2a/examples/client-example.js.map +1 -0
  19. package/dist/a2a/examples/server-example.d.ts +9 -0
  20. package/dist/a2a/examples/server-example.d.ts.map +1 -0
  21. package/dist/a2a/examples/server-example.js +209 -0
  22. package/dist/a2a/examples/server-example.js.map +1 -0
  23. package/dist/a2a/examples/weather-agent.d.ts +8 -0
  24. package/dist/a2a/examples/weather-agent.d.ts.map +1 -0
  25. package/dist/a2a/examples/weather-agent.js +232 -0
  26. package/dist/a2a/examples/weather-agent.js.map +1 -0
  27. package/dist/a2a/executor.d.ts +43 -0
  28. package/dist/a2a/executor.d.ts.map +1 -0
  29. package/dist/a2a/executor.js +507 -0
  30. package/dist/a2a/executor.js.map +1 -0
  31. package/dist/a2a/index.d.ts +378 -0
  32. package/dist/a2a/index.d.ts.map +1 -0
  33. package/dist/a2a/index.js +72 -0
  34. package/dist/a2a/index.js.map +1 -0
  35. package/dist/a2a/memory/cleanup.d.ts +58 -0
  36. package/dist/a2a/memory/cleanup.d.ts.map +1 -0
  37. package/dist/a2a/memory/cleanup.js +281 -0
  38. package/dist/a2a/memory/cleanup.js.map +1 -0
  39. package/dist/a2a/memory/factory.d.ts +38 -0
  40. package/dist/a2a/memory/factory.d.ts.map +1 -0
  41. package/dist/a2a/memory/factory.js +369 -0
  42. package/dist/a2a/memory/factory.js.map +1 -0
  43. package/dist/a2a/memory/index.d.ts +13 -0
  44. package/dist/a2a/memory/index.d.ts.map +1 -0
  45. package/dist/a2a/memory/index.js +16 -0
  46. package/dist/a2a/memory/index.js.map +1 -0
  47. package/dist/a2a/memory/providers/in-memory.d.ts +10 -0
  48. package/dist/a2a/memory/providers/in-memory.d.ts.map +1 -0
  49. package/dist/a2a/memory/providers/in-memory.js +539 -0
  50. package/dist/a2a/memory/providers/in-memory.js.map +1 -0
  51. package/dist/a2a/memory/providers/postgres.d.ts +10 -0
  52. package/dist/a2a/memory/providers/postgres.d.ts.map +1 -0
  53. package/dist/a2a/memory/providers/postgres.js +404 -0
  54. package/dist/a2a/memory/providers/postgres.js.map +1 -0
  55. package/dist/a2a/memory/providers/redis.d.ts +10 -0
  56. package/dist/a2a/memory/providers/redis.d.ts.map +1 -0
  57. package/dist/a2a/memory/providers/redis.js +435 -0
  58. package/dist/a2a/memory/providers/redis.js.map +1 -0
  59. package/dist/a2a/memory/serialization.d.ts +53 -0
  60. package/dist/a2a/memory/serialization.d.ts.map +1 -0
  61. package/dist/a2a/memory/serialization.js +233 -0
  62. package/dist/a2a/memory/serialization.js.map +1 -0
  63. package/dist/a2a/memory/types.d.ts +395 -0
  64. package/dist/a2a/memory/types.d.ts.map +1 -0
  65. package/dist/a2a/memory/types.js +85 -0
  66. package/dist/a2a/memory/types.js.map +1 -0
  67. package/dist/a2a/protocol.d.ts +38 -0
  68. package/dist/a2a/protocol.d.ts.map +1 -0
  69. package/dist/a2a/protocol.js +211 -0
  70. package/dist/a2a/protocol.js.map +1 -0
  71. package/dist/a2a/server.d.ts +343 -0
  72. package/dist/a2a/server.d.ts.map +1 -0
  73. package/dist/a2a/server.js +362 -0
  74. package/dist/a2a/server.js.map +1 -0
  75. package/dist/a2a/types.d.ts +730 -0
  76. package/dist/a2a/types.d.ts.map +1 -0
  77. package/dist/a2a/types.js +73 -0
  78. package/dist/a2a/types.js.map +1 -0
  79. package/dist/adk/agents/index.d.ts +48 -0
  80. package/dist/adk/agents/index.d.ts.map +1 -0
  81. package/dist/adk/agents/index.js +277 -0
  82. package/dist/adk/agents/index.js.map +1 -0
  83. package/dist/adk/artifacts/index.d.ts +62 -0
  84. package/dist/adk/artifacts/index.d.ts.map +1 -0
  85. package/dist/adk/artifacts/index.js +394 -0
  86. package/dist/adk/artifacts/index.js.map +1 -0
  87. package/dist/adk/config/llm-config.d.ts +75 -0
  88. package/dist/adk/config/llm-config.d.ts.map +1 -0
  89. package/dist/adk/config/llm-config.js +422 -0
  90. package/dist/adk/config/llm-config.js.map +1 -0
  91. package/dist/adk/content/index.d.ts +58 -0
  92. package/dist/adk/content/index.d.ts.map +1 -0
  93. package/dist/adk/content/index.js +220 -0
  94. package/dist/adk/content/index.js.map +1 -0
  95. package/dist/adk/examples/advanced-features.d.ts +22 -0
  96. package/dist/adk/examples/advanced-features.d.ts.map +1 -0
  97. package/dist/adk/examples/advanced-features.js +380 -0
  98. package/dist/adk/examples/advanced-features.js.map +1 -0
  99. package/dist/adk/examples/basic-agent.d.ts +28 -0
  100. package/dist/adk/examples/basic-agent.d.ts.map +1 -0
  101. package/dist/adk/examples/basic-agent.js +207 -0
  102. package/dist/adk/examples/basic-agent.js.map +1 -0
  103. package/dist/adk/examples/multi-agent.d.ts +24 -0
  104. package/dist/adk/examples/multi-agent.d.ts.map +1 -0
  105. package/dist/adk/examples/multi-agent.js +321 -0
  106. package/dist/adk/examples/multi-agent.js.map +1 -0
  107. package/dist/adk/examples/streaming-example.d.ts +9 -0
  108. package/dist/adk/examples/streaming-example.d.ts.map +1 -0
  109. package/dist/adk/examples/streaming-example.js +193 -0
  110. package/dist/adk/examples/streaming-example.js.map +1 -0
  111. package/dist/adk/index.d.ts +65 -0
  112. package/dist/adk/index.d.ts.map +1 -0
  113. package/dist/adk/index.js +251 -0
  114. package/dist/adk/index.js.map +1 -0
  115. package/dist/adk/models.d.ts +338 -0
  116. package/dist/adk/models.d.ts.map +1 -0
  117. package/dist/adk/models.js +466 -0
  118. package/dist/adk/models.js.map +1 -0
  119. package/dist/adk/providers/error-handler.d.ts +100 -0
  120. package/dist/adk/providers/error-handler.d.ts.map +1 -0
  121. package/dist/adk/providers/error-handler.js +289 -0
  122. package/dist/adk/providers/error-handler.js.map +1 -0
  123. package/dist/adk/providers/llm-service.d.ts +41 -0
  124. package/dist/adk/providers/llm-service.d.ts.map +1 -0
  125. package/dist/adk/providers/llm-service.js +520 -0
  126. package/dist/adk/providers/llm-service.js.map +1 -0
  127. package/dist/adk/providers/type-converters.d.ts +34 -0
  128. package/dist/adk/providers/type-converters.d.ts.map +1 -0
  129. package/dist/adk/providers/type-converters.js +436 -0
  130. package/dist/adk/providers/type-converters.js.map +1 -0
  131. package/dist/adk/runners/index.d.ts +33 -0
  132. package/dist/adk/runners/index.d.ts.map +1 -0
  133. package/dist/adk/runners/index.js +466 -0
  134. package/dist/adk/runners/index.js.map +1 -0
  135. package/dist/adk/schemas/index.d.ts +85 -0
  136. package/dist/adk/schemas/index.d.ts.map +1 -0
  137. package/dist/adk/schemas/index.js +363 -0
  138. package/dist/adk/schemas/index.js.map +1 -0
  139. package/dist/adk/sessions/examples/session-provider-usage.d.ts +10 -0
  140. package/dist/adk/sessions/examples/session-provider-usage.d.ts.map +1 -0
  141. package/dist/adk/sessions/examples/session-provider-usage.js +145 -0
  142. package/dist/adk/sessions/examples/session-provider-usage.js.map +1 -0
  143. package/dist/adk/sessions/index.d.ts +53 -0
  144. package/dist/adk/sessions/index.d.ts.map +1 -0
  145. package/dist/adk/sessions/index.js +451 -0
  146. package/dist/adk/sessions/index.js.map +1 -0
  147. package/dist/adk/sessions/postgres-provider.d.ts +22 -0
  148. package/dist/adk/sessions/postgres-provider.d.ts.map +1 -0
  149. package/dist/adk/sessions/postgres-provider.js +293 -0
  150. package/dist/adk/sessions/postgres-provider.js.map +1 -0
  151. package/dist/adk/sessions/redis-provider.d.ts +19 -0
  152. package/dist/adk/sessions/redis-provider.d.ts.map +1 -0
  153. package/dist/adk/sessions/redis-provider.js +237 -0
  154. package/dist/adk/sessions/redis-provider.js.map +1 -0
  155. package/dist/adk/streaming/index.d.ts +76 -0
  156. package/dist/adk/streaming/index.d.ts.map +1 -0
  157. package/dist/adk/streaming/index.js +419 -0
  158. package/dist/adk/streaming/index.js.map +1 -0
  159. package/dist/adk/tools/index.d.ts +27 -0
  160. package/dist/adk/tools/index.d.ts.map +1 -0
  161. package/dist/adk/tools/index.js +506 -0
  162. package/dist/adk/tools/index.js.map +1 -0
  163. package/dist/adk/types.d.ts +351 -0
  164. package/dist/adk/types.d.ts.map +1 -0
  165. package/dist/adk/types.js +107 -0
  166. package/dist/adk/types.js.map +1 -0
  167. package/dist/core/engine.d.ts +3 -0
  168. package/dist/core/engine.d.ts.map +1 -0
  169. package/dist/core/engine.js +438 -0
  170. package/dist/core/engine.js.map +1 -0
  171. package/dist/core/errors.d.ts +8 -0
  172. package/dist/core/errors.d.ts.map +1 -0
  173. package/dist/core/errors.js +84 -0
  174. package/dist/core/errors.js.map +1 -0
  175. package/dist/core/tool-results.d.ts +57 -0
  176. package/dist/core/tool-results.d.ts.map +1 -0
  177. package/dist/core/tool-results.js +133 -0
  178. package/dist/core/tool-results.js.map +1 -0
  179. package/dist/core/tracing.d.ts +32 -0
  180. package/dist/core/tracing.d.ts.map +1 -0
  181. package/dist/core/tracing.js +132 -0
  182. package/dist/core/tracing.js.map +1 -0
  183. package/dist/core/types.d.ts +165 -0
  184. package/dist/core/types.d.ts.map +1 -0
  185. package/dist/core/types.js +3 -0
  186. package/dist/core/types.js.map +1 -0
  187. package/dist/demo/agents.d.ts +23 -0
  188. package/dist/demo/agents.d.ts.map +1 -0
  189. package/dist/demo/agents.js +69 -0
  190. package/dist/demo/agents.js.map +1 -0
  191. package/dist/demo/index.d.ts +2 -0
  192. package/dist/demo/index.d.ts.map +1 -0
  193. package/dist/demo/index.js +250 -0
  194. package/dist/demo/index.js.map +1 -0
  195. package/dist/demo/mock-provider.d.ts +22 -0
  196. package/dist/demo/mock-provider.d.ts.map +1 -0
  197. package/dist/demo/mock-provider.js +138 -0
  198. package/dist/demo/mock-provider.js.map +1 -0
  199. package/dist/demo/tools.d.ts +14 -0
  200. package/dist/demo/tools.d.ts.map +1 -0
  201. package/dist/demo/tools.js +115 -0
  202. package/dist/demo/tools.js.map +1 -0
  203. package/dist/index.d.ts +20 -0
  204. package/dist/index.d.ts.map +1 -0
  205. package/dist/index.js +30 -0
  206. package/dist/index.js.map +1 -0
  207. package/dist/memory/factory.d.ts +22 -0
  208. package/dist/memory/factory.d.ts.map +1 -0
  209. package/dist/memory/factory.js +88 -0
  210. package/dist/memory/factory.js.map +1 -0
  211. package/dist/memory/providers/in-memory.d.ts +7 -0
  212. package/dist/memory/providers/in-memory.d.ts.map +1 -0
  213. package/dist/memory/providers/in-memory.js +287 -0
  214. package/dist/memory/providers/in-memory.js.map +1 -0
  215. package/dist/memory/providers/postgres.d.ts +15 -0
  216. package/dist/memory/providers/postgres.d.ts.map +1 -0
  217. package/dist/memory/providers/postgres.js +495 -0
  218. package/dist/memory/providers/postgres.js.map +1 -0
  219. package/dist/memory/providers/redis.d.ts +18 -0
  220. package/dist/memory/providers/redis.d.ts.map +1 -0
  221. package/dist/memory/providers/redis.js +354 -0
  222. package/dist/memory/providers/redis.js.map +1 -0
  223. package/dist/memory/types.d.ts +296 -0
  224. package/dist/memory/types.d.ts.map +1 -0
  225. package/dist/memory/types.js +93 -0
  226. package/dist/memory/types.js.map +1 -0
  227. package/dist/policies/handoff.d.ts +16 -0
  228. package/dist/policies/handoff.d.ts.map +1 -0
  229. package/dist/policies/handoff.js +20 -0
  230. package/dist/policies/handoff.js.map +1 -0
  231. package/dist/policies/validation.d.ts +14 -0
  232. package/dist/policies/validation.d.ts.map +1 -0
  233. package/dist/policies/validation.js +92 -0
  234. package/dist/policies/validation.js.map +1 -0
  235. package/dist/providers/mcp.d.ts +17 -0
  236. package/dist/providers/mcp.d.ts.map +1 -0
  237. package/dist/providers/mcp.js +111 -0
  238. package/dist/providers/mcp.js.map +1 -0
  239. package/dist/providers/model.d.ts +3 -0
  240. package/dist/providers/model.d.ts.map +1 -0
  241. package/dist/providers/model.js +113 -0
  242. package/dist/providers/model.js.map +1 -0
  243. package/dist/server/index.d.ts +35 -0
  244. package/dist/server/index.d.ts.map +1 -0
  245. package/dist/server/index.js +66 -0
  246. package/dist/server/index.js.map +1 -0
  247. package/dist/server/server.d.ts +12 -0
  248. package/dist/server/server.d.ts.map +1 -0
  249. package/dist/server/server.js +394 -0
  250. package/dist/server/server.js.map +1 -0
  251. package/dist/server/types.d.ts +456 -0
  252. package/dist/server/types.d.ts.map +1 -0
  253. package/dist/server/types.js +75 -0
  254. package/dist/server/types.js.map +1 -0
  255. package/dist/test-utils/db-setup.d.ts +34 -0
  256. package/dist/test-utils/db-setup.d.ts.map +1 -0
  257. package/dist/test-utils/db-setup.js +149 -0
  258. package/dist/test-utils/db-setup.js.map +1 -0
  259. package/dist/utils/logger.d.ts +63 -0
  260. package/dist/utils/logger.d.ts.map +1 -0
  261. package/dist/utils/logger.js +199 -0
  262. package/dist/utils/logger.js.map +1 -0
  263. package/dist/utils/safe-math.d.ts +31 -0
  264. package/dist/utils/safe-math.d.ts.map +1 -0
  265. package/dist/utils/safe-math.js +86 -0
  266. package/dist/utils/safe-math.js.map +1 -0
  267. package/dist/visualization/example.d.ts +9 -0
  268. package/dist/visualization/example.d.ts.map +1 -0
  269. package/dist/visualization/example.js +236 -0
  270. package/dist/visualization/example.js.map +1 -0
  271. package/dist/visualization/graphviz.d.ts +42 -0
  272. package/dist/visualization/graphviz.d.ts.map +1 -0
  273. package/dist/visualization/graphviz.js +403 -0
  274. package/dist/visualization/graphviz.js.map +1 -0
  275. package/dist/visualization/index.d.ts +10 -0
  276. package/dist/visualization/index.d.ts.map +1 -0
  277. package/dist/visualization/index.js +12 -0
  278. package/dist/visualization/index.js.map +1 -0
  279. package/package.json +99 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 Xyne HQ
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,596 @@
1
+ # Juspay Agent Framework (JAF)
2
+
3
+ [![CI](https://github.com/xynehq/jaf/workflows/CI/badge.svg)](https://github.com/xynehq/jaf/actions)
4
+ [![Documentation](https://img.shields.io/badge/docs-mkdocs-blue)](https://xynehq.github.io/jaf/)
5
+ [![npm version](https://img.shields.io/npm/v/@xynehq/jaf.svg)](https://www.npmjs.com/package/@xynehq/jaf)
6
+ [![npm downloads](https://img.shields.io/npm/dm/@xynehq/jaf.svg)](https://www.npmjs.com/package/@xynehq/jaf)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
8
+
9
+ ![Juspay Agent Framework](/docs/cover.png?raw=true "Juspay Agent Framework")
10
+
11
+ A purely functional agent framework built on immutable state, type safety, and composable policies. JAF enables building production-ready AI agent systems with built-in security, observability, and error handling.
12
+
13
+ ๐Ÿ“š **[Read the Documentation](https://xynehq.github.io/jaf/)**
14
+
15
+ ## ๐ŸŽฏ Core Philosophy
16
+
17
+ - **Immutability**: All core data structures are deeply `readonly`
18
+ - **Pure Functions**: Core logic expressed as pure, predictable functions
19
+ - **Effects at the Edge**: Side effects isolated in Provider modules
20
+ - **Composition over Configuration**: Build complex behavior by composing simple functions
21
+ - **Type-Safe by Design**: Leverages TypeScript's advanced features for compile-time safety
22
+ - **Functional Composition**: Complex behaviors built through function composition, not inheritance or mutation
23
+
24
+ ## ๐Ÿš€ Quick Start
25
+
26
+ ### Installation
27
+
28
+ ```bash
29
+ # Install from npm
30
+ npm install @xynehq/jaf
31
+
32
+ # Or using yarn
33
+ yarn add @xynehq/jaf
34
+
35
+ # Or using pnpm
36
+ pnpm add @xynehq/jaf
37
+ ```
38
+
39
+ ### Development Setup
40
+
41
+ ```bash
42
+ # Clone the repository
43
+ git clone https://github.com/xynehq/jaf.git
44
+ cd jaf
45
+
46
+ # Install dependencies
47
+ npm install
48
+
49
+ # Build the project
50
+ npm run build
51
+
52
+ # Run tests
53
+ npm test
54
+ ```
55
+
56
+ ## ๐Ÿ“ Project Structure
57
+
58
+ ```
59
+ src/
60
+ โ”œโ”€โ”€ core/ # Core framework types and engine
61
+ โ”‚ โ”œโ”€โ”€ engine.ts # Main execution engine
62
+ โ”‚ โ”œโ”€โ”€ errors.ts # Error handling and types
63
+ โ”‚ โ”œโ”€โ”€ tool-results.ts # Tool execution results
64
+ โ”‚ โ”œโ”€โ”€ tracing.ts # Event tracing system
65
+ โ”‚ โ””โ”€โ”€ types.ts # Core type definitions
66
+ โ”œโ”€โ”€ memory/ # Memory providers for conversation persistence
67
+ โ”‚ โ”œโ”€โ”€ factory.ts # Memory provider factory
68
+ โ”‚ โ”œโ”€โ”€ types.ts # Memory system types
69
+ โ”‚ โ””โ”€โ”€ providers/
70
+ โ”‚ โ”œโ”€โ”€ in-memory.ts # In-memory provider
71
+ โ”‚ โ”œโ”€โ”€ postgres.ts # PostgreSQL provider
72
+ โ”‚ โ””โ”€โ”€ redis.ts # Redis provider
73
+ โ”œโ”€โ”€ providers/ # External integrations
74
+ โ”‚ โ”œโ”€โ”€ mcp.ts # Model Context Protocol integration
75
+ โ”‚ โ””โ”€โ”€ model.ts # LLM provider integrations
76
+ โ”œโ”€โ”€ policies/ # Validation and security policies
77
+ โ”‚ โ”œโ”€โ”€ handoff.ts # Agent handoff policies
78
+ โ”‚ โ””โ”€โ”€ validation.ts # Input/output validation
79
+ โ”œโ”€โ”€ server/ # HTTP server implementation
80
+ โ”‚ โ”œโ”€โ”€ index.ts # Server entry point
81
+ โ”‚ โ”œโ”€โ”€ server.ts # Express server setup
82
+ โ”‚ โ””โ”€โ”€ types.ts # Server-specific types
83
+ โ”œโ”€โ”€ __tests__/ # Test suite
84
+ โ”‚ โ”œโ”€โ”€ engine.test.ts # Engine tests
85
+ โ”‚ โ””โ”€โ”€ validation.test.ts # Validation tests
86
+ โ””โ”€โ”€ index.ts # Main framework exports
87
+ examples/
88
+ โ”œโ”€โ”€ rag-demo/ # Vertex AI RAG integration demo
89
+ โ”‚ โ”œโ”€โ”€ index.ts # Demo entry point
90
+ โ”‚ โ”œโ”€โ”€ rag-agent.ts # RAG agent implementation
91
+ โ”‚ โ””โ”€โ”€ rag-tool.ts # RAG tool implementation
92
+ โ””โ”€โ”€ server-demo/ # Development server demo
93
+ โ””โ”€โ”€ index.ts # Server demo entry point
94
+ docs/ # Documentation
95
+ โ”œโ”€โ”€ getting-started.md
96
+ โ”œโ”€โ”€ core-concepts.md
97
+ โ”œโ”€โ”€ api-reference.md
98
+ โ”œโ”€โ”€ tools.md
99
+ โ”œโ”€โ”€ memory-system.md
100
+ โ”œโ”€โ”€ model-providers.md
101
+ โ”œโ”€โ”€ server-api.md
102
+ โ”œโ”€โ”€ examples.md
103
+ โ”œโ”€โ”€ deployment.md
104
+ โ””โ”€โ”€ troubleshooting.md
105
+ ```
106
+
107
+ ## ๐Ÿ—๏ธ Key Components
108
+
109
+ ### Core Types
110
+
111
+ ```typescript
112
+ import { z } from 'zod';
113
+ import { Agent, Tool, RunState, run } from '@xynehq/jaf';
114
+
115
+ // Define your context type
116
+ type MyContext = {
117
+ userId: string;
118
+ permissions: string[];
119
+ };
120
+
121
+ // Create a tool
122
+ const calculatorTool: Tool<{ expression: string }, MyContext> = {
123
+ schema: {
124
+ name: "calculate",
125
+ description: "Perform mathematical calculations",
126
+ parameters: z.object({
127
+ expression: z.string().describe("Math expression to evaluate")
128
+ }),
129
+ },
130
+ execute: async (args) => {
131
+ const result = eval(args.expression); // Don't do this in production!
132
+ return `${args.expression} = ${result}`;
133
+ },
134
+ };
135
+
136
+ // Define an agent
137
+ const mathAgent: Agent<MyContext, string> = {
138
+ name: 'MathTutor',
139
+ instructions: () => 'You are a helpful math tutor',
140
+ tools: [calculatorTool],
141
+ };
142
+ ```
143
+
144
+ ### Running the Framework
145
+
146
+ ```typescript
147
+ import { run, makeLiteLLMProvider } from '@xynehq/jaf';
148
+
149
+ const modelProvider = makeLiteLLMProvider('http://localhost:4000');
150
+ const agentRegistry = new Map([['MathTutor', mathAgent]]);
151
+
152
+ const config = {
153
+ agentRegistry,
154
+ modelProvider,
155
+ maxTurns: 10,
156
+ onEvent: (event) => console.log(event), // Real-time tracing
157
+ };
158
+
159
+ const initialState = {
160
+ runId: generateRunId(),
161
+ traceId: generateTraceId(),
162
+ messages: [{ role: 'user', content: 'What is 2 + 2?' }],
163
+ currentAgentName: 'MathTutor',
164
+ context: { userId: 'user123', permissions: ['user'] },
165
+ turnCount: 0,
166
+ };
167
+
168
+ const result = await run(initialState, config);
169
+ ```
170
+
171
+ ## ๐Ÿ”„ Function Composition
172
+
173
+ JAF emphasizes function composition to build complex behaviors from simple, reusable functions:
174
+
175
+ ### Composing Tools
176
+
177
+ ```typescript
178
+ import { createFunctionTool, composeTool, withRetry, withCache } from '@xynehq/jaf';
179
+
180
+ // Simple base tools
181
+ const fetchWeatherTool = createFunctionTool({
182
+ name: 'fetch_weather',
183
+ description: 'Fetch weather data',
184
+ execute: async ({ location }) => {
185
+ const response = await fetch(`/api/weather?location=${location}`);
186
+ return response.json();
187
+ },
188
+ parameters: [{ name: 'location', type: 'string', required: true }]
189
+ });
190
+
191
+ const formatTemperatureTool = createFunctionTool({
192
+ name: 'format_temp',
193
+ description: 'Format temperature reading',
194
+ execute: ({ temp, unit }) => `${temp}ยฐ${unit.toUpperCase()}`,
195
+ parameters: [
196
+ { name: 'temp', type: 'number', required: true },
197
+ { name: 'unit', type: 'string', required: true }
198
+ ]
199
+ });
200
+
201
+ // Compose tools with higher-order functions
202
+ const cachedWeatherTool = withCache(fetchWeatherTool, { ttl: 300000 }); // 5 min cache
203
+ const reliableWeatherTool = withRetry(cachedWeatherTool, { maxRetries: 3 });
204
+
205
+ // Chain tools together
206
+ const weatherReportTool = composeTool([
207
+ reliableWeatherTool,
208
+ formatTemperatureTool
209
+ ], 'weather_report', 'Get formatted weather report');
210
+ ```
211
+
212
+ ### Composing Validators
213
+
214
+ ```typescript
215
+ import { compose, createValidator } from '@xynehq/jaf';
216
+
217
+ // Base validators
218
+ const isPositive = createValidator<number>(
219
+ n => n > 0,
220
+ 'Value must be positive'
221
+ );
222
+
223
+ const isInteger = createValidator<number>(
224
+ n => Number.isInteger(n),
225
+ 'Value must be an integer'
226
+ );
227
+
228
+ const isInRange = (min: number, max: number) => createValidator<number>(
229
+ n => n >= min && n <= max,
230
+ `Value must be between ${min} and ${max}`
231
+ );
232
+
233
+ // Compose validators
234
+ const validateAge = compose(
235
+ isPositive,
236
+ isInteger,
237
+ isInRange(0, 150)
238
+ );
239
+
240
+ // Use in tool parameters
241
+ const ageTool = createFunctionTool({
242
+ name: 'process_age',
243
+ description: 'Process age data',
244
+ execute: ({ age }) => `Age ${age} is valid`,
245
+ parameters: [{
246
+ name: 'age',
247
+ type: 'number',
248
+ required: true,
249
+ validate: validateAge
250
+ }]
251
+ });
252
+ ```
253
+
254
+ ### Composing Agent Behaviors
255
+
256
+ ```typescript
257
+ import { createAgent, withMiddleware, withFallback } from '@xynehq/jaf';
258
+
259
+ // Base agents
260
+ const primaryAgent = createAgent({
261
+ name: 'primary',
262
+ model: 'gpt-4',
263
+ instruction: 'Primary processing agent',
264
+ tools: [calculatorTool]
265
+ });
266
+
267
+ const fallbackAgent = createAgent({
268
+ name: 'fallback',
269
+ model: 'gpt-3.5-turbo',
270
+ instruction: 'Fallback processing agent',
271
+ tools: [simpleMathTool]
272
+ });
273
+
274
+ // Compose with middleware
275
+ const loggingMiddleware = (agent) => ({
276
+ ...agent,
277
+ execute: async (input) => {
278
+ console.log(`[${agent.name}] Processing:`, input);
279
+ const result = await agent.execute(input);
280
+ console.log(`[${agent.name}] Result:`, result);
281
+ return result;
282
+ }
283
+ });
284
+
285
+ const rateLimitMiddleware = (limit: number) => (agent) => {
286
+ let count = 0;
287
+ const resetTime = Date.now() + 60000;
288
+
289
+ return {
290
+ ...agent,
291
+ execute: async (input) => {
292
+ if (Date.now() > resetTime) {
293
+ count = 0;
294
+ }
295
+ if (count >= limit) {
296
+ throw new Error('Rate limit exceeded');
297
+ }
298
+ count++;
299
+ return agent.execute(input);
300
+ }
301
+ };
302
+ };
303
+
304
+ // Compose everything
305
+ const productionAgent = compose(
306
+ withFallback(fallbackAgent),
307
+ withMiddleware(loggingMiddleware),
308
+ withMiddleware(rateLimitMiddleware(100))
309
+ )(primaryAgent);
310
+ ```
311
+
312
+ ### Composing Memory Providers
313
+
314
+ ```typescript
315
+ import { composeMemoryProviders, createCacheLayer } from '@xynehq/jaf';
316
+
317
+ // Layer memory providers for performance and reliability
318
+ const memoryProvider = composeMemoryProviders([
319
+ createCacheLayer({ maxSize: 100 }), // L1: In-memory cache
320
+ createRedisProvider({ ttl: 3600 }), // L2: Redis cache
321
+ createPostgresProvider({ table: 'chat' }) // L3: Persistent storage
322
+ ]);
323
+
324
+ // The composed provider automatically:
325
+ // - Reads from the fastest available layer
326
+ // - Writes to all layers
327
+ // - Falls back on layer failure
328
+ ```
329
+
330
+ ## ๐Ÿ›ก๏ธ Security & Validation
331
+
332
+ ### Composable Validation Policies
333
+
334
+ ```typescript
335
+ import { createPathValidator, createPermissionValidator, composeValidations } from '@xynehq/jaf';
336
+
337
+ // Create individual validators
338
+ const pathValidator = createPathValidator(['/shared', '/public']);
339
+ const permissionValidator = createPermissionValidator('admin', ctx => ctx);
340
+
341
+ // Compose them
342
+ const combinedValidator = composeValidations(pathValidator, permissionValidator);
343
+
344
+ // Apply to tools
345
+ const secureFileTool = withValidation(baseFileTool, combinedValidator);
346
+ ```
347
+
348
+ ### Guardrails
349
+
350
+ ```typescript
351
+ import { createContentFilter, createRateLimiter } from '@xynehq/jaf';
352
+
353
+ const config = {
354
+ // ... other config
355
+ initialInputGuardrails: [
356
+ createContentFilter(),
357
+ createRateLimiter(10, 60000, input => 'global')
358
+ ],
359
+ finalOutputGuardrails: [
360
+ createContentFilter()
361
+ ],
362
+ };
363
+ ```
364
+
365
+ ## ๐Ÿ”— Agent Handoffs
366
+
367
+ ```typescript
368
+ import { handoffTool } from '@xynehq/jaf';
369
+
370
+ const triageAgent: Agent<Context, { agentName: string }> = {
371
+ name: 'TriageAgent',
372
+ instructions: () => 'Route requests to specialized agents',
373
+ tools: [handoffTool],
374
+ handoffs: ['MathTutor', 'FileManager'], // Allowed handoff targets
375
+ outputCodec: z.object({
376
+ agentName: z.enum(['MathTutor', 'FileManager'])
377
+ }),
378
+ };
379
+ ```
380
+
381
+ ## ๐Ÿ“Š Observability
382
+
383
+ ### Real-time Tracing
384
+
385
+ ```typescript
386
+ import { ConsoleTraceCollector, FileTraceCollector } from '@xynehq/jaf';
387
+
388
+ // Console logging
389
+ const consoleTracer = new ConsoleTraceCollector();
390
+
391
+ // File logging
392
+ const fileTracer = new FileTraceCollector('./traces.log');
393
+
394
+ // Composite tracing
395
+ const tracer = createCompositeTraceCollector(consoleTracer, fileTracer);
396
+
397
+ const config = {
398
+ // ... other config
399
+ onEvent: tracer.collect.bind(tracer),
400
+ };
401
+ ```
402
+
403
+ ### Error Handling
404
+
405
+ ```typescript
406
+ import { JAFErrorHandler } from '@xynehq/jaf';
407
+
408
+ if (result.outcome.status === 'error') {
409
+ const formattedError = JAFErrorHandler.format(result.outcome.error);
410
+ const isRetryable = JAFErrorHandler.isRetryable(result.outcome.error);
411
+ const severity = JAFErrorHandler.getSeverity(result.outcome.error);
412
+
413
+ console.error(`[${severity}] ${formattedError} (retryable: ${isRetryable})`);
414
+ }
415
+ ```
416
+
417
+ ## ๐Ÿ”Œ Provider Integrations
418
+
419
+ ### LiteLLM Provider
420
+
421
+ ```typescript
422
+ import { makeLiteLLMProvider } from '@xynehq/jaf';
423
+
424
+ // Connect to LiteLLM proxy for 100+ model support
425
+ const modelProvider = makeLiteLLMProvider(
426
+ 'http://localhost:4000', // LiteLLM proxy URL
427
+ 'your-api-key' // Optional API key
428
+ );
429
+ ```
430
+
431
+ ### MCP (Model Context Protocol) Tools
432
+
433
+ ```typescript
434
+ import { makeMCPClient, mcpToolToJAFTool } from '@xynehq/jaf';
435
+
436
+ // Connect to MCP server
437
+ const mcpClient = await makeMCPClient('python', ['-m', 'mcp_server']);
438
+
439
+ // Get available tools
440
+ const mcpTools = await mcpClient.listTools();
441
+
442
+ // Convert to JAF tools with validation
443
+ const jafTools = mcpTools.map(tool =>
444
+ mcpToolToJAFTool(mcpClient, tool, myValidationPolicy)
445
+ );
446
+ ```
447
+
448
+ ## ๐Ÿš€ Development Server
449
+
450
+ JAF includes a built-in development server for testing agents locally via HTTP endpoints:
451
+
452
+ ```typescript
453
+ import { runServer, makeLiteLLMProvider, createInMemoryProvider } from '@xynehq/jaf';
454
+
455
+ const myAgent = {
456
+ name: 'MyAgent',
457
+ instructions: 'You are a helpful assistant',
458
+ tools: [calculatorTool, greetingTool]
459
+ };
460
+
461
+ const modelProvider = makeLiteLLMProvider('http://localhost:4000');
462
+ const memoryProvider = createInMemoryProvider();
463
+
464
+ // Start server on port 3000
465
+ const server = await runServer(
466
+ [myAgent],
467
+ { modelProvider },
468
+ { port: 3000, defaultMemoryProvider: memoryProvider }
469
+ );
470
+ ```
471
+
472
+ Server provides RESTful endpoints:
473
+ - `GET /health` - Health check
474
+ - `GET /agents` - List available agents
475
+ - `POST /chat` - General chat endpoint
476
+ - `POST /agents/{name}/chat` - Agent-specific endpoint
477
+
478
+ ## ๐Ÿ“š Documentation
479
+
480
+ Comprehensive documentation is available in the [`/docs`](./docs) folder:
481
+
482
+ - **[Getting Started](./docs/getting-started.md)** - Installation, basic concepts, and first agent
483
+ - **[Core Concepts](./docs/core-concepts.md)** - JAF's functional architecture and principles
484
+ - **[API Reference](./docs/api-reference.md)** - Complete TypeScript API documentation
485
+ - **[ADK Layer](./docs/adk-layer.md)** - Agent Development Kit for simplified agent creation
486
+ - **[A2A Protocol](./docs/a2a-protocol.md)** - Agent-to-Agent communication and task management
487
+ - **[Tools](./docs/tools.md)** - Building robust tools with validation and error handling
488
+ - **[Memory System](./docs/memory-system.md)** - Conversation persistence (in-memory, Redis, PostgreSQL)
489
+ - **[Model Providers](./docs/model-providers.md)** - LLM integration and configuration
490
+ - **[Server & API](./docs/server-api.md)** - HTTP server setup and REST API
491
+ - **[Visualization](./docs/visualization.md)** - Generate Graphviz diagrams of agents and tools
492
+ - **[Examples](./docs/examples.md)** - Tutorials and integration patterns
493
+ - **[Deployment](./docs/deployment.md)** - Production deployment guide
494
+ - **[Troubleshooting](./docs/troubleshooting.md)** - Common issues and debugging
495
+
496
+ ### ๐Ÿ“– Documentation Website
497
+
498
+ Browse the full documentation online at **[https://xynehq.github.io/jaf/](https://xynehq.github.io/jaf/)**
499
+
500
+ The documentation site features:
501
+ - ๐Ÿ” Full-text search
502
+ - ๐ŸŒ“ Dark/light mode toggle
503
+ - ๐Ÿ“ฑ Mobile-friendly responsive design
504
+ - ๐Ÿ”— Deep linking to sections
505
+ - ๐Ÿ“‹ Code block copy buttons
506
+
507
+ #### Running Documentation Locally
508
+
509
+ ```bash
510
+ # Install documentation dependencies
511
+ pip install -r requirements.txt
512
+
513
+ # Run local documentation server
514
+ mkdocs serve
515
+ # Visit http://127.0.0.1:8000
516
+
517
+ # Or use the convenience script
518
+ ./docs/serve.sh
519
+ ```
520
+
521
+ ## ๐ŸŽฎ Example Applications
522
+
523
+ Explore the example applications to see the framework in action:
524
+
525
+ ### Development Server Demo
526
+
527
+ ```bash
528
+ cd examples/server-demo
529
+ npm install
530
+ npm run dev
531
+ ```
532
+
533
+ The server demo showcases:
534
+ - โœ… Multiple agent types with different capabilities
535
+ - โœ… RESTful API with type-safe validation
536
+ - โœ… Tool integration (calculator, greeting)
537
+ - โœ… Real-time tracing and error handling
538
+ - โœ… CORS support and graceful shutdown
539
+
540
+ ### Vertex AI RAG Demo
541
+
542
+ ```bash
543
+ cd examples/rag-demo
544
+ npm install
545
+ npm run dev
546
+ ```
547
+
548
+ The RAG demo showcases:
549
+ - โœ… Real Vertex AI RAG integration with Google GenAI SDK
550
+ - โœ… Permission-based access control
551
+ - โœ… Real-time streaming responses with source attribution
552
+ - โœ… Performance metrics and comprehensive error handling
553
+ - โœ… JAF framework orchestration with type-safe tools
554
+ - โœ… Multi-turn conversations with observability
555
+
556
+ ## ๐Ÿงช Testing
557
+
558
+ ```bash
559
+ npm test # Run tests
560
+ npm run lint # Lint code
561
+ npm run typecheck # Type checking
562
+ ```
563
+
564
+ ## ๐Ÿ›๏ธ Architecture Principles
565
+
566
+ ### Immutable State Machine
567
+ - All state transformations create new state objects
568
+ - No mutation of existing data structures
569
+ - Predictable, testable state transitions
570
+
571
+ ### Type Safety
572
+ - Runtime validation with Zod schemas
573
+ - Compile-time safety with TypeScript
574
+ - Branded types prevent ID mixing
575
+
576
+ ### Pure Functions
577
+ - Core logic is side-effect free
578
+ - Easy to test and reason about
579
+ - Deterministic behavior
580
+
581
+ ### Effect Isolation
582
+ - Side effects only in Provider modules
583
+ - Clear boundaries between pure and impure code
584
+ - Easier mocking and testing
585
+
586
+ ## ๐Ÿค Contributing
587
+
588
+ 1. Fork the repository
589
+ 2. Create a feature branch
590
+ 3. Add tests for new functionality
591
+ 4. Run the test suite
592
+ 5. Submit a pull request
593
+
594
+ ---
595
+
596
+ **JAF** - Building the future of functional AI agent systems ๐Ÿš€
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Pure functional Agent Card generation
3
+ * Transforms JAF agents into A2A Agent Cards
4
+ */
5
+ import type { AgentCard, AgentSkill, A2AAgent, A2AServerConfig } from './types.js';
6
+ export declare const generateAgentCard: (config: A2AServerConfig["agentCard"], agents: ReadonlyMap<string, A2AAgent>, baseUrl?: string) => AgentCard;
7
+ export declare const generateSkillsFromAgents: (agents: ReadonlyMap<string, A2AAgent>) => readonly AgentSkill[];
8
+ export declare const generateExamplesForAgent: (agent: A2AAgent) => readonly string[];
9
+ export declare const generateExamplesForTool: (tool: any) => readonly string[];
10
+ export declare const generateSecuritySchemes: () => Readonly<Record<string, any>>;
11
+ export declare const generateSecurityRequirements: () => readonly Record<string, readonly string[]>[];
12
+ export declare const generateAgentCardForAgent: (agentName: string, agent: A2AAgent, config?: Partial<A2AServerConfig["agentCard"]>, baseUrl?: string) => AgentCard;
13
+ export declare const validateAgentCard: (card: AgentCard) => {
14
+ isValid: boolean;
15
+ errors: readonly string[];
16
+ };
17
+ export declare const createMinimalAgentCard: (name: string, description: string, url?: string) => AgentCard;
18
+ export declare const mergeAgentCards: (baseCard: AgentCard, ...additionalCards: AgentCard[]) => AgentCard;
19
+ export declare const createAgentCardFromConfig: (config: {
20
+ readonly name: string;
21
+ readonly description: string;
22
+ readonly agents: ReadonlyMap<string, A2AAgent>;
23
+ readonly baseUrl?: string;
24
+ readonly version?: string;
25
+ readonly provider?: AgentCard["provider"];
26
+ readonly capabilities?: Partial<AgentCard["capabilities"]>;
27
+ }) => AgentCard;
28
+ //# sourceMappingURL=agent-card.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent-card.d.ts","sourceRoot":"","sources":["../../src/a2a/agent-card.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGnF,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,eAAe,CAAC,WAAW,CAAC,EACpC,QAAQ,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,EACrC,UAAS,MAAgC,KACxC,SAkBD,CAAC;AAGH,eAAO,MAAM,wBAAwB,GACnC,QAAQ,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,KACpC,SAAS,UAAU,EAkCrB,CAAC;AAGF,eAAO,MAAM,wBAAwB,GAAI,OAAO,QAAQ,KAAG,SAAS,MAAM,EAYzE,CAAC;AAGF,eAAO,MAAM,uBAAuB,GAAI,MAAM,GAAG,KAAG,SAAS,MAAM,EAIlE,CAAC;AAGF,eAAO,MAAM,uBAAuB,QAAO,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAYrE,CAAC;AAGH,eAAO,MAAM,4BAA4B,QAAO,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,EAOzF,CAAC;AAGF,eAAO,MAAM,yBAAyB,GACpC,WAAW,MAAM,EACjB,OAAO,QAAQ,EACf,SAAQ,OAAO,CAAC,eAAe,CAAC,WAAW,CAAC,CAAM,EAClD,UAAS,MAAgC,KACxC,SAcF,CAAC;AAGF,eAAO,MAAM,iBAAiB,GAAI,MAAM,SAAS,KAAG;IAClD,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CA+D3B,CAAC;AAaF,eAAO,MAAM,sBAAsB,GACjC,MAAM,MAAM,EACZ,aAAa,MAAM,EACnB,MAAK,MAAoC,KACxC,SAqBD,CAAC;AAGH,eAAO,MAAM,eAAe,GAC1B,UAAU,SAAS,EACnB,GAAG,iBAAiB,SAAS,EAAE,KAC9B,SAgCF,CAAC;AAGF,eAAO,MAAM,yBAAyB,GAAI,QAAQ;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC;IAC1C,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC;CAC5D,KAAG,SAwBH,CAAC"}