flowra 0.0.98__tar.gz → 0.0.99.dev118__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 (381) hide show
  1. {flowra-0.0.98 → flowra-0.0.99.dev118}/CHANGELOG.md +148 -0
  2. {flowra-0.0.98 → flowra-0.0.99.dev118}/PKG-INFO +5 -2
  3. {flowra-0.0.98 → flowra-0.0.99.dev118}/README.md +4 -1
  4. {flowra-0.0.98 → flowra-0.0.99.dev118}/context7.json +13 -9
  5. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/agents.md +185 -18
  6. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/architecture.md +8 -6
  7. flowra-0.0.99.dev118/docs/interrupts.md +224 -0
  8. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/llm.md +10 -4
  9. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/observability.md +4 -0
  10. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/patterns.md +15 -11
  11. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/review_prompts/step3_documentation.md +3 -2
  12. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/review_prompts/step5_doc_audit.md +1 -1
  13. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/escalation.py +5 -6
  14. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/_typing.py +18 -4
  15. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/__init__.py +3 -1
  16. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/definition/__init__.py +4 -0
  17. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/definition/compile/compiler.py +8 -4
  18. flowra-0.0.99.dev118/flowra/agent/definition/compile/contract.py +153 -0
  19. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/definition/compile/instance.py +98 -3
  20. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/definition/compile/step_params.py +84 -16
  21. flowra-0.0.99.dev118/flowra/agent/definition/compile/step_validation.py +148 -0
  22. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/definition/compile/steps.py +13 -5
  23. flowra-0.0.99.dev118/flowra/agent/definition/errors.py +43 -0
  24. flowra-0.0.99.dev118/flowra/agent/definition/interrupted.py +32 -0
  25. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/definition/model.py +17 -0
  26. flowra-0.0.99.dev118/flowra/agent/definition/step.py +49 -0
  27. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/definition/step_helpers.py +22 -0
  28. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/flow/__init__.py +3 -3
  29. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/flow/flowing_registry.py +1 -1
  30. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/flow/interrupt.py +7 -11
  31. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/runtime/engine.py +50 -20
  32. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/runtime/execution.py +7 -4
  33. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/runtime/runtime.py +91 -33
  34. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/runtime/serialization.py +3 -3
  35. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/runtime/spawn_satisfaction.py +6 -4
  36. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/chat/__init__.py +2 -1
  37. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/chat/agent.py +21 -14
  38. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/chat/hook_events.py +7 -3
  39. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/chat/spec.py +12 -1
  40. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/decision_call/agent.py +0 -2
  41. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/llm_call/agent.py +0 -2
  42. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/llm_caller.py +22 -7
  43. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/turn/__init__.py +2 -1
  44. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/turn/agent.py +255 -103
  45. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/turn/config.py +1 -1
  46. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/turn/spec.py +15 -3
  47. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/turn/tool_call/agent.py +32 -21
  48. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/version.py +1 -1
  49. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/definition/compile/test_compile.py +155 -1
  50. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/definition/test_step_helpers.py +1 -1
  51. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/flow/test_interrupt.py +17 -0
  52. flowra-0.0.99.dev118/tests/agent/runtime/test_runtime.py +3668 -0
  53. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/runtime/test_serialization.py +6 -1
  54. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/test_chat_agent.py +166 -6
  55. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/test_decision_call_agent.py +14 -5
  56. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/test_llm_call_agent.py +18 -2
  57. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/test_llm_caller.py +91 -6
  58. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/test_turn_agent.py +544 -12
  59. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/turn/test_render.py +4 -4
  60. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/test_typing.py +10 -1
  61. flowra-0.0.98/flowra/agent/definition/compile/contract.py +0 -102
  62. flowra-0.0.98/flowra/agent/definition/compile/step_validation.py +0 -72
  63. flowra-0.0.98/flowra/agent/definition/step.py +0 -48
  64. flowra-0.0.98/tests/agent/runtime/test_runtime.py +0 -1611
  65. {flowra-0.0.98 → flowra-0.0.99.dev118}/.agents/skills/source-command-update-pricing/SKILL.md +0 -0
  66. {flowra-0.0.98 → flowra-0.0.99.dev118}/.claude/commands/update-pricing.md +0 -0
  67. {flowra-0.0.98 → flowra-0.0.99.dev118}/.env.example +0 -0
  68. {flowra-0.0.98 → flowra-0.0.99.dev118}/.github/CODEOWNERS +0 -0
  69. {flowra-0.0.98 → flowra-0.0.99.dev118}/.github/workflows/master.yml +0 -0
  70. {flowra-0.0.98 → flowra-0.0.99.dev118}/.github/workflows/publish.yml +0 -0
  71. {flowra-0.0.98 → flowra-0.0.99.dev118}/.github/workflows/pull_request.yml +0 -0
  72. {flowra-0.0.98 → flowra-0.0.99.dev118}/.gitignore +0 -0
  73. {flowra-0.0.98 → flowra-0.0.99.dev118}/.python-version +0 -0
  74. {flowra-0.0.98 → flowra-0.0.99.dev118}/AGENTS.md +0 -0
  75. {flowra-0.0.98 → flowra-0.0.99.dev118}/CLAUDE.md +0 -0
  76. {flowra-0.0.98 → flowra-0.0.99.dev118}/LICENSE +0 -0
  77. {flowra-0.0.98 → flowra-0.0.99.dev118}/Makefile +0 -0
  78. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/getting-started.md +0 -0
  79. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/agent_async_init.md +0 -0
  80. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/agent_tool_errors.md +0 -0
  81. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/anthropic_web_search.md +0 -0
  82. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/e2e_security.md +0 -0
  83. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/enum_slot_values.md +0 -0
  84. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/final_tools.md +0 -0
  85. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/langchain_comparison.md +0 -0
  86. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/lifecycle_hooks_and_conversation.md +0 -0
  87. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/llm_retry_backoff.md +0 -0
  88. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/named_scope_lazy_hydration.md +0 -0
  89. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/named_scope_type_registry.md +0 -0
  90. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/named_scopes.md +0 -0
  91. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/pricing_complexity.md +0 -0
  92. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/pydantic_ai_comparison.md +0 -0
  93. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/strands_comparison.md +0 -0
  94. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/tool_error_signals.md +0 -0
  95. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/tool_errors_vs_failures.md +0 -0
  96. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/tool_registry_redesign.md +0 -0
  97. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/tool_search_tool.md +0 -0
  98. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/research/voice_stt.md +0 -0
  99. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/review_prompts/step1_structure.md +0 -0
  100. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/review_prompts/step2_code_style.md +0 -0
  101. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/review_prompts/step4_doc_readability.md +0 -0
  102. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/review_prompts/step6_tests.md +0 -0
  103. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/todo.md +0 -0
  104. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/tools.md +0 -0
  105. {flowra-0.0.98 → flowra-0.0.99.dev118}/docs/video_script.md +0 -0
  106. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/TRACING_COMBINATIONS.md +0 -0
  107. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/__init__.py +0 -0
  108. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/agent_as_tool.py +0 -0
  109. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/app_agent.py +0 -0
  110. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/console_chat.py +0 -0
  111. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/docs/__init__.py +0 -0
  112. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/docs/agents_custom.py +0 -0
  113. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/docs/agents_parallel.py +0 -0
  114. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/docs/getting_started_chat.py +0 -0
  115. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/docs/getting_started_streaming.py +0 -0
  116. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/docs/getting_started_tools.py +0 -0
  117. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/docs/llm_streaming.py +0 -0
  118. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/docs/llm_structured_output.py +0 -0
  119. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/docs/tools_service_injection.py +0 -0
  120. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/llm_logging.py +0 -0
  121. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/llm_routing.py +0 -0
  122. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/menu_agent.py +0 -0
  123. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/menu_agent_class.py +0 -0
  124. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/mlflow_demo.py +0 -0
  125. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/mlflow_dual_export_demo.py +0 -0
  126. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/mlflow_nested_demo.py +0 -0
  127. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/mlflow_otel_both_demo.py +0 -0
  128. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/mlflow_otel_nested_demo.py +0 -0
  129. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/mlflow_parallel_demo.py +0 -0
  130. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/model_registry.py +0 -0
  131. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/otel_demo.py +0 -0
  132. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/otel_jaeger_demo.py +0 -0
  133. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/otel_nested_demo.py +0 -0
  134. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/otel_visualize.py +0 -0
  135. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/race.py +0 -0
  136. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/span_crash_demo.py +0 -0
  137. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/span_demo.py +0 -0
  138. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/system_prompt.txt +0 -0
  139. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/tools/__init__.py +0 -0
  140. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/tools/calculator.py +0 -0
  141. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/tools/random_numbers.py +0 -0
  142. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/tools/switch_model.py +0 -0
  143. {flowra-0.0.98 → flowra-0.0.99.dev118}/examples/tui_chat.py +0 -0
  144. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/__init__.py +0 -0
  145. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/_sentinel.py +0 -0
  146. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/definition/_path.py +0 -0
  147. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/definition/actions.py +0 -0
  148. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/definition/agent.py +0 -0
  149. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/definition/agent_arg.py +0 -0
  150. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/definition/compile/__init__.py +0 -0
  151. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/definition/compile/init_params.py +0 -0
  152. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/definition/compile/type_registry.py +0 -0
  153. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/definition/registry.py +0 -0
  154. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/definition/shared_persistent.py +0 -0
  155. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/definition/spawn.py +0 -0
  156. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/flow/context.py +0 -0
  157. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/flow/hooks.py +0 -0
  158. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/flow/interrupt_helpers.py +0 -0
  159. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/flow/timeout.py +0 -0
  160. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/runtime/__init__.py +0 -0
  161. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/runtime/instance_factory.py +0 -0
  162. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/runtime/key_locks.py +0 -0
  163. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/runtime/scope.py +0 -0
  164. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/runtime/spans.py +0 -0
  165. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/runtime/spawn_tree.py +0 -0
  166. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/runtime/visibility.py +0 -0
  167. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/services.py +0 -0
  168. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/session_state.py +0 -0
  169. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/state/__init__.py +0 -0
  170. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/state/markers.py +0 -0
  171. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/state/persistent.py +0 -0
  172. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/state/store.py +0 -0
  173. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/state/values.py +0 -0
  174. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/storage/__init__.py +0 -0
  175. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/storage/file.py +0 -0
  176. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/storage/in_memory.py +0 -0
  177. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/agent/storage/session_storage.py +0 -0
  178. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/ext/__init__.py +0 -0
  179. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/ext/_session.py +0 -0
  180. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/ext/mlflow.py +0 -0
  181. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/ext/otel.py +0 -0
  182. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/__init__.py +0 -0
  183. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/chat/config.py +0 -0
  184. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/chat/conversation.py +0 -0
  185. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/config_value.py +0 -0
  186. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/decision_call/__init__.py +0 -0
  187. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/decision_call/config.py +0 -0
  188. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/decision_call/spec.py +0 -0
  189. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/decision_config.py +0 -0
  190. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/llm_call/__init__.py +0 -0
  191. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/llm_call/config.py +0 -0
  192. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/llm_call/spec.py +0 -0
  193. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/llm_config.py +0 -0
  194. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/observability/__init__.py +0 -0
  195. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/observability/llm_hooks.py +0 -0
  196. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/turn/context.py +0 -0
  197. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/turn/hook_events.py +0 -0
  198. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/turn/tool_call/__init__.py +0 -0
  199. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/turn/tool_call/agent_tool.py +0 -0
  200. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/lib/turn/tool_call/context.py +0 -0
  201. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/__init__.py +0 -0
  202. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/_schema_nodes.py +0 -0
  203. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/base.py +0 -0
  204. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/blocks.py +0 -0
  205. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/decision.py +0 -0
  206. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/errors.py +0 -0
  207. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/ext/__init__.py +0 -0
  208. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/ext/anthropic/__init__.py +0 -0
  209. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/ext/anthropic/cache.py +0 -0
  210. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/ext/anthropic/presets.py +0 -0
  211. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/ext/anthropic/tool_search.py +0 -0
  212. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/ext/anthropic/web_search.py +0 -0
  213. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/ext/openai/__init__.py +0 -0
  214. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/ext/openai/tool_search.py +0 -0
  215. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/gemini_schema.py +0 -0
  216. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/messages.py +0 -0
  217. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/openai_schema.py +0 -0
  218. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/pricing/__init__.py +0 -0
  219. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/pricing/bundled.py +0 -0
  220. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/pricing/data/custom/anthropic.json +0 -0
  221. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/pricing/data/custom/typesafe.json +0 -0
  222. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/pricing/data/custom/vertex.json +0 -0
  223. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/pricing/data/generated/anthropic.json +0 -0
  224. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/pricing/data/generated/azure_openai.json +0 -0
  225. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/pricing/data/generated/bedrock.json +0 -0
  226. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/pricing/data/generated/gemini_api.json +0 -0
  227. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/pricing/data/generated/inception.json +0 -0
  228. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/pricing/data/generated/openai.json +0 -0
  229. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/pricing/data/generated/vertex.json +0 -0
  230. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/pricing/model_pricing.py +0 -0
  231. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/pricing/price_list.py +0 -0
  232. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/provider.py +0 -0
  233. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/providers/__init__.py +0 -0
  234. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/providers/_anthropic_common.py +0 -0
  235. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/providers/_openai_common.py +0 -0
  236. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/providers/anthropic.py +0 -0
  237. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/providers/anthropic_bedrock.py +0 -0
  238. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/providers/anthropic_foundry.py +0 -0
  239. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/providers/anthropic_vertex.py +0 -0
  240. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/providers/azure_openai.py +0 -0
  241. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/providers/google_vertex.py +0 -0
  242. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/providers/openai.py +0 -0
  243. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/providers/openai_decisions.py +0 -0
  244. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/providers/openai_responses.py +0 -0
  245. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/providers/typesafe.py +0 -0
  246. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/request.py +0 -0
  247. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/response.py +0 -0
  248. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/schema_formatting.py +0 -0
  249. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/schema_validation.py +0 -0
  250. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/stream.py +0 -0
  251. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/llm/tools.py +0 -0
  252. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/py.typed +0 -0
  253. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/tools/__init__.py +0 -0
  254. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/tools/_mcp_content.py +0 -0
  255. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/tools/_mcp_headers.py +0 -0
  256. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/tools/local_tool.py +0 -0
  257. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/tools/mcp_connection.py +0 -0
  258. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/tools/result_format.py +0 -0
  259. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/tools/tool_arg.py +0 -0
  260. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/tools/tool_filter.py +0 -0
  261. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/tools/tool_registry.py +0 -0
  262. {flowra-0.0.98 → flowra-0.0.99.dev118}/flowra/tools/types.py +0 -0
  263. {flowra-0.0.98 → flowra-0.0.99.dev118}/pyproject.toml +0 -0
  264. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/__init__.py +0 -0
  265. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/__init__.py +0 -0
  266. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/definition/__init__.py +0 -0
  267. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/definition/compile/__init__.py +0 -0
  268. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/definition/test_actions.py +0 -0
  269. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/definition/test_agent.py +0 -0
  270. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/definition/test_registry.py +0 -0
  271. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/definition/test_spawn.py +0 -0
  272. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/flow/__init__.py +0 -0
  273. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/flow/test_context.py +0 -0
  274. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/flow/test_flowing_registry.py +0 -0
  275. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/flow/test_flowing_registry_tasks.py +0 -0
  276. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/flow/test_flowing_sync.py +0 -0
  277. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/flow/test_hooks.py +0 -0
  278. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/flow/test_interruptible.py +0 -0
  279. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/flow/test_spans.py +0 -0
  280. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/flow/test_timeout.py +0 -0
  281. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/flow/test_with_interrupt.py +0 -0
  282. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/runtime/__init__.py +0 -0
  283. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/runtime/test_engine.py +0 -0
  284. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/runtime/test_engine_spans.py +0 -0
  285. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/runtime/test_ephemeral_isolation.py +0 -0
  286. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/runtime/test_hook_context.py +0 -0
  287. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/runtime/test_named_scope_persistence.py +0 -0
  288. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/runtime/test_named_scope_registry.py +0 -0
  289. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/runtime/test_named_scopes.py +0 -0
  290. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/runtime/test_parallel_failure.py +0 -0
  291. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/runtime/test_persistence.py +0 -0
  292. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/runtime/test_primitive_join.py +0 -0
  293. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/runtime/test_scope.py +0 -0
  294. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/runtime/test_spec_in_constructor.py +0 -0
  295. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/state/__init__.py +0 -0
  296. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/state/test_values.py +0 -0
  297. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/storage/__init__.py +0 -0
  298. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/storage/test_file.py +0 -0
  299. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/storage/test_in_memory.py +0 -0
  300. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/test_missing_scenarios.py +0 -0
  301. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/agent/test_session_state.py +0 -0
  302. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/examples/__init__.py +0 -0
  303. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/examples/test_menu_agent.py +0 -0
  304. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/ext/__init__.py +0 -0
  305. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/ext/_mlflow.py +0 -0
  306. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/ext/test_mlflow.py +0 -0
  307. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/ext/test_mlflow_cross_task.py +0 -0
  308. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/ext/test_otel.py +0 -0
  309. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/__init__.py +0 -0
  310. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/_helpers.py +0 -0
  311. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/ext/__init__.py +0 -0
  312. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/ext/anthropic/__init__.py +0 -0
  313. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/ext/anthropic/test_anthropic.py +0 -0
  314. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/ext/openai/__init__.py +0 -0
  315. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/ext/openai/test_openai_tool_search.py +0 -0
  316. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/test_chat_spec.py +0 -0
  317. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/test_config_value.py +0 -0
  318. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/test_conversation.py +0 -0
  319. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/test_matches_tool_filter.py +0 -0
  320. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/test_tool_call_agent.py +0 -0
  321. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/test_tool_call_agent_call_agent.py +0 -0
  322. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/turn/__init__.py +0 -0
  323. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/turn/test_hook_events.py +0 -0
  324. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/turn/test_per_call_headers.py +0 -0
  325. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/lib/turn/test_tool_errors.py +0 -0
  326. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/__init__.py +0 -0
  327. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/pricing/__init__.py +0 -0
  328. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/pricing/test_bundled.py +0 -0
  329. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/pricing/test_model_pricing.py +0 -0
  330. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/pricing/test_price_list.py +0 -0
  331. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/__init__.py +0 -0
  332. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/_mock_http.py +0 -0
  333. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/_raw_body.py +0 -0
  334. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/_tool_result_blocks.py +0 -0
  335. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_anthropic.py +0 -0
  336. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_anthropic_bedrock.py +0 -0
  337. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_anthropic_bedrock_e2e.py +0 -0
  338. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_anthropic_e2e.py +0 -0
  339. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_anthropic_foundry.py +0 -0
  340. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_anthropic_foundry_e2e.py +0 -0
  341. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_anthropic_vertex.py +0 -0
  342. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_anthropic_vertex_locations_e2e.py +0 -0
  343. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_azure_openai_e2e.py +0 -0
  344. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_cross_provider_e2e.py +0 -0
  345. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_decision_e2e.py +0 -0
  346. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_errors.py +0 -0
  347. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_fallback_e2e.py +0 -0
  348. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_google_vertex.py +0 -0
  349. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_google_vertex_e2e.py +0 -0
  350. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_history_across_models.py +0 -0
  351. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_openai_decisions.py +0 -0
  352. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_openai_e2e.py +0 -0
  353. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_openai_provider.py +0 -0
  354. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_openai_responses.py +0 -0
  355. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_openai_responses_e2e.py +0 -0
  356. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_refusals.py +0 -0
  357. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_schemas_e2e.py +0 -0
  358. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/providers/test_typesafe.py +0 -0
  359. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/test_blocks.py +0 -0
  360. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/test_cost_breakdown.py +0 -0
  361. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/test_decision.py +0 -0
  362. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/test_gemini_schema.py +0 -0
  363. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/test_metadata.py +0 -0
  364. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/test_openai_schema.py +0 -0
  365. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/test_provider.py +0 -0
  366. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/test_response.py +0 -0
  367. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/test_schema_formatting.py +0 -0
  368. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/test_schema_nodes.py +0 -0
  369. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/test_schema_validation.py +0 -0
  370. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/llm/test_stream.py +0 -0
  371. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/scripts/__init__.py +0 -0
  372. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/scripts/test_sync_pricing.py +0 -0
  373. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/tools/__init__.py +0 -0
  374. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/tools/test_local_tool.py +0 -0
  375. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/tools/test_mcp_connection.py +0 -0
  376. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/tools/test_mcp_headers.py +0 -0
  377. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/tools/test_result_format.py +0 -0
  378. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/tools/test_tool_registry.py +0 -0
  379. {flowra-0.0.98 → flowra-0.0.99.dev118}/tests/tools/test_types.py +0 -0
  380. {flowra-0.0.98 → flowra-0.0.99.dev118}/tools/sync_pricing.py +0 -0
  381. {flowra-0.0.98 → flowra-0.0.99.dev118}/uv.lock +0 -0
