Nishieee opened a new pull request, #354:
URL: https://github.com/apache/hugegraph-ai/pull/354
## Summary
Closes #347
- Adds opt-in `include_trace` on `POST /rag` for graph retrieval debugging.
- Default `/rag` response is unchanged (no trace unless requested).
- Vector/rerank trace deferred to follow-up, per the issue scope.
## What changed
| Area | Change |
| --- | --- |
| `RAGRequest` | New field `include_trace: bool = False` |
| `RAGTrace` | Typed model with 6 graph-recall fields (same names as
`/rag/graph`, minus `query`) |
| Flows | `RAGGraphOnlyFlow` / `RAGGraphVectorFlow` copy allowlisted fields
from `WkFlowState` when trace is enabled |
| `flows/common.py` | `GRAPH_RECALL_TRACE_KEYS` (6) for `/rag` trace;
`GRAPH_TRACE_KEYS` (7, incl. `query`) for `/rag/graph` |
| `rag_api.py` | Builds response via `serialize_rag_trace()`
(`exclude_none=True`); attaches `trace` only for `graph_only` or
`graph_vector_answer` |
| `rag_block.py` | Passes `include_trace` through the scheduler (Gradio UI
unchanged) |
## Behavior
- `include_trace=false` -> same as before: `query` + answer field(s).
- `include_trace=true` + graph mode -> adds `trace` with e.g. `keywords`,
`match_vids`, `gremlin`, `graph_result`, etc.
- `vector_only` / `raw_answer` only -> no trace.
- Secrets and prompts are excluded via the allowlist (not a full state dump).
- Missing trace fields are omitted; empty lists are kept when recall ran but
matched nothing, so clients can distinguish "didn't run" from "ran, no matches."
## Test plan
- [x] Default `/rag` - no trace, same shape
- [x] `include_trace=true` + `graph_only` - trace returned
- [x] `include_trace=true` + `graph_vector_answer` - trace returned
- [x] `include_trace=true` + `vector_only` only - no trace
- [x] Allowlist excludes prompts/secrets
- [x] `RAGGraphOnlyFlow` / `RAGGraphVectorFlow` `post_deal` populate trace
- [x] `serialize_rag_trace` omits `None` fields
```bash
cd hugegraph-llm
SKIP_EXTERNAL_SERVICES=true uv run pytest src/tests/api/test_rag_api.py -v
--tb=short
```
--
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]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
