[enhancement] Add adaptive routing, degradation, and the production retrieval service
- Dominant language
- Java
- Stars
- 808
- Forks
- 188
- Avg merge
- 3d 22h
- Merged PRs (30d)
- 2
Description
**Phase 3 of Parent epic:** [#863](https://github.com/apache/geaflow/issues/863)
## Summary
Complete the decision and serving layer on top of the Phase 2 retrieval core. Implement a
deterministic rule-based Adaptive Hybrid policy, explicit budget and failure semantics, and a versioned Solon REST adapter that upper-layer applications can call directly.
The REST contract established in Phase 1 is the compatibility boundary. This issue adds production behavior and operational safeguards without renaming or removing its core fields.
## Motivation
Different queries need different retrieval work. A fixed strategy can waste latency and token budget on simple queries or fail to explore difficult multi-hop questions. In addition, the current service prototype does not expose a stable, typed retrieval endpoint with readiness, observability, and degradation semantics.
## Scope
- Implement immutable `RoutingContext`, `RetrievalPlan`, and `RetrievalProgress` models.
- Implement `DeterministicRulePolicy` using query length, average IDF, first-stage score gap, anchor count/confidence, candidate degree, and graph growth rate.
- Validate every plan against hard limits, available indexes, supported hop count, and configured fallback rules before execution.
- Add optional bounded replanning at stage boundaries with a configured `maxReplanCount`.
- Implement typed failures for invalid requests, missing graphs, unavailable indexes, timeouts, unsupported options, and internal errors. Hybrid fallback must preserve completed evidence and record the degraded channels and reason codes.
- Add `POST /api/v1/retrievals` to the existing Solon service. Support request IDs via
`X-Request-Id`, server defaults, graph/index version selection, mode, optional query vectors, `topK`, timeout, and candidate/token budgets.
- Add `/health`, `/ready`, and a machine-readable metrics endpoint or metrics integration consistent with existing GeaFlow service conventions.
- Add structured logs containing request ID, graph/version, selected mode, effective budgets, channel work, result count, latency, status, and degradation reason.
- Provide a runnable upper-layer HTTP example using `curl` or a small client.
## Suggested implementation locations
- `geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/policy/` - routing context, rule policy, plan validation, and bounded replanning.
- `geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/service/` - orchestration, error mapping, readiness, trace, and metrics.
- `geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/api/` - Solon controllers and HTTP DTOs.
- `geaflow-ai/src/main/resources/application.yml` - versioned defaults and hard limits.
- `geaflow-ai/src/test/java/org/apache/geaflow/ai/retrieval/` - policy, service, contract, and HTTP integration tests.
## Testing requirements
- Unit tests for feature extraction, rule boundaries, plan validation, fallback, and replan limits.
- Service tests for each typed error, timeout behavior, request ID propagation, effective budgets, graph versions, and non-null response collections.
- Solon HTTP contract tests for success, empty result, failure, readiness, and metrics responses.
- Regression tests proving all existing `/query/*` behavior remains available.
## Dependencies and follow-up
- Later policy implementations may be added behind `AdaptivePolicy` without changing the REST API.
Contributor guide
Research direction
Start by reading the existing retrieval code under geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/ and the Phase 1 REST contract, then run the retrieval tests under geaflow-ai/src/test/java/org/apache/geaflow/ai/retrieval/. Done means the policy, validation, service, Solon endpoints, defaults, logging, metrics, examples, and listed regression tests cover the required behavior without breaking existing /query/* endpoints.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, yaml
- Domain
- api, backend, observability, testing
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100