sangkyoonnam opened a new pull request, #1362: URL: https://github.com/apache/flink-agents/pull/1362
Linked issue: #1333 ### Purpose of change Python agents can register model routers and select candidates with rules or a named custom executor. This builds on the merged chat-attempt refactor. #### Runtime flow The chat action resolves a router once, persists its decision under `route:<router>`, then invokes the selected candidate under `chat:<router>:<candidate>`. The action emits routing observations and saves metadata until the final response. #### Key decisions Descriptors use Java's keys and strategy tags. Python validates custom executor classes; Java skips `Class.forName` only for Python-provided routers. Both validators still check shared descriptor fields and rule syntax. Resource-existence lookup does not construct resources. Python scoped model/router names use the nearest declaration across both types; tool follow-ups execute an explicit concrete selection, as in Java. ### Behavioral Semantics #### Interaction decisions | Condition | Result | | --- | --- | | Abstention or non-candidate selection | Declared default, otherwise first candidate | | Selected model exhausts retries; fallback enabled | Remaining candidates in declaration order | | Python child model/router shadows the same name in a parent | Local declaration wins across both types; unshadowed routers inherit | | Tool loop begins | Concrete model reused; no later routing or fallback | | Strategy exception | Request failure, preserved for replay | | Durable storage failure/cancellation | Propagates; no fallback | #### Behavioral contracts and failure behavior Rules inspect the latest user text. Custom executors select models without receiving the runner context. If the initial candidate sequence is exhausted, its causes appear in one failure response. A later tool-round failure reports that round's error. Routing events do not drive dispatch. Successful final responses for routed requests include selection/fallback metadata; failed responses and responses to direct concrete-model requests do not. Decision latency has its own histogram. LLM-judge routing, decision-model routing and Java router execution in Python agents fail during plan compilation. YAML declarations remain separate. ### Tests | Contract | Tests | | --- | --- | | Registration, collisions and descriptor validation | Registration and routing-validation suites | | Selection, ordered fallback and failure causes | `test_model_routing.py` | | Scoped lookup, inherited routers and pinned tool follow-ups | `test_scoped_model_requests_and_tool_followups`, cache inheritance tests | | Success metadata and later tool-round failure boundary | Tool-round success/cleanup and `test_fallback_tool_failure_reports_current_round_without_routing_metadata` | | Durable route/model replay | Runtime journal and action replay tests | | Python descriptors/events accepted by Java | Committed snapshots and Java readers | | Custom-provider bridge and regex limits | Java routing validation tests | Focused Python action/API/plan/runtime checks passed 521 tests without skips or deselections. Java snapshot/validation checks executed 76 cases, with 18 snapshot-generation skips and no failures. Ruff 0.11.13 and JDK 11 Spotless passed; Java tests used JDK 21 with current reactor sources. Runtime replay tests use the real Python durable runner with a fake Java journal. Full suites, live LLMs, restarted Flink clusters and the complete version matrix were not tested. Regex matching has documented Python/JDK differences. ### API Adds router/strategy declarations, routing context/decision types, `ModelRoutingEvent` and `RunnerContext.has_resource`. Custom runner-context implementations must implement the new lookup. Python sub-agent declarations shadow inherited model/router names across both types. Other concrete model requests retain their behavior. ### Documentation - [x] doc-included ### Was this patch authored or co-authored using generative AI tooling? - [x] Yes - [ ] No Generated-by: Codex CLI 0.166.0 (gpt-6-astra) Generated-by: Codex CLI 0.166.0 (gpt-6.1-sol) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
