versionhq 1.2.1.22__tar.gz → 1.2.2.0__tar.gz

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 (151) hide show
  1. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/PKG-INFO +8 -7
  2. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/README.md +7 -6
  3. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/core/agent/config.md +0 -3
  4. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/core/agent/task-handling.md +4 -8
  5. versionhq-1.2.2.0/docs/core/agent-network/config.md +6 -0
  6. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/core/agent-network/index.md +1 -1
  7. versionhq-1.2.2.0/docs/core/agent-network/ref.md +54 -0
  8. versionhq-1.2.2.0/docs/core/agent-network/task-handling.md +6 -0
  9. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/core/task/evaluation.md +0 -2
  10. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/core/task/index.md +1 -1
  11. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/core/task/task-execution.md +6 -10
  12. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/core/task/task-ref.md +1 -0
  13. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/core/tool.md +20 -41
  14. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/quickstart.md +2 -2
  15. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/stylesheets/main.css +2 -2
  16. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/mkdocs.yml +3 -0
  17. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/pyproject.toml +1 -1
  18. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/__init__.py +3 -4
  19. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/_utils/__init__.py +1 -1
  20. versionhq-1.2.2.0/src/versionhq/_utils/usage_metrics.py +55 -0
  21. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/agent/inhouse_agents.py +5 -1
  22. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/agent/model.py +4 -37
  23. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/agent_network/model.py +193 -189
  24. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/memory/model.py +4 -2
  25. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/storage/task_output_storage.py +51 -16
  26. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/storage/utils.py +1 -0
  27. versionhq-1.2.2.0/src/versionhq/task/TEMPLATES/Description.py +10 -0
  28. versionhq-1.2.1.22/src/versionhq/task/evaluate.py → versionhq-1.2.2.0/src/versionhq/task/evaluation.py +38 -22
  29. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/task/model.py +60 -61
  30. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/task_graph/draft.py +1 -1
  31. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/task_graph/model.py +73 -48
  32. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq.egg-info/PKG-INFO +8 -7
  33. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq.egg-info/SOURCES.txt +5 -2
  34. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/agent/agent_test.py +1 -1
  35. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/agent_network/agent_network_test.py +36 -31
  36. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/doc_test.py +6 -5
  37. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/task/doc_taskoutput_test.py +2 -3
  38. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/task/doc_test.py +1 -1
  39. versionhq-1.2.2.0/tests/task/eval_test.py +53 -0
  40. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/task/task_test.py +5 -22
  41. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/task_graph/doc_test.py +2 -2
  42. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/tool/doc_test.py +1 -2
  43. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/usecase_test.py +1 -1
  44. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/uv.lock +1 -1
  45. versionhq-1.2.1.22/src/versionhq/_utils/usage_metrics.py +0 -23
  46. versionhq-1.2.1.22/src/versionhq/task/TEMPLATES/Description.py +0 -5
  47. versionhq-1.2.1.22/src/versionhq/task/log_handler.py +0 -59
  48. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/.env.sample +0 -0
  49. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/.github/workflows/deploy_docs.yml +0 -0
  50. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/.github/workflows/publish.yml +0 -0
  51. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/.github/workflows/publish_testpypi.yml +0 -0
  52. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/.github/workflows/run_tests.yml +0 -0
  53. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/.github/workflows/security_check.yml +0 -0
  54. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/.gitignore +0 -0
  55. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/.pre-commit-config.yaml +0 -0
  56. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/.python-version +0 -0
  57. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/LICENSE +0 -0
  58. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/SECURITY.md +0 -0
  59. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/db/preprocess.py +0 -0
  60. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/CNAME +0 -0
  61. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/_logos/favicon.ico +0 -0
  62. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/_logos/logo192.png +0 -0
  63. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/core/agent/index.md +0 -0
  64. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/core/agent/ref.md +0 -0
  65. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/core/llm/index.md +0 -0
  66. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/core/task/response-field.md +0 -0
  67. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/core/task/task-output.md +0 -0
  68. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/core/task/task-strc-response.md +0 -0
  69. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/core/task-graph/index.md +0 -0
  70. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/index.md +0 -0
  71. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/docs/tags.md +0 -0
  72. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/requirements-dev.txt +0 -0
  73. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/requirements.txt +0 -0
  74. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/runtime.txt +0 -0
  75. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/setup.cfg +0 -0
  76. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/_utils/i18n.py +0 -0
  77. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/_utils/logger.py +0 -0
  78. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/_utils/process_config.py +0 -0
  79. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/_utils/vars.py +0 -0
  80. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/agent/TEMPLATES/Backstory.py +0 -0
  81. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/agent/TEMPLATES/__init__.py +0 -0
  82. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/agent/__init__.py +0 -0
  83. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/agent/parser.py +0 -0
  84. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/agent/rpm_controller.py +0 -0
  85. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/agent_network/__init__.py +0 -0
  86. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/agent_network/formation.py +0 -0
  87. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/cli/__init__.py +0 -0
  88. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/clients/__init__.py +0 -0
  89. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/clients/customer/__init__.py +0 -0
  90. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/clients/customer/model.py +0 -0
  91. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/clients/product/__init__.py +0 -0
  92. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/clients/product/model.py +0 -0
  93. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/clients/workflow/__init__.py +0 -0
  94. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/clients/workflow/model.py +0 -0
  95. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/knowledge/__init__.py +0 -0
  96. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/knowledge/_utils.py +0 -0
  97. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/knowledge/embedding.py +0 -0
  98. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/knowledge/model.py +0 -0
  99. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/knowledge/source.py +0 -0
  100. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/knowledge/source_docling.py +0 -0
  101. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/knowledge/storage.py +0 -0
  102. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/llm/__init__.py +0 -0
  103. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/llm/llm_vars.py +0 -0
  104. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/llm/model.py +35 -35
  105. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/memory/__init__.py +0 -0
  106. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/memory/contextual_memory.py +0 -0
  107. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/storage/__init__.py +0 -0
  108. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/storage/base.py +0 -0
  109. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/storage/ltm_sqlite_storage.py +0 -0
  110. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/storage/mem0_storage.py +0 -0
  111. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/storage/rag_storage.py +0 -0
  112. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/task/__init__.py +0 -0
  113. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/task/formatter.py +0 -0
  114. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/task/structured_response.py +0 -0
  115. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/task_graph/__init__.py +0 -0
  116. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/task_graph/colors.py +0 -0
  117. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/tool/__init__.py +0 -0
  118. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/tool/cache_handler.py +0 -0
  119. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/tool/composio_tool.py +0 -0
  120. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/tool/composio_tool_vars.py +0 -0
  121. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/tool/decorator.py +0 -0
  122. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/tool/model.py +0 -0
  123. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq/tool/tool_handler.py +0 -0
  124. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq.egg-info/dependency_links.txt +0 -0
  125. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq.egg-info/requires.txt +0 -0
  126. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/src/versionhq.egg-info/top_level.txt +0 -0
  127. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/__init__.py +0 -0
  128. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/agent/__init__.py +0 -0
  129. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/agent/doc_test.py +0 -0
  130. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/agent_network/Prompts/Demo_test.py +0 -0
  131. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/agent_network/__init__.py +0 -0
  132. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/cli/__init__.py +0 -0
  133. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/clients/customer_test.py +0 -0
  134. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/clients/product_test.py +0 -0
  135. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/clients/workflow_test.py +0 -0
  136. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/conftest.py +0 -0
  137. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/formation_test.py +0 -0
  138. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/knowledge/__init__.py +0 -0
  139. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/knowledge/knowledge_test.py +0 -0
  140. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/knowledge/mock_report_compressed.pdf +0 -0
  141. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/llm/__init__.py +0 -0
  142. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/llm/llm_test.py +0 -0
  143. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/memory/__init__.py +0 -0
  144. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/memory/memory_test.py +0 -0
  145. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/task/__init__.py +0 -0
  146. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/task/llm_connection_test.py +0 -0
  147. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/task_graph/__init__.py +0 -0
  148. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/task_graph/task_graph_test.py +0 -0
  149. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/tool/__init__.py +0 -0
  150. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/tool/composio_test.py +0 -0
  151. {versionhq-1.2.1.22 → versionhq-1.2.2.0}/tests/tool/tool_test.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.2
