apache / apache/geaflow

[enhancement] Add adaptive routing, degradation, and the production retrieval service

Open
#866 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.