Contributing to TableRAG

Thank you for improving TableRAG. Changes should preserve its project-agnostic, read-only boundary and remain verifiable without access to private spreadsheet data.

Development setup

Requires Python 3.10+ and uv.

git clone https://github.com/BitDG/TableRAG.git
cd TableRAG
uv sync --extra dev --locked
uv run pytest

Build the distributable wheel with:

uv build

Pull requests

1. Keep each pull request focused on one coherent change.
2. Add or update tests for behavior changes.
3. Run the full test suite and repository safety scan before pushing.
4. Explain the user impact and verification boundary in the pull request description.
5. Keep source changes, generated packages, and runtime verification distinct.

uv run pytest
uv build
uv run python scripts\check_repository_secrets.py --include-untracked

Data-safety rules

Do not commit:

• Real spreadsheets, exported CSV files, or generated DuckDB catalogs.
• projects/*.local.yaml files or machine-specific absolute paths.
• Credentials, access tokens, Webhooks, private keys, or private contact information.
• Project-specific commercial rules unless the repository owner has explicitly approved them.

Tests should create small synthetic workbooks in temporary directories. Examples should use neutral paths such as C:\path\to\TableRAG or D:/data/config.

Architecture boundary

The Python package provides project-agnostic parsing, indexing, diagnostics, retrieval, MCP, and Web workflows. Workbook naming conventions, semantic layouts, relation knowledge, and source paths belong in YAML or separately reviewed rule packages.

TableRAG does not write source spreadsheets. A proposed mutation feature should be implemented behind a separate governed product boundary rather than added to the read-only MCP surface.