2
2
  Name: versionhq
3
- Version: 1.2.1.22
3
+ Version: 1.2.2.0
4
4
  Summary: An agentic orchestration framework for building agent networks that handle task automation.
5
5
  Author-email: Kuriko Iwai <kuriko@versi0n.io>
6
6
  License: MIT License
@@ -259,7 +259,7 @@ agent.update(
259
259
  task="YOUR AMAZING TASK OVERVIEW",
260
260
  expected_outcome="YOUR OUTCOME EXPECTATION",
261
261
  )
262
- res = network.launch()
262
+ res, _ = network.launch()
263
263
  ```
264
264
 
265
265
  This will form a network with multiple agents on `Formation` and return `TaskOutput` object with output in JSON, plane text, Pydantic model format with evaluation.
@@ -290,15 +290,16 @@ task = vhq.Task(
290
290
  callback_kwargs=dict(message="Hi! Here is the result: ")
291
291
  )
292
292
 
293
- res = task.execute(context="amazing context to consider.")
294
- print(res)
293
+ res = task.execute(context="context to consider")
294
+
295
+ assert isinstance(res, vhq.TaskOutput)
295
296
  ```
296
297
 
297
298
 
298
299
  This will return a `TaskOutput` object that stores response in plane text, JSON, and Pydantic model: `CustomOutput` formats with a callback result, tool output (if given), and evaluation results (if given).
