docs(contributing): add CONTRIBUTING.md and improve linting CI feedback#2829
Closed
danielaskdd wants to merge 53 commits intoHKUDS:mainfrom
Closed
docs(contributing): add CONTRIBUTING.md and improve linting CI feedback#2829danielaskdd wants to merge 53 commits intoHKUDS:mainfrom
danielaskdd wants to merge 53 commits intoHKUDS:mainfrom
Conversation
…ter-based text - Add EntityExtractionResult Pydantic model for structured JSON output - Add JSON-mode prompt templates for entity/relationship extraction - Add _process_json_extraction_result() JSON parser in extraction pipeline - Add entity_extraction_use_json config option, default True - Add extraction_max_tokens config to prevent output truncation - OpenAI: use response_format json_object with auto-fallback retry - Ollama/Gemini: use native JSON mode for entity extraction - Other providers: pop entity_extraction kwarg for compatibility - Cache rebuild auto-detects JSON vs delimiter format - Skip relationships with empty descriptions to prevent merge errors
…ndles truncation)
Bring the RAG-Anything parsing/analyze flow into LightRAG's document pipeline and let extract, keyword, query, and VLM roles run with independent model settings. This keeps structured extraction, DOCX interchange ingestion, and relation merge hardening upstreamable without including the entity disambiguation experiment. Made-with: Cursor
Document the companion parser-side changes made in RAG-Anything so reviewers can understand how heading and table normalization align with this LightRAG multimodal pipeline PR without including external repository code here. Made-with: Cursor
Add safe example settings for the new structured extraction, parser integration, staged pipeline, and role-specific LLM/VLM routing options while keeping env.example ready for cp env.example .env deployment without exposing private models or secrets. Made-with: Cursor
Align the combined structured extraction and multimodal pipeline branch with the repository pre-commit rules so the upstream PR can pass formatting and lint checks cleanly. Made-with: Cursor
Sync env.example with the upstream interactive setup wizard template while keeping the multimodal parsing, staged pipeline, JSON extraction, and role-specific LLM settings exposed for configuration. Made-with: Cursor
Rebase env.example onto the latest upstream interactive setup template while preserving the multimodal parsing, staged pipeline, JSON extraction, and role-specific model configuration added by this PR. Made-with: Cursor
Keep LIGHTRAG_RUNTIME_TARGET in the latest upstream wizard template form so env.example remains a configuration template rather than activating a concrete runtime value in place. Made-with: Cursor
Refresh env.example against the latest interactive setup template updates, including runtime metadata, Mongo/OpenSearch storage guidance, and device-related comments, while preserving this PR's structured extraction, multimodal parsing, staged pipeline, and role-specific model settings. Made-with: Cursor
Add the OpenSearch client to offline storage dependencies and make the offline test workflow install storage backends so mocked OpenSearch storage tests can be collected in CI. Made-with: Cursor
Reorder requirements-offline-storage.txt to match the repository requirements formatter so pre-commit passes cleanly in CI. Made-with: Cursor
Add runtime role-specific LLM reconfiguration, provider option overrides per role, isolated role kwargs for Ollama query paths, and expanded offline coverage for role isolation, VLM, rollback behavior, and Ollama role kwargs. Made-with: Cursor
- Defer .docx upload parsing to three-stage pipeline via pending_parse format instead of synchronous API-layer extraction - Fill positions field in interchange JSONL with para_id from docx - Extract embedded images from .docx to *.blocks.assets directory - Add extract_docx_images() for binary image extraction via r:embed - Extend _extract_drawing_info() to return relationship ID - Add FULL_DOCS_FORMAT_PENDING_PARSE constant and parse_native branch - Mark engine_capabilities with "i" when images are present Made-with: Cursor
Made-with: Cursor
Cherry-pick runtime_validation.py from upstream/main so the test_runtime_target_validation tests can be collected during CI merge preview. Made-with: Cursor
Cherry-pick opensearch_impl.py and update kg/__init__.py from upstream/main so test_opensearch_storage tests can be collected during CI merge preview. Made-with: Cursor
Cherry-pick all files that exist in upstream/main but were missing from this branch. CI merge preview collects tests from both branches, so missing source modules cause ImportError during test collection. Includes: Makefile, docker-compose-full, InteractiveSetup docs, OpenSearch examples, setup wizard scripts/templates, and 4 upstream test files (zhipu, opensearch, runtime_target, interactive_setup). Note: test_interactive_setup_outputs has 4 pre-existing failures in upstream/main itself (port mapping assertion format mismatch). Made-with: Cursor
The port mapping assertions expected variable-format strings
(${HOST:-0.0.0.0}:${PORT:-9621}:9621) but setup.sh produces
concrete values (127.0.0.1:8080:9621). Update assertions to
match the actual behavior.
Made-with: Cursor
Keep test assertions identical to upstream/main to avoid merge conflicts. The 4 port-mapping assertion failures are a known upstream issue (setup.sh outputs concrete values but tests expect variable-format strings). Made-with: Cursor
Pull the latest setup.sh from upstream/main which now produces variable-format port mappings matching the test assertions. Made-with: Cursor
- add `ready_for_review` to PR trigger types for linting and tests workflows - add conditional check to skip jobs when PR is in draft state
- remove offline-storage extra from pip install command in CI workflow - all offline tests does not require storage backends
- add `type: ignore[import-untyped]` comment to silence mypy warning for untyped raganything.parser module
- Add .github/CONTRIBUTING.md with full contributor guide covering setup, code style, pre-commit, testing, and PR workflow - Update linting workflow to post fix instructions as Job Summary and PR comment when pre-commit checks fail, so developers know how to resolve issues without leaving the PR page - Add Contributing Guide link to README.md and README-zh.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Improve the contributor experience by adding a proper contributing guide and making linting CI failures actionable directly from the PR page.
Related Issues
N/A
Changes Made
.github/CONTRIBUTING.md— full contributor guide covering development setup (uv sync), pre-commit/code style, running tests, PR workflow, and issue reporting.github/workflows/linting.yaml— when pre-commit checks fail, the CI now:README.md/README-zh.md— added a "Contributing Guide" link in the🤝 Contributionsection so the guide is discoverable from the project homepageChecklist
Additional Notes
GitHub natively recognizes
.github/CONTRIBUTING.mdand automatically shows a banner prompting contributors to read it when they open a new issue or pull request.The linting workflow now requires
permissions: pull-requests: write(added at the workflow level) so the bot comment step can post to PRs.