简体中文 · English

TableRAG

Turn Excel and CSV folders into a traceable, read-only knowledge layer for AI.

TableRAG turns folders of .xls, .xlsx, .xlsm, and .csv files into a local semantic catalog. It preserves exact spreadsheet records in DuckDB, discovers fields, rules, and cross-table relationships, and exposes deterministic read-only queries through MCP, CLI, and a local Web workbench.

No model or embedding provider is required. Project paths, workbook conventions, and reviewed domain knowledge stay in YAML instead of being hard-coded into the Python package.

Quick start · How it works · AI onboarding · Configuration · Security

Why TableRAG

Spreadsheet problem	TableRAG behavior
AI repeatedly opens and reparses large workbook folders	Incremental SHA-256 indexing keeps a reusable local catalog
Header rows and field meanings vary between files	Automatic detection plus explicit, reviewable per-Sheet layouts
Search results lose their source context	Results retain workbook, Sheet, row, column, and cell evidence
Similar field names imply unreliable relationships	Candidate and human-verified relations remain separate
Branch switches mix incompatible configuration data	Optional branch-isolated DuckDB catalogs
Source files contain sensitive business data	Source spreadsheets stay local and are never modified by TableRAG

What you get

• Exact record lookup, field filtering, table discovery, rule search, and relation traversal.
• One evidence-backed search across schemas, annotations, rules, relations, and records.
• Candidate primary-key validation instead of assuming the first column is unique.
• Explicit and inferred rules kept separate with confidence and cell-level evidence.
• Configurable semantic rows for field names, Chinese notes, English descriptions, types, and project metadata.
• Formal-name localization from a configured folder or an auto-discovered strings/cn folder.
• Near-real-time debounced updates after Excel or WPS saves, with one serialized index writer.
• Human-reviewed, field-scoped knowledge with candidate, verified, and deprecated states.
• Local MCP over stdio, Streamable HTTP, or legacy SSE.
• A guided localhost Web workbench for scope confirmation, spreadsheet preview, layout repair, diagnostics, knowledge review, and builds.

How it works

flowchart LR
    A["Spreadsheet folders"] --> B["Scope and layout rules"]
    B --> C["Parser and diagnostics"]
    C --> D["DuckDB semantic catalog"]
    K["Reviewed project knowledge"] --> D
    D --> E["CLI"]
    D --> F["Read-only MCP"]
    D --> G["Local Web workbench"]
    F --> H["AI clients"]

The catalog stores normalized records, schema metadata, rules, relations, localization, and searchable semantic documents. Every retrieval path points back to source evidence; TableRAG does not write to the source spreadsheets.

Quick start

Requires Python 3.10+ and uv.

On Windows, double-click start.bat to open the local setup workbench, or run:

cd C:\path\to\TableRAG
uv sync --extra dev
uv run table-rag init C:\path\to\spreadsheet-folder `
  --output projects\my-project.local.yaml `
  --name "My Project"
uv run table-rag web --project projects\my-project.local.yaml

In the Web workbench:

1. Confirm source folders, file types, recursion, included Sheets, and excluded columns.
2. Preview a workbook and confirm or repair its semantic-row layout.
3. Resolve blocking diagnostics so malformed tables cannot enter the active catalog.
4. Build the index and copy the generated MCP configuration.

For intentional automation, use the CLI directly:

uv run table-rag build --project projects\my-project.local.yaml
uv run table-rag doctor --project projects\my-project.local.yaml
uv run table-rag query --project projects\my-project.local.yaml --table item --id 1001
uv run table-rag rag --project projects\my-project.local.yaml --query "Find the item fields and records"
uv run table-rag watch --project projects\my-project.local.yaml

Local project files use the .local.yaml suffix and are ignored by Git.

Connect an AI client

Local desktop clients should prefer stdio:

{
  "mcpServers": {
    "TableRAG": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\TableRAG",
        "run",
        "table-rag",
        "mcp",
        "--project",
        "C:\\path\\to\\TableRAG\\projects\\my-project.local.yaml",
        "--transport",
        "stdio"
      ]
    }
  }
}

For local Streamable HTTP:

uv run table-rag mcp `
  --project projects\my-project.local.yaml `
  --transport streamable-http `
  --host 127.0.0.1 `
  --port 8765

The endpoint is http://127.0.0.1:8765/mcp. Keep it on localhost unless authentication, TLS, and an explicit network policy are configured externally. See AI onboarding for the full handoff, verification, and routing workflow.

Query surface

Purpose	MCP tools
Project and schema discovery	get_project, list_tables, find_tables, describe_table, describe_column
Exact records	get_record, get_records_by_field, search_records
Semantic retrieval	search_knowledge, search_project_knowledge, search_rules
Relations and explanations	trace_relations, get_field_knowledge, explain_record

All tools are read-only. Rules report whether they are explicit or inferred and include confidence and source evidence such as orders.xlsx#Sheet1!F1.

Safety model

• Source spreadsheets are read-only inputs; TableRAG never edits them.
• Local project YAML, DuckDB catalogs, generated reports, and build artifacts are ignored by Git.
• The Web workbench binds to localhost and restricts preview paths to the confirmed source scope.
• Explicit spreadsheet rules, human-reviewed knowledge, and statistical inferences remain distinguishable.
• Verified relations are checked against the current branch catalog before becoming normal search knowledge.

Review SECURITY.md before exposing an MCP endpoint or sharing a repository snapshot.

Documentation

Guide	Use it for
AI onboarding	Copy-ready MCP configuration, verification, and query routing
Configuration reference	Sources, layouts, localization, branches, watchers, and project knowledge
Contributing	Development setup, tests, pull requests, and data-safety rules
Security	Private reporting and deployment boundaries

Development

uv sync --extra dev --locked
uv run pytest
uv build
uv run python scripts\check_repository_secrets.py --include-untracked

The default VS Code build task runs the test suite and builds the wheel. CI covers supported Python versions on Windows and Linux.

License

Apache License 2.0