299
300
 
300
301
  ```python
301
- res == TaskOutput(
302
+ res == vhq.TaskOutput(
302
303
  task_id=UUID('<TASK UUID>'),
303
304
  raw='{\"test1\":\"random str\", \"test2\":[\"str item 1\", \"str item 2\", \"str item 3\"]}',
304
305
  json_dict={'test1': 'random str', 'test2': ['str item 1', 'str item 2', 'str item 3']},
@@ -337,9 +338,9 @@ network =vhq.AgentNetwork(
337
338
  vhq.Member(agent=agent_b, is_manager=True, tasks=[task_2]), # Agent B as a manager
338
339
  ],
339
340
  )
340
- res = network.launch()
341
+ res, _ = network.launch()
341
342
 
342
- assert isinstance(res, vhq.NetworkOutput)
343
+ assert isinstance(res, vhq.TaskOutput)
343
344
  assert not [item for item in task_1.processed_agents if "vhq-Delegated-Agent" == item]
344
345
  assert [item for item in task_1.processed_agents if "agent b" == item]
345
346
  ```
@@ -178,7 +178,7 @@ agent.update(
178
178
  task="YOUR AMAZING TASK OVERVIEW",
179
179
  expected_outcome="YOUR OUTCOME EXPECTATION",
180
180
  )
181
- res = network.launch()
181
+ res, _ = network.launch()
182
182
  ```
183
183
 
184
184
  This will form a network with multiple agents on `Formation` and return `TaskOutput` object with output in JSON, plane text, Pydantic model format with evaluation.
@@ -209,15 +209,16 @@ task = vhq.Task(
209
209
  callback_kwargs=dict(message="Hi! Here is the result: ")
210
210
  )
211
211
 
212
- res = task.execute(context="amazing context to consider.")
213
- print(res)
212
+ res = task.execute(context="context to consider")
213
+
214
+ assert isinstance(res, vhq.TaskOutput)
214
215
  ```
215
216
 
216
217
 
217
218
  This will return a `TaskOutput` object that stores response in plane text, JSON, and Pydantic model: `CustomOutput` formats with a callback result, tool output (if given), and evaluation results (if given).
218
219
 
219
220
  ```python
220
- res == TaskOutput(
221
+ res == vhq.TaskOutput(
221
222
  task_id=UUID('<TASK UUID>'),
222
223
  raw='{\"test1\":\"random str\", \"test2\":[\"str item 1\", \"str item 2\", \"str item 3\"]}',
223
224
  json_dict={'test1': 'random str', 'test2': ['str item 1', 'str item 2', 'str item 3']},
@@ -256,9 +257,9 @@ network =vhq.AgentNetwork(
256
257
  vhq.Member(agent=agent_b, is_manager=True, tasks=[task_2]), # Agent B as a manager
257
258
  ],
258
259
  )
259
- res = network.launch()
260
+ res, _ = network.launch()
260
261
 
261
- assert isinstance(res, vhq.NetworkOutput)
262
+ assert isinstance(res, vhq.TaskOutput)
262
263
  assert not [item for item in task_1.processed_agents if "vhq-Delegated-Agent" == item]
263
264
  assert [item for item in task_1.processed_agents if "agent b" == item]
264
265
  ```
@@ -1,6 +1,3 @@
1
-
2
- <hr />
3
-
4
1
  ## Optimizing Model
5
2
 
6
3
  **Model Optimization**
@@ -1,7 +1,7 @@
1
1
 
2
- ## Prompting
2
+ ## Prompt Engineering
3
3
 
4
- **Developer Prompt (System Prompt)**
4
+ **Developer Prompt**
5
5
 
6
6
  `[var]`<bold>`backstory: Optional[str] = TEMPLATE_BACKSTORY`<bold>
7
7
 
@@ -25,9 +25,7 @@ agent = vhq.Agent(
25
25
  goal="Coping with price competition in saturated markets"
26
26
  )
27
27
 
