# lian_ask_data

**Repository Path**: ppcirgo/lian_ask_data

## Basic Information

- **Project Name**: lian_ask_data
- **Description**: 一款现代化的智能问数应用。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2026-09-08
- **Last Updated**: 2026-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Harness, DataAgent

## README

# Lian Ask Data

## Project Introduction

Lian Ask Data is an intelligent data query system based on AI Agents, designed to help users complete data queries and analysis via natural language processing technology. The system adopts a Multi-Agent architecture, integrating multiple sub-agents such as intent recognition, query planning, metric calculation, and detail queries, achieving a complete closed loop from user questions to executable SQL.

## Core Features

- **Natural Language Query**: Users can describe data requirements using everyday language, and the system automatically converts them into structured queries.
- **Multi-Agent Collaboration**: Adopts the ReAct mode, utilizing multiple specialized sub-agents to collaborate on complex query tasks.
- **Metric & Detail Dual Engine**: Supports two modes: metric queries (aggregated statistics) and detail queries (detailed data).
- **Multi-SQL Dialect Support**: Built-in SQL dialect renderers for MySQL, PostgreSQL, DuckDB, etc.
- **Deterministic Compilation**: The query compilation process is deterministic, facilitating testing and verification.
- **Comprehensive Quality Check Mechanism**: Built-in query quality checks to ensure the correctness of output SQL.

## Tech Stack

- **Model Runtime**: Alibaba Cloud Qwen 3.6 27B
- **Development Language**: Java
- **Build Tool**: Maven
- **AI Framework**: AgentScope 2.x https://java.agentscope.io/v2/zh/docs/index.html#
- **SQL Rendering**: Supports MySQL, PostgreSQL, DuckDB

## Module Description

### ask_data_common

Public module providing core data structures and protocol definitions:

- **Condition Interface System**: Supports four condition types: AndCondition, OrCondition, NotCondition, LeafCondition, enabling flexible composition of structured WHERE clauses.
- **LianQL**: Unified query DSL, including definitions for metrics, filter conditions, sorting, time ranges, etc.
- **CompileResult**: Encapsulation of compilation results, containing SQL, error codes, error messages, etc.
- **Agent Protocol**: Defines agent interaction protocols such as Intent Decision (IntentDecision), DAG Plan (DagPlan), Question State (QuestionState), etc.

### ask_data_harness

Orchestration engine responsible for scheduling and collaboration among multi-agents:

- **AskOrchestrator**: Core orchestrator coordinating workflows of various sub-agents, handling retry and revision logic.
- **Sub-agent Interfaces**:
  - IntentClassifier (Intent Recognition): Determines user query type (metric/detail/clarification).
  - Planner (Query Planning): Generates query execution plans (DAG structure).
  - MetricAnswerer (Metric Answering): Handles aggregated statistical queries.
  - DetailAnswerer (Detail Answering): Handles detailed data queries.
  - QualityChecker (Quality Check): Verifies the correctness of query results.
- **Runtime**: DashScopeQwenModel, integration of Qwen models based on Alibaba Cloud DashScope.
- **Ontology Directory**: InMemoryOntologyDirectory, manages metadata for entities, fields, and metrics.

### ask_detail_engine

Detail query engine responsible for compiling DetailSpec into executable SQL:

- **DetailCompiler**: Core compiler implementing the conversion of query logic to SQL.
- **JoinPlanner**: Automatically plans multi-table join paths, supporting depth-controlled JOIN compilation.
- **ConditionRenderer**: Condition expression renderer supporting nested condition trees.
- **DialectRenderers**: SQL dialect renderers supporting MySQL, PostgreSQL, DuckDB.
- **Semantic Store**: DetailSemanticStore, manages table structures, foreign key relationships, and other metadata.

### ask_data_web

Web frontend interface providing a visual query interaction interface.

## Quick Start

### Environment Requirements

- JDK 17+
- Maven 3.6+
- Alibaba Cloud DashScope API Key (for calling Qwen models)

### Build Project

