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