28
- print(agent.backstory)
29
-
30
- # You are an expert marketing analyst with relevant skillsets and abilities to query relevant information from the given knowledge sources. Leveraging these, you will identify competitive solutions to achieve the following goal: coping with price competition in saturated markets.
28
+ assert agent.backstory == "You are an expert marketing analyst with relevant skillsets and abilities to query relevant information from the given knowledge sources. Leveraging these, you will identify competitive solutions to achieve the following goal: coping with price competition in saturated markets."
31
29
  ```
32
30
 
33
31
  You can also specify your own backstory by simply adding the value to the backstory field of the Agent model:
@@ -41,9 +39,7 @@ agent = vhq.Agent(
41
39
  backstory="You are a marketing analyst for a company in a saturated market. The market is becoming increasingly price-competitive, and your company's profit margins are shrinking. Your primary goal is to develop and implement strategies to help your company maintain its market share and profitability in this challenging environment."
42
40
  )
43
41
 
44
- print(agent.backstory)
45
-
46
- # You are a marketing analyst for a company in a saturated market. The market is becoming increasingly price-competitive, and your company's profit margins are shrinking. Your primary goal is to develop and implement strategies to help your company maintain its market share and profitability in this challenging environment.
42
+ assert agent.backstory == "You are a marketing analyst for a company in a saturated market. The market is becoming increasingly price-competitive, and your company's profit margins are shrinking. Your primary goal is to develop and implement strategies to help your company maintain its market share and profitability in this challenging environment."
47
43
  ```
48
44
  <hr />
49
45
 
@@ -0,0 +1,6 @@
1
+ ---
2
+ tags:
3
+ - Agent Network
4
+ ---
5
+
6
+ # Generating
@@ -33,7 +33,7 @@ network = vhq.form_agent_network(
33
33
  expected_outcome='media mix, key messages, and CTA targets.'
34
34
  )
35
35
 
36
- res = network.launch()
36
+ res, _ = network.launch()
37
37
 
38
38
  assert isinstance(res, vhq.TaskOutput)
39
39
  ```
@@ -0,0 +1,54 @@
1
+ ---
2
+ tags:
3
+ - Agent Network
4
+ ---
5
+
6
+ ## Variable `AgentNetwork`
7
+
8
+
9
+ | <div style="width:160px">**Variable**</div> | **Data Type** | **Default** | **Nullable** | **Description** |
10
+ | :--- | :--- | :--- | :--- | :--- |
11
+ | **`id`** | UUID4 | uuid.uuid4() | False | Stores auto-generated ID as identifier. Not editable. |
12
+ | **`role`** | str | None | False | Stores a role of the agent. |
13
+ | **`goal`** | str | None | False | Stores a goal of the agent. |
14
+ | **`backstory`** | str | None | True | Stores backstory of the agent. Utilized as system prompt. |
15
+ | **`tools`** | List[InstanceOf[`Tool` \| `ToolSet`] \| Type[`Tool`]] | None | True | Stores tools to be used when executing a task. |
16
+ | **`knowledge_sources`** | List[`BaseKnowledgeSource` \| Any] | None | True | Stores knowledge sources in text, file path, or url. |
17
+ | **`embedder_config`** | Dict[str, Any] | None | True | Stores embedding configuration for storing knowledge sources. |
18
+ | **`with_memory`** | bool | False | - | Whether to store tasks and results in memory. |
19
+ | **`memory_config`** | Dict[str, Any] | None | True | Stores configuration of the memory. |
20
+ | **`short_term_memory`** | InstanceOf[`ShortTermMemory`] | None | True | Stores `ShortTermMemory` object. |
21
+ | **`long_term_memory`** | InstanceOf[`LongTermMemory`] | None | True | Stores `LongTermMemory` object. |
22
+ | **`user_memory`** | InstanceOf[`UserMemory`] | None | True | Stores `UserMemory` object. |
23
+ | **`use_developer_prompt`** | bool | True | - | Whether to use the system (developer) prompt when calling the model. |
24
+ | **`developer_promt_template`** | str | None | True | File path to the prompt template. |
25
+ | **`user_promt_template`** | str | None | True | File path to the prompt template. |
26
+ | **`networks`** | List[Any] | list() | True | Stores a list of agent networks that the agent belongs to. |
27
+ | **`allow_delegation`** | bool | False | - | Whether the agent can delegate assinged tasks to another agent. |
28
+ | **`max_retry_limit`** | int | 2 | - | Maximum number of retries when the task execution failed. |
29
+ | **`maxit`** | int | 25 | - | Maximum number of total optimization loops conducted when an error occues during the task execution. |
30
+ | **`callbacks`** | List[Callabale] | None | True | Stores a list of callback functions that must be called after every task execution completed.|
31
+ | **`llm`** | str \| InstanceOf[`LLM`] \| Dict[str, Any] | None | False | Stores the main model that the agent runs on. |
32
+ | **`func_calling_llm`** | str \| InstanceOf[`LLM`] \| Dict[str, Any] | None | False | Stores the function calling model that the agent runs on. |
33
+ | **`respect_context_window`** | bool | True | - | Whether to follow the main model's maximum context window size. |
34
+ | **`max_execution_time`** | int | None | True | Stores maximum execution time in seconds. |
35
+ | **`max_rpm`** | int | None | True | Stores maximum number of requests per minute. |
36
+ | **`llm_config`** | Dict[str, Any] | None | True | Stores configuration of `LLM` object. |
37
+ | **`config`** | Dict[str, Any] | None | True | Stores model config. |
38
+
39
+
40
+ ## Class Methods `AgentNetwork`
41
+
42
+ | <div style="width:120px">**Method**</div> | **Params** | **Returns** | **Description** |
43
+ | :--- | :--- | :--- | :--- |
44
+ | **`update`** | **kwargs: Any | Self | Updates agents with given kwargs. Invalid keys will be ignored. |
45
+ | **`start`** | context: Any = None <br> tool_res_as_final: bool = False | `TaskOutput` \| None | Starts to operate the agent. |
46
+ | **`execute_task`** | task: [Task] <br> context: Any = None <br> task_tools: Optional[List[Tool \| ToolSet]] = list() | str | Returns response from the model in plane text format. |
47
+
48
+
49
+
50
+ ## Properties `AgentNetwork`
51
+
52
+ | <div style="width:120px">**Property**</div> | **Returns** | **Description** |
53
+ | :--- | :--- | :--- |
54
+ | **`key`** | str | Unique identifier of the agent using its ID and sanitized role. |
@@ -0,0 +1,6 @@
1
+ ---
2
+ tags:
3
+ - Agent Network
4
+ ---
5
+
6
+ # Task Handling
@@ -4,5 +4,3 @@ tags:
4
4
  ---
5
5
 
6
6
  # Evaluation
7
-
8
- Under drafting
@@ -15,7 +15,7 @@ Ref. Node / Edge / <a href="/core/task-graph">TaskGraph</a> class
15
15
 
16
16
  ## Quick Start
17
17
 
18
- Create a task by defining its description in one simple sentence. The `description` will be used for task prompting later.
18
+ Create a task by defining its description in one simple sentence. The `description` will be used in the prompt later.
19
19
 
20
20
  Each task will be assigned a unique ID as an identifier.
21
21
 
@@ -1,9 +1,7 @@
1
1
  # Executing Task
2
2
 
3
3
 
4
- ## Prompting
5
-
6
- `[class method]`<bold>`prompt(self, model_provider: str = None, context: Optional[Any] = None) -> str`</bold>
4
+ ## Prompt Engineering
7
5
 
8
6
  Prompts are generated automatically based on the task `description`, response format, context, agent `role`, and `goal`.
9
7
 
@@ -40,9 +38,7 @@ In this scenario, `sub_task_2` executes before the main task. Its string output
40
38
 
41
39
  <hr>
42
40
 
43
- ## Executing
44
-
45
- **Agent delegation**
41
+ ## Delegation
46
42
 
47
43
  `[var]`<bold>`allow_delegation: bool = False`</bold>
48
44
 
@@ -58,13 +54,13 @@ task = vhq.Task(
58
54
  task.execute()
59
55
 
60
56
  assert task.output is not None
61
- assert "vhq-Delegated-Agent" in task.processed_agents # delegated agent
57
+ assert task.processed_agents is not None # auto assigned
62
58
  assert task.delegations ==1
63
59
  ```
