How antgroup/agentar-scale-sql works
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.