flowra 0.0.99.dev118__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 (393) hide show
  1. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/.github/workflows/master.yml +1 -1
  2. {flowra-0.0.99.dev118 → 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.99.dev118 → flowra-0.0.99.dev119}/AGENTS.md +2 -2
  5. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/CHANGELOG.md +272 -96
  6. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/CLAUDE.md +4 -4
  7. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/Makefile +1 -1
  8. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/PKG-INFO +20 -17
  9. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/README.md +5 -2
  10. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/context7.json +27 -26
  11. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/agents.md +148 -124
  12. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/architecture.md +9 -7
  13. {flowra-0.0.99.dev118 → 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.99.dev118 → flowra-0.0.99.dev119}/docs/llm.md +60 -17
  16. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/observability.md +55 -15
  17. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/patterns.md +29 -11
  18. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/e2e_security.md +1 -1
  19. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/review_prompts/step2_code_style.md +9 -1
  20. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/todo.md +10 -0
  21. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/tools.md +63 -3
  22. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/video_script.md +1 -1
  23. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/agent_as_tool.py +11 -0
  24. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/app_agent.py +1 -2
  25. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/console_chat.py +4 -0
  26. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/docs/agents_custom.py +7 -0
  27. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/docs/agents_parallel.py +14 -2
  28. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/docs/getting_started_chat.py +4 -0
  29. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/docs/getting_started_streaming.py +4 -0
  30. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/docs/getting_started_tools.py +6 -0
  31. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/docs/llm_streaming.py +4 -0
  32. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/docs/llm_structured_output.py +4 -0
  33. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/docs/tools_service_injection.py +7 -0
  34. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/escalation.py +22 -4
  35. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/llm_logging.py +5 -0
  36. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/menu_agent.py +9 -0
  37. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/menu_agent_class.py +12 -0
  38. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/mlflow_demo.py +4 -0
  39. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/mlflow_dual_export_demo.py +4 -0
  40. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/mlflow_nested_demo.py +5 -0
  41. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/mlflow_otel_both_demo.py +4 -0
  42. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/mlflow_otel_nested_demo.py +5 -0
  43. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/mlflow_parallel_demo.py +6 -0
  44. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/otel_demo.py +6 -2
  45. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/otel_jaeger_demo.py +5 -0
  46. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/otel_nested_demo.py +5 -0
  47. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/otel_visualize.py +9 -2
  48. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/race.py +20 -4
  49. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/span_crash_demo.py +4 -0
  50. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/span_demo.py +4 -0
  51. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/tools/__init__.py +2 -0
  52. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/tools/calculator.py +8 -0
  53. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/tools/random_numbers.py +5 -0
  54. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/tui_chat.py +191 -182
  55. flowra-0.0.99.dev119/flowra/_aio.py +20 -0
  56. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/_typing.py +91 -9
  57. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/__init__.py +4 -1
  58. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/__init__.py +2 -1
  59. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/compile/contract.py +38 -29
  60. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/compile/instance.py +7 -7
  61. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/compile/step_params.py +26 -13
  62. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/compile/step_validation.py +54 -33
  63. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/compile/steps.py +2 -2
  64. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/compile/type_registry.py +13 -30
  65. flowra-0.0.99.dev119/flowra/agent/definition/interrupted.py +29 -0
  66. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/model.py +5 -4
  67. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/shared_persistent.py +2 -2
  68. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/step.py +4 -10
  69. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/step_helpers.py +0 -11
  70. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/flow/hooks.py +53 -62
  71. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/flow/interrupt.py +1 -1
  72. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/flow/interrupt_helpers.py +4 -0
  73. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/runtime/__init__.py +2 -1
  74. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/runtime/engine.py +121 -85
  75. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/runtime/execution.py +17 -1
  76. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/runtime/key_locks.py +1 -1
  77. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/runtime/runtime.py +128 -56
  78. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/runtime/scope.py +34 -29
  79. flowra-0.0.99.dev119/flowra/agent/runtime/serialization.py +97 -0
  80. flowra-0.0.99.dev119/flowra/agent/runtime/spans.py +58 -0
  81. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/runtime/spawn_satisfaction.py +1 -1
  82. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/storage/file.py +5 -0
  83. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/ext/mlflow.py +17 -5
  84. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/ext/otel.py +39 -1
  85. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/chat/__init__.py +2 -2
  86. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/chat/agent.py +14 -9
  87. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/chat/conversation.py +10 -8
  88. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/chat/spec.py +5 -5
  89. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/llm_caller.py +105 -27
  90. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/turn/__init__.py +2 -2
  91. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/turn/agent.py +44 -34
  92. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/turn/spec.py +5 -4
  93. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/turn/tool_call/agent.py +8 -5
  94. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/turn/tool_call/context.py +4 -2
  95. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/__init__.py +2 -1
  96. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/blocks.py +16 -0
  97. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/errors.py +6 -3
  98. flowra-0.0.99.dev119/flowra/llm/ext/__init__.py +1 -0
  99. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/openai_schema.py +28 -1
  100. flowra-0.0.99.dev119/flowra/llm/providers/__init__.py +1 -0
  101. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/providers/_openai_common.py +13 -5
  102. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/providers/anthropic.py +8 -8
  103. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/providers/anthropic_bedrock.py +6 -4
  104. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/providers/anthropic_foundry.py +1 -0
  105. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/providers/anthropic_vertex.py +8 -15
  106. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/providers/google_vertex.py +61 -41
  107. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/providers/openai.py +18 -13
  108. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/providers/openai_decisions.py +1 -1
  109. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/providers/openai_responses.py +26 -10
  110. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/tools/__init__.py +2 -1
  111. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/tools/mcp_connection.py +108 -30
  112. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/version.py +1 -1
  113. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/pyproject.toml +12 -9
  114. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/definition/compile/test_compile.py +44 -48
  115. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/flow/test_context.py +10 -0
  116. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/flow/test_hooks.py +8 -0
  117. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/flow/test_interrupt.py +0 -3
  118. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/flow/test_timeout.py +7 -15
  119. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/flow/test_with_interrupt.py +45 -91
  120. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/runtime/test_engine.py +70 -29
  121. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/runtime/test_engine_spans.py +5 -4
  122. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/runtime/test_persistence.py +340 -12
  123. flowra-0.0.99.dev119/tests/agent/runtime/test_run_span.py +232 -0
  124. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/runtime/test_runtime.py +1071 -403
  125. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/runtime/test_scope.py +22 -4
  126. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/runtime/test_serialization.py +56 -5
  127. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/storage/test_in_memory.py +1 -1
  128. flowra-0.0.99.dev119/tests/examples/test_escalation.py +121 -0
  129. flowra-0.0.99.dev119/tests/examples/test_race.py +36 -0
  130. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/ext/test_mlflow.py +39 -6
  131. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/ext/test_mlflow_cross_task.py +21 -10
  132. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/ext/test_otel.py +24 -0
  133. flowra-0.0.99.dev119/tests/ext/test_tracing_under_interrupts.py +742 -0
  134. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/lib/_helpers.py +6 -3
  135. flowra-0.0.99.dev118/tests/lib/test_chat_agent.py → flowra-0.0.99.dev119/tests/lib/chat/test_agent.py +147 -180
  136. {flowra-0.0.99.dev118/tests/lib → flowra-0.0.99.dev119/tests/lib/chat}/test_conversation.py +3 -33
  137. flowra-0.0.99.dev118/tests/lib/test_decision_call_agent.py → flowra-0.0.99.dev119/tests/lib/decision_call/test_agent.py +2 -3
  138. flowra-0.0.99.dev118/tests/lib/test_llm_call_agent.py → flowra-0.0.99.dev119/tests/lib/llm_call/test_agent.py +2 -3
  139. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/lib/test_llm_caller.py +361 -10
  140. flowra-0.0.99.dev118/tests/lib/test_turn_agent.py → flowra-0.0.99.dev119/tests/lib/turn/test_agent.py +197 -26
  141. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/lib/turn/test_render.py +6 -5
  142. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/lib/turn/test_tool_errors.py +6 -1
  143. flowra-0.0.99.dev118/tests/lib/test_tool_call_agent.py → flowra-0.0.99.dev119/tests/lib/turn/tool_call/test_agent.py +37 -5
  144. flowra-0.0.99.dev118/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
  145. {flowra-0.0.99.dev118/tests/lib → flowra-0.0.99.dev119/tests/llm}/ext/anthropic/test_anthropic.py +0 -4
  146. flowra-0.0.99.dev119/tests/llm/providers/__init__.py +0 -0
  147. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_anthropic.py +55 -0
  148. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_anthropic_bedrock.py +10 -1
  149. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_anthropic_e2e.py +2 -1
  150. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_anthropic_foundry.py +10 -0
  151. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_anthropic_vertex.py +12 -3
  152. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_anthropic_vertex_locations_e2e.py +2 -1
  153. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_cross_provider_e2e.py +19 -0
  154. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_errors.py +76 -0
  155. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_fallback_e2e.py +2 -1
  156. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_google_vertex.py +35 -0
  157. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_history_across_models.py +20 -0
  158. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_openai_decisions.py +18 -4
  159. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_openai_provider.py +107 -0
  160. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_openai_responses.py +21 -0
  161. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_refusals.py +0 -1
  162. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_schemas_e2e.py +25 -0
  163. flowra-0.0.99.dev119/tests/llm/providers/test_stream_closing.py +89 -0
  164. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_typesafe.py +16 -3
  165. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/test_blocks.py +20 -1
  166. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/test_openai_schema.py +52 -1
  167. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/test_response.py +99 -1
  168. flowra-0.0.99.dev119/tests/scripts/__init__.py +0 -0
  169. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/test_typing.py +133 -0
  170. flowra-0.0.99.dev119/tests/tools/__init__.py +0 -0
  171. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/tools/test_mcp_connection.py +304 -24
  172. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/uv.lock +940 -1177
  173. flowra-0.0.99.dev118/.python-version +0 -1
  174. flowra-0.0.99.dev118/docs/interrupts.md +0 -224
  175. flowra-0.0.99.dev118/flowra/agent/definition/interrupted.py +0 -32
  176. flowra-0.0.99.dev118/flowra/agent/runtime/serialization.py +0 -73
  177. flowra-0.0.99.dev118/flowra/agent/runtime/spans.py +0 -39
  178. flowra-0.0.99.dev118/flowra/agent/state/markers.py +0 -22
  179. flowra-0.0.99.dev118/tests/agent/test_missing_scenarios.py +0 -156
  180. flowra-0.0.99.dev118/tests/llm/test_cost_breakdown.py +0 -101
  181. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/.agents/skills/source-command-update-pricing/SKILL.md +0 -0
  182. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/.claude/commands/update-pricing.md +0 -0
  183. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/.env.example +0 -0
  184. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/.github/CODEOWNERS +0 -0
  185. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/.github/workflows/publish.yml +0 -0
  186. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/.gitignore +0 -0
  187. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/LICENSE +0 -0
  188. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/agent_async_init.md +0 -0
  189. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/agent_tool_errors.md +0 -0
  190. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/anthropic_web_search.md +0 -0
  191. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/enum_slot_values.md +0 -0
  192. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/final_tools.md +0 -0
  193. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/langchain_comparison.md +0 -0
  194. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/lifecycle_hooks_and_conversation.md +0 -0
  195. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/llm_retry_backoff.md +0 -0
  196. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/named_scope_lazy_hydration.md +0 -0
  197. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/named_scope_type_registry.md +0 -0
  198. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/named_scopes.md +0 -0
  199. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/pricing_complexity.md +0 -0
  200. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/pydantic_ai_comparison.md +0 -0
  201. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/strands_comparison.md +0 -0
  202. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/tool_error_signals.md +0 -0
  203. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/tool_errors_vs_failures.md +0 -0
  204. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/tool_registry_redesign.md +0 -0
  205. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/tool_search_tool.md +0 -0
  206. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/research/voice_stt.md +0 -0
  207. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/review_prompts/step1_structure.md +0 -0
  208. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/review_prompts/step3_documentation.md +0 -0
  209. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/review_prompts/step4_doc_readability.md +0 -0
  210. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/review_prompts/step5_doc_audit.md +0 -0
  211. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/docs/review_prompts/step6_tests.md +0 -0
  212. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/TRACING_COMBINATIONS.md +0 -0
  213. {flowra-0.0.99.dev118/flowra/ext → flowra-0.0.99.dev119/examples}/__init__.py +0 -0
  214. {flowra-0.0.99.dev118/flowra/llm/ext → flowra-0.0.99.dev119/examples/docs}/__init__.py +0 -0
  215. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/llm_routing.py +0 -0
  216. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/model_registry.py +0 -0
  217. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/system_prompt.txt +0 -0
  218. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/examples/tools/switch_model.py +0 -0
  219. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/__init__.py +0 -0
  220. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/_sentinel.py +0 -0
  221. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/_path.py +0 -0
  222. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/actions.py +0 -0
  223. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/agent.py +0 -0
  224. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/agent_arg.py +0 -0
  225. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/compile/__init__.py +0 -0
  226. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/compile/compiler.py +0 -0
  227. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/compile/init_params.py +0 -0
  228. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/errors.py +0 -0
  229. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/registry.py +0 -0
  230. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/definition/spawn.py +0 -0
  231. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/flow/__init__.py +0 -0
  232. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/flow/context.py +0 -0
  233. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/flow/flowing_registry.py +0 -0
  234. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/flow/timeout.py +0 -0
  235. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/runtime/instance_factory.py +11 -11
  236. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/runtime/spawn_tree.py +0 -0
  237. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/runtime/visibility.py +0 -0
  238. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/services.py +4 -4
  239. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/session_state.py +0 -0
  240. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/state/__init__.py +0 -0
  241. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/state/persistent.py +0 -0
  242. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/state/store.py +3 -3
  243. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/state/values.py +0 -0
  244. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/storage/__init__.py +0 -0
  245. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/storage/in_memory.py +0 -0
  246. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/agent/storage/session_storage.py +0 -0
  247. {flowra-0.0.99.dev118/flowra/llm/providers → flowra-0.0.99.dev119/flowra/ext}/__init__.py +0 -0
  248. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/ext/_session.py +0 -0
  249. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/__init__.py +0 -0
  250. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/chat/config.py +0 -0
  251. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/chat/hook_events.py +0 -0
  252. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/config_value.py +0 -0
  253. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/decision_call/__init__.py +0 -0
  254. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/decision_call/agent.py +0 -0
  255. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/decision_call/config.py +0 -0
  256. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/decision_call/spec.py +0 -0
  257. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/decision_config.py +0 -0
  258. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/llm_call/__init__.py +0 -0
  259. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/llm_call/agent.py +0 -0
  260. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/llm_call/config.py +0 -0
  261. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/llm_call/spec.py +0 -0
  262. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/llm_config.py +0 -0
  263. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/observability/__init__.py +0 -0
  264. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/observability/llm_hooks.py +0 -0
  265. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/turn/config.py +0 -0
  266. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/turn/context.py +0 -0
  267. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/turn/hook_events.py +0 -0
  268. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/turn/tool_call/__init__.py +0 -0
  269. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/lib/turn/tool_call/agent_tool.py +0 -0
  270. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/_schema_nodes.py +0 -0
  271. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/base.py +0 -0
  272. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/decision.py +0 -0
  273. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/ext/anthropic/__init__.py +0 -0
  274. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/ext/anthropic/cache.py +0 -0
  275. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/ext/anthropic/presets.py +0 -0
  276. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/ext/anthropic/tool_search.py +0 -0
  277. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/ext/anthropic/web_search.py +0 -0
  278. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/ext/openai/__init__.py +0 -0
  279. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/ext/openai/tool_search.py +0 -0
  280. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/gemini_schema.py +0 -0
  281. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/messages.py +0 -0
  282. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/pricing/__init__.py +0 -0
  283. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/pricing/bundled.py +0 -0
  284. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/custom/anthropic.json +0 -0
  285. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/custom/typesafe.json +0 -0
  286. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/custom/vertex.json +0 -0
  287. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/generated/anthropic.json +0 -0
  288. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/generated/azure_openai.json +0 -0
  289. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/generated/bedrock.json +0 -0
  290. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/generated/gemini_api.json +0 -0
  291. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/generated/inception.json +0 -0
  292. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/generated/openai.json +0 -0
  293. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/pricing/data/generated/vertex.json +0 -0
  294. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/pricing/model_pricing.py +0 -0
  295. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/pricing/price_list.py +8 -8
  296. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/provider.py +0 -0
  297. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/providers/_anthropic_common.py +0 -0
  298. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/providers/azure_openai.py +0 -0
  299. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/providers/typesafe.py +0 -0
  300. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/request.py +0 -0
  301. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/response.py +0 -0
  302. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/schema_formatting.py +0 -0
  303. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/schema_validation.py +0 -0
  304. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/stream.py +0 -0
  305. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/llm/tools.py +0 -0
  306. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/py.typed +0 -0
  307. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/tools/_mcp_content.py +0 -0
  308. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/tools/_mcp_headers.py +0 -0
  309. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/tools/local_tool.py +0 -0
  310. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/tools/result_format.py +0 -0
  311. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/tools/tool_arg.py +0 -0
  312. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/tools/tool_filter.py +0 -0
  313. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/tools/tool_registry.py +0 -0
  314. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/flowra/tools/types.py +0 -0
  315. {flowra-0.0.99.dev118/examples → flowra-0.0.99.dev119/tests}/__init__.py +0 -0
  316. {flowra-0.0.99.dev118/examples/docs → flowra-0.0.99.dev119/tests/agent}/__init__.py +0 -0
  317. {flowra-0.0.99.dev118/tests → flowra-0.0.99.dev119/tests/agent/definition}/__init__.py +0 -0
  318. {flowra-0.0.99.dev118/tests/agent → flowra-0.0.99.dev119/tests/agent/definition/compile}/__init__.py +0 -0
  319. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/definition/test_actions.py +0 -0
  320. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/definition/test_agent.py +0 -0
  321. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/definition/test_registry.py +0 -0
  322. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/definition/test_spawn.py +0 -0
  323. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/definition/test_step_helpers.py +0 -0
  324. {flowra-0.0.99.dev118/tests/agent/definition → flowra-0.0.99.dev119/tests/agent/flow}/__init__.py +0 -0
  325. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/flow/test_flowing_registry.py +0 -0
  326. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/flow/test_flowing_registry_tasks.py +0 -0
  327. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/flow/test_flowing_sync.py +0 -0
  328. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/flow/test_interruptible.py +0 -0
  329. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/flow/test_spans.py +0 -0
  330. {flowra-0.0.99.dev118/tests/agent/definition/compile → flowra-0.0.99.dev119/tests/agent/runtime}/__init__.py +0 -0
  331. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/runtime/test_ephemeral_isolation.py +0 -0
  332. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/runtime/test_hook_context.py +0 -0
  333. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/runtime/test_named_scope_persistence.py +0 -0
  334. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/runtime/test_named_scope_registry.py +0 -0
  335. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/runtime/test_named_scopes.py +0 -0
  336. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/runtime/test_parallel_failure.py +0 -0
  337. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/runtime/test_primitive_join.py +0 -0
  338. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/runtime/test_spec_in_constructor.py +0 -0
  339. {flowra-0.0.99.dev118/tests/agent/flow → flowra-0.0.99.dev119/tests/agent/state}/__init__.py +0 -0
  340. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/state/test_values.py +0 -0
  341. {flowra-0.0.99.dev118/tests/agent/runtime → flowra-0.0.99.dev119/tests/agent/storage}/__init__.py +0 -0
  342. /flowra-0.0.99.dev118/tests/agent/storage/__init__.py → /flowra-0.0.99.dev119/tests/agent/storage/_helpers.py +0 -0
  343. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/storage/test_file.py +0 -0
  344. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/agent/test_session_state.py +0 -0
  345. {flowra-0.0.99.dev118/tests/agent/state → flowra-0.0.99.dev119/tests/examples}/__init__.py +0 -0
  346. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/examples/test_menu_agent.py +0 -0
  347. {flowra-0.0.99.dev118/tests/examples → flowra-0.0.99.dev119/tests/ext}/__init__.py +0 -0
  348. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/ext/_mlflow.py +0 -0
  349. {flowra-0.0.99.dev118/tests/ext → flowra-0.0.99.dev119/tests/lib}/__init__.py +0 -0
  350. {flowra-0.0.99.dev118/tests/lib → flowra-0.0.99.dev119/tests/lib/chat}/__init__.py +0 -0
  351. /flowra-0.0.99.dev118/tests/lib/test_chat_spec.py → /flowra-0.0.99.dev119/tests/lib/chat/test_spec.py +0 -0
  352. {flowra-0.0.99.dev118/tests/lib/ext → flowra-0.0.99.dev119/tests/lib/decision_call}/__init__.py +0 -0
  353. {flowra-0.0.99.dev118/tests/lib/ext/anthropic → flowra-0.0.99.dev119/tests/lib/llm_call}/__init__.py +0 -0
  354. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/lib/test_config_value.py +0 -0
  355. {flowra-0.0.99.dev118/tests/lib/ext/openai → flowra-0.0.99.dev119/tests/lib/turn}/__init__.py +0 -0
  356. /flowra-0.0.99.dev118/tests/lib/test_matches_tool_filter.py → /flowra-0.0.99.dev119/tests/lib/turn/test_config.py +0 -0
  357. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/lib/turn/test_hook_events.py +0 -0
  358. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/lib/turn/test_per_call_headers.py +0 -0
  359. {flowra-0.0.99.dev118/tests/lib/turn → flowra-0.0.99.dev119/tests/lib/turn/tool_call}/__init__.py +0 -0
  360. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/__init__.py +0 -0
  361. {flowra-0.0.99.dev118/tests/llm/pricing → flowra-0.0.99.dev119/tests/llm/ext}/__init__.py +0 -0
  362. {flowra-0.0.99.dev118/tests/llm/providers → flowra-0.0.99.dev119/tests/llm/ext/anthropic}/__init__.py +0 -0
  363. {flowra-0.0.99.dev118/tests/scripts → flowra-0.0.99.dev119/tests/llm/ext/openai}/__init__.py +0 -0
  364. {flowra-0.0.99.dev118/tests/lib → flowra-0.0.99.dev119/tests/llm}/ext/openai/test_openai_tool_search.py +0 -0
  365. {flowra-0.0.99.dev118/tests/tools → flowra-0.0.99.dev119/tests/llm/pricing}/__init__.py +0 -0
  366. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/pricing/test_bundled.py +0 -0
  367. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/pricing/test_model_pricing.py +0 -0
  368. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/pricing/test_price_list.py +0 -0
  369. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/_mock_http.py +0 -0
  370. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/_raw_body.py +0 -0
  371. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/_tool_result_blocks.py +0 -0
  372. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_anthropic_bedrock_e2e.py +0 -0
  373. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_anthropic_foundry_e2e.py +0 -0
  374. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_azure_openai_e2e.py +0 -0
  375. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_decision_e2e.py +0 -0
  376. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_google_vertex_e2e.py +0 -0
  377. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_openai_e2e.py +0 -0
  378. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/providers/test_openai_responses_e2e.py +0 -0
  379. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/test_decision.py +0 -0
  380. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/test_gemini_schema.py +0 -0
  381. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/test_metadata.py +0 -0
  382. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/test_provider.py +0 -0
  383. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/test_schema_formatting.py +0 -0
  384. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/test_schema_nodes.py +0 -0
  385. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/test_schema_validation.py +0 -0
  386. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/llm/test_stream.py +0 -0
  387. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/scripts/test_sync_pricing.py +0 -0
  388. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/tools/test_local_tool.py +0 -0
  389. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/tools/test_mcp_headers.py +0 -0
  390. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/tools/test_result_format.py +0 -0
  391. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/tools/test_tool_registry.py +0 -0
  392. {flowra-0.0.99.dev118 → flowra-0.0.99.dev119}/tests/tools/test_types.py +0 -0
  393. {flowra-0.0.99.dev118 → 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
 
@@ -7,22 +7,116 @@ and this project adheres to [Semantic Versioning](https://semver.org).
7
7
 
8
8
  ## [Unreleased]
9
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.
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`.
24
118
  - **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
119
+ interrupt, unless its agent was signalled itself.** A parameter that takes
26
120
  only `T` and finds an interrupted child raises `StepBindingError` (new, a
27
121
  `TypeError`, from `flowra.agent`) naming the step, the parameter and what
28
122
  each child it looked at gave; before, the agent ended `Interrupted`, so a
@@ -30,45 +124,47 @@ and this project adheres to [Semantic Versioning](https://semver.org).
30
124
  whose own token has fired still ends `Interrupted`. An annotated parameter
31
125
  that nothing binds to now raises `StepBindingError` instead of Python's
32
126
  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`.
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`.
44
137
  - **`T | Interrupted` takes the interrupt only of a child that could give a
45
138
  `T`**, by its declared result types (a child without types could), so an
46
139
  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.
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.
52
145
  - **Every step annotates its return type with classes.** A step without a
53
146
  return annotation, or with `Any`, a type variable or a `Literal` in it, is a
54
147
  `TypeError` when the class is defined; before, its result went unchecked
55
148
  and its agent's result types left it out.
56
- - **A step returns exactly a type it declares**, its `Interrupted[D]` data
149
+ - **A step returns exactly a type it declares**, its `InterruptedWith[D]` data
57
150
  exactly a declared `D`: a subclass of one (a `bool` for an `int` too) is a
58
151
  `TypeError` when the step returns. Before, it ran until the result was
59
152
  saved, where an unregistered subclass failed.
60
153
  - **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
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
65
158
  `interrupt_children()` kept working). An interrupt that came after the last
66
159
  save is not in it. The runtime's interrupt now lasts until `run()` or
67
160
  `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.
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.
72
168
  - **A subclass of a primitive is refused as a step's result or parameter type,
73
169
  and in `Agent[S, R]`** (a `str` subclass, a `StrEnum`, an `IntEnum`): saved
74
170
  as the primitive, it came back as one after a resume, so a step binding it
@@ -77,76 +173,156 @@ and this project adheres to [Semantic Versioning](https://semver.org).
77
173
  step parameter may be a spec or a child, so it refuses one too, a `list` or
78
174
  `dict` subclass included; a service of such a type takes
79
175
  `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).
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).
86
202
  - **An `AgentRuntime` runs one `run()` or `resume()` at a time**: a second
87
203
  call while one is going raises `RuntimeError` ("already going", where a
88
204
  `run()` with storage used to get "Pending execution exists" once the first
89
205
  had saved). Before, a second `run()` without storage or before the first
90
206
  save, or any second `resume()`, ran a second tree that freed the first
91
207
  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
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.
130
309
  - **`LLMCaller` checks an interrupt before the first attempt too**, not only
131
310
  before a fallback: a call made once the interrupt has fired raises
132
311
  `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.
312
+ `LLMCallSpan` or `DecisionCallSpan` showed in traces).
136
313
  - **An interrupt does not drop a refusal `LLMCaller` holds.** With
137
314
  `switch_on_refusal=True`, an interrupt that came after a config refused
138
315
  raised `InterruptedError`, before the next attempt or cutting it short, and
139
316
  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.
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.
150
326
  - **`WhenAny`, `WhenN` and `timeout` wait for a child to end, not for its first
151
327
  step.** A child's step that went on (`GotoStep`, `GotoAgent`, `Spawn`)
152
328
  counted as the child finishing, so the child that started first won and the
@@ -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.99.dev118
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
 
@@ -136,13 +136,16 @@ flowra/
136
136
  ├── llm/ # LLM abstraction (messages, blocks, provider interface)
137
137
  ├── tools/ # Tool definition, registration, execution
138
138
  ├── agent/ # Agent framework + execution engine + persistence
139
- └── lib/ # Pre-built agents (ChatAgent, TurnAgent, hooks, caching)
139
+ ├── lib/ # Pre-built agents (ChatAgent, TurnAgent, hooks, caching)
140
+ └── ext/ # Tracing integrations (MLflow, OpenTelemetry)
140
141
  ```
141
142
 
142
143
  ## Documentation
143
144
 
144
145
  - **[Getting Started](docs/getting-started.md)** — from installation to a working
145
146
  chatbot with tools in 5 minutes
147
+ - [Architecture](docs/architecture.md) — package structure, dependency graph,
148
+ data flow
146
149
  - [Working with LLMs](docs/llm.md) — providers, streaming, structured output,
147
150
  caching, extended thinking
148
151
  - [Tools](docs/tools.md) — tool groups, MCP servers, service injection