Skip to content

AGENTS.md

Latest commit

 

History

History
57 lines (49 loc) · 6.25 KB

AGENTS.md

File metadata and controls

57 lines (49 loc) · 6.25 KB

Repository Guidelines

LightRAG is an advanced Retrieval-Augmented Generation (RAG) framework designed to enhance information retrieval and generation through graph-based knowledge representation.

Project Structure & Module Organization

  • lightrag/: Core Python package with orchestrators (lightrag/lightrag.py), storage adapters in kg/, LLM bindings in llm/, and helpers such as operate.py and utils_*.py.
  • lightrag-api/: FastAPI service (lightrag_server.py) with routers under routers/ and Gunicorn launcher run_with_gunicorn.py.
  • lightrag_webui/: React 19 + TypeScript client driven by Bun + Vite; UI components live in src/.
  • scripts/setup/: Interactive environment setup wizard. setup.sh orchestrates staged --base / --storage / --server / validation flows, lib/ holds prompt/validation/file helpers, and templates/*.yml contains compose fragments for bundled services.
  • Tests live in tests/ and root-level test_*.py. Working datasets stay in inputs/, rag_storage/, temp/; deployment collateral lives in docs/, k8s-deploy/, and docker-compose.yml.
  • Makefile: Canonical entry point for the setup wizard and local developer shortcuts; prefer documented targets over invoking ad hoc shell snippets.

Build, Test, and Development Commands

  • python -m venv .venv && source .venv/bin/activate: set up the Python runtime.
  • pip install -e . / pip install -e .[api]: install the package and API extras in editable mode.
  • make env-base: first-run interactive setup for LLM, embedding, and reranker configuration; writes .env and may generate docker-compose.final.yml.
  • make env-storage, make env-server: optional follow-up wizard stages for storage backends and server/security/SSL settings; both reuse the existing .env.
  • make env-validate, make env-security-check, make env-backup: validate, audit, or back up the current .env via the setup wizard.
  • lightrag-server or uvicorn lightrag.api.lightrag_server:app --reload: start the API locally; ensure .env is present.
  • python -m pytest tests (offline markers apply by default) or python -m pytest tests --run-integration / python test_graph_storage.py: run the full suite, opt into integration coverage, or target an individual script.
  • ruff check .: lint Python sources before committing.
  • bun install, bun run dev, bun run build, bun test: manage the web UI workflow (Bun is mandatory).

Coding Style & Naming Conventions

  • Backend code follow PEP 8 with four-space indentation, annotate functions, and reach for dataclasses when modelling state.
  • Use lightrag.utils.logger instead of print; respect logger configuration flags.
  • Extend storage or pipeline abstractions via lightrag.base and keep reusable helpers in the existing utils_*.py.
  • Python modules remain lowercase with underscores; React components use PascalCase.tsx and hooks-first patterns.
  • Front-end code should remain in TypeScript with two-space indentation, rely on functional React components with hooks, and follow Tailwind utility style.

Testing Guidelines

  • Keep pytest additions close to the code you touch (tests/ mirrors feature folders and there are root-level test_*.py helpers); functions must start with test_.
  • Follow tests/pytest.ini: markers include offline, integration, requires_db, and requires_api, and the suite runs with -m "not integration" by default—pass --run-integration (or set LIGHTRAG_RUN_INTEGRATION=true) when external services are available.
  • Use the custom CLI toggles from tests/conftest.py: --keep-artifacts/LIGHTRAG_KEEP_ARTIFACTS=true, --stress-test/LIGHTRAG_STRESS_TEST=true, and --test-workers N/LIGHTRAG_TEST_WORKERS to dial up workloads or preserve temp files during investigations.
  • Export other required LIGHTRAG_* environment variables before running integration or storage tests so adapters can reach configured backends.
  • For UI updates, pair changes with Vitest specs and run bun test.

Commit & Pull Request Guidelines

  • Use concise, imperative commit subjects (e.g., Fix lock key normalization) and add body context only when necessary.
  • PRs should include a summary, operational impact, linked issues, and screenshots or API samples for user-facing work.
  • Verify ruff check ., python -m pytest, and affected Bun commands succeed before requesting review; note the runs in the PR text.
  • This repo is a fork of HKUDS/LightRAG. Always target HKUDS/LightRAG:main (upstream) when creating PRs, not the fork's own main.

Security & Configuration Tips

  • Copy .env.example and config.ini.example; never commit secrets or real connection strings.
  • Configure storage backends through LIGHTRAG_* variables and validate them with docker-compose services when needed.
  • Treat lightrag.log* as local artefacts; purge sensitive information before sharing logs or outputs.

Automation & Agent Workflow

  • Use repo-relative workdir arguments for every shell command and prefer rg/rg --files for searches since they are faster under the CLI harness.
  • Default edits to ASCII, rely on apply_patch for single-file changes, and only add concise comments that aid comprehension of complex logic.
  • Honor existing local modifications; never revert or discard user changes (especially via git reset --hard) unless explicitly asked.
  • Follow the planning tool guidance: skip it for trivial fixes, but provide multi-step plans for non-trivial work and keep the plan updated as steps progress.
  • Validate changes by running the relevant ruff/pytest/bun test commands whenever feasible, and describe any unrun checks with follow-up guidance.
  • For Codex and other fresh-shell automation, prefer ./scripts/test.sh instead of bare pytest; the script falls back through PYTHON, the active virtualenv, uv, .venv, and venv before trying python or python3.
  • For setup workflow changes, prefer make env-* targets over calling scripts/setup/setup.sh directly; the Makefile resolves a Bash 4+ interpreter for macOS/Linux compatibility.
  • When editing setup logic, keep .env host-usable and treat docker-compose.final.yml as generated output assembled from scripts/setup/templates/*.yml; compose-only overrides belong in the wizard-managed compose layer rather than being persisted back into .env.