64
60
 
65
61
  <hr>
66
62
 
67
- **SYNC - ASYNC**
63
+ ## Sync - Async Execution
68
64
 
69
65
  `[var]`<bold>`type: bool = False`</bold>
70
66
 
@@ -87,7 +83,7 @@ with patch.object(vhq.Agent, "execute_task", return_value="test") as execute:
87
83
 
88
84
  <hr>
89
85
 
90
- **Using tools**
86
+ ## Using Tools
91
87
 
92
88
  `[var]`<bold>`tools: Optional[List[ToolSet | Tool | Any]] = None`</bold>
93
89
 
@@ -146,7 +142,7 @@ assert res.tool_output == "simple func"
146
142
 
147
143
  <hr>
148
144
 
149
- ## Callback
145
+ ## Callbacks
150
146
 
151
147
  `[var]`<bold>`callback: Optional[Callable] = None`</bold>
152
148
 
@@ -16,6 +16,7 @@
16
16
  | **`callback_kwargs`** | Optional[Dict[str, Any]] | dict() | True | Args for the callback function (if any)|
17
17
  | **`should_evaluate`** | bool | False | - | Whether to evaluate the task output using eval criteria |
18
18
  | **`eval_criteria`** | Optional[List[str]] | list() | True | Evaluation criteria given by the human client |
19
+ | **`fsls`** | Optional[List[str]] | None | True | Examples of excellent and weak responses |
19
20
  | **`processed_agents`** | Set[str] | set() | True | [Ops] Stores roles of the agents executed the task |
20
21
  | **`tool_errors`** | int | 0 | True | [Ops] Stores number of tool errors |