@@ -5,6 +5,154 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org).
7
7
 
8
+ ## [Unreleased]
9
+
10
+ ### Changed
11
+ - **An interrupted agent does not enter its next step**, unless the step is
12
+ declared with `@step(runs_when_interrupted=True)`: the agent ends
13
+ `Interrupted` instead. Before, every step ran, and a step that did not check
14
+ the token went on with its work after the interrupt. It applies once the
15
+ agent's own token has fired (interrupted from outside, by an ancestor or by
16
+ its own `InterruptControl.interrupt()`, or started after the interrupt);
17
+ interrupting one's own children does not stop the parent's next step. The
18
+ `StepSpan` open at a skipped step closes with result `Interrupted`. A step
19
+ that must run on an interrupt (to save what was done or to take an
20
+ interrupted child) now declares it. The steps of `TurnAgent`, `ChatAgent`
21
+ and `ToolCallAgent` do, so they behave as before. A hand-built
22
+ `AgentDefinition` with no `StepMeta` for a step is not gated: its
23
+ `call_step` gets the step, as before.
24
+ - **A step that cannot take an interrupted child is an error, not an
25
+ interrupt, unless its agent was interrupted itself.** A parameter that takes
26
+ only `T` and finds an interrupted child raises `StepBindingError` (new, a
27
+ `TypeError`, from `flowra.agent`) naming the step, the parameter and what
28
+ each child it looked at gave; before, the agent ended `Interrupted`, so a
29
+ race that took its cancelled loser strictly looked interrupted. An agent
30
+ whose own token has fired still ends `Interrupted`. An annotated parameter
31
+ that nothing binds to now raises `StepBindingError` instead of Python's
32
+ missing-argument `TypeError`; one with a default takes it, even when it is
33
+ also optional (it used to get `None`); and a `TypeError` raised in a step's
34
+ body is no longer turned into `Interrupted` when a child was interrupted.
35
+ A parameter looks only at the children whose declared result types could
36
+ give it a value (a child built by hand without types always could), so a
37
+ service nobody provides is a `StepBindingError` even beside an interrupted
38
+ child whose declared types could not give it, also when the agent itself
39
+ was signalled (it used to end `Interrupted`), and the error no longer blames
40
+ that child; a
41
+ child the parameter's tag names that never could is named as the mistake
42
+ (`StepBindingError.mismatched`). `ChildOutput` carries the child's declared
43
+ `result_types`.
44
+ - **`T | Interrupted` takes the interrupt only of a child that could give a
45
+ `T`**, by its declared result types (a child without types could), so an
46
+ interrupted sibling no longer makes it ambiguous beside a finished `T`;
47
+ `Interrupted` alone still takes any child's, and `Interrupted[D]` any whose
48
+ data is a `D`. A step that took the interrupt of a child that can never give
49
+ a `T` through `T | Interrupted` now has nothing to bind from it (a
50
+ `StepBindingError`, also when the agent was signalled): take it with
51
+ `Interrupted` in a parameter of its own.
52
+ - **Every step annotates its return type with classes.** A step without a
53
+ return annotation, or with `Any`, a type variable or a `Literal` in it, is a
54
+ `TypeError` when the class is defined; before, its result went unchecked
55
+ and its agent's result types left it out.
56
+ - **A step returns exactly a type it declares**, its `Interrupted[D]` data
57
+ exactly a declared `D`: a subclass of one (a `bool` for an `int` too) is a
58
+ `TypeError` when the step returns. Before, it ran until the result was
59
+ saved, where an unregistered subclass failed.
60
+ - **An interrupt survives a resume.** Each agent's interrupt is saved with
61
+ the run, and `resume()` restores it: an agent interrupted before a crash is
62
+ still interrupted after it, so its next step is skipped and its children
63
+ start interrupted. Before, a resume started with every token clear, and an
64
+ interrupted run went on as if nothing had stopped it (a child stopped by
65
+ `interrupt_children()` kept working). An interrupt that came after the last
66
+ save is not in it. The runtime's interrupt now lasts until `run()` or
67
+ `resume()` returns or raises, wherever it stopped: before, one that failed
68
+ (or timed out) left it set, and the next run started interrupted. An
69
+ interrupt sent between runs still stops the next one, and a call refused
70
+ before it starts (another call still going, a pending execution, nothing
71
+ to resume, the storage failing to read) leaves it alone.
72
+ - **A subclass of a primitive is refused as a step's result or parameter type,
73
+ and in `Agent[S, R]`** (a `str` subclass, a `StrEnum`, an `IntEnum`): saved
74
+ as the primitive, it came back as one after a resume, so a step binding it
75
+ matched before a crash and not after. It is a `TypeError` when the class is
76
+ defined; use the primitive, or a dataclass that holds the value. An unmarked
77
+ step parameter may be a spec or a child, so it refuses one too, a `list` or
78
+ `dict` subclass included; a service of such a type takes
79
+ `Annotated[..., agent_arg.SERVICE]`.
80
+ - **An agent's `__post_init__` that raises `InterruptedError` interrupts the
81
+ agent instead of failing the run.** It is the agent's own decision to stop,
82
+ as a step's `InterruptedError` is; not being a step, it makes the agent
83
+ interrupt itself, and the agent's next step goes by the step gate. Before,
84
+ the error left the run (from a hook a `__post_init__` emits, such as
85
+ `TurnAgent`'s `TurnReadyEvent`, too).
86
+ - **An `AgentRuntime` runs one `run()` or `resume()` at a time**: a second
87
+ call while one is going raises `RuntimeError` ("already going", where a
88
+ `run()` with storage used to get "Pending execution exists" once the first
89
+ had saved). Before, a second `run()` without storage or before the first
90
+ save, or any second `resume()`, ran a second tree that freed the first
91
+ one's locks and, ending, cut the first one off from `runtime.interrupt()`.
92
+ - **An interrupted turn ends `Interrupted[TurnPartial]`, not a `TurnResult`.**
93
+ `Interrupted` (now generic, from `flowra.agent` as before) carries the data
94
+ an agent hands back when it stops: an agent declares it in its result type,
95
+ `Agent[S, R | Interrupted[D]]`, and its steps return `Interrupted(data=...)`
96
+ (an `Interrupted[D]` whose `data` is never `None`), with `D` a dataclass or
97
+ exactly a primitive (`str`, but not a subclass of `str`; anything else, a
98
+ bare `Interrupted` in `Agent[S, R]`, or a step's `Interrupted[D]` its agent
99
+ does not declare, is a `TypeError` when the class is defined). A bare
100
+ `Interrupted()` is an `Interrupted[None]`, which any agent can end with. The
101
+ data is saved with the run and survives a resume. A parent takes it by the
102
+ data's type: `T | Interrupted[D]` gets one whose data is a `D`,
103
+ `T | Interrupted[None]` a bare one, `T | Interrupted` one from a child that
104
+ could give a `T` (`Interrupted` alone: any). A step may now
105
+ return a bare `Interrupted` without declaring it. `TurnAgent` is an
106
+ `Agent[TurnSpec, TurnResult | Interrupted[TurnPartial]]` and ends
107
+ every interrupted turn with `Interrupted(data=TurnPartial(messages, usage))`
108
+ (`TurnPartial` from `flowra.lib.turn`), a hook's `InterruptedError`
109
+ included: its calls are answered, and before, such a turn lost its messages
110
+ (or, from `TurnReadyEvent`, failed the run); one from a hook watching a
111
+ reply (`UsageEvent`, `TextReasoningEvent`, `ResultMessageEvent`, …) keeps
112
+ the reply and completes the turn. A response with tool calls that an
113
+ interrupt stops before they run (a hook on the response,
114
+ `BeforeToolCallsEvent`, `BeforeToolCallEvent`) is kept too: each call is
115
+ answered `Tool execution interrupted` (one a `BeforeToolCallsEvent` handler
116
+ answered keeps that answer, a cut-off call its own error), where it used to
117
+ be dropped. `TurnStatus.INTERRUPTED` is gone: a parent that took
118
+ `TurnResult` and checked the status takes `TurnResult | Interrupted[TurnPartial]`
119
+ in a `runs_when_interrupted` step. `ChatAgent` saves such a turn, as
120
+ before, and ends `Interrupted[ChatPartial]` (`ChatPartial(usage)` from
121
+ `flowra.lib.chat`: the turn's usage, which a bare `Interrupted` lost; a
122
+ `SaveHistoryEvent` hook that raises `InterruptedError` leaves the turn
123
+ unsaved and ends a bare one); a turn that finished is now a `ChatResult` even
124
+ when the interrupt comes while it is saved (it used to end `Interrupted`).
125
+ `SaveHistoryEvent` gets `interrupted: bool`, and its `status` is `None`
126
+ for an interrupted turn: a hook that checked `status is
127
+ TurnStatus.INTERRUPTED` checks `interrupted`.
128
+
129
+ ### Fixed
130
+ - **`LLMCaller` checks an interrupt before the first attempt too**, not only
131
+ before a fallback: a call made once the interrupt has fired raises
132
+ `InterruptedError` without building a request or opening a span (a failed
133
+ `LLMCallSpan` or `DecisionCallSpan` showed in traces). `LLMCallAgent` and
134
+ `DecisionCallAgent` no longer check it themselves: an interrupted agent does
135
+ not enter their step anyway.
136
+ - **An interrupt does not drop a refusal `LLMCaller` holds.** With
137
+ `switch_on_refusal=True`, an interrupt that came after a config refused
138
+ raised `InterruptedError`, before the next attempt or cutting it short, and
139
+ the refusal was lost; the refusal is now returned.
140
+ - **A step's `Interrupted[D]` beside a `Literal` (or another member the result
141
+ check cannot read) is declared.** Such a member stopped the check before it
142
+ reached `Interrupted[D]`: `D` was not registered for saving, and an agent
143
+ that did not declare it was not told so.
144
+ - **A step parameter typed as a union with a generic member binds.**
145
+ `list[R] | Interrupted`, `dict[str, R] | Interrupted`, `list[R] | R` and
146
+ `list[R] | Interrupted[None]`, with `agent_arg.CHILD` or unmarked, dropped
147
+ the generic member and failed with `StepBindingError` on the child's list or
148
+ dict. A generic member is now matched by its class (`list`, `dict`), and the
149
+ error names it.
150
+ - **`WhenAny`, `WhenN` and `timeout` wait for a child to end, not for its first
151
+ step.** A child's step that went on (`GotoStep`, `GotoAgent`, `Spawn`)
152
+ counted as the child finishing, so the child that started first won and the
153
+ others were interrupted: `examples/race.py` always named the first model the
154
+ winner, and a worker whose first step went on stopped its `timeout`.
155
+
8
156
  ## [0.0.98] - 2026-11-10
