Module aql Architecture

Navigation: Home > Modules

Architecture - AQL Module

Overview

The AQL module composes assistance-oriented components around AQL authoring and LLM-augmented workflows. It sits beside the core query execution stack and focuses on generation quality, validation confidence, and developer/operator support surfaces.

Main Execution Planes

1. Translation and command plane

• NL-to-AQL and LLM command orchestration
• integration with model/provider-facing paths

2. Validation and quality plane

• structural and schema-aware checks
• syntax highlighting and annotation support
• confidence scoring and explainability helpers

3. Context and tooling plane

• conversation context and few-shot retrieval
• template/query-builder and assistant utility paths
• agent and bridge utilities for composed workflows

Core Contracts

Contract	Behavior
translation interfaces	transform NL and command inputs into AQL-oriented outputs
validation interfaces	enforce structural/schema checks and issue reporting
context/scoring interfaces	manage quality signals and bounded conversation state
tooling interfaces	expose helper utilities for docs, templates, and orchestration

Integration with Query Module (src/query/)

This module is intentionally layered on top of the core Query Engine. It depends on but is not depended upon:

Dependency:

src/aql/ (LLM Assistance)
    └─→ calls AQLParserService::parse() [from src/query/]
    └─→ reads FunctionRegistry [from src/query/]
    └─→ uses QueryOptimizer::estimateCost() [from src/query/]

src/query/ (Query Engine)
    └─→ NEVER imports from src/aql/

Validation Pipeline: When LLM generates candidate AQL (in llm_aql_handler.cpp):

1. Generate NL→AQL via LLM client
2. Call AQLParserService::parse(aql_string) → validate syntax (NEW)
3. On failure: attempt retry with corrective feedback (max 1×)
4. Return only validated AQL to user
5. Emit metrics to Prometheus

For Details: See src/query/AQL_LLM_INTEGRATION_CONTRACT.md (canonical integration specification)

Failure Semantics

• malformed or unsupported flows return structured errors rather than silent acceptance.
• validation/highlighting/scoring stages provide bounded diagnostics surfaces.
• capability-dependent flows degrade through explicit fallback behavior paths.

Sourcecode Verification (Module: aql/architecture)

• Verified files:
  • src/aql/llm_aql_handler.cpp
  • src/aql/aql_query_validator.cpp
  • src/aql/aql_query_builder.cpp
  • src/aql/aql_syntax_highlighter.cpp
  • src/aql/aql_confidence_scorer.cpp
  • src/aql/aql_conversation_context.cpp
  • src/aql/aql_fewshot_example_library.cpp
• Verified architecture claims:
  • separation of translation, validation, and tooling planes
  • dedicated quality/diagnostic helper surfaces
  • capability-sensitive integration behavior in assistance paths

---

Direct Downstream Consumers (modules that use this module)

Module	Via	Notes
server	include/aql/llm_aql_handler.h, include/aql/llm_error_codes.h	HTTP LLM API endpoint dispatches NL→AQL requests through LLMAQLHandler (src/server/llm_api_handler.cpp)
query	include/aql/llm_query_context.h, include/aql/classify_bridge.h	LLMGenerateOperator uses LLM query context for in-plan generation; FunctionRegistry calls classify bridge for AQL classification (include/query/llm_generate_operator.h, src/query/functions/function_registry.cpp)
metadata	include/aql/aql_schema_provider.h	AQLSchemaBridge maps schema metadata into AQL-aware provider surfaces (include/metadata/aql_schema_bridge.h:16)
toolbox	include/aql/aql_ingestion_bridge.h	ToolboxBuilder uses AQL ingestion bridge for data-pipeline toolbox composition (src/toolbox/toolbox_builder.cpp)

---

ThemisDB 1.9.0-beta · Home · Module-Index · GitHub · Issues