fix(ragflow): type rerankId as String to match the RAGFlow API

[haosong384]

AgentScope-Java Version

2.0.3-SNAPSHOT (main at bf7b7da)

Description

Background

RAGFlowConfig declares rerankId as Integer, but RAGFlow's /api/v1/retrieval endpoint identifies rerank models by name, e.g. "BAAI/bge-reranker-v2-m3@BAAI" or a hex UUID such as "b2a62730759d11ef987d0242ac120004".

RAGFlowClient forwards the value verbatim:

// RAGFlowClient.java:168
requestBody.put("rerank_id", config.getRerankId());

Since no Integer corresponds to a real rerank model, there is no way to enable reranking through the Java SDK — the feature is unreachable, as reported in #2740. The existing Javadoc already described the field as the "rerank model ID", so the declared type contradicted its own documented meaning.

Changes

• rerankId field, builder field and getRerankId() are now String.
• New Builder.rerankId(String) is the supported entry point, documented with both accepted ID forms.
• Builder.rerankId(Integer) is retained as @Deprecated(forRemoval = true) so existing builder call sites keep compiling; it stringifies the value.
• Test call sites updated from integer literals to real RAGFlow model IDs, plus 3 new tests.
• docs/v1/{en,zh}/docs/task/rag.md updated: the RAGFlow config example showed .rerankId(1), i.e. it was actively teaching the unusable form.

On the null guard in the deprecated overload

this.rerankId = rerankId != null ? String.valueOf(rerankId) : null;

The guard is not redundant. An Integer argument binds to String.valueOf(Object) (reference widening resolves in overload phase 1, before unboxing is considered), and that overload maps null to the literal string "null" rather than to null. Without the guard, .rerankId((Integer) null) would put {"rerank_id": "null"} on the wire — worse than omitting the field. Verified:

String.valueOf((Integer) null) = [null]   // 4-character String, not null

nullRerankIdStaysNullForBothOverloads locks this behaviour down for both overloads.

Source compatibility — please read

This change is not fully source-compatible, and I want to be explicit rather than claim otherwise:

Call shape	Status
.rerankId(42) (builder)	✅ still compiles, via the deprecated overload
Integer id = config.getRerankId()	❌ breaks — the getter now returns String

Keeping an Integer-returning getter alongside a String field was considered and rejected: it would need duplicated state and could never return a usable value for a name-based ID, so it would preserve compilation while guaranteeing incorrect behaviour.

Practical exposure looks minimal: RAGFlowClient is the only reader of the getter in this repository, and because no valid Integer ever existed, callers are unlikely to be reading a meaningful value today. Still, this is the maintainers' call — happy to switch to a fully additive shape (leave Integer in place, add a separately named String accessor) if you prefer to avoid the break entirely.

How to test

mvn -pl agentscope-extensions/agentscope-extensions-rag/agentscope-extensions-rag-ragflow -am test
# Tests run: 99, Failures: 0, Errors: 0, Skipped: 0
# BUILD SUCCESS

New tests in RAGFlowConfigTest.AdvancedFeaturesTest:

• shouldAcceptRerankIdAsModelName — both the vendor/model@provider and hex-UUID forms round-trip
• deprecatedIntegerRerankIdIsStringified — the deprecated overload yields "42"
• nullRerankIdStaysNullForBothOverloads — neither overload produces the string "null"

The tests were verified to actually exercise the fix: stubbing out rerankId(String) turns 6 tests red, including shouldAcceptRerankIdAsModelName.

Relationship to open PRs

#2633 also touches this extension but only modifies RAGFlowClient, RAGFlowKnowledge and RAGFlowKnowledgeTest — it does not touch RAGFlowConfig or rerankId (diff checked), so there is no overlap.

Checklist

Please check the following items before code is ready to be reviewed.

• Code has been formatted with mvn spotless:apply (spotless:check passes)
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions (both overloads document the accepted ID forms; the deprecated one explains why it cannot work and what to use instead)
• Related documentation has been updated (e.g. links, examples, etc.) — the RAGFlow example in docs/v1/en/docs/task/rag.md and its Chinese counterpart both showed .rerankId(1) and are updated to a real model name
• Code is ready for review

---

Closes #2740

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!