9
157
 
10
158
  ### Fixed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: flowra
3
- Version: 0.0.98
3
+ Version: 0.0.99.dev118
4
4
  Summary: Flowra — flow infrastructure for building stateful LLM agents
5
5
  Project-URL: Repository, https://github.com/anna-money/flowra
6
6
  Project-URL: Changelog, https://github.com/anna-money/flowra/blob/master/CHANGELOG.md
@@ -69,7 +69,8 @@ parallel execution, and crash recovery. Requires Python 3.12+.
69
69
  - **Agents as tools** — `@agent_tool` decorator exposes an agent as a tool the
70
70
  LLM can call autonomously; sub-agent runs its own system prompt and tool loop
71
71
  - **Cooperative interrupts** — `InterruptToken` for graceful cancellation across
72
- the entire execution tree
72
+ the entire execution tree, by [rules](docs/interrupts.md) that keep a simple
73
+ agent right without handling them
73
74
  - **Pre-built agents** — `ChatAgent` (multi-turn chat with session history) and
74
75
  `TurnAgent` (single-turn LLM tool loop with hooks and caching)
75
76
 
@@ -147,6 +148,8 @@ flowra/
147
148
  - [Tools](docs/tools.md) — tool groups, MCP servers, service injection
148
149
  - [Agents](docs/agents.md) — custom agents, state machines, control flow,