21
22
  | **`delegation`** | int | 0 | True | [Ops] Stores number of agent delegations |
@@ -22,8 +22,7 @@ def demo_func(message: str) -> str:
22
22
  my_tool = vhq.Tool(func=demo_func)
23
23
  res = my_tool.run(params=dict(message="Hi!"))
24
24
 
25
- print(res)
26
- # Hi!_demo
25
+ assert res == "Hi!_demo"
27
26
  ```
28
27
 
29
28
  e.g. Build an agent with a simple tool
@@ -87,8 +86,7 @@ def demo_func() -> str:
87
86
 
88
87
  my_tool = Tool(func=demo_func)
89
88
 
90
- print(my_tool.name)
91
- # demo_func
89
+ assert my_tool.name == "demo_func"
92
90
  ```
93
91
 
94
92
  ```python
@@ -96,8 +94,7 @@ from versionhq import Tool
96
94
 
97
95
  my_tool = Tool(name="my empty tool", func=lambda x: x)
98
96
 
99
- print(my_tool.name)
100
- # my empty tool
97
+ assert my_tool.name == "my empty tool"
101
98
  ```
102
99
 
103
100
  Tool names are used to call cached tools later.
@@ -119,8 +116,7 @@ from versionhq import Tool
119
116
  my_tool = Tool(func=lambda x: f"demo-{x}")
120
117
  res = my_tool._run(x="TESTING")
121
118
 
122
- print(res)
123
- # demo-TESTING
119
+ assert res == "demo-TESTING"
124
120
  ```
125
121
 
126
122
  Another way to define the logic is to add a function to the `func` field.
@@ -137,8 +133,7 @@ def demo_func() -> str:
137
133
  my_tool = Tool(func=demo_func)
138
134
  res = my_tool._run()
139
135
 
140
- print(res)
141
- # demo
136
+ assert res == "demo"
142
137
  ```
143
138
 
144
139
  You can also pass parameters using the class method.
@@ -152,8 +147,7 @@ def demo_func(message: str) -> str:
152
147
  my_tool = Tool(func=demo_func)
153
148
  res = my_tool._run(message="Hi!")
154
149
 
155
- print(res)
156
- # Hi!_demo
150
+ assert res == "Hi!_demo"
157
151
  ```
158
152
 
159
153
  ### Custom tool execution
@@ -173,8 +167,7 @@ class MyCustomTool(Tool):
173
167
  my_custom_tool = MyCustomTool(func=lambda x: len(x))
174
168
  res = my_custom_tool._run(["demo1", "demo2"])
175
169
 
176
- print(res)
177
- # 2
170
+ assert res == 2
178
171
  ```
179
172
 
180
173
  ### Cached tool execution
@@ -197,11 +190,8 @@ def demo_func(demo_list: List[Any]) -> int:
197
190
  my_tool = CustomTool(func=demo_func)
198
191
  res = my_tool.run(params=dict(demo_list=["demo1", "demo2"]))
199
192
 
200
- print(res)
201
- # 2
202
-
203
- print(my_tool.tool_handler)
204
- # ToolHandler object
193
+ assert res == 2
194
+ assert isinstance(my_tool.tool_handler, vhq.ToolHandler)
205
195
  ```
206
196
 
207
197
  *Reference: <bold>`ToolHandler` class</bold>
@@ -252,8 +242,7 @@ task = Task(
252
242
  )
253
243
 
254
244
  res = task.execute(agent=agent)
255
- print(res)
256
- # demo func
245
+ assert res == "demo func"
257
246
  ```
258
247
 
259
248
  When the function calling LLM is not provided, we use the main model or default model `gpt-4o` .
@@ -278,8 +267,7 @@ task = Task(
278
267
  )
279
268
 
280
269
  res = task.execute(agent=agent)
281
- print(res.tool_output)
282
- # demo func
270
+ assert res.tool_output == "demo func"
283
271
  ```
284
272
 
285
273
  ```python
@@ -300,11 +288,8 @@ task = Task(
300
288
  )
301
289
 
302
290
  res = task.execute(agent=agent)
303
- print(res.tool_output)
304
- # "demo func"
305
-
306
- print(task.processed_agents)
307
- # {'Demo Tool Handler'}
291
+ assert res.tool_output == "demo func"
292
+ assert agent.key in task.processed_agents
308
293
  ```
309
294
 
310
295
  <hr />
@@ -320,8 +305,9 @@ If you want to see if the model of your choice supports function calling <bold>e
320
305
  ```python
321
306
  from versionhq.llm.model import LLM
322
307
  llm = LLM(model="<MODEL_NAME_OF_YOUR_CHOICE>")
