apache / apache/geaflow

[enhancement] Complete acceptance, documentation, and release readiness

Open
#868 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 5 of Parent epic:** [#863](https://github.com/apache/geaflow/issues/863)

## Summary

Prepare the GraphRAG engine for maintainer review and final acceptance. Consolidate the implementation from Phases before, close integration gaps, document supported usage and limitations, and verify that a fresh contributor can run the service, invoke the REST API, and reproduce the benchmark artifacts.

## Motivation

An implementation is not complete when the code works only in the author's environment. The final phase must make behavior discoverable, preserve compatibility with existing `geaflow-ai` APIs, and provide an auditable acceptance package for the GeaFlow community.

## Scope

- Run the complete Java unit, integration, HTTP contract, and legacy `/query/*` regression suites.
- Run the end-to-end ingestion, index build, retrieval, evaluation, and benchmark smoke commands from a clean checkout and verified local cache.
- Fix release-blocking defects, flaky tests, nondeterministic ordering, resource leaks, and unclear error messages discovered during maintainer review.
- Publish API documentation for `POST /api/v1/retrievals`, `/health`, `/ready`, request IDs, version selection, budgets, response fields, error codes, and degradation behavior.
- Add runnable `curl` and/or Java examples showing graph preparation and an upper-layer retrieval call, including successful, empty, and typed-error responses.
- Document configuration defaults, hard limits, supported retrieval/execution modes, dataset licenses, cache/artifact requirements, known limitations, and operational responsibilities of the deployment gateway.
- Assemble the final experiment report with methodology, raw artifact locations, reproducibility commands, ablations, negative results, and applicability boundaries.
- Verify Java compatibility, dependency/license notices, formatting, and repository contribution conventions before delivery on 2026-11-10.

## Suggested implementation locations

- `geaflow-ai/src/test/` - final unit, integration, HTTP, and compatibility coverage.
- `examples/graphrag/` or the repository-approved examples location - runnable service/client examples.
- `docs/` - API, configuration, ingestion, evaluation, and troubleshooting documentation.
- `tools/graphrag/` - reproduction scripts and validation commands.

## Testing and review checklist

- Unit, integration, HTTP contract, and end-to-end smoke tests.
- Backward-compatibility check for `/query/context`, `/query/exec`, and `/query/result`.
- Reproducibility check using the published manifests, seeds, and commands.
- Resource and timeout checks for the service and retrieval executors.
- Documentation link, command, JSON schema, and license review.

Contributor guide

Open the contributing guide

Research direction

Start by reading parent issue #863 and the existing implementation, tests, and conventions under geaflow-ai/src/test/, examples/graphrag/, docs/, and tools/graphrag/. Run the listed unit, integration, HTTP, compatibility, and end-to-end checks from a clean checkout. Done means the service and examples are reproducible, the required API and operational documentation is published, and the complete acceptance checklist passes.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
backend-api-design, documentation, release, 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.