149
150
  parallel execution
151
+ - [Interrupts](docs/interrupts.md) — how an interrupt travels through the agent
152
+ tree: the principles and rules every agent and building block follows
150
153
  - [Patterns](docs/patterns.md) — multi-agent patterns: router, pipeline, race,
151
154
  fan-out
152
155
  - [Observability](docs/observability.md) — hooks, spans, MLflow and OTel
@@ -24,7 +24,8 @@ parallel execution, and crash recovery. Requires Python 3.12+.
24
24
  - **Agents as tools** — `@agent_tool` decorator exposes an agent as a tool the
25
25
  LLM can call autonomously; sub-agent runs its own system prompt and tool loop
26
26
  - **Cooperative interrupts** — `InterruptToken` for graceful cancellation across
27
- the entire execution tree
27
+ the entire execution tree, by [rules](docs/interrupts.md) that keep a simple
28
+ agent right without handling them
28
29
  - **Pre-built agents** — `ChatAgent` (multi-turn chat with session history) and
29
30
  `TurnAgent` (single-turn LLM tool loop with hooks and caching)
30
31
 
@@ -102,6 +103,8 @@ flowra/
102
103
  - [Tools](docs/tools.md) — tool groups, MCP servers, service injection
103
104
  - [Agents](docs/agents.md) — custom agents, state machines, control flow,
104
105
  parallel execution
106
+ - [Interrupts](docs/interrupts.md) — how an interrupt travels through the agent
107
+ tree: the principles and rules every agent and building block follows
105
108
  - [Patterns](docs/patterns.md) — multi-agent patterns: router, pipeline, race,
106
109
  fan-out