323
- llm._supports_function_calling()
324
- # return bool
308
+ res = llm._supports_function_calling()
309
+
310
+ assert type(res) == bool
325
311
  ```
326
312
 
327
313
  ### 2. Add tools to the task
@@ -355,8 +341,7 @@ task = Task(
355
341
  )
356
342
 
357
343
  res = task.execute(agent=agent)
358
- print(res)
359
- # empty func_demo
344
+ assert res == "empty func_demo"
360
345
  ```
361
346
 
362
347
  ## Decorator
@@ -373,13 +358,7 @@ def my_tool(test_words: str) -> str:
373
358
  """Test a tool decorator."""
374
359
  return test_words
375
360
 
376
- print(my_tool.name)
377
- # demo
378
-
379
- print(my_tool.description)
380
- # Tool: demo
381
- # Args: {'test_words': {'description': '', 'type': 'str'}}
382
-
383
- print(my_tool.func("tool's final part!"))
384
- # tool's final part!
361
+ assert my_tool.name == "demo"
362
+ assert "Tool: demo" in my_tool.description and "'test_words': {'description': '', 'type': 'str'" in my_tool.description
363
+ assert my_tool.func("testing") == "testing"
385
364
  ```
@@ -23,7 +23,7 @@ network = vhq.form_agent_network(
23
23
  task="YOUR AMAZING TASK OVERVIEW",
24
24
  expected_outcome="YOUR OUTCOME EXPECTATION",
25
25
  )
26
- res = network.launch()
26
+ res, _ = network.launch()
27
27
  ```
28
28
 
29
29
  This will form a network with multiple agents on `Formation` and return results as a `TaskOutput` object, storing outputs in JSON, plane text, Pydantic model formats along with evaluation.
@@ -104,7 +104,7 @@ network =vhq.AgentNetwork(
104
104
  vhq.Member(agent=agent_b, is_manager=True, tasks=[task_2]), # Agent B as a manager
105
105
  ],
106
106
  )
107
- res = network.launch()
107
+ res, _ = network.launch()
108
108
 
109
109
  assert isinstance(res, vhq.NetworkOutput)
110
110
  assert "agent b" in task_1.processed_agents # agent_b delegated by agent_a
@@ -6,9 +6,9 @@
6
6
 
7
7
 
8
8
  class {
9
- background-color: #363636;
9
+ background-color: hsl(0, 0%, 21%);
10
10
  padding: 8px 10px;
11
- border-radius: 5px;
11
+ border-radius: 3px;
12
12
  color: #ededeb;
13
13
  }
14
14
 
@@ -112,6 +112,9 @@ nav:
112
112
  - Quick Start: 'quickstart.md'
113
113
  - Agent Network:
114
114
  - 'core/agent-network/index.md'
115
+ - Configuration: 'core/agent-network/config.md'
116
+ - Task Handling: 'core/agent-network/task-handling.md'
117
+ - Reference: 'core/agent-network/ref.md'
115
118
  - Agent:
116
119
  - 'core/agent/index.md'
117
120
  - Configuration: 'core/agent/config.md'
@@ -15,7 +15,7 @@ exclude = ["test*", "__pycache__", "*.egg-info"]
15
15
 
16
16
  [project]
17
17
  name = "versionhq"
18
- version = "1.2.1.22"
18
+ version = "1.2.2.0"
19
19
  authors = [{ name = "Kuriko Iwai", email = "kuriko@versi0n.io" }]
20
20
  description = "An agentic orchestration framework for building agent networks that handle task automation."
21
21
  readme = "README.md"
@@ -8,7 +8,7 @@ from dotenv import load_dotenv
8
8
  load_dotenv(override=True)
9
9
 
10
10
  from versionhq.agent.model import Agent
11
- from versionhq.agent_network.model import AgentNetwork, NetworkOutput, Formation, Member, TaskHandlingProcess
11
+ from versionhq.agent_network.model import AgentNetwork, Formation, Member, TaskHandlingProcess
12
12
  from versionhq.llm.model import LLM
13
13
  from versionhq.llm.llm_vars import LLM_CONTEXT_WINDOW_SIZES, PARAMS, PROVIDERS, MODELS
14
14
  from versionhq.clients.customer.model import Customer
@@ -19,7 +19,7 @@ from versionhq.knowledge.source import PDFKnowledgeSource, CSVKnowledgeSource, J
19
19
  from versionhq.knowledge.source_docling import DoclingSource
20
20
  from versionhq.task_graph.model import TaskStatus, TaskGraph, Node, Edge, DependencyType
21
21
  from versionhq.task.model import Task, TaskOutput, ResponseField, TaskExecutionType
22
- from versionhq.task.evaluate import Evaluation, EvaluationItem
22
+ from versionhq.task.evaluation import Evaluation, EvaluationItem
23
23
  from versionhq.tool.model import Tool, ToolSet
24
24
  from versionhq.tool.cache_handler import CacheHandler
