wenjin272 opened a new pull request, #1377: URL: https://github.com/apache/flink-agents/pull/1377
Related issue: #1133 (annotation-contract cleanup only; this does not implement the router annotation). ### Purpose of change `@ChatModelSetup`, `@Prompt` and `@VectorStore` now reject field declarations at Java compile time. Previously, descriptor fields were silently ignored, actual chat model setup instances were rejected by the serializable-resource field path, and prompt/vector-store fields were never extracted. #### Runtime flow Java compilation enforces method-only targets. During plan construction, the existing static-method paths register chat model/vector-store descriptors and prompt instances under their method names. The unsupported chat-model field extraction path is removed. Plan and runtime fixtures now use descriptor methods, including a real `BaseChatModelSetup` subclass in the resource-cache test. #### Key decisions Remove the unsupported field contract instead of adding a second declaration mechanism. Preserve the working `@Tool` and `@Action` field APIs. Javadocs and the Resources guide document the method signatures and migration. ### Behavioral Semantics #### Interaction decisions and contracts | Annotation / declaration | Result | | --- | --- | | ChatModelSetup, Prompt or VectorStore on a field | Java compilation rejects the annotation target | | ChatModelSetup or VectorStore on a public static zero-argument method | Existing descriptor registration path | | Prompt on a public static zero-argument method | Existing prompt-instance registration path | | Tool or Action on a supported field | Existing behavior retained | #### Failure behavior The formerly unsupported field declarations fail at source compilation. Method invocation, descriptor validation and resource initialization retain their existing exception behavior; no new retries, fallbacks or service calls are introduced. ### Tests | Contract | Coverage | | --- | --- | | All three annotations accept methods and reject fields | `ResourceDeclarationAnnotationTest.acceptsMethodAndRejectsField` compiles both forms with the JDK compiler | | Chat model method names, descriptors and Java/Python provider selection remain intact | `AgentPlanTest.testExtractResourceProvidersFromAgent` | | Chat model instances can still be resolved and used | `AgentPlanDeclareChatModelTest.retrieveAndChat`, `jsonRoundTrip` | | Descriptor configuration reaches the runtime and cached instances are reused | `ResourceCacheTest.testGetResourceFromResourceProvider` | | Tool fields remain registered and usable | Existing tool assertions in the plan and resource-cache tests | Validation: - Focused API/plan/runtime reactor tests: 45 passed on JDK 11. - Python API/plan non-integration tests: 1,661 passed, 18 skipped (Python 3.11, Flink 2.3). - `./tools/ut.sh -j`: full reactor build/install passed; the Java test phase is still running. - Spotless checks passed in the reactor. Apache RAT reports zero unknown licenses after excluding the local untracked `.codex/` configuration (the standard script flags that local file). Not verified: live model/vector-store services, deployed-job recovery, and compatibility with already-compiled agents using the removed field annotations. ### API Intentional Java source incompatibility: move these field annotations to public static zero-argument methods, retaining the resource name. Chat model/vector-store methods return `ResourceDescriptor`; prompt methods return `Prompt`. Previously compiled chat-model fields are no longer registered by `AgentPlan`; callers should migrate and recompile. Method declarations, programmatic registration, Python/YAML APIs and plan serialization formats are unchanged. ### Documentation - [ ] `doc-needed` - [ ] `doc-not-needed` - [x] `doc-included` ### Was this patch authored or co-authored using generative AI tooling? - [x] Yes - [ ] No Generated-by: Codex CLI 0.153.4 (GPT-6) -- 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]