107
110
  - [Observability](docs/observability.md) — hooks, spans, MLflow and OTel
@@ -55,14 +55,14 @@
55
55
  "ToolRegistry is a ConfigValue[ToolRegistry | None] in ChatConfig and TurnConfig (field name: tools)",
56
56
  "Tool handlers receive DI-injected services via type-annotated parameters; T | None receives None when the service is missing. @tool reads annotations in any spelling, as agent constructors and steps do: Optional/Union, Annotated outside or inside a union (Annotated[T, tool_arg.SERVICE] | None, Optional[Annotated[...]]), type aliases, for parameters and the return type",
57
57
 
58
- "AGENT FRAMEWORK: Agents are classes inheriting from Agent[S, R] with @step methods forming states. S is the spec (input) type, R is the result (output) type. Step params and result types can be dataclasses, primitives (str, int, float, bool, bytes, UUID, datetime, date, time, Decimal), or containers (list, dict). Generic forms like list[int] or dict[str, Foo] are accepted; the container origin is used for runtime dispatch. Action types (GotoStep/GotoAgent/Spawn) and None are also permitted as step returns",
58
+ "AGENT FRAMEWORK: Agents are classes inheriting from Agent[S, R] with @step methods forming states. S is the spec (input) type, R is the result (output) type. Step params and result types can be dataclasses, exactly primitives (str, int, float, bool, bytes, UUID, datetime, date, time, Decimal — not a subclass such as a StrEnum, which comes back as the primitive after a resume and is a TypeError when the class is defined, in Agent[S, R] too), or containers (list, dict). Generic forms like list[int] or dict[str, Foo] are accepted; the container origin is used for runtime dispatch. Action types (GotoStep/GotoAgent/Spawn) and None are also permitted as step returns",
59
59
  "Transitions: GotoStep/GotoAgent move to another step or agent (GotoAgent accepts state= to control persistent scope), Spawn runs parallel children with composable strategies, CallStep(fork_ephemeral=True) forks ephemeral state, CallAgent(state=...) controls child's persistent scope",
60
60
  "Spawn forms: Spawn(children=[...], then='join') flat list (implicit WhenAll), Spawn(child1, child2, then='join') positional args, Spawn(WhenAny(worker, timeout(seconds=30)), then='join') combinator form",
61
61
  "Composable spawn strategies: WhenAll(*nodes) waits for all, WhenAny(*nodes) first to complete interrupts rest, WhenN(*nodes, n=k) waits for k completions. Nestable: WhenAny(WhenAll(a, b), timeout(minutes=5))",
62
62
  "timeout(seconds=, minutes=) helper returns CallAgent for built-in timeout agent. Returns TimeoutExpired(seconds=...) on expiry, Interrupted() if cancelled by sibling",
63
- "Interrupted frozen dataclass — typed result for interrupted agents. Flows through execution tree via auto-propagation. Join steps bind Interrupted by type like any other result — use nullable T | None = None. Steps that declare | Interrupted in their return union type receive Interrupted child results instead of having them filtered",
63
+ "Interrupted[D] frozen dataclass (from flowra.agent; data: D, never None for Interrupted[D]; a bare Interrupted() is an Interrupted[None]) — typed result for interrupted agents. An agent that hands back what it got done declares it in its result type, Agent[S, R | Interrupted[D]], and its steps return Interrupted(data=...) with the same Interrupted[D] in their return types (D a dataclass or exactly a primitive — str, not a subclass of str: a list, a union or Any goes into a dataclass). A TypeError when the class is defined: another D, a step's Interrupted[D] the agent does not declare, or a bare Interrupted / Interrupted[None] in Agent[S, R] (any agent can end with a bare Interrupted(), so declaring it says nothing). The declaration registers D for saving, and the data survives a resume. It flows through the execution tree as a result a parent binds by type like any other: T | Interrupted gets one from a child whose declared result types could give a T (Interrupted alone gets any child's), T | Interrupted[D] one whose data is a D (nothing for a bare one or other data; list[T | Interrupted[D]] collects the same way), T | Interrupted[None] a bare one, T | None gets None, list[T] leaves it out; a parent that must take every way a child stops takes T | Interrupted[D] | Interrupted[None]. A parameter taking only T has nothing to bind: the parent ends Interrupted when its own token has fired (only a runs_when_interrupted step gets there), and otherwise raises StepBindingError (a TypeError naming the step, the parameter and what each child it looked at gave) — a child the parent interrupted, or one that interrupted itself (part of that child's contract), not taken, is a mistake, not an interrupt; a TypeError raised in a step's body is never turned into Interrupted. Steps that declare | Interrupted in a parameter's type receive the Interrupted results of the children that could give one of its other types (any child's when Interrupted stands alone), instead of having them filtered (once the parent itself is signalled — its own token fired — only a step declared @step(runs_when_interrupted=True) gets there; see STEP GATE)",
64
64
  "Returning a result (dataclass or primitive) completes the agent. Use None for agents without input or output: Agent[None, MyResult], Agent[MySpec, None], Agent[MySpec, int]. When a primitive-result agent is exposed via @agent_tool/make_agent_tool, its value is stringified into the ToolResultBlock's text block (str() for scalars, ISO format for dates) and output_schema is None",
65
- "Step parameter injection: params bind by type annotation automatically — no annotations needed when types are unambiguous. Markers via Annotated: agent_arg.AGENT_SPEC, agent_arg.STEP_SPEC, agent_arg.SERVICE, agent_arg.CHILD/CHILD('tag') (strictly single child, ANY type including list[X]=one list-returning child), agent_arg.CHILDREN/CHILDREN('tag') (strictly plural, requires list[X], yields [] when no matches). No marker on list[X] tries both Single(list) and Plural(X) at bind time — unique match wins, both raise RuntimeError('Ambiguous binding'), neither defaults to []. CallStep/CallAgent accept tag='name' for disambiguation. Agent spec (S from Agent[S, R]) is injected via __init__ by type matching, NOT available in step params. Steps can also receive services via DI",
65
+ "Step parameter injection: params bind by type annotation automatically — no annotations needed when types are unambiguous. Markers via Annotated: agent_arg.AGENT_SPEC, agent_arg.STEP_SPEC, agent_arg.SERVICE, agent_arg.CHILD/CHILD('tag') (strictly single child, ANY type including list[X]=one list-returning child), agent_arg.CHILDREN/CHILDREN('tag') (strictly plural, requires list[X], yields [] when no matches). No marker on list[X] tries both Single(list) and Plural(X) at bind time — unique match wins, both raise RuntimeError('Ambiguous binding'), neither defaults to []. An annotated parameter nothing binds to takes its default when the method gives one, else None when optional, and otherwise raises StepBindingError (from flowra.agent, a TypeError). A parameter looks only at the children whose declared result types could give it a value (issubclass of a declared type to the parameter's; a hand-built child without types always could): a service nobody provides fails with StepBindingError, not blamed on a child whose declared types could not give it, and a child its tag names that never could is named in StepBindingError.mismatched; a bare Interrupted counts only the children that could give one of the other types. Every step annotates its return type with classes (no annotation, Any, a TypeVar or a Literal is a TypeError at class definition), and returns exactly a declared type — a subclass (a bool for an int) or Interrupted data of a subclass of D is a TypeError when the step returns. CallStep/CallAgent accept tag='name' for disambiguation. Agent spec (S from Agent[S, R]) is injected via __init__ by type matching, NOT available in step params. Steps can also receive services via DI",
66
66
  "Agent path convention (filesystem-style): '/foo/bar' absolute; 'foo/bar' or './foo/bar' relative down from caller; '../foo' relative up; '.' self; '..' parent. Bare refs without a caller context (top-level: runtime.run, root-level hooks) are absolute. Applies to CallAgent(agent=...), GotoAgent(agent=...), runtime.run(agent=...), hooks.on(scope=...)/hooks.on(during=...). CallAgent/GotoAgent/runtime.run only accept agents declared by the caller or one of its registry ancestors (same rule for types and strings) — an absolute path into a sibling branch raises KeyError; runtime.run starts top-level agents only; GotoAgent targets must be declared by the replaced agent's caller or its ancestors. scope=/during= are filters and may name any path",
67
67
  "hooks.on/on_span matching has three layers: (1) baseline — agent-context subscriptions only fire when the subscriber's path appears as a strict ancestor on event.context.stack (never self-emits, never siblings, never ancestors); global subscriptions via runtime.hooks skip the baseline and fire on everything; (2) scope= (optional) — registry-path filter on the emitter: str follows path convention, type resolves via registry.name_for_type starting from subscriber's path; emitter.path must be at or under resolved scope; (3) during= (optional) — call-stack filter: str matches frame.path under resolved path, type matches frame.source_type; searched in frames below subscriber, never above. All applied filters AND together. scope='.' resolves to subscriber path (baseline still excludes self). on_self_span is separate from this matching machinery: it stores the handler on the agent's own hooks instance and fires for that instance's own emits only (no scope/during)",
