Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
79 lines (60 loc) · 2.99 KB

ARCHITECTURE.md

File metadata and controls

79 lines (60 loc) · 2.99 KB

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
  1. Validation and quality plane
  • structural and schema-aware checks
  • syntax highlighting and annotation support
  • confidence scoring and explainability helpers
  1. 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