How gradiant/mrt_tableqa works
Project type and purpose
• This is an open-source Python CLI/tool (Table-QA) for question answering over tabular data (SemEval 2025 DataBench challenge).
• It ingests tables (datasets), formulates prompts, invokes LLMs (via OpenAI), processes and formats model outputs into answers or reports.
File structure
• Top-level:
• tqa/ → main package
• tests/ → unit and system tests
• docs/ → developer guides (external config, hooks)
• Dockerfile, Makefile, pyproject.toml, .env.example, etc.
• Under tqa/:
• tqa/cli → (implied) CLI entrypoints
• tqa/coder/ → “adapter” for QA flows
• controllers/ → parse CLI args into use-case calls
• usecases/ → orchestrate domain services
• domain/services/ → business-logic operations (descriptor, interpreter, formatter, reporter)
• domain/entities/ → DTOs (ColumnDescriptor, QA context, etc.)
• tqa/common/ → shared framework
• configuration/ → Pydantic settings, logger setup
• domain/services → abstractions (Parser, Evaluator, Reporter, InferenceService)
• infrastructure/ → I/O implementations (OpenAI engine, Postgres engine, abstract repo)
• usecases/ → base classes for commands
• Configuration and deployment: .env, Dockerfile, docker-compose in tools/docker, Makefile for CI, pdm for dependencies.
Key architectural patterns
• Clean/Hexagonal (Ports & Adapters)
• Adapters: CLI controllers, infrastructure (OpenAI, Postgres)
• Ports: common domain service interfaces
• Core: use-cases and domain services
• Layered domain: Entities → Services → Use-cases → Controllers
• Dependency inversion: use-cases depend on abstract services, implementations injected via config.
Main components & interactions
• CLI Layer (tqa.cli)
→ Controller(s): parse user commands (e.g., process_table, run_benchmark)
→ Invoke appropriate Use-case
• Use-case Layer (tqa.coder/usecases & tqa.common/usecases)
→ Coordinates multiple domain services (e.g., ColumnDescriptorService, InterpreterUsecase, FormatterUsecase, ReporterUsecase)
• Domain Service Layer (tqa.coder/domain/services & tqa.common/domain/services)
→ Encapsulate single operations (prompt building, output parsing, evaluation)
→ They call external adapters
• Infrastructure Adapters (tqa.common/infrastructure)
→ OpenAI engine (abstract_engine → calls OpenAI API)
→ PostgresEngine (optional DB persistence)
• Configuration & Logging (tqa.common/configuration)
→ Pydantic Settings loaded from .env
→ YAML-driven logger
• External Dependencies
→ OpenAI API (for LLM calls)
→ File System (for reading/writing JSON outputs)
→ Docker/Compose for containerized deployment