Add semantic-layer agent: SMQ compiler and semantic analysis strategy

[Copilot]

Reproduces the semantic-layer-mediated NL2SQL agent from the paper. Semantic models and joins are defined explicitly. A deterministic compiler turns Semantic Model Queries (SMQ) into trusted SQL, and a constrained Think–Act loop composes the final query from that SQL. direct and loop are unchanged, so the three can be compared.

ava.semantic({
  models: [{
    name: 'orders', table: 'orders',
    dimensions: [{ name: 'channel', column: 'channel' }, { name: 'status', column: 'status' }],
    measures: [{ name: 'revenue', agg: 'sum', column: 'amount' }],
  }],
  joins: [], // { from, to, keys: [{ from, to }], type?: 'left' | 'inner' }
});

// Pure and deterministic: no LLM, no DB
const { sql } = ava.compileSMQ({
  metrics: ['orders__revenue'],
  filters: ["orders__status = 'paid'"],
  group_by: ['orders__channel'],
});

await ava.analyze('Paid revenue by channel', { strategy: { type: 'semantic', maxSteps: 20 } });

• Semantic layer (src/semantic/)
  • Models are validated with zod. Elements are referenced as model__name. YAML is not supported; configs are an object or a JSON string.
  • JoinGraph finds the shortest join path between models (BFS) and orients the join keys along it.
  • SemanticRegistry.validateAgainstSchema checks at analyze time that every model's table exists in the engine schema.
• Compiler (compiler/)
  • compileSMQ supports metrics, filters, group_by, order_by and limit.
  • Filters use a small fixed grammar: comparisons, IN, LIKE, BETWEEN, IS NULL and AND/OR/NOT. Subqueries and ; are rejected.
  • Metric filters go to HAVING. Mixing dimensions and metrics in one filter is an error.
  • Dialects are pluggable (DuckDB, PostgreSQL, ClickHouse, MySQL, ANSI). The default is inferred from engine.language.name.
• semantic strategy (analysis/semantic.ts)
  • Each step is one JSON tool call: getModelDataElements, convertSmqToSql (with a 5-row preview) or execute.
  • execute is terminal and runs at most once. A failed run is not retried.
  • execute is rejected, without running, if no SMQ has compiled successfully yet, or if the final SQL uses a table that no compiled SMQ introduced.
  • maxSteps defaults to 20. A last-step hint tells the model to execute.
  • Compile and protocol errors are fed back to the model as observations.
• API and wiring
  • AVA.semantic(), AVA.compileSMQ(), semantic on AnalysisRuntime, the strategy union entry and the exported types.
  • The README has a short section on the new strategy.

For review

• Tool calls: the tool calls use a JSON text protocol through generateText, not native AI SDK tool calling. This keeps one call per step and makes the loop easy to mock. I can switch to native tools if you prefer.
• Table check: the "only compiled tables" check is a textual scan of FROM/JOIN names. It handles CTEs and EXTRACT(… FROM …) but is not a SQL parser.
• Join fan-out: metrics aggregated across a one-to-many join can be double-counted. There is no guard yet.
• Not included: the CLI and the eval harness don't expose semantic, and there is no real-LLM accuracy comparison against direct/loop yet.

[github-actions]

✅ Preview is ready!

	✅ Ready
	🔗 Preview https://antvis-AVA-preview-pr-1026.surge.sh
	📝 Commit	5750455
	⏱️ Build time	0.01s
	📦 Size	9.6 MB (+188.5 KB ⬆️) · 171 files
	🪵 Logs	View logs
	📱 Mobile

_{↩️ Previous: ⚡️ 5750455 · antvis-AVA-preview-pr-1026.surge.sh (open ↗) · 2026-10-20 09:20:05 UTC}

_{🤖 Powered by surge-preview}