68
68
  "Import agent markers: from flowra.agent import agent_arg. For tools: from flowra.tools import tool_arg",
@@ -76,11 +76,14 @@
76
76
 
77
77
  "RUNTIME: AgentRuntime is the entry point — takes agent definitions, storage, services, and optional safety limits",
78
78
  "Create runtime: AgentRuntime(agents={'name': AgentClass}, storage=storage, services={ServiceType: instance}, max_iterations=1000, timeout=300.0). Each agent class can only be registered once per level (one class = one name) — needed for type-based resolution. To run multiple instances, register once and use multiple CallAgent calls with different specs/tags",
79
+ "POST_INIT INTERRUPT: an InterruptedError raised from an agent's __post_init__ (a hook it emits there, e.g. TurnAgent's TurnReadyEvent) is the agent's own decision to stop: the engine has the agent interrupt itself (its InterruptControl), and its next step goes by the step gate — it used to fail the run",
80
+ "STEP GATE: once an agent's own InterruptToken has fired (runtime.interrupt(), an ancestor interrupted, its own InterruptControl.interrupt(), or the agent started after the interrupt), the engine does not enter its next step and the agent ends Interrupted() — unless the step is declared @step(runs_when_interrupted=True), which then checks the token itself. Interrupting one's own children (interrupt_children(), WhenAny) does not gate the parent's steps. TurnAgent, ChatAgent and ToolCallAgent declare all their steps so; LLMCallAgent, DecisionCallAgent and timeout()'s agent do not: started after an interrupt, they end Interrupted without running. A hand-built AgentDefinition with no StepMeta for a step is not gated: its call_step gets the step. The StepSpan open at a skipped step closes with result Interrupted",
79
81
  "Run agent: result = await runtime.run(agent=AgentClass, spec=SpecObject) — entry point resolved from @step(entry=True)",
80
82
  "Override limits per call: runtime.run(agent=A, max_iterations=50, timeout=30.0) or runtime.resume(max_iterations=100)",
81
83
  "max_iterations limits engine advance steps (raises RuntimeError if exceeded), timeout is wall-clock seconds (raises asyncio.TimeoutError)",
82
84
  "Pass None to disable a constructor default for a specific call: runtime.run(agent=A, max_iterations=None)",
83
85
  "Resume after crash: result = await runtime.resume() — replays from last persisted state",
86
+ "An interrupt is saved with the run: each node's interrupted flag is in the execution snapshot, and resume() restores it (an agent interrupted before a crash stays interrupted; one stopped by its parent's interrupt_children() too; an interrupt after the last save is lost). runtime.interrupt() lasts until the current run()/resume() returns or raises, wherever it stopped; one sent between runs stops the next run()/resume(); a call refused before it starts (another run()/resume() still going — a runtime runs one at a time and raises RuntimeError for a second —, pending execution, nothing to resume, storage failing to read) leaves it as it is",
84
87
  "Check pending: await runtime.has_pending_execution() — True if there's an interrupted execution to resume",
85
88
  "Services are DI-injected into agent constructors by matching parameter type annotations. Visibility is lexical (registry tree, not call stack): an agent sees AgentRuntime(services=...) plus services provided (ServiceLocator.provide in __init__) by its registry ancestors; nearer provides shadow farther ones; a caller from another branch contributes nothing. So an agent gets the same services no matter who calls it. Tools see the services of the agent running them (plus ToolCallAgentContext). A missing required (non-Optional in any spelling, no default) constructor service raises MissingServiceError naming the service, agent path and candidate providers",
86
89
 
@@ -103,11 +106,12 @@
103
106
  "Seed a session: state = SessionState(); state.store()['conversation'].slot(MutableList[Message], 'messages').extend(recorded); runtime = AgentRuntime(agents=..., storage=InMemorySessionStorage(state.snapshot()))",
104
107
  "Reuse, do not duplicate, the scope address: a production helper create(store: AgentStore) -> ConversationHistory is the only thing that knows the scope name and slot key, and works unchanged against both a live store and a SessionState store",
105
108
 
109
+ "INTERRUPTS REFERENCE: docs/interrupts.md holds the principles (P1-P5), the rules (R1-R9) and what each building block does when interrupted; agents.md shows the API. A simple agent needs no interrupt handling: an interrupted agent does not enter its next step, a parent gets a child's declared type or nothing, and a mistake (a child the parent interrupted itself and does not take) is an error, never an interrupt",
106
110
  "COOPERATIVE INTERRUPTS: .NET-style CancellationToken pattern — InterruptToken.check() raises InterruptedError, with_interrupt() raises InterruptedError. InterruptControl DI service provides interrupt() and interrupt_children() for self/child interruption",
107
111
  "InterruptTokenSource creates tokens: source = InterruptTokenSource(); token = source.token; source.interrupt(). Runtime exposes runtime.interrupt()",
108
112
  "token.check() raises InterruptedError if signaled (like ThrowIfCancellationRequested). with_interrupt(ait, token) wraps AsyncIterator and raises InterruptedError when token fires; interruptible(awaitable, token) awaits one awaitable and raises InterruptedError as soon as the token fires, cancelling it (a result ready by then is kept)",
109
- "When a step raises InterruptedError, engine catches it per-node and converts to Interrupted() result that flows up via auto-propagation — runtime.run() returns Interrupted(). Agents can catch InterruptedError explicitly for partial results",
110
- "TurnAgent catches interrupts and returns TurnResult(status=INTERRUPTED) with accumulated messages — no message loss on interrupt. ChatAgent saves turn history to persistent storage before propagating Interrupted up",
113
+ "When a step raises InterruptedError, engine catches it per-node and converts to Interrupted() result that its parent binds by type (see Interrupted) — runtime.run() returns Interrupted() when the root ends so. Agents can catch InterruptedError explicitly for partial results",
114
+ "TurnAgent catches interrupts and ends Interrupted[TurnPartial] (TurnPartial(messages, usage) from flowra.lib.turn: the turn's messages so far, every tool call answered; a response whose calls an interrupt stopped before they ran is kept, each call answered 'Tool execution interrupted' — one a BeforeToolCallsEvent handler answered keeps that answer, a cut-off call its own error) — no message loss on interrupt; TurnStatus has no INTERRUPTED. ChatAgent takes TurnResult | Interrupted[TurnPartial], saves an interrupted turn to the history and ends Interrupted[ChatPartial] (ChatPartial(usage) from flowra.lib.chat; a SaveHistoryEvent hook's InterruptedError leaves the turn unsaved and ends a bare Interrupted); a turn that finished is a ChatResult even if the interrupt comes while it is saved",
111
115
  "ToolCallAgent catches InterruptedError from tool execution (raised inside a @tool function too) and returns an error ToolResultBlock ('Tool execution interrupted', no error log) — tools can safely call interrupt.check() without crashing the execution tree. An interrupted sub-agent behind an agent tool yields the same error result ('Tool execution interrupted', is_error=True), never a serialized Interrupted — every tool_use the turn committed still gets a tool_result",
112
116
 
113
117
  "PRE-BUILT AGENTS — LLMCallAgent: single LLM call with tools/json_schema support, no tool loop, no history",
@@ -118,21 +122,21 @@
118
122
 
119
123
  "PRE-BUILT AGENTS — ChatAgent: multi-turn chat with session history persistence",
120
124
  "ChatAgent usage: runtime.run(agent=ChatAgent, spec=ChatSpec.text(text))",
121
- "ChatSpec(messages: list[UserMessage]) is the input, ChatResult(status: TurnStatus, response: str | None, usage: Usage | None, stop_reason: StopReason | None, refusal: Refusal | None) is the output; status is the turn's (COMPLETED with a stop_reason, or MAX_LLM_CALLS / FINISH_REQUESTED without one), so only COMPLETED + END_TURN is a reply; an interrupted run returns Interrupted, not a ChatResult. A refused turn has response None, stop_reason REFUSAL, and ChatAgent leaves the whole refused turn out of the history (Anthropic: a kept refused turn gets the next ones refused too). A failed LLM call raises its LLMError out of ChatAgent / TurnAgent (resume() after fixing)",
125
+ "ChatSpec(messages: list[UserMessage]) is the input, ChatResult(status: TurnStatus, response: str | None, usage: Usage | None, stop_reason: StopReason | None, refusal: Refusal | None) is the output; status is the turn's (COMPLETED with a stop_reason, or MAX_LLM_CALLS / FINISH_REQUESTED without one), so only COMPLETED + END_TURN is a reply; an interrupted run returns Interrupted[ChatPartial] with the turn's usage, not a ChatResult. A refused turn has response None, stop_reason REFUSAL, and ChatAgent leaves the whole refused turn out of the history (Anthropic: a kept refused turn gets the next ones refused too). A failed LLM call raises its LLMError out of ChatAgent / TurnAgent (resume() after fixing)",
122
126
  "ChatConfig configures ChatAgent: ChatConfig(llm_config=LLMConfig(model='...'), system=[SystemMessage(...)]). Optional history= controls where conversation history is stored: None (default) uses store.persistent.slot(MutableList, 'history'); a callable (AgentStore) -> MutableList for custom scopes (e.g. lambda store: store['shared'].slot(...) or store.ephemeral.slot(...)); or a pre-created MutableList instance",
