flowra 0.0.98__tar.gz → 0.0.99.dev119__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 (395) hide show
  1. {flowra-0.0.98 → flowra-0.0.99.dev119}/.github/workflows/master.yml +1 -1
  2. {flowra-0.0.98 → flowra-0.0.99.dev119}/.github/workflows/pull_request.yml +1 -1
  3. flowra-0.0.99.dev119/.python-version +1 -0
  4. {flowra-0.0.98 → flowra-0.0.99.dev119}/AGENTS.md +2 -2
  5. {flowra-0.0.98 → flowra-0.0.99.dev119}/CHANGELOG.md +324 -0
  6. {flowra-0.0.98 → flowra-0.0.99.dev119}/CLAUDE.md +4 -4
  7. {flowra-0.0.98 → flowra-0.0.99.dev119}/Makefile +1 -1
  8. {flowra-0.0.98 → flowra-0.0.99.dev119}/PKG-INFO +24 -18
  9. {flowra-0.0.98 → flowra-0.0.99.dev119}/README.md +9 -3
  10. {flowra-0.0.98 → flowra-0.0.99.dev119}/context7.json +30 -25
  11. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/agents.md +255 -64
  12. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/architecture.md +12 -8
  13. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/getting-started.md +9 -2
  14. flowra-0.0.99.dev119/docs/interrupts.md +279 -0
  15. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/llm.md +69 -20
  16. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/observability.md +56 -12
  17. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/patterns.md +37 -15
  18. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/e2e_security.md +1 -1
  19. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/review_prompts/step2_code_style.md +9 -1
  20. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/review_prompts/step3_documentation.md +3 -2
  21. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/review_prompts/step5_doc_audit.md +1 -1
  22. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/todo.md +10 -0
  23. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/tools.md +63 -3
  24. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/video_script.md +1 -1
  25. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/agent_as_tool.py +11 -0
  26. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/app_agent.py +1 -2
  27. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/console_chat.py +4 -0
  28. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/docs/agents_custom.py +7 -0
  29. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/docs/agents_parallel.py +14 -2
  30. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/docs/getting_started_chat.py +4 -0
  31. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/docs/getting_started_streaming.py +4 -0
  32. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/docs/getting_started_tools.py +6 -0
  33. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/docs/llm_streaming.py +4 -0
  34. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/docs/llm_structured_output.py +4 -0
  35. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/docs/tools_service_injection.py +7 -0
  36. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/escalation.py +26 -9
  37. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/llm_logging.py +5 -0
  38. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/menu_agent.py +9 -0
  39. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/menu_agent_class.py +12 -0
  40. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/mlflow_demo.py +4 -0
  41. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/mlflow_dual_export_demo.py +4 -0
  42. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/mlflow_nested_demo.py +5 -0
  43. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/mlflow_otel_both_demo.py +4 -0
  44. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/mlflow_otel_nested_demo.py +5 -0
  45. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/mlflow_parallel_demo.py +6 -0
  46. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/otel_demo.py +6 -2
  47. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/otel_jaeger_demo.py +5 -0
  48. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/otel_nested_demo.py +5 -0
  49. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/otel_visualize.py +9 -2
  50. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/race.py +20 -4
  51. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/span_crash_demo.py +4 -0
  52. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/span_demo.py +4 -0
  53. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/tools/__init__.py +2 -0
  54. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/tools/calculator.py +8 -0
  55. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/tools/random_numbers.py +5 -0
  56. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/tui_chat.py +191 -182
  57. flowra-0.0.99.dev119/flowra/_aio.py +20 -0
  58. flowra-0.0.99.dev119/flowra/_typing.py +226 -0
  59. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/__init__.py +7 -2
  60. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/definition/__init__.py +5 -0
  61. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/definition/compile/compiler.py +8 -4
  62. flowra-0.0.99.dev119/flowra/agent/definition/compile/contract.py +162 -0
  63. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/definition/compile/instance.py +98 -3
  64. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/definition/compile/step_params.py +99 -18
  65. flowra-0.0.99.dev119/flowra/agent/definition/compile/step_validation.py +169 -0
  66. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/definition/compile/steps.py +12 -4
  67. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/definition/compile/type_registry.py +13 -30
  68. flowra-0.0.99.dev119/flowra/agent/definition/errors.py +43 -0
  69. flowra-0.0.99.dev119/flowra/agent/definition/interrupted.py +29 -0
  70. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/definition/model.py +18 -0
  71. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/definition/shared_persistent.py +2 -2
  72. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/definition/step.py +8 -13
  73. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/definition/step_helpers.py +11 -0
  74. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/flow/__init__.py +3 -3
  75. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/flow/flowing_registry.py +1 -1
  76. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/flow/hooks.py +53 -62
  77. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/flow/interrupt.py +8 -12
  78. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/flow/interrupt_helpers.py +4 -0
  79. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/runtime/__init__.py +2 -1
  80. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/runtime/engine.py +138 -72
  81. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/runtime/execution.py +24 -5
  82. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/runtime/key_locks.py +1 -1
  83. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/runtime/runtime.py +212 -82
  84. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/runtime/scope.py +34 -29
  85. flowra-0.0.99.dev119/flowra/agent/runtime/serialization.py +97 -0
  86. flowra-0.0.99.dev119/flowra/agent/runtime/spans.py +58 -0
  87. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/runtime/spawn_satisfaction.py +7 -5
  88. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/storage/file.py +5 -0
  89. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/ext/mlflow.py +17 -5
  90. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/ext/otel.py +39 -1
  91. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/chat/__init__.py +2 -1
  92. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/chat/agent.py +24 -12
  93. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/chat/conversation.py +10 -8
  94. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/chat/hook_events.py +7 -3
  95. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/chat/spec.py +12 -1
  96. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/decision_call/agent.py +0 -2
  97. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/llm_call/agent.py +0 -2
  98. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/llm_caller.py +124 -31
  99. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/turn/__init__.py +2 -1
  100. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/turn/agent.py +266 -104
  101. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/turn/config.py +1 -1
  102. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/turn/spec.py +16 -3
  103. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/turn/tool_call/agent.py +36 -22
  104. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/turn/tool_call/context.py +4 -2
  105. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/__init__.py +2 -1
  106. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/blocks.py +16 -0
  107. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/errors.py +6 -3
  108. flowra-0.0.99.dev119/flowra/llm/ext/__init__.py +1 -0
  109. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/openai_schema.py +28 -1
  110. flowra-0.0.99.dev119/flowra/llm/providers/__init__.py +1 -0
  111. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/providers/_openai_common.py +13 -5
  112. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/providers/anthropic.py +8 -8
  113. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/providers/anthropic_bedrock.py +6 -4
  114. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/providers/anthropic_foundry.py +1 -0
  115. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/providers/anthropic_vertex.py +8 -15
  116. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/providers/google_vertex.py +61 -41
  117. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/providers/openai.py +18 -13
  118. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/providers/openai_decisions.py +1 -1
  119. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/providers/openai_responses.py +26 -10
  120. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/tools/__init__.py +2 -1
  121. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/tools/mcp_connection.py +108 -30
  122. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/version.py +1 -1
  123. {flowra-0.0.98 → flowra-0.0.99.dev119}/pyproject.toml +12 -9
  124. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/definition/compile/test_compile.py +183 -33
  125. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/definition/test_step_helpers.py +1 -1
  126. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/flow/test_context.py +10 -0
  127. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/flow/test_hooks.py +8 -0
  128. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/flow/test_interrupt.py +17 -3
  129. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/flow/test_timeout.py +7 -15
  130. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/flow/test_with_interrupt.py +45 -91
  131. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/runtime/test_engine.py +70 -29
  132. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/runtime/test_engine_spans.py +5 -4
  133. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/runtime/test_persistence.py +340 -12
  134. flowra-0.0.99.dev119/tests/agent/runtime/test_run_span.py +232 -0
  135. flowra-0.0.99.dev119/tests/agent/runtime/test_runtime.py +4336 -0
  136. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/runtime/test_scope.py +22 -4
  137. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/runtime/test_serialization.py +59 -3
  138. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/storage/test_in_memory.py +1 -1
  139. flowra-0.0.99.dev119/tests/examples/test_escalation.py +121 -0
  140. flowra-0.0.99.dev119/tests/examples/test_race.py +36 -0
  141. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/ext/test_mlflow.py +39 -6
  142. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/ext/test_mlflow_cross_task.py +21 -10
  143. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/ext/test_otel.py +24 -0
  144. flowra-0.0.99.dev119/tests/ext/test_tracing_under_interrupts.py +742 -0
  145. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/lib/_helpers.py +6 -3
  146. flowra-0.0.98/tests/lib/test_chat_agent.py → flowra-0.0.99.dev119/tests/lib/chat/test_agent.py +302 -175
  147. {flowra-0.0.98/tests/lib → flowra-0.0.99.dev119/tests/lib/chat}/test_conversation.py +3 -33
  148. flowra-0.0.98/tests/lib/test_decision_call_agent.py → flowra-0.0.99.dev119/tests/lib/decision_call/test_agent.py +13 -5
  149. flowra-0.0.98/tests/lib/test_llm_call_agent.py → flowra-0.0.99.dev119/tests/lib/llm_call/test_agent.py +17 -2
  150. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/lib/test_llm_caller.py +447 -11
  151. flowra-0.0.98/tests/lib/test_turn_agent.py → flowra-0.0.99.dev119/tests/lib/turn/test_agent.py +717 -14
  152. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/lib/turn/test_render.py +6 -5
  153. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/lib/turn/test_tool_errors.py +6 -1
  154. flowra-0.0.98/tests/lib/test_tool_call_agent.py → flowra-0.0.99.dev119/tests/lib/turn/tool_call/test_agent.py +37 -5
  155. flowra-0.0.98/tests/lib/test_tool_call_agent_call_agent.py → flowra-0.0.99.dev119/tests/lib/turn/tool_call/test_call_agent.py +104 -1
  156. {flowra-0.0.98/tests/lib → flowra-0.0.99.dev119/tests/llm}/ext/anthropic/test_anthropic.py +0 -4
  157. flowra-0.0.99.dev119/tests/llm/providers/__init__.py +0 -0
  158. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_anthropic.py +55 -0
  159. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_anthropic_bedrock.py +10 -1
  160. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_anthropic_e2e.py +2 -1
  161. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_anthropic_foundry.py +10 -0
  162. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_anthropic_vertex.py +12 -3
  163. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_anthropic_vertex_locations_e2e.py +2 -1
  164. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_cross_provider_e2e.py +19 -0
  165. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_errors.py +76 -0
  166. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_fallback_e2e.py +2 -1
  167. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_google_vertex.py +35 -0
  168. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_history_across_models.py +20 -0
  169. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_openai_decisions.py +18 -4
  170. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_openai_provider.py +107 -0
  171. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_openai_responses.py +21 -0
  172. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_refusals.py +0 -1
  173. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_schemas_e2e.py +25 -0
  174. flowra-0.0.99.dev119/tests/llm/providers/test_stream_closing.py +89 -0
  175. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_typesafe.py +16 -3
  176. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/test_blocks.py +20 -1
  177. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/test_openai_schema.py +52 -1
  178. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/test_response.py +99 -1
  179. flowra-0.0.99.dev119/tests/scripts/__init__.py +0 -0
  180. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/test_typing.py +143 -1
  181. flowra-0.0.99.dev119/tests/tools/__init__.py +0 -0
  182. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/tools/test_mcp_connection.py +304 -24
  183. {flowra-0.0.98 → flowra-0.0.99.dev119}/uv.lock +940 -1177
  184. flowra-0.0.98/.python-version +0 -1
  185. flowra-0.0.98/flowra/_typing.py +0 -130
  186. flowra-0.0.98/flowra/agent/definition/compile/contract.py +0 -102
  187. flowra-0.0.98/flowra/agent/definition/compile/step_validation.py +0 -72
  188. flowra-0.0.98/flowra/agent/runtime/serialization.py +0 -73
  189. flowra-0.0.98/flowra/agent/runtime/spans.py +0 -39
  190. flowra-0.0.98/flowra/agent/state/markers.py +0 -22
  191. flowra-0.0.98/tests/agent/runtime/test_runtime.py +0 -1611
  192. flowra-0.0.98/tests/agent/test_missing_scenarios.py +0 -156
  193. flowra-0.0.98/tests/llm/test_cost_breakdown.py +0 -101
  194. {flowra-0.0.98 → flowra-0.0.99.dev119}/.agents/skills/source-command-update-pricing/SKILL.md +0 -0
  195. {flowra-0.0.98 → flowra-0.0.99.dev119}/.claude/commands/update-pricing.md +0 -0
  196. {flowra-0.0.98 → flowra-0.0.99.dev119}/.env.example +0 -0
  197. {flowra-0.0.98 → flowra-0.0.99.dev119}/.github/CODEOWNERS +0 -0
  198. {flowra-0.0.98 → flowra-0.0.99.dev119}/.github/workflows/publish.yml +0 -0
  199. {flowra-0.0.98 → flowra-0.0.99.dev119}/.gitignore +0 -0
  200. {flowra-0.0.98 → flowra-0.0.99.dev119}/LICENSE +0 -0
  201. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/agent_async_init.md +0 -0
  202. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/agent_tool_errors.md +0 -0
  203. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/anthropic_web_search.md +0 -0
  204. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/enum_slot_values.md +0 -0
  205. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/final_tools.md +0 -0
  206. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/langchain_comparison.md +0 -0
  207. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/lifecycle_hooks_and_conversation.md +0 -0
  208. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/llm_retry_backoff.md +0 -0
  209. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/named_scope_lazy_hydration.md +0 -0
  210. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/named_scope_type_registry.md +0 -0
  211. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/named_scopes.md +0 -0
  212. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/pricing_complexity.md +0 -0
  213. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/pydantic_ai_comparison.md +0 -0
  214. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/strands_comparison.md +0 -0
  215. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/tool_error_signals.md +0 -0
  216. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/tool_errors_vs_failures.md +0 -0
  217. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/tool_registry_redesign.md +0 -0
  218. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/tool_search_tool.md +0 -0
  219. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/research/voice_stt.md +0 -0
  220. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/review_prompts/step1_structure.md +0 -0
  221. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/review_prompts/step4_doc_readability.md +0 -0
  222. {flowra-0.0.98 → flowra-0.0.99.dev119}/docs/review_prompts/step6_tests.md +0 -0
  223. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/TRACING_COMBINATIONS.md +0 -0
  224. {flowra-0.0.98/flowra/ext → flowra-0.0.99.dev119/examples}/__init__.py +0 -0
  225. {flowra-0.0.98/flowra/llm/ext → flowra-0.0.99.dev119/examples/docs}/__init__.py +0 -0
  226. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/llm_routing.py +0 -0
  227. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/model_registry.py +0 -0
  228. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/system_prompt.txt +0 -0
  229. {flowra-0.0.98 → flowra-0.0.99.dev119}/examples/tools/switch_model.py +0 -0
  230. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/__init__.py +0 -0
  231. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/_sentinel.py +0 -0
  232. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/definition/_path.py +0 -0
  233. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/definition/actions.py +0 -0
  234. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/definition/agent.py +0 -0
  235. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/definition/agent_arg.py +0 -0
  236. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/definition/compile/__init__.py +0 -0
  237. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/definition/compile/init_params.py +0 -0
  238. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/definition/registry.py +0 -0
  239. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/definition/spawn.py +0 -0
  240. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/flow/context.py +0 -0
  241. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/flow/timeout.py +0 -0
  242. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/runtime/instance_factory.py +11 -11
  243. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/runtime/spawn_tree.py +0 -0
  244. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/runtime/visibility.py +0 -0
  245. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/services.py +4 -4
  246. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/session_state.py +0 -0
  247. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/state/__init__.py +0 -0
  248. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/state/persistent.py +0 -0
  249. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/state/store.py +3 -3
  250. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/state/values.py +0 -0
  251. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/storage/__init__.py +0 -0
  252. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/storage/in_memory.py +0 -0
  253. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/agent/storage/session_storage.py +0 -0
  254. {flowra-0.0.98/flowra/llm/providers → flowra-0.0.99.dev119/flowra/ext}/__init__.py +0 -0
  255. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/ext/_session.py +0 -0
  256. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/__init__.py +0 -0
  257. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/chat/config.py +0 -0
  258. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/config_value.py +0 -0
  259. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/decision_call/__init__.py +0 -0
  260. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/decision_call/config.py +0 -0
  261. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/decision_call/spec.py +0 -0
  262. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/decision_config.py +0 -0
  263. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/llm_call/__init__.py +0 -0
  264. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/llm_call/config.py +0 -0
  265. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/llm_call/spec.py +0 -0
  266. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/llm_config.py +0 -0
  267. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/observability/__init__.py +0 -0
  268. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/observability/llm_hooks.py +0 -0
  269. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/turn/context.py +0 -0
  270. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/turn/hook_events.py +0 -0
  271. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/turn/tool_call/__init__.py +0 -0
  272. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/lib/turn/tool_call/agent_tool.py +0 -0
  273. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/_schema_nodes.py +0 -0
  274. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/base.py +0 -0
  275. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/decision.py +0 -0
  276. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/ext/anthropic/__init__.py +0 -0
  277. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/ext/anthropic/cache.py +0 -0
  278. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/ext/anthropic/presets.py +0 -0
  279. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/ext/anthropic/tool_search.py +0 -0
  280. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/ext/anthropic/web_search.py +0 -0
  281. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/ext/openai/__init__.py +0 -0
  282. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/ext/openai/tool_search.py +0 -0
  283. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/gemini_schema.py +0 -0
  284. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/messages.py +0 -0
  285. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/pricing/__init__.py +0 -0
  286. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/pricing/bundled.py +0 -0
  287. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/custom/anthropic.json +0 -0
  288. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/custom/typesafe.json +0 -0
  289. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/custom/vertex.json +0 -0
  290. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/generated/anthropic.json +0 -0
  291. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/generated/azure_openai.json +0 -0
  292. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/generated/bedrock.json +0 -0
  293. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/generated/gemini_api.json +0 -0
  294. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/generated/inception.json +0 -0
  295. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/generated/openai.json +0 -0
  296. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/generated/vertex.json +0 -0
  297. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/pricing/model_pricing.py +0 -0
  298. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/pricing/price_list.py +8 -8
  299. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/provider.py +0 -0
  300. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/providers/_anthropic_common.py +0 -0
  301. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/providers/azure_openai.py +0 -0
  302. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/providers/typesafe.py +0 -0
  303. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/request.py +0 -0
  304. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/response.py +0 -0
  305. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/schema_formatting.py +0 -0
  306. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/schema_validation.py +0 -0
  307. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/stream.py +0 -0
  308. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/llm/tools.py +0 -0
  309. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/py.typed +0 -0
  310. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/tools/_mcp_content.py +0 -0
  311. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/tools/_mcp_headers.py +0 -0
  312. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/tools/local_tool.py +0 -0
  313. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/tools/result_format.py +0 -0
  314. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/tools/tool_arg.py +0 -0
  315. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/tools/tool_filter.py +0 -0
  316. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/tools/tool_registry.py +0 -0
  317. {flowra-0.0.98 → flowra-0.0.99.dev119}/flowra/tools/types.py +0 -0
  318. {flowra-0.0.98/examples → flowra-0.0.99.dev119/tests}/__init__.py +0 -0
  319. {flowra-0.0.98/examples/docs → flowra-0.0.99.dev119/tests/agent}/__init__.py +0 -0
  320. {flowra-0.0.98/tests → flowra-0.0.99.dev119/tests/agent/definition}/__init__.py +0 -0
  321. {flowra-0.0.98/tests/agent → flowra-0.0.99.dev119/tests/agent/definition/compile}/__init__.py +0 -0
  322. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/definition/test_actions.py +0 -0
  323. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/definition/test_agent.py +0 -0
  324. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/definition/test_registry.py +0 -0
  325. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/definition/test_spawn.py +0 -0
  326. {flowra-0.0.98/tests/agent/definition → flowra-0.0.99.dev119/tests/agent/flow}/__init__.py +0 -0
  327. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/flow/test_flowing_registry.py +0 -0
  328. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/flow/test_flowing_registry_tasks.py +0 -0
  329. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/flow/test_flowing_sync.py +0 -0
  330. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/flow/test_interruptible.py +0 -0
  331. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/flow/test_spans.py +0 -0
  332. {flowra-0.0.98/tests/agent/definition/compile → flowra-0.0.99.dev119/tests/agent/runtime}/__init__.py +0 -0
  333. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/runtime/test_ephemeral_isolation.py +0 -0
  334. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/runtime/test_hook_context.py +0 -0
  335. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/runtime/test_named_scope_persistence.py +0 -0
  336. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/runtime/test_named_scope_registry.py +0 -0
  337. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/runtime/test_named_scopes.py +0 -0
  338. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/runtime/test_parallel_failure.py +0 -0
  339. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/runtime/test_primitive_join.py +0 -0
  340. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/runtime/test_spec_in_constructor.py +0 -0
  341. {flowra-0.0.98/tests/agent/flow → flowra-0.0.99.dev119/tests/agent/state}/__init__.py +0 -0
  342. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/state/test_values.py +0 -0
  343. {flowra-0.0.98/tests/agent/runtime → flowra-0.0.99.dev119/tests/agent/storage}/__init__.py +0 -0
  344. /flowra-0.0.98/tests/agent/storage/__init__.py → /flowra-0.0.99.dev119/tests/agent/storage/_helpers.py +0 -0
  345. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/storage/test_file.py +0 -0
  346. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/agent/test_session_state.py +0 -0
  347. {flowra-0.0.98/tests/agent/state → flowra-0.0.99.dev119/tests/examples}/__init__.py +0 -0
  348. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/examples/test_menu_agent.py +0 -0
  349. {flowra-0.0.98/tests/examples → flowra-0.0.99.dev119/tests/ext}/__init__.py +0 -0
  350. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/ext/_mlflow.py +0 -0
  351. {flowra-0.0.98/tests/ext → flowra-0.0.99.dev119/tests/lib}/__init__.py +0 -0
  352. {flowra-0.0.98/tests/lib → flowra-0.0.99.dev119/tests/lib/chat}/__init__.py +0 -0
  353. /flowra-0.0.98/tests/lib/test_chat_spec.py → /flowra-0.0.99.dev119/tests/lib/chat/test_spec.py +0 -0
  354. {flowra-0.0.98/tests/lib/ext → flowra-0.0.99.dev119/tests/lib/decision_call}/__init__.py +0 -0
  355. {flowra-0.0.98/tests/lib/ext/anthropic → flowra-0.0.99.dev119/tests/lib/llm_call}/__init__.py +0 -0
  356. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/lib/test_config_value.py +0 -0
  357. {flowra-0.0.98/tests/lib/ext/openai → flowra-0.0.99.dev119/tests/lib/turn}/__init__.py +0 -0
  358. /flowra-0.0.98/tests/lib/test_matches_tool_filter.py → /flowra-0.0.99.dev119/tests/lib/turn/test_config.py +0 -0
  359. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/lib/turn/test_hook_events.py +0 -0
  360. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/lib/turn/test_per_call_headers.py +0 -0
  361. {flowra-0.0.98/tests/lib/turn → flowra-0.0.99.dev119/tests/lib/turn/tool_call}/__init__.py +0 -0
  362. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/__init__.py +0 -0
  363. {flowra-0.0.98/tests/llm/pricing → flowra-0.0.99.dev119/tests/llm/ext}/__init__.py +0 -0
  364. {flowra-0.0.98/tests/llm/providers → flowra-0.0.99.dev119/tests/llm/ext/anthropic}/__init__.py +0 -0
  365. {flowra-0.0.98/tests/scripts → flowra-0.0.99.dev119/tests/llm/ext/openai}/__init__.py +0 -0
  366. {flowra-0.0.98/tests/lib → flowra-0.0.99.dev119/tests/llm}/ext/openai/test_openai_tool_search.py +0 -0
  367. {flowra-0.0.98/tests/tools → flowra-0.0.99.dev119/tests/llm/pricing}/__init__.py +0 -0
  368. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/pricing/test_bundled.py +0 -0
  369. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/pricing/test_model_pricing.py +0 -0
  370. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/pricing/test_price_list.py +0 -0
  371. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/_mock_http.py +0 -0
  372. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/_raw_body.py +0 -0
  373. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/_tool_result_blocks.py +0 -0
  374. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_anthropic_bedrock_e2e.py +0 -0
  375. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_anthropic_foundry_e2e.py +0 -0
  376. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_azure_openai_e2e.py +0 -0
  377. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_decision_e2e.py +0 -0
  378. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_google_vertex_e2e.py +0 -0
  379. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_openai_e2e.py +0 -0
  380. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/providers/test_openai_responses_e2e.py +0 -0
  381. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/test_decision.py +0 -0
  382. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/test_gemini_schema.py +0 -0
  383. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/test_metadata.py +0 -0
  384. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/test_provider.py +0 -0
  385. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/test_schema_formatting.py +0 -0
  386. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/test_schema_nodes.py +0 -0
  387. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/test_schema_validation.py +0 -0
  388. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/llm/test_stream.py +0 -0
  389. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/scripts/test_sync_pricing.py +0 -0
  390. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/tools/test_local_tool.py +0 -0
  391. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/tools/test_mcp_headers.py +0 -0
  392. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/tools/test_result_format.py +0 -0
  393. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/tools/test_tool_registry.py +0 -0
  394. {flowra-0.0.98 → flowra-0.0.99.dev119}/tests/tools/test_types.py +0 -0
  395. {flowra-0.0.98 → flowra-0.0.99.dev119}/tools/sync_pricing.py +0 -0
