# gradiant/mrt_tableqa architecture

> Architecture diagram of the GitHub repository gradiant/mrt_tableqa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gradiant/mrt_tableqa
- Repository: https://github.com/gradiant/mrt_tableqa

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        Controller["CLI Controller"]:::cli
    end

    %% Use-case Layer
    subgraph "Use-case Layer"
        ColumnDescriptionUC["Column Description Use-case"]:::usecase
        FormatterUC["Formatter Use-case"]:::usecase
        InterpreterUC["Interpreter Use-case"]:::usecase
        OutputParseUC["Output Parsing Use-case"]:::usecase
        ProcessBatchesUC["Process Batches Use-case"]:::usecase
        ProcessTableUC["Process Single Table Use-case"]:::usecase
        QAUsecase["QA Flow Use-case"]:::usecase
        ReportUsecase["Reporting Use-case"]:::usecase
        BaseUC["Base Use-case"]:::usecase
    end

    %% Domain Services
    subgraph "Domain Services"
        ColumnDescriptorSvc["Column Descriptor Service"]:::domain
        OutputParseSvc["Output Parse Service"]:::domain
        ServiceAbstraction["Service Abstractions"]:::domain
    end

    subgraph "Ports (Common Interfaces)"
        ParserIF["Parser Interface"]:::domain
        EvaluatorIF["Evaluator Interface"]:::domain
        InferenceIF["Inference Service Interface"]:::domain
        ReporterIF["Reporter Interface"]:::domain
        GenericServiceIF["Generic Service Interface"]:::domain
        CoderParserIF["Coder Parser Service Interface"]:::domain
    end

    %% Infrastructure Adapters
    subgraph "Infrastructure Adapters"
        AbstractEngine["Abstract Engine (LLM Adapter)"]:::infra
        AbstractRepo["Abstract Repository"]:::infra
        PostgresEngine["Postgres Engine (Optional)"]:::infra
    end

    %% Configuration & Logging
    subgraph "Configuration & Logging"
        ConfigPydantic["Pydantic Settings"]:::config
        LoggerSetup["Logger Setup"]:::config
    end

    %% External Systems
    subgraph "External Systems"
        OpenAIAPI["OpenAI API"]:::external
        FileSystem["File System I/O"]:::external
        PostgresDB["Postgres Database"]:::external
    end

    %% Connections
    Controller -->|"invokes"| ProcessTableUC
    Controller -->|"invokes"| QAUsecase
    Controller -->|"invokes"| ReportUsecase

    ProcessTableUC -->|"uses"| ColumnDescriptorSvc
    ProcessTableUC -->|"uses"| OutputParseSvc
    ProcessTableUC -->|"uses"| ServiceAbstraction

    QAUsecase -->|"uses"| InterpreterUC
    QAUsecase -->|"uses"| FormatterUC
    QAUsecase -->|"uses"| OutputParseSvc

    ColumnDescriptorSvc -->|"calls"| AbstractEngine
    OutputParseSvc -->|"calls"| AbstractEngine

    AbstractEngine -->|"requests"| OpenAIAPI
    OpenAIAPI -->|"response"| AbstractEngine

    AbstractEngine -->|"returns"| ColumnDescriptorSvc
    AbstractEngine -->|"returns"| OutputParseSvc

    ProcessTableUC -->|"aggregates"| ReportUsecase
    ReportUsecase -->|"outputs"| FileSystem
    ReportUsecase -->|"outputs"| Controller

    AbstractRepo -->|"connects"| PostgresDB
    ServiceAbstraction -->|"depends on"| AbstractRepo

    ConfigPydantic -->|"provides config to"| Controller
    ConfigPydantic -->|"provides config to"| AbstractEngine

    LoggerSetup -->|"provides logger to"| Controller
    LoggerSetup -->|"provides logger to"| AbstractEngine

    %% Click Events
    click Controller "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/coder/controllers/controller.py"
    click ColumnDescriptionUC "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/coder/usecases/column_description_usecase.py"
    click FormatterUC "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/coder/usecases/formatter_usecase.py"
    click InterpreterUC "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/coder/usecases/interpreter_usecase.py"
    click OutputParseUC "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/coder/usecases/output_parse_uc.py"
    click ProcessBatchesUC "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/coder/usecases/process_batches_usecase.py"
    click ProcessTableUC "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/coder/usecases/process_table_usecase.py"
    click QAUsecase "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/coder/usecases/qa_usecase.py"
    click ReportUsecase "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/coder/usecases/report_usecase.py"
    click BaseUC "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/common/usecases/base.py"
    click ColumnDescriptorSvc "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/coder/domain/services/column_descriptor_service.py"
    click OutputParseSvc "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/coder/domain/services/output_parse_service.py"
    click ServiceAbstraction "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/coder/domain/services/service.py"
    click ParserIF "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/common/domain/services/Parser.py"
    click EvaluatorIF "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/common/domain/services/Evaluator.py"
    click InferenceIF "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/common/domain/services/InferenceService.py"
    click ReporterIF "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/common/domain/services/Reporter.py"
    click GenericServiceIF "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/common/domain/services/Service.py"
    click CoderParserIF "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/common/domain/services/CoderParserService.py"
    click AbstractEngine "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/common/infrastructure/abstract_engine.py"
    click AbstractRepo "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/common/infrastructure/abstract_repository.py"
    click PostgresEngine "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/common/infrastructure/postgres_engine.py"
    click ConfigPydantic "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/common/configuration/config.py"
    click LoggerSetup "https://github.com/gradiant/mrt_tableqa/blob/master/tqa/common/configuration/logger.py"

    %% Styles
    classDef cli fill:#E0F7FA,stroke:#0288D1
    classDef usecase fill:#C8E6C9,stroke:#388E3C
    classDef domain fill:#FFF9C4,stroke:#FBC02D
    classDef infra fill:#FFE0B2,stroke:#F57C00
    classDef external fill:#CFD8DC,stroke:#455A64
    classDef config fill:#E1BEE7,stroke:#8E24AA
```