123
127
  "Hook system: HookSubscription (ABC, subscribe-only) and Hooks (ABC, subscribe + emit). Single implementation HooksImpl. Root instance (runtime.hooks) stores global handlers; agent instances share root storage and add emit/span. Agents declare hooks: Hooks in __init__. Dynamic handler resolution at emit time (no snapshots)",
124
128
  "ExecutionContext: automatic execution metadata stamped on every emitted Event. Two hierarchies: execution stack (ExecutionContext.stack — tuple[ExecutionFrame, ...] from root to emitter) and registration hierarchy (AgentInfo.parent chain). ExecutionFrame has agent: AgentInfo, spec, tag. AgentInfo has name, path, source_type, parent. Stack navigation: ctx.find_spec(T)/get_spec(T) find nearest spec by type, ctx.find_frame(spec_type=, agent_type=)/get_frame(...) find nearest frame. get_* raise LookupError on miss",
125
129
  "Import ExecutionContext types: from flowra.agent import ExecutionContext, ExecutionFrame, AgentInfo. Access via event.context in handlers",
126
130
  "Scoped subscription: agents subscribe to sub-agent events via hooks.on(EventType, handler) and hooks.on_span(SpanType, handler) in __init__. scope= parameter (registry filter on the emitter): None (all descendants), str (child path), type[Agent] (resolved through the registry from the subscriber's path upwards). during= parameter: call-stack filter by agent type or path. Global handlers always see all events. Scoped handlers are additive, cannot block propagation",
127
131
  "Child agents share parent handlers automatically — HooksImpl.for_agent(context) creates an agent-scoped view sharing root storage. Dynamic lookup at emit time includes both global and matching scoped handlers",
128
- "SaveHistoryEvent emitted before messages are saved to session history (not for a refused turn, which ChatAgent does not save); event.data.status is the turn's TurnStatus — an INTERRUPTED turn ends with no reply, so a hook can append a marker for the next turn — mutate event.data.messages in place to control what gets persisted; a tool result is dropped along with a call the save leaves out, and a call that stays needs its result, so remove or rename a call and its result together. After the hook, ChatAgent automatically strips messages with transient=True and transient blocks inside remaining messages, including transient blocks inside a ToolResultBlock's content (a message left with no blocks is dropped)",
132
+ "SaveHistoryEvent emitted before messages are saved to session history (not for a refused turn, which ChatAgent does not save); event.data.interrupted says the turn was interrupted (event.data.status is then None, otherwise the turn's TurnStatus) — an interrupted turn ends with no reply, so a hook can append a marker for the next turn — mutate event.data.messages in place to control what gets persisted; a tool result is dropped along with a call the save leaves out, and a call that stays needs its result, so remove or rename a call and its result together. After the hook, ChatAgent automatically strips messages with transient=True and transient blocks inside remaining messages, including transient blocks inside a ToolResultBlock's content (a message left with no blocks is dropped)",
129
133
  "Transient messages and transient blocks (transient=True) are automatically filtered from ChatAgent session history. No manual SaveHistoryEvent hook needed. The hook still fires first, so handlers can process transient content before auto-filtering",
130
134
 
131
135
  "PRE-BUILT AGENTS — TurnAgent: single-turn LLM tool loop with hooks and caching",
132
136
  "TurnAgent sends messages to LLM, executes tool calls, feeds results back, repeats until done",
133
137
  "TurnAgent stop handling: a response without tool calls ends the turn with TurnStatus.COMPLETED and TurnResult.stop_reason (END_TURN, MAX_TOKENS, STOP_SEQUENCE, OTHER, SCHEMA_VALIDATION_FAILED, REFUSAL). On REFUSAL TurnResult.refusal is set, result_message is None and messages keep the turn so far (tool calls included) with no empty assistant message. If a response stopped with anything but END_TURN/TOOL_USE ends on a tool call, that call was cut off: it is not run and gets an error ToolResultBlock (it appears in BeforeToolCallsEvent.tool_uses; no BeforeToolCallEvent/AfterToolCallEvent, no ToolCallSpan, not counted in max_consecutive_errors), the complete calls before it run, and the loop continues so the model can retry (bounded by max_llm_calls). History never holds an unanswered tool_use",
134
138
  "TurnConfig configures TurnAgent: TurnConfig(llm_config=LLMConfig(model='...'), system=[...], history=[...])",
135
- "RENDER: ChatConfig.render / TurnConfig.render (PromptRender = Callable[[Prompt], Prompt | Awaitable[Prompt]]; Prompt from flowra.lib.turn has system and messages) is called once per LLM call of the turn (not per fallback attempt), before LLMCaller, with the system messages and the conversation (history, then turn messages). What it returns is sent to every fallback link; each link's request_extensions apply after it, and each attempt's LLMCallSpan carries the request with them applied. Stored history and turn messages are not changed, so a marker block can be rendered from live state on each call; build new messages, never edit the given ones. Messages left with no blocks are not sent, none left at all is a ValueError before the call; a tool call must still be followed straight away by its results (Claude and OpenAI Chat Completions reject anything in between); an error in render is raised from the turn as is; an interrupt stops an async render and ends the turn INTERRUPTED",
139
+ "RENDER: ChatConfig.render / TurnConfig.render (PromptRender = Callable[[Prompt], Prompt | Awaitable[Prompt]]; Prompt from flowra.lib.turn has system and messages) is called once per LLM call of the turn (not per fallback attempt), before LLMCaller, with the system messages and the conversation (history, then turn messages). What it returns is sent to every fallback link; each link's request_extensions apply after it, and each attempt's LLMCallSpan carries the request with them applied. Stored history and turn messages are not changed, so a marker block can be rendered from live state on each call; build new messages, never edit the given ones. Messages left with no blocks are not sent, none left at all is a ValueError before the call; a tool call must still be followed straight away by its results (Claude and OpenAI Chat Completions reject anything in between); an error in render is raised from the turn as is; an interrupt stops an async render and ends the turn Interrupted",
136
140
  "TurnAgent lifecycle: __post_init__ emits TurnReadyEvent(context, turn_messages) — fires on both creation and crash recovery. ChatAgent subscribes and emits ConversationReadyEvent(conversation, context) with a Conversation view combining history + turn messages",
137
141
  "Conversation class (from flowra.lib.chat): read-only Sequence view over history + turn_messages. Supports len(), indexing, slicing, forward/reverse iteration. Live — reflects changes to underlying lists. Properties: history_len, turn_len. Method without_pending_tool_use() -> list[UserMessage | AssistantMessage] returns messages with ToolUseBlocks stripped from the last AssistantMessage (drops the message entirely if it becomes empty) — use it inside an agent-as-tool to feed the parent conversation to a child LLM call without the unresolved tool-use that spawned it",