@@ -17,7 +17,7 @@ jobs:
17
17
  fail-fast: false
18
18
  matrix:
19
19
  os: [ubuntu-latest, macos-latest]
20
- python: ["3.12", "3.13", "3.14"]
20
+ python: ["3.13", "3.14"]
21
21
  steps:
22
22
  - name: Checkout code
23
23
  uses: actions/checkout@v6
@@ -16,7 +16,7 @@ jobs:
16
16
  fail-fast: false
17
17
  matrix:
18
18
  os: [ubuntu-latest, macos-latest]
19
- python: ["3.12", "3.13", "3.14"]
19
+ python: ["3.13", "3.14"]
20
20
  steps:
21
21
  - name: Checkout code
22
22
  uses: actions/checkout@v6
@@ -0,0 +1 @@
1
+ 3.13
@@ -12,7 +12,7 @@ This file provides guidance to Codex when working with code in this repository.
12
12
  - `make test` — run all tests in parallel (`-n auto`)
13
13
  - `make test name="some_name"` — filter tests by name (`-k`)
14
14
  - `make test name="foo or bar"` — multiple name filters (properly quoted)
15
- - `make test file="tests/lib/test_chat_agent.py"` — run specific file
15
+ - `make test file="tests/lib/chat/test_agent.py"` — run specific file
16
16
  - `make test parallel=0` — run tests sequentially
