2a97ec3e58
* docs: turn README into an index and move reference detail to docs/guide The README had grown to 393 KB because every change appended its notes there. The text moves verbatim into 18 topic guides under docs/guide/; only headings are re-leveled and relative links re-pointed. The README keeps the introduction, a quick start and a guide index. Contributor test notes move to CONTRIBUTING.md. * docs: send user docs to topic guides and budget the root README The rule 'update README.md for user-facing changes' is what grew the README. Guidance now points to docs/guide/, and check_agent_guidance.py fails when the root README exceeds 16 KiB (AG003). * chore: remove unreferenced screenshots and finished plan notes pr-build/ holds two PR screenshots (3 MB) from #1986. plans/ holds the plan for the merged #4049. docs/SKILL_NAME_CONFLICT_FIX.md is a February change note. Nothing references them. * docs: route always-loaded AGENTS.md files to scoped guides * docs(agents): cut scoped guides to scope, verify, traps, decisions Each AGENTS.md keeps four kinds of content: the scope of the directory, the verification commands, traps a local test run does not show, and decisions the code cannot state. Values, field lists, function inventories, test names, issue numbers and history are deleted, because the code, the tests and git state them. Search and fetch providers share one community guide. Four guides with no remaining content are removed. The size check now allows 6 KiB per file (hard limit 8 KiB) and 24 KiB per chain (hard limit 32 KiB). * style: format frontend guide table and guidance test imports --------- Co-authored-by: Willem Jiang <willem.jiang@gmail.com>
LightRAG entity relation retrieval
Optional read-only plugin for #6269's new Phase 1. Provides document retrieval
and entity relations through the existing tool configuration, scope admission,
shared evidence formatter and citation readers. No management or frontend plugin
is required. Requires a host with the new relations_search capability.
The response mapping follows LightRAG v1.5.7 commit
28ff1b05f2ac3f3e6fa14dd2cd33656579bd0c9c
(convert_to_user_format), using POST /query/data in hybrid mode.
Install from the repository root:
make extension-install SOURCE=/absolute/path/to/examples/deerflow-extension-lightrag
Merge into the installed plugin configuration and restart Gateway:
plugins:
- use: deerflow_extension_lightrag:install
enabled: true
required: true
config:
base_url: https://lightrag.example.com
api_key_env: LIGHTRAG_API_KEY
user_ids: ["YOUR_DEERFLOW_USER_ID"]
# Optional exact current executors, including allowed subagents:
agent_names: ["lead_agent", "researcher"]
top_k: 20
timeout: 30
knowledge_base:
enabled: true
tool_groups:
- name: knowledge
tools:
- name: entity_relations_search
group: knowledge
use: deerflow.knowledge.tools:entity_relations_search_tool
provider: lightrag-relations
# Optional document search using the same authorized connection:
- name: knowledge_search
group: knowledge
use: deerflow.knowledge.tools:knowledge_search_tool
provider: lightrag-relations
Set LIGHTRAG_API_KEY in the Gateway environment. This plugin requires an explicit
credential and exact user binding; it never falls back to an anonymous or more
privileged connection. Bound users share the credential's upstream visibility;
this is not upstream user impersonation. Upstream authorization remains final.
Remove a tool entry to disable that operation. The legacy built-in LightRAG document tool remains compatible and does not require this plugin.
Evidence and limits
- Returns upstream entities and one-edge paths (
src_id,tgt_id, description). It does not compute multi-hop paths, infer new edges, or claim graph completeness. - Each edge's
source_idis split using LightRAG's<SEP>delimiter and joined to retrievedchunks[].chunk_id. Only those actual chunks can receive document citations, using their file title or the returned reference mapping. - Edge descriptions and entity summaries remain unattributed graph facts. A
returned edge without matching retrieved chunks is explicitly marked as lacking
document evidence. Merely sharing
file_pathdoes not establish evidence. - Uses the existing
KnowledgeSourceenvelope unchanged. Graph descriptions and document excerpts are separate hits, so a graph summary cannot become a quotation. - Scope is limited to
all(the bound workspace) ordisabled. Dataset/document selections are rejected before requests; no unrestricted retry. Combining different registered providers also disables the shared selector because their resource IDs have no common namespace. - Requests do not follow redirects, have a timeout and a 4 MiB response cap. Core bounds displayed results and citations; returned graphs are partial views.
Offline synthetic tests cover HTTP requests, permissions, evidence joins, malformed payloads, secret redaction, combinations, delegation, replay and budgets. A real OrbStack deployment with bge-m3 and GLM-5.3 also passed provider and three-tool agent checks; see the validation record for versions, reproduction steps and limits. Offline passes alone are not live acceptance. Deployment verification must inspect both relation facts and original evidence.
Shared graph evidence chunks are emitted once per returned chunk ID, before the first referencing edge. Every edge names its evidence result positions; prefix truncation therefore cannot leave a retained edge pointing to omitted evidence.