RE-Tab: Reward-Enhanced Tabular Agent

A plug-and-play framework that architecturally enforces world model reasoning via lightweight, training-free reward modeling during State Transition and Simulative Reasoning.

Contents

• main.py - Unified CLI entry point for TableQA agents.
• sample_datasets - sample datasets containing five TableQAs extracted from WikiTQ, MMQA and MMTU for reproducibility. For full access, please visit the original repositories.
• scripts/ - Agent runners:
  • cot_script.py - Chain-of-Table agent.
  • tot_script.py - Tree-of-Table agent.
• tools/ - Shared toolset:
  • tools.py - Pydantic-typed tool definitions that emit executable code snippets for tabular transforms.
  • tools_def.py - Helper functions used by the tools (e.g., wrappers around Pandas transforms).
  • shared_utils.py - Shared helpers (TabROUGE constants, normalization, metrics).
• requirements.txt - Python dependencies.
• __init__.py - Package marker.

Motivation

Workflow Overview

Setup

python -m venv .venv
source .venv/bin/activate  # or .venv\\Scripts\\activate on Windows
pip install -r requirements.txt

Environment variables:

• OPENAI_API_KEY for OpenAI-hosted models.
• Optional local Ollama endpoints if you use those backends in tot_script.py.

Running the agents

python main.py cot --dataset-path ./sample_datasets/mmqa --n-samples 1 --llm gpt-4.1-nano --state-transition-reward
python main.py tot --dataset-path ./sample_datasets/mmqa --n-samples 1 --llm gpt-4.1-nano --state-transition-reward --use-tree-of-table

Key flags (see --help):

• --dataset-path : folder containing dataset files.
• --n-samples : how many questions to run.
• --llm : choose a model from the predefined configs.
• --save-conversation : persist runs to JSON for later analysis.
• --state-transition-reward with --rouge-window 3 --rouge-eps 0.005 : enable TabROUGE-based early stopping when the table/text match stabilizes.

Development tips

• Tools generate Python code executed by tablegpt IPython tool; keep transformations idempotent and safe.
• Use python -m py_compile RE_Tab/*.py to sanity-check syntax before committing.
• Add new tools by defining a Pydantic schema + BaseTool subclass in tools.py and referencing them in ENHANCED_MODULAR_TOOLS.