```bash
# Clone project
git clone https://gitee.com/ppcirgo/lian_ask_data.git
cd lian_ask_data

# Build all modules
mvn clean install -DskipTests

# Run tests
mvn test
```

### Configuration

The project root directory provides a `llm-config.example.yml` configuration template for setting model call parameters:

```yaml
llm:
  provider: DASH_SCOPE
  modelId: qwen-turbo
  baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1
  apiKey: ${DASHSCOPE_API_KEY}
```

### Example Code

```java
// Initialize Ontology Directory
OntologyDirectory directory = InMemoryOntologyDirectory.sampleDomain();

// Initialize components
IntentClassifier intentClassifier = new ReActIntentClassifier(model);
Planner planner = new ReActPlanner(model);
DetailAnswerer detailAnswerer = new RuleDetailAnswerer(compiler);
MetricAnswerer metricAnswerer = new StubMetricAnswerer();
QualityChecker qualityChecker = new SimpleQualityChecker();

// Create Orchestrator
AskOrchestrator orchestrator = new AskOrchestrator(
    intentClassifier, planner, 
    metricAnswerer, detailAnswerer, 
    qualityChecker
);

// Execute query
QuestionState state = QuestionState.of("Total number of orders in the last 30 days");
AskOutcome outcome = orchestrator.ask(state);

if (outcome instanceof AskOutcome.Compiled compiled) {
    System.out.println("Generated SQL: " + compiled.result().getSql());
}
```

## Query Syntax

### LianQL Structure

LianQL is a unified facade `record(queryType, spec)`, where `spec` is a `QuerySpec` (sealed interface implemented by `MetricSpec` / `DetailSpec`).

```java
// Metric query (AME): MetricSpec
MetricSpec metric = new MetricSpec(
    List.of("order_count", "total_amount"), // metrics
    List.of("order_date"),                  // groupBy
    List.of("status = 'COMPLETED'"),        // where (native metricflow boolean expression, mixed AND/OR)
    "2024-01-01", "2024-01-31",             // startTime / endTime (end is inclusive)
    List.of("-order_count"),                // orderBy
    100,                                    // limit
    0);                                     // offset (non-zero unsupported)
LianQL metricQL = new LianQL(QueryType.METRIC, metric);

// Detail query (ADE): DetailSpec
DetailSpec detail = new DetailSpec();
detail.setEntity("orders");
detail.setProject(List.of("orders.id", "customers.name"));
LianQL detailQL = new LianQL(QueryType.DETAIL, detail);
```

### Condition Structure

```java
// Single condition
LeafCondition condition = new LeafCondition("status", Operator.EQ, "COMPLETED");

// Composite condition
AndCondition andCondition = new AndCondition(List.of(
    new LeafCondition("amount", Operator.GT, 100),
    new LeafCondition("status", Operator.EQ, "PENDING")
));
```

## Testing Strategy

The project adopts a deterministic testing strategy to ensure the stability and consistency of compilation results:

- **Unit Tests**: Cover core functionality of each module.
- **Integration Tests**: Verify multi-agent collaboration workflows.
- **Compilation Deterministic Tests**: Ensure identical inputs produce identical outputs.

## Extension Guide

### Adding New SQL Dialects

1. Implement the `SqlDialectRenderer` interface.
2. Register the new dialect in `DialectRenderers`.
3. Add corresponding test cases.

### Adding New Query Types

1. Add the new type to the `QueryType` enum.
2. Implement the corresponding Answerer interface.
3. Add planning logic in the Planner.

## License

This project follows the license agreement specified in the [LICENSE](LICENSE) file.

## Contribution Guide

Issues and Pull Requests are welcome. Before submitting code, please ensure:

1. Follow the project coding standards.
2. Add sufficient test cases.
3. Update relevant documentation.

## Future Plans

- Support more data sources (ElasticSearch, MongoDB, etc.)
- Optimize query performance, support query caching.
- Enhance quality check capabilities, support more rules.
- Provide visual query plan display.