feat(graph-extractor): prompt v2 — 7 hard requirements + window-aware parser (task #30-A3)

[earayu]

Summary

Task #30-A3 / sub-task #53. Implements the prompt v2 contract from docs/zh-CN/architecture/task-30-graph-chunk-window-spec-v1.md §3.1.3 — every entity / relation now carries a non-empty source_chunk_ids list, the prompt prepends a [[chunk_id=<id> index=<n>]] boundary marker per chunk, and the parser validates returned ids against the window allowlist.

7 hard requirements landed

1. Per-chunk boundary markers in the rendered prompt.
2. source_chunk_ids REQUIRED on every entity + relation in the JSON schema.
3. Cross-chunk relations encouraged in the prompt rules.
4. Dedup / canonical-name guidance in the prompt rules.
5. Fail-safe / no-fabrication clause.
6. Cap rules now talk about per-window output (the max_entities and max_relations numbers are still rendered as-is from caller args; @huangheng's task feat: page framework #30-A2 / task fix: husky hooks #54 fills the co-scale formula).
7. Graph extractor still passes response_format={"type": "json_object"} to the LLM callable (kept verbatim from task feat: socket debug #14 / PR feat(llm): wire response_format=json_object through CompletionService for graph extractor (issue #1861, task #14) #1877).

Implementation

• aperag/indexing/llm.py — ENTITY_RELATION_EXTRACTION rewritten with the v2 rules; render_extraction_prompt now takes window_chunks instead of a single input_text and renders one [[chunk_id=...]] block per chunk. New few_shot_locale opt-in (default None) pulls from a zh / cross_chunk example library for collection configs that want a non-English or cross-chunk hint without paying the prompt-token tax by default.
• aperag/indexing/graph_extractor.py — new _extract_one_window taking a sequence of chunks; the legacy _extract_one_chunk is kept as a thin compat shim that wraps a single-chunk window so @ziang's task feat: page framework #30-A1 (PR feat(indexing): add graph extraction window assembler #1918) dispatcher + existing callers stay green until A1 lands. Parser rewired: _parse_extraction_response now takes allowed_chunk_ids, and the new _resolve_source_chunk_ids enforces the spec invariant — single-chunk window falls back to the lone allowed id when the field is missing, multi-chunk window requires the LLM to populate it (otherwise the record is skipped + warned), and any out-of-allowlist id is silently dropped before the non-empty check so hallucinated chunk_ids do not poison provenance.

Tests

• Rewire every _parse_extraction_response call to the new allowed_chunk_ids keyword.
• Update the rendered-prompt smoke test to the new window_chunks signature.
• New tests: per-chunk markers, few-shot opt-in, empty-window guard, single-chunk fallback, multi-chunk required-provenance branch, out-of-allowlist drop, cross-chunk provenance preservation.
• The build_collection_llm_callable monkeypatch stubs now accept **_kwargs so the patched lambdas tolerate the response_format keyword that build_collection_graph_extractor has been passing since task feat: socket debug #14 (these stubs were silently accumulating an arity mismatch).

Out of scope

• Window assembler + graph_extraction_window_size config — task feat: page framework #30-A1 / @ziang PR feat(indexing): add graph extraction window assembler #1918.
• MAX_ENTITIES / MAX_RELATIONS / TIMEOUT / BOOTSTRAP / MAX_PROMPT_TOKENS co-scale — task feat: page framework #30-A2 / @huangheng task fix: husky hooks #54.
• Frontend / generated schema for the new collection config — A1 covers them.

Merge order

PM @不穷 dispatched A1 → A3 → A2 (msg=fadcd64c). This PR (A3) will be rebased onto A1 after PR #1918 lands; A2 then folds the co-scale formula into the prompt's max_entities / max_relations placeholders.

Test plan

• uvx ruff@0.15.12 check aperag/ tests/ — pass
• uvx ruff@0.15.12 format --check aperag/ tests/ — pass
• uv run --extra test python -m pytest tests/integration/test_graph_extractor.py -q — 36 passed
• Full CI lint-and-unit + e2e-http-smoke + e2e-http-provider (after rebase onto A1)

🤖 Generated with Claude Code