25
25
  from versionhq.tool.tool_handler import ToolHandler
@@ -31,12 +31,11 @@ from versionhq.agent_network.formation import form_agent_network
31
31
  from versionhq.task_graph.draft import workflow
32
32
 
33
33
 
34
- __version__ = "1.2.1.22"
34
+ __version__ = "1.2.2.0"
35
35
  __all__ = [
36
36
  "Agent",
37
37
 
38
38
  "AgentNetwork",
39
- "NetworkOutput",
40
39
  "Formation",
41
40
  "Member",
42
41
  "TaskHandlingProcess",
@@ -1,3 +1,3 @@
1
1
  from versionhq._utils.logger import Logger
2
2
  from versionhq._utils.process_config import process_config
3
- from versionhq._utils.usage_metrics import UsageMetrics
3
+ from versionhq._utils.vars import KNOWLEDGE_DIRECTORY, MAX_FILE_NAME_LENGTH
@@ -0,0 +1,55 @@
1
+ from pydantic import BaseModel, Field
2
+
3
+
4
+ class UsageMetrics(BaseModel):
5
+ """
6
+ Model to track usage
7
+ """
8
+
9
+ total_tokens: int = Field(default=0, description="total number of tokens used")
10
+ prompt_tokens: int = Field(default=0, description="number of tokens used in prompts")
11
+ cached_prompt_tokens: int = Field(default=0, description="number of cached prompt tokens used")
12
+ completion_tokens: int = Field(default=0, description="number of tokens used in completions")
13
+ successful_requests: int = Field(default=0, description="number of successful requests made")
14
+
15
+ def add_usage_metrics(self, usage_metrics: "UsageMetrics") -> None:
16
+ """
17
+ Add the usage metrics from another UsageMetrics object.
18
+ """
19
+ self.total_tokens += usage_metrics.total_tokens
20
+ self.prompt_tokens += usage_metrics.prompt_tokens
21
+ self.cached_prompt_tokens += usage_metrics.cached_prompt_tokens
22
+ self.completion_tokens += usage_metrics.completion_tokens
23
+ self.successful_requests += usage_metrics.successful_requests
24
+
25
+
26
+
27
+ # class TokenProcess:
28
+ # total_tokens: int = 0
29
+ # prompt_tokens: int = 0
30
+ # cached_prompt_tokens: int = 0
31
+ # completion_tokens: int = 0
32
+ # successful_requests: int = 0
33
+
34
+ # def sum_prompt_tokens(self, tokens: int) -> None:
35
+ # self.prompt_tokens = self.prompt_tokens + tokens
36
+ # self.total_tokens = self.total_tokens + tokens
37
+
38
+ # def sum_completion_tokens(self, tokens: int) -> None:
39
+ # self.completion_tokens = self.completion_tokens + tokens
40
+ # self.total_tokens = self.total_tokens + tokens
41
+
42
+ # def sum_cached_prompt_tokens(self, tokens: int) -> None:
43
+ # self.cached_prompt_tokens = self.cached_prompt_tokens + tokens
44
+
45
+ # def sum_successful_requests(self, requests: int) -> None:
46
+ # self.successful_requests = self.successful_requests + requests
47
+
48
+ # def get_summary(self) -> UsageMetrics:
49
+ # return UsageMetrics(
50
+ # total_tokens=self.total_tokens,
51
+ # prompt_tokens=self.prompt_tokens,
52
+ # cached_prompt_tokens=self.cached_prompt_tokens,
53
+ # completion_tokens=self.completion_tokens,
54
+ # successful_requests=self.successful_requests,
55
+ # )
@@ -10,13 +10,15 @@ vhq_client_manager = Agent(
10
10
  role="vhq-Client Manager",
11
11
  goal="Efficiently communicate with the client on the task progress",
12
12
  llm=DEFAULT_MODEL_NAME,
13
+ maxit=1,
14
+ max_retry_limit=1,
13
15
  with_memory=True,
14
16
  )
15
17
 
16
18
 
17
19
  vhq_task_evaluator = Agent(
18
20
  role="vhq-Task Evaluator",
19
- goal="score the output according to the given evaluation criteria.",
21
+ goal="score the output according to the given evaluation criteria, taking a step by step approach.",
20
22
  llm=DEFAULT_MODEL_NAME,
21
23
  llm_config=dict(top_p=0.8, top_k=30, max_tokens=5000, temperature=0.9),
22
24
  maxit=1,
@@ -45,4 +47,6 @@ vhq_agent_creator = Agent(
45
47
  role="vhq-Agent Creator",
46
48
  goal="build an agent that can handle the given task",
47
49
  llm="gemini/gemini-2.0-flash-exp",
50
+ maxit=1,
51
+ max_retry_limit=1,
48
52
  )