17
17
  - `make test args="-vv -s"` — pass extra pytest arguments
18
18
  - `make test-mlflow version=3.10.0` — like `make test` without the provider tests, with the given mlflow (`X.Y.Z` or `latest` from PyPI) instead of the locked one (takes `file`/`name`/`args`)
@@ -36,7 +36,7 @@ A `.env` file in the project root contains real LLM provider credentials (API ke
36
36
 
37
37
  ## Architecture
38
38
 
39
- Python 3.12+ library. Package manager: **uv**. All config in `pyproject.toml`.
39
+ Python 3.13+ library. Package manager: **uv**. All config in `pyproject.toml`.
40
40
 
41
41
  ### LLM abstraction (`flowra/llm/`)
42
42
 
@@ -5,6 +5,330 @@ 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
+ ### Added
11
+ - **`RunSpan`: one span per `run()` or `resume()`.** The runtime opens it
12
+ before building (or restoring) the root and closes it when the call returns,
13
+ with the root's `agent_info` and `spec`, `is_resume` and the result; it
14
+ closes with an `InterruptedError` when the run ends `Interrupted` and with the
15
+ error when the run raises. The root's `AgentSpan` opens inside it, and so does
16
+ the next root's after a root `GotoAgent`. The MLflow and OpenTelemetry
17
+ integrations trace it as the root of the trace (`trace_runs=True`; MLflow
18
+ type `WORKFLOW`, named `run <path>` or `resume <path>`): a run is one trace,
19
+ where a root `GotoAgent` used to start a second one, and MLflow's trace
20
+ previews and session move to it.
21
+
22
+ ### Changed
23
+ - **`LLMCaller` retries a link before it moves on, and no client flowra builds
24
+ retries on its own.** A config that fails in a way a moment may fix
25
+ (`FallbackPolicy.retries_link`: by default `UnavailableError` — a failed
26
+ connection, a server error, a stream cut before any event) is tried again
27
+ `FallbackPolicy.retries` times (1), after `retry_delay` × the retry's number
28
+ seconds (0.5) or the error's `retry_after`, up to `max_retry_delay` (5); a
29
+ config without fallbacks is retried too, each try is its own attempt and
30
+ span, and an error after a stream had yielded events is never retried. Rate
31
+ limits, overload and timeouts move on to the next config at once, as before.
32
+ `OpenAIProvider`, `OpenAIResponsesProvider` and `OpenAIDecisionProvider`
33
+ built from an API key used the OpenAI SDK's default two retries, unseen by
34
+ `LLMCaller` (so a fallback after a 429 waited for them); they are now built
35
+ with `max_retries=0`, as every other client flowra builds. Code that calls a
36
+ provider directly, not through `LLMCaller`, gets no retries from these
37
+ clients now: call through `DEFAULT_LLM_CALLER` or an `LLMCaller` of your own,
38
+ or pass a client built with the SDK's `max_retries`. `LLMCaller(sleep=...)` replaces `asyncio.sleep` (for tests).
39
+ - **`McpConnection` no longer sends a tool call again when the tool may
40
+ already have run.** After a read or write timeout, a connection dropped
41
+ mid-request, a 5xx or a 4xx other than a refusal of the request (such as a
42
+ gateway's 408), the model gets `Tool '...' failed, and it is unknown
43
+ whether it took effect; check before calling it again` instead of a second
44
+ `tools/call` after a reconnect, which could run a tool with side effects
45
+ twice. A call that never reached the tool (a connect error or timeout, or
46
+ 400, 401, 403, 404, 405, 415, 429, such as an expired session) is still
47
+ retried once. The new
48
+ `McpCallPolicy` (from `flowra.tools`), passed as
49
+ `McpConnection.connect(..., policy=...)`, sets `retry_unknown_outcome=True`
50
+ to retry those calls too (for servers that recognise a repeat by an
51
+ idempotency key) and the request `timeout` (30 seconds, as before, now
52
+ configurable). The log line of a failed call names the exception type.
53
+ - **Python 3.13+ is required.** Python 3.12 is no longer supported or tested.
54
+ - **The provider extras require the SDK versions flowra is tested with:**
55
+ `anthropic>=2.8` (`flowra[anthropic]`, `flowra[bedrock]`),
56
+ `google-genai>=3.3` (`flowra[google]`), `openai>=3.51` (`flowra[openai]`)
57
+ and, in every provider extra, `httpx2>=2.16`. anthropic 2.x sends its API
58
+ version `2026-10-21` to every Claude endpoint (the `anthropic-version`
59
+ header on Foundry, `anthropic_version` in the body on Vertex and Bedrock),
60
+ where 1.x sent `2023-06-01`, `vertex-2023-10-16` and `bedrock-2023-05-31`.
61
+ The Claude clients flowra builds itself turn off the SDK's own
62
+ OpenTelemetry spans (`open_telemetry=False`), so a traced call is one
63
+ `LLMCallSpan`, not two; a client passed in keeps whatever it was built
64
+ with. The Vertex client flowra builds no longer retries on its own
65
+ (`max_retries=0`): `LLMCaller` decides (see the first entry).
66
+ - **An interrupted turn ends `InterruptedWith[TurnProgress]`, not a
67
+ `TurnResult`.** `InterruptedWith[D]` (new, from `flowra.agent`) is an
68
+ `Interrupted` that carries the data an agent hands back when it stops: an
69
+ agent declares it in its result type, `Agent[S, R | InterruptedWith[D]]`,
70
+ and its steps return `InterruptedWith(data=...)`, with `D` a dataclass or
71
+ exactly a primitive (`str`, but not a subclass of `str`; anything else,
72
+ `InterruptedWith[None]` or a bare `InterruptedWith` anywhere, a bare
73
+ `Interrupted` in `Agent[S, R]`, an interrupt inside a result in a step's
74
+ return type or `Agent[S, R]` (`list[Interrupted]`: an agent ends with a
75
+ result or with an interrupt), an interrupt anywhere in a spec type, or a
76
+ step's `InterruptedWith[D]` its agent does not declare, is a `TypeError`
77
+ when the class is defined). A bare
78
+ `Interrupted()` carries nothing, and any agent can end with it; a step may
79
+ return it without declaring it. The data is saved with the run and survives
80
+ a resume. A parent takes it by the parameter's type: `T | Interrupted` any
81
+ interrupt of a child that could give a `T`, with data or without
82
+ (`Interrupted` alone: any child's), `T | InterruptedWith[D]` one whose data
83
+ is a `D`. `TurnAgent` is an `Agent[TurnSpec, TurnResult |
84
+ InterruptedWith[TurnProgress]]`: a turn interrupted after it started ends
85
+ `InterruptedWith(data=TurnProgress(messages, usage))` (`TurnProgress` from
86
+ `flowra.lib.turn`), a hook's `InterruptedError` included: its calls are
87
+ answered, and before, such a turn lost its messages; one from a hook
88
+ watching a reply (`UsageEvent`, `TextReasoningEvent`, `ResultMessageEvent`,
89
+ …) keeps the reply and completes the turn. A response with tool calls that
90
+ an interrupt stops before they run (a hook on the response,
91
+ `BeforeToolCallsEvent`, `BeforeToolCallEvent`) is kept too: each call is
92
+ answered `Tool execution interrupted` (one a `BeforeToolCallsEvent` handler
93
+ answered keeps that answer, a cut-off call its own error), where it used to
94
+ be dropped. A turn that did not start ends a bare `Interrupted`.
95
+ `TurnStatus.INTERRUPTED` is gone: a parent that took `TurnResult` and
96
+ checked the status takes `TurnResult | Interrupted` (and `isinstance(result,
97
+ InterruptedWith)` for the messages); one that takes only `TurnResult` cannot
98
+ take an interrupted turn: its agent ends `Interrupted` when it was signalled
99
+ itself, and fails with `StepBindingError` otherwise (a hook stopped the
100
+ turn). `ChatAgent` saves such a turn, as before, and ends
101
+ `InterruptedWith[ChatProgress]` (`ChatProgress(usage)` from
102
+ `flowra.lib.chat`: the turn's usage, which a bare `Interrupted` lost; a
103
+ `SaveHistoryEvent` hook that raises `InterruptedError` leaves the turn
104
+ unsaved and ends a bare one); a turn that finished is now a `ChatResult`
105
+ even when the interrupt comes while it is saved (it used to end
106
+ `Interrupted`). `SaveHistoryEvent` gets `interrupted: bool`, and its
107
+ `status` is `None` for an interrupted turn: a hook that checked `status is
108
+ TurnStatus.INTERRUPTED` checks `interrupted`.
109
+
110
+ - **An agent that may `GotoAgent` declares its result types.** A step that
111
+ can return `GotoAgent` in an agent without `Agent[S, R]` is a `TypeError`
112
+ when the class is defined: the caller gets the target's result, which the
113
+ steps do not show, so an interrupted router looked to its signalled parent
114
+ like a child that never gives anything, and the parent failed with
115
+ `StepBindingError` instead of ending `Interrupted`. When it goes, the
116
+ target's declared results and `InterruptedWith[D]` data must be in the
117
+ source's `R`, or the run fails with a `TypeError`.
118
+ - **A step that cannot take an interrupted child is an error, not an
119
+ interrupt, unless its agent was signalled itself.** A parameter that takes
120
+ only `T` and finds an interrupted child raises `StepBindingError` (new, a
121
+ `TypeError`, from `flowra.agent`) naming the step, the parameter and what
122
+ each child it looked at gave; before, the agent ended `Interrupted`, so a
123
+ race that took its cancelled loser strictly looked interrupted. An agent
124
+ whose own token has fired still ends `Interrupted`. An annotated parameter
125
+ that nothing binds to now raises `StepBindingError` instead of Python's
126
+ missing-argument `TypeError`; one with a default takes it, even when it is
127
+ also optional (it used to get `None`); and a `TypeError` raised in a
128
+ step's body is no longer turned into `Interrupted` when a child was
129
+ interrupted. A parameter looks only at the children whose declared result
130
+ types could give it a value (a child built by hand without types always
131
+ could), so a service nobody provides is a `StepBindingError` even beside
132
+ an interrupted child whose declared types could not give it, also when the
133
+ agent itself was signalled (it used to end `Interrupted`), and the error
134
+ no longer blames that child; a child the parameter's tag names that never
135
+ could is named as the mistake (`StepBindingError.mismatched`).
136
+ `ChildOutput` carries the child's declared `result_types`.
137
+ - **`T | Interrupted` takes the interrupt only of a child that could give a
138
+ `T`**, by its declared result types (a child without types could), so an
139
+ interrupted sibling no longer makes it ambiguous beside a finished `T`;
140
+ `Interrupted` alone still takes any child's; `InterruptedWith[D]`
141
+ takes any whose data is a `D`. A step that took the interrupt of a child
142
+ that can never give a `T` through `T | Interrupted` now has nothing to bind
143
+ from it (a `StepBindingError`, also when the agent was signalled): take it
144
+ with `Interrupted` in a parameter of its own.
145
+ - **Every step annotates its return type with classes.** A step without a
146
+ return annotation, or with `Any`, a type variable or a `Literal` in it, is a
147
+ `TypeError` when the class is defined; before, its result went unchecked
148
+ and its agent's result types left it out.
149
+ - **A step returns exactly a type it declares**, its `InterruptedWith[D]` data
150
+ exactly a declared `D`: a subclass of one (a `bool` for an `int` too) is a
151
+ `TypeError` when the step returns. Before, it ran until the result was
152
+ saved, where an unregistered subclass failed.
153
+ - **An interrupt survives a resume.** Each agent's interrupt is saved with
154
+ the run, and `resume()` restores it: an agent signalled before a crash is
155
+ still signalled after it: its steps and its children see the token fired.
156
+ Before, a resume started with every token clear, and an interrupted run went
157
+ on as if nothing had stopped it (a child stopped by
158
+ `interrupt_children()` kept working). An interrupt that came after the last
159
+ save is not in it. The runtime's interrupt now lasts until `run()` or
160
+ `resume()` returns or raises, wherever it stopped: before, one that failed
161
+ (or timed out) left it set, and the next run started signalled. An
162
+ interrupt sent while neither is going stops the next `run()` from its
163
+ start; to a `resume()`, which continues the run a crash cut off, it is one
164
+ that came while that run was going (the agents restored run their steps
165
+ and see it). A call refused before it starts (another call still going, a
166
+ pending execution, nothing to resume, the storage failing to read) leaves
167
+ it alone.
168
+ - **A subclass of a primitive is refused as a step's result or parameter type,
169
+ and in `Agent[S, R]`** (a `str` subclass, a `StrEnum`, an `IntEnum`): saved
170
+ as the primitive, it came back as one after a resume, so a step binding it
171
+ matched before a crash and not after. It is a `TypeError` when the class is
172
+ defined; use the primitive, or a dataclass that holds the value. An unmarked
173
+ step parameter may be a spec or a child, so it refuses one too, a `list` or
174
+ `dict` subclass included; a service of such a type takes
175
+ `Annotated[..., agent_arg.SERVICE]`.
176
+ - **An agent signalled before it starts does not start.** One whose token has
177
+ fired before it is built — a run started after `runtime.interrupt()`, a
178
+ child or a `GotoAgent` target of an agent that was signalled — is not built
179
+ at all (no constructor, no state, no `__post_init__`, so no hook they emit
180
+ fires: a turn's `TurnReadyEvent` neither), and one whose `__post_init__`
181
+ signalled it is built and does not start; either ends `Interrupted` without
182
+ entering its first step. A `CallStep` branch, and an agent that has
183
+ started, runs its steps as before. A `TurnAgent`, `ChatAgent` or
184
+ `ToolCallAgent` that does not start runs none of its steps: a turn runs no
185
+ `StartTurnEvent` / `MessageAcceptedEvent` hooks and a chat saves nothing
186
+ (no `SaveHistoryEvent`), where before they ran, and saved the user's
187
+ message. An agent that does not start has its
188
+ `AgentSpan` opened and closed at once with an `InterruptedError`, with no
189
+ `StepSpan`; its own `on_self_span` handlers, registered in a constructor
190
+ that never runs, do not fire, so a call whose `ToolCallAgent` was not built
191
+ has no `ToolCallSpan` (no tool ran), where before one carried
192
+ `Tool execution interrupted`. A `TurnAgent` answers a call whose
193
+ `ToolCallAgent` did not start `Tool execution interrupted`, and a
194
+ `ChatAgent` takes a turn that did not start (`ChatProgress(usage=None)`,
195
+ nothing saved).
196
+ - **An agent's `__post_init__` that raises `InterruptedError` signals the
197
+ agent instead of failing the run.** It fires the agent's own token, as
198
+ `InterruptControl.interrupt()` would: an agent being built does not start,
199
+ and a `CallStep` branch or an agent restored on a resume runs its steps
200
+ signalled. Before, the error left the run (from a hook a `__post_init__`
201
+ emits, such as `TurnAgent`'s `TurnReadyEvent`, too).
202
+ - **An `AgentRuntime` runs one `run()` or `resume()` at a time**: a second
203
+ call while one is going raises `RuntimeError` ("already going", where a
204
+ `run()` with storage used to get "Pending execution exists" once the first
205
+ had saved). Before, a second `run()` without storage or before the first
206
+ save, or any second `resume()`, ran a second tree that freed the first
207
+ one's locks and, ending, cut the first one off from `runtime.interrupt()`.
208
+ ### Fixed
209
+ - **`Annotated` around a member of a union, or around an optional, reads as
210
+ the type it annotates.** `x: Annotated[Out, "doc"] | None` and
211
+ `x: Annotated[Out | None, "doc"]` bound any value (`object`), an interrupted
212
+ child's `Interrupted` too, and `Annotated[Out, "doc"] | B` lost `Out`; a
213
+ step returning `Annotated[Out, "doc"] | None` was refused as "not a class".
214
+ Every reader of annotations now unwraps it.
215
+ - **The docs no longer offer `FileSessionStorage` as the way to recover from
216
+ crashes.** It is a sample for development: it writes each file in place, so a
217
+ crash mid-write can leave a file unreadable, and a step is not one
218
+ transaction. The docs now say so and point production to a `SessionStorage`
219
+ of your own over a database.
220
+ - **A map in a schema no longer comes back empty from OpenAI.** Strict mode
221
+ closes every object (`additionalProperties: false`), so `make_schema_strict`
222
+ turned a map (`dict[str, X]`, `additionalProperties` with a schema) into an
223
+ object with no properties, and the model could only answer `{}` — in a
224
+ `json_schema` answer (Chat Completions and Responses) and in a Chat
225
+ Completions tool's arguments, with no error. A schema strict mode cannot hold
226
+ — a map, a free-form object (`additionalProperties: true`, or an object that
227
+ names no properties), an `allOf` that does not merge (which the API used to
228
+ reject) — now goes as it is with `strict: false`: the model sees the whole
229
+ schema, without the API's guarantee that the answer follows it. The new
230
+ `fits_strict_mode(schema)` (from `flowra.llm`) says which way a schema goes.
231
+ - **A dict in a slot, a result or a spec comes back as it was saved.** A
232
+ dict was saved with its keys as they were: one with a key spelled like the
233
+ checkpoint's own tags (`"__date__"`, `"__interrupted__"`, `"__type__"`, …)
234
+ came back as a date, an `Interrupted` or an unknown-tag `TypeError`; `int`
235
+ keys came back as strings from `FileSessionStorage` (and as `int` from
236
+ `InMemorySessionStorage`); a `UUID` key failed to save to a file. A dict is
237
+ now saved as its key/value pairs (`{"__dict__": [[key, value], …]}`), each
238
+ key saved like any value, so it keeps its type in every storage. A dict
239
+ saved before still loads.
240
+ - **A tool call cut off in an OpenAI reply no longer breaks the history for
241
+ Claude and Gemini.** OpenAI's arguments are JSON text, kept as it came; a
242
+ call whose text is no JSON object — a reply cut off mid call, which
243
+ `TurnAgent` keeps in the history answered with an error, or malformed
244
+ arguments — made `AnthropicProvider` and `GoogleVertexProvider` fail before
245
+ sending with a bare `JSONDecodeError` (a JSON array went to Claude and got a
246
+ 400), so a fallback from GPT to Claude or Gemini broke on that history. They
247
+ now send such a call's arguments as `{"raw_input": "<the text>"}`. The new
248
+ `ToolUseBlock.input_object()` gives that object to a provider of your own.
249
+ - **A Responses API stream cut short raises `UnavailableError`.** An
250
+ `OpenAIResponsesProvider` stream that ended without a `response.completed`
251
+ or `response.incomplete` event raised the OpenAI SDK's bare
252
+ `RuntimeError`, which the fallback chain did not switch on and
253
+ `LLMCallAgent` did not return as a failure. It is now an
254
+ `UnavailableError`, with `partial=True` when text had already gone out.
255
+ - **A Gemini stream cut short is an error, not a finished reply.** A
256
+ `GoogleVertexProvider` stream that ended before any chunk carried a finish
257
+ reason (a dropped connection, a proxy closing the response) returned the
258
+ text so far with `stop_reason=END_TURN`, so a truncated reply passed for a
259
+ whole one. It now raises `UnavailableError`, with `partial=True` when events
260
+ had already gone out; the fallback chain treats it as any other stream
261
+ failure.
262
+ - **A refusal the fallback chain moves past is counted in the usage.** With
263
+ `FallbackPolicy(switch_on_refusal=True)`, the tokens of a refused attempt
264
+ showed only on its span: the response returned (and the agent's
265
+ `usage` — `LLMCallResult`, `TurnResult`, `ChatResult`) carried the
266
+ answering attempt's alone. The response returned by `LLMCaller.call()` and
267
+ `decide()` now carries the usage of every refusal before it as well,
268
+ split by model (`usage.per_model()`); each span keeps its own.
269
+ - **A stream that stops early is closed at once.** When a `TextDeltaEvent` or
270
+ `ThinkingDeltaEvent` handler raised, or the run was cancelled, mid-stream,
271
+ `LLMCaller` left the provider's stream suspended, and each provider left
272
+ its inner generator and the HTTP response under it open, until the garbage
273
+ collector found them. Every layer now closes what it iterates (`LLMCaller`,
274
+ `with_interrupt`, `map_stream_errors`, each provider's stream), so the
275
+ response is released before `run()` returns or raises. `with_interrupt`
276
+ cancelled while waiting for the next item now stops that step before
277
+ closing the iterator, which used to fail. Gemini's response still waits
278
+ for the garbage collector: google-genai does not close the generators its
279
+ stream reads from.
280
+ - **`store.flush()` works in `__post_init__`.** A flush finds unsaved slots
281
+ by walking the execution tree, and an agent joins the tree only after its
282
+ `__post_init__`: a root agent's flush there (and a restored agent's on
283
+ `resume()`) failed with a bare `AssertionError`, as there was no tree yet,
284
+ and a GotoAgent target's or a new child's saved every other agent's slots
285
+ but not its own, so its writes waited for the next save. A flush now saves
286
+ the calling agent's own slots first, then those of the agents in the tree,
287
+ then the named scopes.
288
+ - **A forked branch keeps its copy of the parent's ephemeral state across a
289
+ resume.** `CallStep(fork_ephemeral=True)` saved only what the branch wrote
290
+ itself, so a branch resumed after a crash lost what it had copied from its
291
+ agent (a scalar read as unset, a list held only the branch's own items).
292
+ The whole copy is now saved under the branch.
293
+ - **A `store.flush()` after a resume saves an agent's state where the next
294
+ resume looks for it.** A `CallStep` branch restored on its agent's scope
295
+ (not `fork_ephemeral`) took over that scope's flush, so a flush from the
296
+ agent or the branch saved the agent's ephemeral state under the branch's
297
+ node, and a crash before the next save lost it. The branch now keeps its
298
+ agent's flush, as it does when it is first built.
299
+ - **A tool that fails after `ctx.call_agent()` answers with its error.** The
300
+ request is part of the tool's answer: a tool that raised (or whose wrapper
301
+ returned an error `ToolResult`) after asking for an agent used to start the
302
+ agent anyway and report its result as a success; now the model gets the
303
+ tool's error and the agent does not start. A second `call_agent()` in one
304
+ call is such an error too.
305
+ - **Gemini's connection errors and timeouts through httpx2 are `LLMError`s.**
306
+ google-genai 3.x sends through httpx2 by default, and its transport errors
307
+ reached the caller raw: no `UnavailableError` / `LLMTimeoutError`, and no
308
+ fallback to the next config.
309
+ - **`LLMCaller` checks an interrupt before the first attempt too**, not only
310
+ before a fallback: a call made once the interrupt has fired raises
311
+ `InterruptedError` without building a request or opening a span (a failed
312
+ `LLMCallSpan` or `DecisionCallSpan` showed in traces).
313
+ - **An interrupt does not drop a refusal `LLMCaller` holds.** With
314
+ `switch_on_refusal=True`, an interrupt that came after a config refused
315
+ raised `InterruptedError`, before the next attempt or cutting it short, and
316
+ the refusal was lost; the refusal is now returned.
317
+ - **A generic type alias is read through its value.** A step parameter typed
318
+ `Alias[int]` (with `type Alias[T] = ...`) took any value, as if it were
319
+ `Any`; it is now read as the alias's value with `int` for its type
320
+ parameter.
321
+ - **A step parameter typed as a union with a generic member binds.** `list[R]
322
+ | Interrupted`, `dict[str, R] | Interrupted` and `list[R] | R`, with
323
+ `agent_arg.CHILD` or unmarked, dropped the generic member and failed to bind
324
+ the child's list or dict. A generic member is now matched by its class
325
+ (`list`, `dict`), and the error names it.
326
+ - **`WhenAny`, `WhenN` and `timeout` wait for a child to end, not for its first
327
+ step.** A child's step that went on (`GotoStep`, `GotoAgent`, `Spawn`)
328
+ counted as the child finishing, so the child that started first won and the
329
+ others were interrupted: `examples/race.py` always named the first model the
330
+ winner, and a worker whose first step went on stopped its `timeout`.
331
+
8
332
  ## [0.0.98] - 2026-11-10
9
333
 
10
334
  ### Fixed
@@ -12,7 +12,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
12
12
  - `make test` — run all tests in parallel (`-n auto`)
13
13
  - `make test name="some_name"` — filter tests by name (`-k`)
14
14
  - `make test name="foo or bar"` — multiple name filters (properly quoted)
15
- - `make test file="tests/lib/test_chat_agent.py"` — run specific file
15
+ - `make test file="tests/lib/chat/test_agent.py"` — run specific file
16
16
  - `make test parallel=0` — run tests sequentially
17
17
  - `make test args="-vv -s"` — pass extra pytest arguments
18
18
  - `make test-mlflow version=3.10.0` — like `make test` without the provider tests, with the given mlflow (`X.Y.Z` or `latest` from PyPI) instead of the locked one (takes `file`/`name`/`args`)
@@ -36,20 +36,20 @@ A `.env` file in the project root contains real LLM provider credentials (API ke
36
36
 
37
37
  ## Architecture
38
38
 
39
- Python 3.12+ library. Package manager: **uv**. All config in `pyproject.toml`.
39
+ Python 3.13+ library. Package manager: **uv**. All config in `pyproject.toml`.
40
40
 
41
41
  ### LLM abstraction (`flowra/llm/`)
42
42
 
43
43
  Provider-agnostic interface for calling LLMs:
44
44
 
45
45
  - `LLMProvider` (abc) — `async call(LLMRequest) -> LLMResponse` and `async stream(LLMRequest) -> AsyncIterator[StreamEvent]`
46
- - `LLMRequest` — model, system (`list[SystemMessage]`), messages (`list[UserMessage | AssistantMessage]`), tools, json_schema, temperature, max_tokens, stop_sequences, extra, max_schema_retries
46
+ - `LLMRequest` — model, system (`list[SystemMessage]`), messages (`list[UserMessage | AssistantMessage]`), tools, json_schema, temperature, top_p, max_tokens, stop_sequences, extra, max_schema_retries
47
47
  - `LLMResponse` — messages (`list[UserMessage | AssistantMessage]`), stop_reason, usage, model (the model that served the call, as the provider reports it; falls back to the requested name), refusal (`Refusal` with explanation and the provider's categories; set exactly when stop_reason is `REFUSAL`, and the response then carries no output). Property `message` returns the last `AssistantMessage`. Multi-message responses occur when providers return intermediate items (e.g. OpenAI tool search roundtrips)
48
48
  - `DecisionProvider` (abc, shares `ProviderBase` with `LLMProvider`) — `async decide(DecisionRequest) -> DecisionResponse`: predicate / choice / score questions about a text or images, answered with probabilities; `response.answer(question)` gives the typed answer or a per-question `DecisionRefusal`. Providers of its own, none of them a chat provider: `OpenAIDecisionProvider` and `AzureOpenAIDecisionProvider` (`openai_decisions.py`: OpenAI's Decisions API, a separate endpoint; Azure through its v1 API; a client can be shared with a chat provider), and `TypeSafeProvider` (TypeSafe's Jev); supplier-only options go in the provider's extra on the request, a question or an image
49
49
  - `StreamEvent` = `TextDelta | ThinkingDelta | ContentComplete` — stream events for real-time token delivery
50
50
  - `Usage` — input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens, reasoning_tokens (`int | None`, the reasoning share inside output_tokens; None = not reported, e.g. Claude), cost_usd, cost (`CostBreakdown` with input/output/cache_read/cache_creation), model, by_model. A sum keeps `model` while all parts share it and otherwise splits by model in `by_model`; `per_model()` reads the split either way. Token contract: `input_tokens` excludes cached tokens — input and the two cache buckets are disjoint for every provider; MLflow and OTel spans count the cache back into their `input_tokens`, as their conventions do
51
51
  - Messages: `SystemMessage`, `UserMessage`, `AssistantMessage` — system messages are separate in `LLMRequest.system`
52
- - Blocks: `TextBlock`, `MediaBlock`, `ToolUseBlock`, `ToolResultBlock`, `ThinkingBlock` — all inherit `LLMData` (metadata, extra, transient). `ToolUseBlock.input` is `dict[str, Any] | str | None` — raw from provider (Anthropic: `dict`, OpenAI: JSON `str`, Google: `dict | None`). Parsed to `dict` by `ToolRegistry` at execution time. `ToolResultBlock.content` is `list[TextBlock | MediaBlock]` (`ToolResultContentBlock`), each a full block with its own metadata and transient (a nested block's extra is not sent); `.text` joins the text blocks with `"\n\n"`, `.has_transient_content` says whether one is transient. Providers send text alone as that one string (the same request as a single text block) and a list only for media (OpenAI Chat raises on media; Anthropic marks an error with media by a leading `Error:` text block, since the API takes `is_error` only on a text-only result). Anthropic rejects `cache_control` inside a tool result: a tool result with a transient block inside ends the `*_non_transient_*` prefix. A string `content` stored before 0.0.86 loads as one `TextBlock`. `ChatAgent` strips transient blocks inside tool results on save, drops any tool result whose call the save leaves out (transient, in a transient message, or removed by a `SaveHistoryEvent` hook) and keeps other transient tool results as empty answers
52
+ - Blocks: `TextBlock`, `MediaBlock`, `ToolUseBlock`, `ToolResultBlock`, `ThinkingBlock` — all inherit `LLMData` (metadata, extra, transient). `ToolUseBlock.input` is `dict[str, Any] | str | None` — raw from provider (Anthropic: `dict`, OpenAI: JSON `str`, Google: `dict | None`). Parsed to `dict` by `ToolRegistry` at execution time; `input_object()` gives the object an API that takes only one gets (text that is no JSON object as `{"raw_input": text}`: Anthropic and Google send that). `ToolResultBlock.content` is `list[TextBlock | MediaBlock]` (`ToolResultContentBlock`), each a full block with its own metadata and transient (a nested block's extra is not sent); `.text` joins the text blocks with `"\n\n"`, `.has_transient_content` says whether one is transient. Providers send text alone as that one string (the same request as a single text block) and a list only for media (OpenAI Chat raises on media; Anthropic marks an error with media by a leading `Error:` text block, since the API takes `is_error` only on a text-only result). Anthropic rejects `cache_control` inside a tool result: a tool result with a transient block inside ends the `*_non_transient_*` prefix. A string `content` stored before 0.0.86 loads as one `TextBlock`. `ChatAgent` strips transient blocks inside tool results on save, drops any tool result whose call the save leaves out (transient, in a transient message, or removed by a `SaveHistoryEvent` hook) and keeps other transient tool results as empty answers
53
53
  - `Tool` — inherits from `LLMData` (has metadata, extra, transient). Fields: name, description, input_schema, output_schema
54
54
  - Provider-namespaced extras: `LLMData.extra` and `LLMRequest.extra` use provider-specific namespaces — `extra["anthropic"]`, `extra["openai"]` (Chat Completions), `extra["openai_responses"]`, `extra["google"]`, `extra["openai_decisions"]`, `extra["typesafe"]` (the last two decisions). Typed access via `ProviderExtra` dataclass subclasses: `build_extra(MyExtra(field=value))` to construct, `MyExtra(field=value).write_to(obj)` to mutate, `MyExtra.read_from(obj)` to read. Fields default to `mr.MISSING` (skip on write), `None` clears the field. `LLMResponse.extra` and `Usage.extra` are NOT namespaced (output-only)
55
55
  - Errors: providers raise `LLMError` (`flowra/llm/errors.py`) for API and transport failures, never SDK exceptions — `TransientLLMError` (`RateLimitedError`, `OverloadedError`, `UnavailableError`, `LLMTimeoutError`) and `PermanentLLMError` (`AuthFailedError`, `NotFoundError`, `QuotaExhaustedError`, `BadRequestError` with its `ContextTooLongError`), with `provider`, `model`, `status_code`, `retry_after`, `request_id`, `partial` and the SDK exception (when there is one) as `__cause__`. Each provider family maps its SDK's errors, including errors inside a stream (`map_stream_errors` tracks `partial`); a provider's specific error kind wins over the HTTP status. A safety classifier or content filter declining is not an error but `StopReason.REFUSAL` (Azure's 400 `content_filter` and the Responses API's policy codes included). Agents: `LLMCallAgent` (a building block) returns an `LLMError` as `LLMCallResult.failure` (`LLMFailure`, a serializable record; `.error` rebuilds the exception), while `TurnAgent` / `ChatAgent` (assembled loops) raise it; a refusal completes the turn with `stop_reason=REFUSAL` and `refusal` on `TurnResult` / `ChatResult`, and `ChatAgent` leaves the refused turn out of the history
@@ -28,7 +28,7 @@ endif
28
28
  # make test name="foo or bar" # multiple filters
29
29
  # make test parallel=0 # sequential
30
30
  # make test parallel=4 # 4 workers
31
- # make test file="tests/lib/test_chat.py" # specific file
31
+ # make test file="tests/lib/chat/test_agent.py" # specific file
32
32
  # make test name="e2e" parallel=0 # filter + sequential
33
33
  # make test args="-vv -s" # extra pytest arguments
34
34
  _TEST_ARGS = $(if $(parallel),$(if $(filter 0,$(parallel)),,-n $(parallel)),-n auto) \
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: flowra
3
- Version: 0.0.98
3
+ Version: 0.0.99.dev119
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
@@ -11,36 +11,36 @@ License-File: LICENSE
11
11
  Classifier: Development Status :: 3 - Alpha
12
12
  Classifier: Intended Audience :: Developers
13
13
  Classifier: License :: OSI Approved :: MIT License
14
- Classifier: Programming Language :: Python :: 3.12
15
14
  Classifier: Programming Language :: Python :: 3.13
16
15
  Classifier: Programming Language :: Python :: 3.14
17
16
  Classifier: Topic :: Software Development :: Libraries
18
- Requires-Python: >=3.12
17
+ Requires-Python: >=3.13
19
18
  Requires-Dist: httpx>=0.28
20
19
  Requires-Dist: jsonschema>=4.26
21
20
  Requires-Dist: marshmallow-recipe>=0.0.95
22
21
  Provides-Extra: anthropic
23
- Requires-Dist: anthropic[vertex]; extra == 'anthropic'
24
- Requires-Dist: httpx2>=2.13; extra == 'anthropic'
22
+ Requires-Dist: anthropic[vertex]>=2.8; extra == 'anthropic'
23
+ Requires-Dist: httpx2>=2.16; extra == 'anthropic'
25
24
  Provides-Extra: bedrock
26
- Requires-Dist: anthropic[bedrock]; extra == 'bedrock'
27
- Requires-Dist: httpx2>=2.13; extra == 'bedrock'
25
+ Requires-Dist: anthropic[bedrock]>=2.8; extra == 'bedrock'
26
+ Requires-Dist: httpx2>=2.16; extra == 'bedrock'
28
27
  Provides-Extra: google
29
- Requires-Dist: google-genai; extra == 'google'
28
+ Requires-Dist: google-genai>=3.3; extra == 'google'
29
+ Requires-Dist: httpx2>=2.16; extra == 'google'
30
30
  Provides-Extra: mlflow
31
31
  Requires-Dist: mlflow>=3.10; extra == 'mlflow'
32
32
  Provides-Extra: openai
33
- Requires-Dist: httpx2>=2.13; extra == 'openai'
34
- Requires-Dist: openai>=3.26; extra == 'openai'
33
+ Requires-Dist: httpx2>=2.16; extra == 'openai'
34
+ Requires-Dist: openai>=3.51; extra == 'openai'
35
35
  Provides-Extra: otel
36
36
  Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
37
37
  Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
38
38
  Provides-Extra: providers
39
- Requires-Dist: anthropic[bedrock]; extra == 'providers'
40
- Requires-Dist: anthropic[vertex]; extra == 'providers'
41
- Requires-Dist: google-genai; extra == 'providers'
42
- Requires-Dist: httpx2>=2.13; extra == 'providers'
43
- Requires-Dist: openai>=3.26; extra == 'providers'
39
+ Requires-Dist: anthropic[bedrock]>=2.8; extra == 'providers'
40
+ Requires-Dist: anthropic[vertex]>=2.8; extra == 'providers'
41
+ Requires-Dist: google-genai>=3.3; extra == 'providers'
42
+ Requires-Dist: httpx2>=2.16; extra == 'providers'
43
+ Requires-Dist: openai>=3.51; extra == 'providers'
44
44
  Description-Content-Type: text/markdown
45
45
 
46
46
  # Flowra
@@ -51,7 +51,7 @@ Description-Content-Type: text/markdown
51
51
  [![CI](https://github.com/anna-money/flowra/actions/workflows/master.yml/badge.svg)](https://github.com/anna-money/flowra/actions/workflows/master.yml)
52
52
 
53
53
  **Flow infra** for building stateful, persistent LLM agents with tool use,
54
- parallel execution, and crash recovery. Requires Python 3.12+.
54
+ parallel execution, and crash recovery. Requires Python 3.13+.
55
55
 
56
56
  ## Features
57
57
 
@@ -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
 
@@ -135,18 +136,23 @@ flowra/
135
136
  ├── llm/ # LLM abstraction (messages, blocks, provider interface)
136
137
  ├── tools/ # Tool definition, registration, execution
137
138
  ├── agent/ # Agent framework + execution engine + persistence
138
- └── lib/ # Pre-built agents (ChatAgent, TurnAgent, hooks, caching)
139
+ ├── lib/ # Pre-built agents (ChatAgent, TurnAgent, hooks, caching)
140
+ └── ext/ # Tracing integrations (MLflow, OpenTelemetry)
139
141
  ```
140
142
 
141
143
  ## Documentation
142
144
 
143
145
  - **[Getting Started](docs/getting-started.md)** — from installation to a working
144
146
  chatbot with tools in 5 minutes
147
+ - [Architecture](docs/architecture.md) — package structure, dependency graph,
148
+ data flow
145
149
  - [Working with LLMs](docs/llm.md) — providers, streaming, structured output,
146
150
  caching, extended thinking
147
151
  - [Tools](docs/tools.md) — tool groups, MCP servers, service injection
148
152
  - [Agents](docs/agents.md) — custom agents, state machines, control flow,
149
153
  parallel execution
154
+ - [Interrupts](docs/interrupts.md) — how an interrupt travels through the agent
155
+ tree: the principles and rules every agent and building block follows
150
156
  - [Patterns](docs/patterns.md) — multi-agent patterns: router, pipeline, race,
151
157
  fan-out
152
158
  - [Observability](docs/observability.md) — hooks, spans, MLflow and OTel
@@ -6,7 +6,7 @@
6
6
  [![CI](https://github.com/anna-money/flowra/actions/workflows/master.yml/badge.svg)](https://github.com/anna-money/flowra/actions/workflows/master.yml)
7
7
 
8
8
  **Flow infra** for building stateful, persistent LLM agents with tool use,
9
- parallel execution, and crash recovery. Requires Python 3.12+.
9
+ parallel execution, and crash recovery. Requires Python 3.13+.
10
10
 
11
11
  ## Features
12
12
 
@@ -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
 
@@ -90,18 +91,23 @@ flowra/
90
91
  ├── llm/ # LLM abstraction (messages, blocks, provider interface)
91
92
  ├── tools/ # Tool definition, registration, execution
92
93
  ├── agent/ # Agent framework + execution engine + persistence
93
- └── lib/ # Pre-built agents (ChatAgent, TurnAgent, hooks, caching)
94
+ ├── lib/ # Pre-built agents (ChatAgent, TurnAgent, hooks, caching)
95
+ └── ext/ # Tracing integrations (MLflow, OpenTelemetry)
94
96
  ```
95
97
 
96
98
  ## Documentation
97
99
 
98
100
  - **[Getting Started](docs/getting-started.md)** — from installation to a working
99
101
  chatbot with tools in 5 minutes
102
+ - [Architecture](docs/architecture.md) — package structure, dependency graph,
103
+ data flow
100
104
  - [Working with LLMs](docs/llm.md) — providers, streaming, structured output,
101
105
  caching, extended thinking
102
106
  - [Tools](docs/tools.md) — tool groups, MCP servers, service injection
103
107
  - [Agents](docs/agents.md) — custom agents, state machines, control flow,
104
108
  parallel execution
109
+ - [Interrupts](docs/interrupts.md) — how an interrupt travels through the agent
110
+ tree: the principles and rules every agent and building block follows
105
111
  - [Patterns](docs/patterns.md) — multi-agent patterns: router, pipeline, race,
106
112
  fan-out
107
113
  - [Observability](docs/observability.md) — hooks, spans, MLflow and OTel