138
142
  "TurnAgent hook events: StartTurnEvent (messages, metadata — mutate messages to augment input), MessageAcceptedEvent, StartIterationEvent, TextReasoningEvent (each TextBlock with text in response), ThinkingEvent (each ThinkingBlock with text; not redacted or signature-only thoughts), ServerToolCallEvent (server-side tool call from intermediate messages, e.g. tool search), ServerToolResultEvent (server-side tool result), ResultMessageEvent, BeforeToolCallsEvent (once per model message that has tool calls, even when it has only one, before any runs; tool_uses is every call of the message, a cut-off call included (an answer under its id is not used); put a ToolResult into results under a call's id to answer it without running it — that call gets no BeforeToolCallEvent and no ToolCallSpan, its result goes through AfterToolCallEvent with prefilled=True and max_consecutive_errors in message order, an error without error_kind gets EXECUTION; an answered call never reaches the tool, so neither the registry nor allowed_tools/denied_tools apply: an answer to an unknown or denied tool reaches the model as given, not as Unknown tool; a key not among the message's call ids raises ValueError; tool_uses is the event's own list, so changing it changes neither the calls that run nor the ids that may be answered), BeforeToolCallEvent (has tool_definition: ToolDefinition | None; mutable tool_use (a replacement keeps the call's id; changing it raises ValueError), headers, meta — see ToolCallInfo; not emitted for a call answered in BeforeToolCallsEvent), AfterToolCallEvent (fires after execution, and for a call answered in BeforeToolCallsEvent; has error_kind; prefilled is true for a call answered in BeforeToolCallsEvent; message_tool_uses is every call of the model message it came from, itself included, in order, as BeforeToolCallsEvent got them (a cut-off call included though it fires no AfterToolCallEvent; a call a BeforeToolCallEvent handler replaced is the replacement; replacing the list has no effect; left out or empty when an event is built outside TurnAgent (a call run on its own rather than with the calls of a model message, e.g. one held back and run later), it is just its own call) — tells the calls of its message from calls of earlier messages; result is a single ToolResultBlock; append TextBlock/MediaBlock to additional_blocks to attach them to this call's result — they go at the end of its content, also when max_consecutive_errors replaces it, so they stay with their call and never land between the results of parallel calls; mark one transient to keep it out of saved history; being part of the result, a MediaBlock there takes the providers' rules for media in a tool result (Chat Completions raises, Gemini before 3 does not see it) and a transient block ends the non-transient cache prefix before the result). Delta events: TextDeltaEvent, ThinkingDeltaEvent (from flowra.lib.observability — shared with LLMCallAgent). UsageEvent emitted after each LLM call + subscribed to accumulate usage from child agents (e.g. agent_as_tool). Span-hooks: LLMCallSpan, ToolCallSpan. Request transforms (prompt caching, tool search) are NOT hooks — they live on LLMConfig.request_extensions. A conversation transform for every fallback link goes in ChatConfig.render / TurnConfig.render (see RENDER)",
@@ -149,7 +153,7 @@
149
153
  "Provider-namespaced extras: LLMData.extra uses provider-specific namespaces — extra['anthropic'], extra['openai'] (Chat Completions), extra['openai_responses'], extra['google'], extra['openai_decisions'], extra['typesafe'] (the last two decisions). Hooks write under their provider key, providers read only their own namespace via extra.get('provider_key', {}). Prevents cross-provider conflicts when multiple hooks are installed",
150
154
 
151
155
  "CONFIG: LLMConfig(provider, model, temperature, top_p, max_tokens, stop_sequences, extra, request_extensions, fallback) configures LLM calls. provider (LLMProvider) is part of the config — agents (LLMCallAgent, TurnAgent) read it from LLMConfig. extra is provider-namespaced, use build_extra() to construct. request_extensions is a Sequence[RequestExtension] applied to the LLMRequest just before the provider call",
152
- "FALLBACK: LLMConfig.fallback is a Sequence[LLMConfig] tried in order when the config fails; each fallback is complete on its own (provider, model, parameters, extra, request_extensions) and takes only the conversation (system, messages, tools, json_schema) — nothing from the config before it. A fallback with its own fallback is a ValueError when the LLMConfig is built. flowra.lib.LLMCaller does the calling: caller.call(llm_config, system=..., messages=..., tools=..., json_schema=..., hooks=None, interrupt=None) -> LLMResponse builds a request per config tried, runs that config's extensions, calls its provider. TurnAgent, ChatAgent and LLMCallAgent call through the LLMCaller service, or DEFAULT_LLM_CALLER (one per process) when none is provided; code outside agents calls DEFAULT_LLM_CALLER.call or its own LLMCaller. FallbackPolicy (subclass to change): TransientLLMError -> next config; AuthFailedError/NotFoundError/QuotaExhaustedError -> next config and on_broken(config, error) (sync: called in place, keep it quick; async: runs as its own task, the chain does not wait; once per link until it answers again); BadRequestError incl. ContextTooLongError -> raised; an error after a stream yielded events (partial) -> raised; every config failed -> the last tried config's error raised; an interrupt cuts the current call short, streamed or not (InterruptedError), and stops the chain before its next attempt. A config without fallback is called as is (no rest, no on_broken). A refusal is returned as is unless FallbackPolicy(switch_on_refusal=True), and always when a stream had yielded events before it; then the last refusal is returned if all refuse, and once one refused the chain returns it rather than raise a later error, except a partial one. A link (provider object + model) that failed for its own reasons (FallbackPolicy.rests: transient or broken) rests FallbackPolicy.rest seconds (300): tried after the others, back when the rest is over or once it answers; kept in the LLMCaller's memory with providers held weakly (ProviderBase has a __weakref__ slot), shared by chains with the same link. With hooks each attempt is its own LLMCallSpan; the call streams when TextDeltaEvent/ThinkingDeltaEvent handlers exist. LLMCallAgent returns a failure only once the chain gives up: an error that does not switch, or the last tried config's error when every config failed",
156
+ "FALLBACK: LLMConfig.fallback is a Sequence[LLMConfig] tried in order when the config fails; each fallback is complete on its own (provider, model, parameters, extra, request_extensions) and takes only the conversation (system, messages, tools, json_schema) — nothing from the config before it. A fallback with its own fallback is a ValueError when the LLMConfig is built. flowra.lib.LLMCaller does the calling: caller.call(llm_config, system=..., messages=..., tools=..., json_schema=..., hooks=None, interrupt=None) -> LLMResponse builds a request per config tried, runs that config's extensions, calls its provider. TurnAgent, ChatAgent and LLMCallAgent call through the LLMCaller service, or DEFAULT_LLM_CALLER (one per process) when none is provided; code outside agents calls DEFAULT_LLM_CALLER.call or its own LLMCaller. FallbackPolicy (subclass to change): TransientLLMError -> next config; AuthFailedError/NotFoundError/QuotaExhaustedError -> next config and on_broken(config, error) (sync: called in place, keep it quick; async: runs as its own task, the chain does not wait; once per link until it answers again); BadRequestError incl. ContextTooLongError -> raised; an error after a stream yielded events (partial) -> raised; every config failed -> the last tried config's error raised; an interrupt cuts the current call short, streamed or not (InterruptedError), and stops the chain before its next attempt; a refusal held to try the next link (switch_on_refusal) is returned instead of InterruptedError, also when the interrupt cuts the next attempt short. A config without fallback is called as is (no rest, no on_broken). A refusal is returned as is unless FallbackPolicy(switch_on_refusal=True), and always when a stream had yielded events before it; then the last refusal is returned if all refuse, and once one refused the chain returns it rather than raise a later error, except a partial one. A link (provider object + model) that failed for its own reasons (FallbackPolicy.rests: transient or broken) rests FallbackPolicy.rest seconds (300): tried after the others, back when the rest is over or once it answers; kept in the LLMCaller's memory with providers held weakly (ProviderBase has a __weakref__ slot), shared by chains with the same link. With hooks each attempt is its own LLMCallSpan; the call streams when TextDeltaEvent/ThinkingDeltaEvent handlers exist. LLMCallAgent returns a failure only once the chain gives up: an error that does not switch, or the last tried config's error when every config failed",
153
157
  "DECISION FALLBACK AND AGENT: flowra.lib.DecisionConfig(provider: DecisionProvider, model, extra={}, fallback=()) is LLMConfig's counterpart for decisions (nested fallback is a ValueError). LLMCaller.decide(config, *, input: str | Sequence[TextBlock | MediaBlock], questions, hooks=None, interrupt=None) -> DecisionResponse runs the same chain as call: same FallbackPolicy, resting links, on_broken (OnBroken is told LLMConfig | DecisionConfig); a fallback takes only input and questions — a question's per-supplier options sit in namespaced question.extra, so one question list serves a chain across suppliers; no stream, so never partial; with switch_on_refusal a response refusing any question moves on, and the last refusal is returned if every later link refuses or fails; each attempt deep-copies input and questions; with hooks each attempt is a DecisionCallSpan(request, response). DecisionCallAgent (flowra.lib.decision_call; also flowra.lib) is LLMCallAgent's counterpart: DecisionCallConfig(decision_config: ConfigValue[DecisionConfig], questions: ConfigValue[list[DecisionQuestion]]), DecisionCallSpec(input), DecisionCallResult(answers, usage, model, elapsed, failure; .error; .answer(question) typed like DecisionResponse.answer, KeyError after a failure); returns LLMError as failure, emits UsageEvent, calls through the LLMCaller service or DEFAULT_LLM_CALLER. Tracing: MLflow traces DecisionCallSpan as an LLM span 'decide (<model>)' with inputs (model, extra, input with [image] markers, questions) and outputs (answers, served model) plus token usage/cost; OTel as 'decide <model>' with gen_ai.operation.name=decide, flowra.decision.questions (names), usage attributes, and the request's extra (it can name the end user, e.g. safety_identifier), flowra.decision.input and flowra.decision.answers only with capture_content; install(trace_decision_calls=False) turns either off",
154
158
  "ConfigValue[T] wraps static or dynamic (callable) config values: ConfigValue[str] | ConfigValue[Callable[[], str]]",
155
159