# antgroup/agentar-scale-sql architecture

> Architecture diagram of the GitHub repository antgroup/agentar-scale-sql, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/antgroup/agentar-scale-sql
- Repository: https://github.com/antgroup/agentar-scale-sql

## Overview

##### Project type and purpose
- Agentar-Scale-SQL is an open-source research framework (Text-to-SQL tool) that orchestrates multiple model perspectives at test-time to boost execution accuracy on SQL benchmarks. Its core purpose is to manage pipelines for generating, ranking, and selecting SQL queries given a natural-language question and a database schema.

##### File structure
- At present, the repo only lists README.md and LEGAL.md. However, the README outlines planned code modules:
- Light schema engine
- Offline data preprocessing pipeline
- Task understanding & SQL candidate generation (with closed-source models)
- SQL candidate generation (with fine-tuned open models)
- SQL selection/ranking module

##### README for additional insights
- The README describes an “Orchestrated Test-Time Scaling” strategy that combines three perspectives (e.g., zero-shot, few-shot, fine-tuned) into one execution pipeline.
- Dependencies will include Hugging Face and ModelScope model repositories, a scheduler/orchestrator, and a target SQL execution engine (e.g., SQLite or a real RDBMS for validation).

a. Main components
- User Interface or API Layer: accepts NL questions + schema metadata
- Schema Engine: parses/exposes DB schema to downstream modules
- Orchestrator: central coordinator that spins up multiple model calls
- Model Pods (3 perspectives):
– Closed-source LLM service (e.g., OpenAI API)
– Fine-tuned open model (Hugging Face/ModelScope)
– Possibly a retrieval-enhanced or few-shot LLM service
- SQL Candidate Aggregator & Filter: collates and deduplicates queries
- SQL Selection/Ranking Module: reranks candidates and picks top query
- Execution Engine: runs chosen SQL against a live or sandboxed database
- Monitoring & Metrics: logs performance, accuracy, and resource usage

b. Relationships & data flow
1. Client → API Layer
2. API Layer → Schema Engine (retrieve schema)
3. Orchestrator triggers parallel calls to each Model Pod, passing NL prompt + schema context
4. Model Pods → SQL Candidate Aggregator
5. Aggregator → Selection Module
6. Selection → Execution Engine
7. Execution result → API Layer → Client
8. Monitoring collects logs at each stage

c. Architectural patterns & principles
- Pipeline orchestration (fan-out / fan-in)
- Microservices for each model perspective
- Modular separation: preprocessing, inference, post-processing, execution
- Scalability: each Model Pod can autoscale horizontally
- Observability: centralized logging and metrics

d. Key technologies & frameworks
- Orchestrator: Airflow, Luigi, or custom scheduler
- Models: Hugging Face Transformers, ModelScope, Closed-source APIs
- Database: SQLite / Postgres for execution and validation
- Monitoring: Prometheus + Grafana or MLflow
- Containerization: Docker + Kubernetes for model services

##### Elements
– Blue for API / orchestration components
– Green for model inference services
– Orange for data engines (schema, DB)
– Gray for monitoring/logging

##### Final advice
- Every planned module as an independent component, even if code isn’t released yet.
- Make the orchestration pattern (fan-out/fan-in) very explicit.
- Tech stacks (e.g., “Hugging Face Transformers”, “Kubernetes Service”) next to each component.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User Interaction"
        Client["Client"]:::api
        API["API Layer<br/>(Receives NL Query)"]:::api
    end

    Client --> API

    subgraph "Schema & Preprocessing"
        Schema["Schema Engine<br/>(Parses DB schema)"]:::data
    end

    API --> Schema

    subgraph "Orchestration"
        Orchestrator["Orchestrator<br/>(Airflow/Luigi)"]:::api
    end

    Schema --> Orchestrator

    subgraph "Model Inference (Fan-out)"
        A["Closed-Source LLM Service<br/>(OpenAI API)"]:::inference
        B["Fine-Tuned Open Model<br/>(Hugging Face)"]:::inference
        C["Few-Shot LLM Service"]:::inference
    end

    Orchestrator --> A
    Orchestrator --> B
    Orchestrator --> C

    subgraph "Aggregation & Selection"
        Aggregator["SQL Candidate Aggregator"]:::api
        Selector["SQL Selection & Ranking Module"]:::api
    end

    A --> Aggregator
    B --> Aggregator
    C --> Aggregator
    Aggregator --> Selector

    subgraph "Execution & Data"
        ExecDB["Execution Engine<br/>(SQLite/Postgres)"]:::data
    end

    Selector --> ExecDB
    ExecDB --> API

    subgraph "Monitoring & Metrics"
        Monitor["Monitoring & Metrics<br/>(Prometheus/Grafana)"]:::monitor
    end

    API -->|logs| Monitor
    Schema -->|logs| Monitor
    Orchestrator -->|logs| Monitor
    A -->|logs| Monitor
    B -->|logs| Monitor
    C -->|logs| Monitor
    Aggregator -->|logs| Monitor
    Selector -->|logs| Monitor
    ExecDB -->|logs| Monitor

    Doc["Project Documentation / Overview"]:::api
    Lic["License Information"]:::api

    Doc --> Lic

    click Doc "https://github.com/antgroup/agentar-scale-sql/blob/main/README.md"
    click Lic "https://github.com/antgroup/agentar-scale-sql/blob/main/LEGAL.md"

    classDef api fill:#D0E8FF,stroke:#0288D1,color:#000
    classDef inference fill:#E0F7DA,stroke:#43A047,color:#000
    classDef data fill:#FFE0B2,stroke:#FB8C00,color:#000
    classDef monitor fill:#ECEFF1,stroke:#607D8B,color:#000
```
