aetherdialect 0.1.0__py3-none-any.whl

text2sql/qsim_ops.py

@@ -0,0 +1,1286 @@
+"""LLM operations and question generation for the question-generation simulator.
+
+Provides LLM-based intent filling from structural skeletons, response parsing into ``QSimIntent`` structures, NL question generation, stratified adaptive skeleton selection with coverage guarantees, and intent normalisation utilities.
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Any
+
+from .config import (
+    AGG_PATTERN,
+    TABLE_COL_PATTERN,
+    VALID_FILTER_VALUE_TYPES,
+    VALID_HAVING_OPS,
+    VALID_HAVING_VALUE_TYPES,
+    PolicyConfig,
+    QSimConfig,
+)
+from .contracts_base import QSimSkeleton, RetryFailureContext, SchemaGraph, SkeletonPool
+from .contracts_core import QSimFilter, QSimHaving, QSimIntent
+from .core_utils import debug, llm_json
+from .qsim_struct import (
+    build_fk_adjacency,
+    build_schema_context,
+    compute_intent_id,
+    decompose_between_filter,
+    enumerate_table_sets,
+    generate_all_skeletons,
+    get_aggregatable_columns,
+    get_comparable_column_pairs,
+    get_filterable_columns,
+    get_groupable_columns,
+    is_connected,
+    load_or_create_skeletons,
+    validate_column_exists,
+)
+from .utils import generate_question
+
+_QSIM_FILL_SYSTEM = (
+    "You are a SQL intent generator."
+    " Given structural skeleton constraints, generate a valid query intent filling in specific columns and filters from the available schema."
+    " Rules:"
+    " 1. STRICTLY follow skeleton constraints for tables, aggregation presence, filter count, groupby count, having, orderby."
+    " 2. Use ONLY columns from the provided schema in the specified tables."
+    " 3. For filters, choose columns with meaningful filter potential (status, category, date columns)."
+    " 4. For aggregation, use COUNT/SUM/AVG/MIN/MAX wrapping table.column in select_cols; aggregate numeric columns only (not IDs or foreign keys); COUNT may use any column or *."
+    " 5. For groupby, choose categorical or temporal columns that make semantic sense."
+    " 6. Ensure all column references use table.column format from the specified tables."
+    " 7. Return ONLY valid JSON matching the specified format."
+    " 8. For expr_comparison (filter expr-vs-expr), both expressions must be from different tables with compatible types."
+    " 9. DISTINCT is only valid for non-aggregated queries."
+    " 10. For orderby, include ASC or DESC direction suffix."
+    " 11. DO NOT return columns or tables not in the provided schema."
+    " 12. For having, expression must be an aggregation matching a select_cols aggregation."
+)
+
+
+def _has_aggregation(select_cols: list[str]) -> bool:
+    """Return whether any element of *select_cols* is an aggregation expression.
+
+    Args:
+
+        select_cols: List of SQL select-column strings to inspect.
+
+    Returns:
+
+        ``True`` if at least one string matches the aggregation pattern ``AGG(...)``; ``False`` otherwise.
+    """
+    return any(AGG_PATTERN.match(sc) for sc in select_cols)
+
+
+def _extract_agg_info(expr: str) -> tuple[str, str] | None:
+    """Extract the aggregation function and inner column from an expression string.
+
+    Args:
+
+        expr: A SQL expression string such as ``"COUNT(table.col)"`` or ``"SUM(table.amount)"``.
+
+    Returns:
+
+        A 2-tuple ``(func, inner_column)`` with lowercase function name and the content inside the parentheses, or ``None`` if the expression does not match an aggregation pattern.
+    """
+    m = AGG_PATTERN.match(expr.strip())
+    if m:
+        return (m.group(1).lower(), m.group(2).strip())
+    return None
+
+
+def _extract_tables_from_expr(expr: str) -> set[str]:
+    """Extract all table names from a SQL expression containing ``table.column`` references.
+
+    Args:
+
+        expr: A SQL expression string that may contain one or more ``table.column`` tokens.
+
+    Returns:
+
+        Set of table name strings found in *expr*.
+    """
+    return {m.group(1) for m in TABLE_COL_PATTERN.finditer(expr)}
+
+
+def _validate_skeleton_constraints(response: dict[str, Any], skeleton: QSimSkeleton) -> tuple[bool, list[str]]:
+    """Validate an LLM response dict against the structural requirements of a skeleton.
+
+    Args:
+
+        response: Parsed LLM response dict with keys ``"select_cols"``, ``"filters"``, ``"groupby_cols"``, ``"having"``, ``"distinct"``, and ``"expr_comparison"``.
+        skeleton: The ``QSimSkeleton`` whose constraints the response must satisfy.
+
+    Returns:
+
+        A 2-tuple ``(is_valid, violations)`` where *is_valid* is ``True`` when all constraints are met and *violations* is a list of human-readable violation description strings.
+    """
+    violations = []
+
+    select_cols_raw = response.get("select_cols", [])
+    has_agg = any(AGG_PATTERN.match(sc) for sc in select_cols_raw if isinstance(sc, str))
+
+    if skeleton.has_aggregation and not has_agg:
+        violations.append("skeleton requires aggregation but no aggregated select_cols found")
+    if not skeleton.has_aggregation and has_agg:
+        violations.append("skeleton forbids aggregation but aggregated select_cols found")
+
+    filters = response.get("filters", [])
+    if skeleton.num_filters > 0 and len(filters) == 0 and not skeleton.has_expr_comparison:
+        violations.append(f"skeleton requires {skeleton.num_filters} filters but got 0")
+
+    groupby = response.get("groupby_cols", [])
+    if skeleton.num_groupby > 0 and len(groupby) == 0:
+        violations.append(f"skeleton requires {skeleton.num_groupby} groupby but got 0")
+    if skeleton.num_groupby == 0 and len(groupby) > 0:
+        violations.append(f"skeleton forbids groupby but got {len(groupby)}")
+
+    having = response.get("having", [])
+    if skeleton.has_having and len(having) == 0:
+        violations.append("skeleton requires having but got none")
+    if not skeleton.has_having and len(having) > 0:
+        violations.append(f"skeleton forbids having but got {len(having)}")
+
+    has_distinct = response.get("distinct", False)
+    if skeleton.has_distinct and not has_distinct:
+        violations.append(f"skeleton requires distinct but got distinct={has_distinct}")
+    if not skeleton.has_distinct and has_distinct:
+        violations.append(f"skeleton forbids distinct but got distinct={has_distinct}")
+
+    expr_comparison = response.get("expr_comparison") or response.get("column_comparison")
+    if skeleton.has_expr_comparison and not expr_comparison:
+        violations.append("skeleton requires expr_comparison but got none")
+
+    orderby_cols = response.get("orderby_cols", [])
+    if skeleton.has_orderby and len(orderby_cols) == 0:
+        violations.append("skeleton requires orderby but got none")
+    if not skeleton.has_orderby and len(orderby_cols) > 0:
+        violations.append("skeleton forbids orderby but got orderby_cols")
+
+    return (len(violations) == 0, violations)
+
+
+def _build_retry_guidance(failure_ctx: RetryFailureContext, schema: SchemaGraph, column_roles: dict[str, str]) -> str:
+    """Build a retry guidance string for the LLM based on a previous failure context.
+
+    Args:
+
+        failure_ctx: Context object describing the previous attempt's failure, including required/used/missing tables and attempt number.
+        schema: Schema graph used to suggest available columns for missing tables.
+        column_roles: Map of column key to role string (unused directly but available for future extensions).
+
+    Returns:
+
+        A formatted multi-line string to append to the LLM prompt directing it to correct the missing-table violation.
+    """
+    guidance_parts = []
+
+    guidance_parts.append(f"\n\n    RETRY GUIDANCE (Attempt {failure_ctx.attempt_number + 2}):")
+    guidance_parts.append(f"    Previous attempt failed: {failure_ctx.failure_type}")
+    guidance_parts.append(f"    Required tables: {failure_ctx.required_tables}")
+    guidance_parts.append(f"    Tables you used: {list(failure_ctx.used_tables)}")
+    guidance_parts.append(f"    Tables you MUST include: {list(failure_ctx.missing_tables)}")
+
+    for missing_table in failure_ctx.missing_tables:
+        table_ir = schema.tables.get(missing_table)
+        if table_ir:
+            cols = list(table_ir.columns.keys())[:5]
+            guidance_parts.append(f"    Available columns in {missing_table}: {cols}")
+
+    guidance_parts.append(
+        f"    FIX: Add filters, select_cols, groupby_cols, or aggregation from {list(failure_ctx.missing_tables)}"
+    )
+
+    return "\n".join(guidance_parts)
+
+
+def _llm_fill_intent(skeleton: QSimSkeleton, schema: SchemaGraph, column_roles: dict[str, str]) -> QSimIntent | None:
+    """Use the LLM to fill a structural skeleton with concrete column choices and filter values.
+
+    Builds a detailed prompt from skeleton constraints and schema context, calls the LLM via ``llm_json``, validates the response against skeleton constraints and column existence, and retries with progressive guidance on failure.
+
+    Args:
+
+        skeleton: The structural query skeleton defining table set, aggregation presence, filter count, GROUP BY count, and other constraints.
+        schema: Schema graph providing column metadata and FK relationships.
+        column_roles: Map of ``table.column`` key to column role string.
+
+    Returns:
+
+        A populated ``QSimIntent`` on success, or ``None`` if all retry attempts are exhausted.
+    """
+    context = build_schema_context(skeleton.tables, schema)
+
+    all_filterable = []
+    all_groupable = []
+    all_aggregatable = []
+    for table in skeleton.tables:
+        all_filterable.extend(get_filterable_columns(table, schema, column_roles))
+        all_groupable.extend(get_groupable_columns(table, schema, column_roles))
+        all_aggregatable.extend(get_aggregatable_columns(table, schema, column_roles))
+
+    filterable_list = [col_key for col_key, _ in all_filterable]
+
+    effective_filters = skeleton.num_filters
+    if skeleton.has_expr_comparison:
+        effective_filters = max(0, skeleton.num_filters - 1)
+
+    if skeleton.has_aggregation:
+        agg_instruction = (
+            "MUST include at least one aggregated select column (COUNT/SUM/AVG/MIN/MAX wrapping table.column)"
+        )
+    else:
+        agg_instruction = "NO aggregation - all select_cols must be plain table.column references"
+
+    filter_instruction = (
+        f"MUST include {skeleton.num_filters} filter conditions"
+        if skeleton.num_filters > 0
+        else "DO NOT include filters"
+    )
+    groupby_instruction = (
+        f"MUST include {skeleton.num_groupby} GROUP BY columns"
+        if skeleton.num_groupby > 0
+        else "DO NOT include GROUP BY"
+    )
+    orderby_instruction = (
+        "MUST include ORDER BY clause (non-empty orderby_cols)" if skeleton.has_orderby else "DO NOT include ORDER BY"
+    )
+
+    if skeleton.has_having:
+        having_instruction = (
+            "MUST include a HAVING condition with an aggregation expression. DO NOT return an empty having array."
+        )
+    else:
+        having_instruction = "DO NOT include HAVING"
+
+    distinct_instruction = "Use SELECT DISTINCT (no aggregations)" if skeleton.has_distinct else ""
+
+    expr_comparison_instruction = ""
+    comparable_pairs = []
+    if skeleton.has_expr_comparison:
+        comparable_pairs = get_comparable_column_pairs(skeleton.tables, schema, column_roles)
+        if comparable_pairs:
+            pairs_str = ", ".join([f"{t1}.{c1} vs {t2}.{c2}" for t1, c1, t2, c2, _ in comparable_pairs[:5]])
+            expr_comparison_instruction = (
+                f"MUST include an expr-vs-expr comparison (e.g., {pairs_str}). "
+                "Choose columns and operator that make logical sense. "
+                "DO NOT set expr_comparison to null."
+            )
+
+    filterable_constraint = (
+        f"\n        FILTERABLE COLUMNS (MUST use ONLY these for filters): {filterable_list}"
+        if effective_filters > 0
+        else ""
+    )
+    aggregatable_constraint = (
+        f"\n        AGGREGATABLE COLUMNS (use for SUM/AVG/MIN/MAX): {all_aggregatable}"
+        if skeleton.has_aggregation and all_aggregatable
+        else ""
+    )
+    groupable_constraint = (
+        f"\n        GROUPABLE COLUMNS (MUST use for GROUP BY): {all_groupable}" if skeleton.num_groupby > 0 else ""
+    )
+
+    optional_instructions = []
+    if distinct_instruction:
+        optional_instructions.append(distinct_instruction)
+    if expr_comparison_instruction:
+        optional_instructions.append(expr_comparison_instruction)
+    optional_str = "\n        - ".join([""] + optional_instructions) if optional_instructions else ""
+
+    user_prompt = f"""
+        Schema:
+        {context}
+        {filterable_constraint}{aggregatable_constraint}{groupable_constraint}
+
+        CRITICAL REQUIREMENTS (MUST follow exactly):
+        - Tables: {skeleton.tables}
+        - {agg_instruction}
+        - {filter_instruction}
+        - {groupby_instruction}
+        - {orderby_instruction}
+        - {having_instruction}{optional_str}
+
+        Return JSON:
+        {{
+        "select_cols": ["table.column" | "COUNT(table.column)" | "SUM(table.column)" | "AVG(table.column)" | "MIN(table.column)" | "MAX(table.column)", ...],
+        "filters": [{{"column": "table.column", "op": "=" | ">" | "<" | ">=" | "<=" | "!=" | "like" | "between" | "in" | "not in" | "is null" | "is not null", "value_type": "categorical" | "numeric_categorical" | "numeric" | "temporal" | "boolean" | "null"}}],
+        "groupby_cols": ["table.column", ...],
+        "orderby_cols": ["table.column ASC" | "table.column DESC" | "COUNT(table.column) DESC", ...],
+        "having": [{{"expression": "COUNT(table.column)" | "SUM(table.column)" | "AVG(table.column)" | "MIN(table.column)" | "MAX(table.column)", "op": "=" | "!=" | ">" | "<" | ">=" | "<=" | "in" | "not in" | "between", "value_type": "number" | "integer"}}],
+        "expr_comparison": {{"left_column": "table.column", "op": "=" | ">" | "<" | ">=" | "<=" | "!=", "right_column": "table.column"}} | null,
+        "distinct": true | false
+        }}
+    """
+
+    last_failure_reason = None
+    failure_context = None
+    for attempt in range(PolicyConfig.MAX_REPAIR_LOOPS):
+        prompt_with_context = user_prompt
+        if failure_context and attempt > 0:
+            retry_guidance = _build_retry_guidance(failure_context, schema, column_roles)
+            prompt_with_context = f"{user_prompt}{retry_guidance}"
+        elif last_failure_reason and attempt > 0:
+            prompt_with_context = f"{user_prompt}\n\n    PREVIOUS ATTEMPT FAILED: {last_failure_reason}\n    Please fix this issue in your response."
+
+        result = llm_json(_QSIM_FILL_SYSTEM, prompt_with_context, task="default")
+        if not result:
+            last_failure_reason = "LLM returned empty/null response"
+            failure_context = None
+            debug(
+                f"[qsim_ops.llm_fill_intent] attempt {attempt + 1}/{PolicyConfig.MAX_REPAIR_LOOPS} failed: {last_failure_reason} for skeleton tables={skeleton.tables}"
+            )
+            continue
+
+        debug(
+            f"[qsim_ops.llm_fill_intent] attempt {attempt + 1} LLM returned: select_cols={len(result.get('select_cols', []))}, filters_count={len(result.get('filters', []))}, groupby_count={len(result.get('groupby_cols', []))}, having_count={len(result.get('having', []))}, expr_comparison={result.get('expr_comparison') or result.get('column_comparison')}, distinct={result.get('distinct')}"
+        )
+
+        is_valid, violations = _validate_skeleton_constraints(result, skeleton)
+        if not is_valid:
+            last_failure_reason = "; ".join(violations)
+            failure_context = None
+            debug(
+                f"[qsim_ops.llm_fill_intent] attempt {attempt + 1}/{PolicyConfig.MAX_REPAIR_LOOPS} SKELETON_CONSTRAINT_VIOLATION: {violations}"
+            )
+            continue
+
+        parse_result = _parse_llm_response(result, skeleton, schema, column_roles)
+
+        if isinstance(parse_result, tuple) and len(parse_result) == 3:
+            failure_type, used_tables, missing_tables = parse_result
+            failure_context = RetryFailureContext(
+                failure_type=failure_type,
+                required_tables=skeleton.tables,
+                used_tables=used_tables,
+                missing_tables=missing_tables,
+                attempt_number=attempt,
+            )
+            last_failure_reason = None
+            debug(
+                f"[qsim_ops.llm_fill_intent] attempt {attempt + 1}/{PolicyConfig.MAX_REPAIR_LOOPS} failed: {failure_type} for skeleton tables={skeleton.tables}, missing={missing_tables}"
+            )
+            continue
+
+        if parse_result:
+            debug(
+                f"[qsim_ops.llm_fill_intent] SUCCESS: intent_id={parse_result.intent_id}, grain={parse_result.grain}, filters={len(parse_result.filters_param)}, groupby={len(parse_result.group_by_cols)}, distinct={parse_result.distinct}"
+            )
+            return parse_result
+
+        last_failure_reason = "Response validation failed (filters/columns rejected)"
+        failure_context = None
+        debug(
+            f"[qsim_ops.llm_fill_intent] attempt {attempt + 1}/{PolicyConfig.MAX_REPAIR_LOOPS} failed: parse_llm_response returned None for skeleton tables={skeleton.tables}, LLM response keys={list(result.keys())}"
+        )
+
+    debug(
+        f"[qsim_ops.llm_fill_intent] FINAL_FAILURE: exhausted {PolicyConfig.MAX_REPAIR_LOOPS} attempts for skeleton tables={skeleton.tables}, has_agg={skeleton.has_aggregation}, num_filters={skeleton.num_filters}"
+    )
+    return None
+
+
+def _parse_llm_response(
+    response: dict[str, Any],
+    skeleton: QSimSkeleton,
+    schema: SchemaGraph,
+    column_roles: dict[str, str],
+) -> Any | None:
+    """Parse an LLM response dict into a validated ``QSimIntent``.
+
+    Validates and normalises select columns, filters, GROUP BY, ORDER BY, HAVING, and expr comparisons against the skeleton constraints and schema.
+
+    Args:
+
+        response: Parsed LLM JSON response with intent fields.
+        skeleton: Skeleton whose constraints the response must satisfy.
+        schema: Schema graph for column existence and metadata checks.
+        column_roles: Map of ``table.column`` key to column role string.
+
+    Returns:
+
+        A ``QSimIntent`` on success; ``None`` if validation fails; or a 3-tuple ``(failure_type, used_tables, missing_tables)`` when a three-table coverage violation is detected (used as retry context).
+    """
+    select_cols_raw = response.get("select_cols", [])
+    filter_dicts = response.get("filters", [])
+    groupby_cols = response.get("groupby_cols", [])
+    orderby_cols_raw = response.get("orderby_cols", [])
+    having_dicts = response.get("having", [])
+    expr_comparison_dict = response.get("expr_comparison") or response.get("column_comparison")
+    has_distinct = response.get("distinct", False)
+
+    has_agg = _has_aggregation(select_cols_raw)
+
+    if skeleton.has_aggregation and not has_agg:
+        debug("[qsim_ops.parse_llm_response] REJECTED: skeleton requires aggregation but none in select_cols")
+        return None
+    if skeleton.num_filters > 0 and len(filter_dicts) == 0 and not skeleton.has_expr_comparison:
+        debug(
+            f"[qsim_ops.parse_llm_response] REJECTED: skeleton requires {skeleton.num_filters} filters but none provided"
+        )
+        return None
+    if skeleton.num_groupby > 0 and len(groupby_cols) == 0:
+        debug(
+            f"[qsim_ops.parse_llm_response] REJECTED: skeleton requires {skeleton.num_groupby} groupby cols but none provided"
+        )
+        return None
+
+    if skeleton.has_orderby and len(orderby_cols_raw) == 0:
+        debug("[qsim_ops.parse_llm_response] REJECTED: skeleton requires orderby but none provided")
+        return None
+    if not skeleton.has_orderby and len(orderby_cols_raw) > 0:
+        debug("[qsim_ops.parse_llm_response] REJECTED: skeleton forbids orderby but orderby_cols provided")
+        return None
+
+    if skeleton.has_distinct and skeleton.has_aggregation:
+        debug("[qsim_ops.parse_llm_response] REJECTED: DISTINCT not allowed with aggregation")
+        return None
+
+    select_cols: list[str] = []
+    for sc in select_cols_raw:
+        if not isinstance(sc, str) or not sc.strip():
+            continue
+        sc = sc.strip()
+        agg_info = _extract_agg_info(sc)
+        if agg_info:
+            agg_func, agg_inner = agg_info
+            if agg_inner != "*":
+                if not validate_column_exists(agg_inner, skeleton.tables, schema):
+                    debug(f"[qsim_ops.parse_llm_response] REJECTED_SELECT: {sc}, reason=agg_column_not_found")
+                    continue
+            select_cols.append(f"{agg_func.upper()}({agg_inner})")
+        else:
+            if not validate_column_exists(sc, skeleton.tables, schema):
+                debug(f"[qsim_ops.parse_llm_response] REJECTED_SELECT: {sc}, reason=column_not_found")
+                continue
+            select_cols.append(sc)
+
+    if not select_cols:
+        debug("[qsim_ops.parse_llm_response] REJECTED: no valid select_cols remaining")
+        return None
+
+    aggregated_tables: set[str] = set()
+    if has_agg and groupby_cols:
+        for gcol in groupby_cols:
+            if "." in gcol:
+                aggregated_tables.add(gcol.split(".")[0])
+
+    filters: list[QSimFilter] = []
+    filter_columns_used: set[str] = set()
+    for _filter_idx, fd in enumerate(filter_dicts):
+        col = fd.get("column", "")
+        if not validate_column_exists(col, skeleton.tables, schema):
+            debug(f"[qsim_ops.parse_llm_response] REJECTED_FILTER: col={col}, reason=column_not_found")
+            continue
+
+        table, col_name = col.split(".", 1)
+        col_meta = schema.tables[table].columns.get(col_name)
+        if not col_meta or not col_meta.is_filterable or not col_meta.is_usable:
+            debug(f"[qsim_ops.parse_llm_response] REJECTED_FILTER: col={col}, reason=not_filterable")
+            continue
+
+        if col not in filter_columns_used and len(filter_columns_used) >= QSimConfig.MAX_FILTER_COLUMNS + 1:
+            debug(
+                f"[qsim_ops.parse_llm_response] REJECTED_FILTER: col={col}, reason=max_filter_columns_exceeded (>{QSimConfig.MAX_FILTER_COLUMNS + 1})"
+            )
+            continue
+
+        if col not in filter_columns_used and len(filter_columns_used) >= QSimConfig.MAX_FILTER_COLUMNS:
+            debug(
+                f"[qsim_ops.parse_llm_response] WARNING_FILTER: col={col}, using {len(filter_columns_used) + 1} distinct columns (preferred max={QSimConfig.MAX_FILTER_COLUMNS})"
+            )
+
+        op = fd.get("op", "=")
+        valid_ops = col_meta.get_valid_filter_ops()
+
+        if op not in valid_ops:
+            debug(f"[qsim_ops.parse_llm_response] REJECTED_FILTER: col={col}, reason=invalid_operator_{op}_for_type")
+            continue
+
+        if has_agg and col_meta.is_foreign_key and op == "=":
+            fk_target_table = col_meta.fk_target[0] if col_meta.fk_target else None
+
+            if fk_target_table and fk_target_table in aggregated_tables:
+                debug(
+                    f"[qsim_ops.parse_llm_response] REJECTED_FILTER: col={col}, reason=circular_fk_to_aggregated_table"
+                )
+                continue
+
+            if table in aggregated_tables:
+                debug(
+                    f"[qsim_ops.parse_llm_response] REJECTED_FILTER: col={col}, reason=fk_filter_on_aggregated_source_table"
+                )
+                continue
+
+        value_type = fd.get("value_type", "categorical")
+        if op in ("is null", "is not null"):
+            value_type = "null"
+        elif value_type not in VALID_FILTER_VALUE_TYPES and value_type != "null":
+            value_type = "categorical"
+
+        filter_columns_used.add(col)
+
+        qf = QSimFilter(column=col, op=op, value_type=value_type)
+        if op == "between":
+            decomposed = decompose_between_filter(qf)
+            filters.extend(decomposed)
+            debug(f"[qsim_ops.parse_llm_response] DECOMPOSED_BETWEEN: col={col} into >= and <=")
+        else:
+            filters.append(qf)
+            debug(f"[qsim_ops.parse_llm_response] ACCEPTED_FILTER: col={col}, op={op}, value_type={value_type}")
+
+    if skeleton.has_expr_comparison and expr_comparison_dict:
+        left_col_full = expr_comparison_dict.get("left_column", "")
+        right_col_full = expr_comparison_dict.get("right_column", "")
+        cmp_op = expr_comparison_dict.get("op", "=")
+
+        if left_col_full and right_col_full and "." in left_col_full and "." in right_col_full:
+            left_table, left_col_name = left_col_full.split(".", 1)
+            right_table, right_col_name = right_col_full.split(".", 1)
+
+            left_valid = validate_column_exists(left_col_full, skeleton.tables, schema)
+            right_valid = validate_column_exists(right_col_full, skeleton.tables, schema)
+
+            if left_valid and right_valid:
+                left_meta = schema.tables[left_table].columns.get(left_col_name)
+                right_meta = schema.tables[right_table].columns.get(right_col_name)
+
+                if left_meta and right_meta:
+                    left_is_numeric = left_meta.value_type in ("integer", "number")
+                    right_is_numeric = right_meta.value_type in ("integer", "number")
+                    left_is_temporal = left_meta.value_type == "date"
+                    right_is_temporal = right_meta.value_type == "date"
+
+                    left_role = column_roles.get(f"{left_table}.{left_col_name}", left_meta.role or "unknown")
+                    right_role = column_roles.get(f"{right_table}.{right_col_name}", right_meta.role or "unknown")
+
+                    semantic_compatible = False
+                    rejection_reason = None
+
+                    if left_role == right_role and left_role != "unknown":
+                        semantic_compatible = True
+                    elif left_is_temporal and right_is_temporal:
+                        semantic_compatible = True
+                    elif left_is_numeric and right_is_numeric and left_role == right_role:
+                        semantic_compatible = True
+                    else:
+                        rejection_reason = f"role_mismatch: left={left_col_full}(role={left_role}) vs right={right_col_full}(role={right_role})"
+
+                    if semantic_compatible:
+                        value_type = "temporal" if left_is_temporal else "numeric"
+                        filters.append(
+                            QSimFilter(
+                                column=left_col_full,
+                                op=cmp_op,
+                                value_type=value_type,
+                                right_column=right_col_full,
+                            )
+                        )
+                        debug(
+                            f"[qsim_ops.parse_llm_response] ACCEPTED_COLUMN_COMPARISON: {left_col_full} {cmp_op} {right_col_full}, roles={left_role}={right_role}"
+                        )
+                    else:
+                        debug(
+                            f"[qsim_ops.parse_llm_response] DISCARDED_EXPR_COMPARISON: {left_col_full} {cmp_op} {right_col_full}, reason={rejection_reason}"
+                        )
+                else:
+                    debug("[qsim_ops.parse_llm_response] DISCARDED_EXPR_COMPARISON: column metadata not found")
+            else:
+                debug(
+                    f"[qsim_ops.parse_llm_response] DISCARDED_EXPR_COMPARISON: column validation failed left={left_valid} right={right_valid}"
+                )
+        else:
+            debug("[qsim_ops.parse_llm_response] DISCARDED_EXPR_COMPARISON: invalid column format")
+
+    total_filter_elements = len(filters)
+    if skeleton.num_filters > 0 and total_filter_elements == 0:
+        debug(
+            f"[qsim_ops.parse_llm_response] INSUFFICIENT_FILTERS: requested={skeleton.num_filters}, validated_filters={len(filters)}, rejecting_intent"
+        )
+        return None
+
+    if has_agg and groupby_cols:
+        for sc in select_cols:
+            agg_info = _extract_agg_info(sc)
+            if agg_info:
+                _, agg_inner = agg_info
+                agg_inner_base = agg_inner.split(".")[-1] if "." in agg_inner else agg_inner
+                for gcol in groupby_cols:
+                    gcol_base = gcol.split(".")[-1] if "." in gcol else gcol
+                    if agg_inner == gcol:
+                        debug(
+                            f"[qsim_ops.parse_llm_response] REJECTED: agg_inner={agg_inner} matches groupby_col={gcol}, reason=exact_self_grouping"
+                        )
+                        return None
+                    if agg_inner_base == gcol_base:
+                        debug(
+                            f"[qsim_ops.parse_llm_response] REJECTED: agg_inner={agg_inner} matches groupby_col={gcol}, reason=base_name_self_grouping"
+                        )
+                        return None
+
+    having: list[QSimHaving] = []
+    for hd in having_dicts:
+        h_expression = hd.get("expression", "")
+        h_op = hd.get("op", ">")
+        if h_op not in VALID_HAVING_OPS:
+            h_op = ">"
+        h_value_type = hd.get("value_type", "number")
+        if h_value_type not in VALID_HAVING_VALUE_TYPES:
+            h_value_type = "number"
+        right_expr = hd.get("right_expression", "")
+
+        h_agg_info = _extract_agg_info(h_expression)
+        if not h_agg_info:
+            debug(
+                f"[qsim_ops.parse_llm_response] REJECTED_HAVING: expression={h_expression}, reason=no_aggregation_pattern"
+            )
+            continue
+
+        h_agg_func, h_agg_inner = h_agg_info
+        if h_agg_inner != "*" and not validate_column_exists(h_agg_inner, skeleton.tables, schema):
+            debug(f"[qsim_ops.parse_llm_response] REJECTED_HAVING: expression={h_expression}, reason=column_not_found")
+            continue
+
+        if right_expr:
+            right_agg_info = _extract_agg_info(right_expr)
+            if not right_agg_info:
+                debug(
+                    f"[qsim_ops.parse_llm_response] REJECTED_HAVING: right_expression={right_expr}, reason=no_aggregation_pattern"
+                )
+                continue
+            right_agg_func, right_agg_inner = right_agg_info
+            if right_agg_inner != "*" and not validate_column_exists(right_agg_inner, skeleton.tables, schema):
+                debug(
+                    f"[qsim_ops.parse_llm_response] REJECTED_HAVING: right_expression={right_expr}, reason=column_not_found"
+                )
+                continue
+            having.append(
+                QSimHaving(
+                    expression=f"{h_agg_func.upper()}({h_agg_inner})",
+                    op=h_op,
+                    value_type="expression",
+                    right_expression=f"{right_agg_func.upper()}({right_agg_inner})",
+                )
+            )
+        else:
+            having.append(
+                QSimHaving(
+                    expression=f"{h_agg_func.upper()}({h_agg_inner})",
+                    op=h_op,
+                    value_type=h_value_type,
+                )
+            )
+
+    validated_groupby: list[str] = []
+    for gcol in groupby_cols:
+        if validate_column_exists(gcol, skeleton.tables, schema):
+            validated_groupby.append(gcol)
+        else:
+            debug(f"[qsim_ops.parse_llm_response] REJECTED_GROUPBY: col={gcol}, reason=column_not_found")
+
+    order_by_cols: list[str] = []
+    for ob in orderby_cols_raw:
+        ob_clean = ob.strip()
+        direction = "ASC"
+        if ob_clean.upper().endswith(" DESC"):
+            direction = "DESC"
+            ob_clean = ob_clean[:-5].strip()
+        elif ob_clean.upper().endswith(" ASC"):
+            ob_clean = ob_clean[:-4].strip()
+
+        agg_info = _extract_agg_info(ob_clean)
+        if agg_info:
+            agg_func, agg_inner = agg_info
+            if agg_inner != "*" and not validate_column_exists(agg_inner, skeleton.tables, schema):
+                debug(f"[qsim_ops.parse_llm_response] REJECTED_ORDERBY: {ob}, reason=column_not_found")
+                continue
+            order_by_cols.append(f"{agg_func.upper()}({agg_inner}) {direction}")
+        else:
+            if not validate_column_exists(ob_clean, skeleton.tables, schema):
+                debug(f"[qsim_ops.parse_llm_response] REJECTED_ORDERBY: {ob}, reason=column_not_found")
+                continue
+            order_by_cols.append(f"{ob_clean} {direction}")
+
+    grain = "row_level"
+    if has_agg:
+        grain = "grouped" if validated_groupby else "scalar"
+
+    use_distinct = skeleton.has_distinct and has_distinct and grain == "row_level"
+
+    if skeleton.has_distinct and not use_distinct:
+        if not has_distinct:
+            debug(
+                "[qsim_ops.parse_llm_response] DISTINCT_REJECTED: LLM returned distinct=false despite skeleton.has_distinct=True"
+            )
+        elif grain != "row_level":
+            debug(
+                f"[qsim_ops.parse_llm_response] DISTINCT_REJECTED: grain={grain} incompatible with DISTINCT (requires row_level)"
+            )
+
+    if len(skeleton.tables) >= 3:
+        tables_used: set[str] = set()
+        for sc in select_cols:
+            tables_used.update(_extract_tables_from_expr(sc))
+        for col in validated_groupby:
+            tables_used.update(_extract_tables_from_expr(col))
+        for f in filters:
+            tables_used.update(_extract_tables_from_expr(f.column))
+            if f.right_column:
+                tables_used.update(_extract_tables_from_expr(f.right_column))
+        for ob in order_by_cols:
+            tables_used.update(_extract_tables_from_expr(ob))
+
+        missing_tables = set(skeleton.tables) - tables_used
+        if missing_tables:
+            debug(
+                f"[qsim_ops.parse_llm_response] REJECTED_THREE_TABLE: tables={skeleton.tables}, used={tables_used}, missing={missing_tables}"
+            )
+            return ("three_table_violation", tables_used, missing_tables)
+
+    intent_id_val = compute_intent_id(
+        {
+            "tables": skeleton.tables,
+            "grain": grain,
+            "select_cols": select_cols,
+            "group_by_cols": validated_groupby,
+            "filters_param": [f.to_dict() for f in filters],
+            "having_param": [h.to_dict() for h in having],
+            "distinct": use_distinct,
+        }
+    )
+
+    return QSimIntent(
+        intent_id=intent_id_val,
+        tables=skeleton.tables,
+        grain=grain,
+        select_cols=select_cols,
+        group_by_cols=validated_groupby,
+        order_by_cols=order_by_cols,
+        filters_param=filters,
+        having_param=having,
+        param_values={},
+        distinct=use_distinct,
+    )
+
+
+def _generate_question_from_intent(intent: QSimIntent, schema: SchemaGraph) -> str | None:
+    """Generate a natural-language question from a structured ``QSimIntent``.
+
+    Args:
+
+        intent: The structured intent whose components are used to build the question description passed to ``generate_question``.
+        schema: Schema graph passed through to the question generator.
+        column_roles: Map of column key to role string (currently unused but available for style selection).
+
+    Returns:
+
+        A natural-language question string, or ``None`` if generation failed.
+    """
+    filter_descriptions = []
+    for idx, f in enumerate(intent.filters_param):
+        if f.is_expr_comparison:
+            cond = f"{f.op} {f.right_column}"
+        else:
+            cond = f"{f.op} {intent.param_values.get(f'f{idx}', '?')}"
+        filter_descriptions.append({"column": f.column, "condition": cond})
+
+    having_descriptions = []
+    for hidx, h in enumerate(intent.having_param):
+        if h.is_expression_comparison:
+            cond = f"{h.op} {h.right_expression}"
+        else:
+            cond = f"{h.op} {intent.param_values.get(f'h{hidx}', '?')}"
+        having_descriptions.append({"expression": h.expression, "condition": cond})
+
+    return generate_question(
+        intent.tables,
+        intent.select_cols,
+        filter_descriptions,
+        intent.group_by_cols,
+        having_descriptions,
+        schema,
+    )
+
+
+def generate_all_questions(intents: list[QSimIntent], schema: SchemaGraph) -> list[QSimIntent]:
+    """Generate NL questions for a list of intents and return those with successful questions.
+
+    Args:
+
+        intents: List of ``QSimIntent`` instances to generate questions for.
+        schema: Schema graph passed through to ``generate_question_from_intent``.
+        column_roles: Map of column key to role string.
+
+    Returns:
+
+        List of ``QSimIntent`` instances (copies) with the ``question`` field populated; intents for which generation failed are omitted.
+    """
+    debug(f"[qsim_ops.generate_all_questions] generating: {len(intents)} questions")
+
+    results: list[QSimIntent] = []
+
+    for i, intent in enumerate(intents):
+        if i > 0 and i % 10 == 0:
+            debug(f"[qsim_ops.generate_all_questions] progress: {i}/{len(intents)}")
+
+        question = _generate_question_from_intent(intent, schema)
+        if question:
+            intent_with_question = QSimIntent(
+                intent_id=intent.intent_id,
+                tables=intent.tables,
+                grain=intent.grain,
+                select_cols=intent.select_cols,
+                group_by_cols=intent.group_by_cols,
+                order_by_cols=intent.order_by_cols,
+                filters_param=intent.filters_param,
+                having_param=intent.having_param,
+                param_values=intent.param_values,
+                question=question,
+                variant_idx=intent.variant_idx,
+                limit=intent.limit,
+                distinct=intent.distinct,
+            )
+            results.append(intent_with_question)
+        else:
+            debug(f"[qsim_ops.generate_all_questions] failed: {intent.intent_id}")
+
+    debug(f"[qsim_ops.generate_all_questions] complete: {len(results)} questions")
+    return results
+
+
+def _is_no_variance_skeleton(skeleton: QSimSkeleton) -> bool:
+    """Return whether a skeleton has no variance (no filters and no HAVING).
+
+    No-variance skeletons always produce the same query regardless of value sampling and should be used sparingly.
+
+    Args:
+
+        skeleton: The skeleton to inspect.
+
+    Returns:
+
+        ``True`` if the skeleton has zero required filters and no HAVING clause.
+    """
+    return skeleton.num_filters == 0 and not skeleton.has_having
+
+
+def _compute_skeleton_complexity_tier(skeleton: QSimSkeleton) -> str:
+    """Compute the complexity tier of a skeleton for stratified pool construction.
+
+    Assigns a composite score based on filter count, aggregation, GROUP BY, HAVING, ORDER BY, DISTINCT, and expr comparison presence.
+
+    Args:
+
+        skeleton: The skeleton to score.
+
+    Returns:
+
+        ``"A"`` (score >= 8, high complexity), ``"B"`` (score >= 4, medium), or ``"C"`` (score < 4, low complexity).
+    """
+    score = 0
+    score += skeleton.num_filters * 2
+    score += 3 if skeleton.has_aggregation else 0
+    score += skeleton.num_groupby * 2
+    score += 3 if skeleton.has_having else 0
+    score += 1 if skeleton.has_orderby else 0
+    score += 2 if skeleton.has_distinct else 0
+    score += 3 if skeleton.has_expr_comparison else 0
+
+    if score >= 8:
+        return "A"
+    elif score >= 4:
+        return "B"
+    else:
+        return "C"
+
+
+def _compute_table_set_richness(tables: list[str], schema: SchemaGraph, column_roles: dict[str, str]) -> int:
+    """Compute a richness score for a table set based on column capabilities.
+
+    Args:
+
+        tables: List of table names in the candidate set.
+        schema: Schema graph for column capability lookups.
+        column_roles: Map of column key to role string.
+
+    Returns:
+
+        Integer score reflecting the total number of filterable (×2), aggregatable (×3), groupable (×2), and comparable column-pair (×2) opportunities across all tables.
+    """
+    filterable_count = 0
+    aggregatable_count = 0
+    groupable_count = 0
+
+    for table in tables:
+        filterable_count += len(get_filterable_columns(table, schema, column_roles))
+        aggregatable_count += len(get_aggregatable_columns(table, schema, column_roles))
+        groupable_count += len(get_groupable_columns(table, schema, column_roles))
+
+    comparable_pairs = len(get_comparable_column_pairs(tables, schema, column_roles))
+
+    return filterable_count * 2 + aggregatable_count * 3 + groupable_count * 2 + comparable_pairs * 2
+
+
+def _build_skeleton_pool(
+    schema: SchemaGraph, column_roles: dict[str, str], num_tables: int | None = None
+) -> SkeletonPool:
+    """Build a tiered skeleton pool from all valid table sets for adaptive selection.
+
+    Enumerates table sets, generates all structural skeletons for each, assigns each to tier A/B/C by complexity score, and packages them into a ``SkeletonPool`` with round-robin iteration state.
+
+    Args:
+
+        schema: Schema graph used for skeleton generation and richness scoring.
+        column_roles: Map of column key to role string.
+        num_tables: If provided, restrict the pool to table sets of exactly this size.
+
+    Returns:
+
+        A ``SkeletonPool`` instance ready for adaptive skeleton selection.
+    """
+    table_sets = enumerate_table_sets(schema)
+
+    if num_tables is not None:
+        table_sets = [ts for ts in table_sets if len(ts) == num_tables]
+
+    scored_sets = [(ts, _compute_table_set_richness(ts, schema, column_roles)) for ts in table_sets]
+    scored_sets.sort(key=lambda x: x[1], reverse=True)
+
+    tier_a_by_table_set: dict[str, list[QSimSkeleton]] = {}
+    tier_b_by_table_set: dict[str, list[QSimSkeleton]] = {}
+    tier_c_by_table_set: dict[str, list[QSimSkeleton]] = {}
+
+    for table_set, _ in scored_sets:
+        table_key = "|".join(sorted(table_set))
+        tier_a_by_table_set[table_key] = []
+        tier_b_by_table_set[table_key] = []
+        tier_c_by_table_set[table_key] = []
+
+        skeletons = generate_all_skeletons(table_set, schema, column_roles)
+        for skel in skeletons:
+            tier = _compute_skeleton_complexity_tier(skel)
+            if tier == "A":
+                tier_a_by_table_set[table_key].append(skel)
+            elif tier == "B":
+                tier_b_by_table_set[table_key].append(skel)
+            else:
+                tier_c_by_table_set[table_key].append(skel)
+
+    for table_key in tier_a_by_table_set:
+        random.shuffle(tier_a_by_table_set[table_key])
+        random.shuffle(tier_b_by_table_set[table_key])
+        random.shuffle(tier_c_by_table_set[table_key])
+
+    table_set_keys = list(tier_a_by_table_set.keys())
+    tier_a_indices = {k: 0 for k in table_set_keys}
+    tier_b_indices = {k: 0 for k in table_set_keys}
+    tier_c_indices = {k: 0 for k in table_set_keys}
+
+    total_a = sum(len(v) for v in tier_a_by_table_set.values())
+    total_b = sum(len(v) for v in tier_b_by_table_set.values())
+    total_c = sum(len(v) for v in tier_c_by_table_set.values())
+
+    debug(f"[qsim_ops.build_skeleton_pool] built pool: tier_a={total_a}, tier_b={total_b}, tier_c={total_c}")
+    return SkeletonPool(
+        tier_a_by_table_set=tier_a_by_table_set,
+        tier_b_by_table_set=tier_b_by_table_set,
+        tier_c_by_table_set=tier_c_by_table_set,
+        table_set_keys=table_set_keys,
+        tier_a_indices=tier_a_indices,
+        tier_b_indices=tier_b_indices,
+        tier_c_indices=tier_c_indices,
+    )
+
+
+def _select_next_skeleton(
+    pool: SkeletonPool, need_filters: bool, need_having: bool
+) -> tuple[QSimSkeleton, list[str]] | None:
+    """Select the next skeleton from the pool using round-robin table-set iteration.
+
+    Prefers tier A skeletons, then B, then C, honouring coverage needs for filters and HAVING when specified.
+
+    Args:
+
+        pool: The ``SkeletonPool`` with current iteration state.
+        need_filters: When ``True``, only select skeletons that require at least one filter.
+        need_having: When ``True``, only select skeletons that require HAVING.
+
+    Returns:
+
+        A 2-tuple ``(skeleton, table_set)`` for the selected skeleton, or ``None`` if no suitable skeleton is found across all table sets.
+    """
+
+    def matches_needs(skel: QSimSkeleton) -> bool:
+        if need_filters and skel.num_filters == 0:
+            return False
+        if need_having and not skel.has_having:
+            return False
+        return True
+
+    start_idx = pool.current_table_idx
+    attempts = 0
+    max_attempts = len(pool.table_set_keys)
+
+    tiers = [
+        ("a", pool.tier_a_by_table_set, pool.tier_a_indices),
+        ("b", pool.tier_b_by_table_set, pool.tier_b_indices),
+        ("c", pool.tier_c_by_table_set, pool.tier_c_indices),
+    ]
+
+    while attempts < max_attempts:
+        table_idx = (start_idx + attempts) % len(pool.table_set_keys)
+        table_key = pool.table_set_keys[table_idx]
+        table_set = table_key.split("|")
+
+        for _tier_name, tier_dict, indices_dict in tiers:
+            skeletons = tier_dict[table_key]
+            current_idx = indices_dict[table_key]
+
+            for i in range(current_idx, len(skeletons)):
+                skel = skeletons[i]
+                if matches_needs(skel):
+                    indices_dict[table_key] = i + 1
+                    pool.current_table_idx = (table_idx + 1) % len(pool.table_set_keys)
+                    return skel, table_set
+
+        attempts += 1
+
+    return None
+
+
+def _normalize_qsim_intent(intent: QSimIntent, schema: SchemaGraph) -> QSimIntent:
+    """Normalise a ``QSimIntent`` for canonical deduplication and consistency.
+
+    Enforces grain consistency with aggregation and GROUP BY presence, deduplicates and sorts SELECT and ORDER BY columns, removes table names not referenced in any clause (when the remaining set is still FK-connected), and recomputes the intent ID.
+
+    Args:
+
+        intent: The ``QSimIntent`` to normalise.
+        schema: Schema graph used for FK connectivity checks.
+
+    Returns:
+
+        A new normalised ``QSimIntent`` with canonical field values and a recomputed ``intent_id``.
+    """
+    grain = intent.grain
+    has_agg = _has_aggregation(intent.select_cols)
+
+    if grain == "grouped":
+        if not intent.group_by_cols:
+            grain = "row_level"
+    else:
+        if has_agg:
+            grain = "grouped" if intent.group_by_cols else "scalar"
+
+    normalized_select = sorted(set(intent.select_cols))
+    normalized_orderby = sorted(intent.order_by_cols)
+
+    tables_used: set[str] = set()
+    for sc in normalized_select:
+        tables_used.update(_extract_tables_from_expr(sc))
+    for col in intent.group_by_cols:
+        tables_used.update(_extract_tables_from_expr(col))
+    for ob in normalized_orderby:
+        tables_used.update(_extract_tables_from_expr(ob))
+    for f in intent.filters_param:
+        tables_used.update(_extract_tables_from_expr(f.column))
+        if f.right_column:
+            tables_used.update(_extract_tables_from_expr(f.right_column))
+    for h in intent.having_param:
+        tables_used.update(_extract_tables_from_expr(h.expression))
+
+    tables_used.discard("")
+
+    normalized_tables = intent.tables
+    if tables_used and len(tables_used) < len(intent.tables):
+        adj = build_fk_adjacency(schema)
+        if is_connected(list(tables_used), adj):
+            normalized_tables = sorted(tables_used)
+            debug(f"[qsim_ops.normalize_qsim_intent] removed unnecessary tables: {set(intent.tables) - tables_used}")
+
+    table_prefixed_group_by = []
+    for col in intent.group_by_cols:
+        if "." not in col:
+            if normalized_tables:
+                col = f"{normalized_tables[0]}.{col}"
+        table_prefixed_group_by.append(col)
+
+    intent_id_val = compute_intent_id(
+        {
+            "tables": normalized_tables,
+            "grain": grain,
+            "select_cols": normalized_select,
+            "group_by_cols": table_prefixed_group_by,
+            "filters_param": [f.to_dict() for f in intent.filters_param],
+            "having_param": [h.to_dict() for h in intent.having_param],
+            "distinct": intent.distinct,
+        }
+    )
+
+    return QSimIntent(
+        intent_id=intent_id_val,
+        tables=normalized_tables,
+        grain=grain,
+        select_cols=normalized_select,
+        group_by_cols=table_prefixed_group_by,
+        order_by_cols=normalized_orderby,
+        filters_param=intent.filters_param,
+        having_param=intent.having_param,
+        param_values=intent.param_values,
+        question=intent.question,
+        variant_idx=intent.variant_idx,
+        limit=intent.limit,
+        distinct=intent.distinct,
+    )
+
+
+def generate_all_intents(
+    schema: SchemaGraph, column_roles: dict[str, str], num_intents: int = None
+) -> list[QSimIntent]:
+    """Generate a diverse set of ``QSimIntent`` instances with stratified coverage guarantees.
+
+    Uses adaptive skeleton selection across three table-count strata (single, two-table, three-table) with configurable budgets for each.
+    Enforces minimum ratios for filter coverage, HAVING coverage, and three-table joins, and caps no-variance skeletons.
+
+    Args:
+
+        schema: Schema graph used for skeleton pool construction and LLM filling.
+        column_roles: Map of column key to role string.
+        num_intents: Total number of intents to generate; defaults to ``QSimConfig.INTENT_TYPES``.
+
+    Returns:
+
+        List of normalised, deduplicated ``QSimIntent`` instances up to *num_intents* in length.
+    """
+    random.seed(QSimConfig.RANDOM_SEED)
+    load_or_create_skeletons(schema, column_roles)
+
+    if num_intents is None:
+        num_intents = QSimConfig.INTENT_TYPES
+
+    min_with_filters = int(num_intents * QSimConfig.MIN_FILTER_RATIO)
+    min_with_having = int(num_intents * QSimConfig.MIN_HAVING_RATIO)
+    min_three_table = int(num_intents * QSimConfig.MIN_THREE_TABLE_RATIO)
+    max_no_variance = int(num_intents * QSimConfig.MAX_NO_VARIANCE_RATIO)
+
+    debug(
+        f"[qsim_ops.generate_all_intents] targeting {num_intents} intents, min_filters={min_with_filters}, min_having={min_with_having}, min_three_table={min_three_table}"
+    )
+
+    budget_three = max(int(num_intents * QSimConfig.THREE_TABLE_RATIO), min_three_table)
+    remaining_after_three = num_intents - budget_three
+    budget_single = int(
+        remaining_after_three
+        * QSimConfig.SINGLE_TABLE_RATIO
+        / (QSimConfig.SINGLE_TABLE_RATIO + QSimConfig.TWO_TABLE_RATIO)
+    )
+    budget_two = remaining_after_three - budget_single
+
+    intents: list[QSimIntent] = []
+    seen_ids: set[str] = set()
+    table_set_usage: dict[str, int] = {}
+    no_variance_count = 0
+
+    strata = [
+        (3, budget_three, "three-table"),
+        (1, budget_single, "single-table"),
+        (2, budget_two, "two-table"),
+    ]
+
+    for num_tables, stratum_budget, stratum_name in strata:
+        if stratum_budget == 0:
+            continue
+
+        pool = _build_skeleton_pool(schema, column_roles, num_tables=num_tables)
+
+        consecutive_duplicates = 0
+        consecutive_failures = 0
+        stratum_intents = 0
+
+        while stratum_intents < stratum_budget:
+            if consecutive_duplicates >= QSimConfig.MAX_CONSECUTIVE_DUPLICATES:
+                debug(
+                    f"[qsim_ops.generate_all_intents] EARLY_EXIT ({stratum_name}): {consecutive_duplicates} consecutive duplicates"
+                )
+                break
+
+            if consecutive_failures >= QSimConfig.MAX_CONSECUTIVE_FAILURES:
+                debug(
+                    f"[qsim_ops.generate_all_intents] EARLY_EXIT ({stratum_name}): {consecutive_failures} consecutive failures"
+                )
+                break
+
+            current_with_filters = len([i for i in intents if i.filters_param])
+            current_with_having = len([i for i in intents if i.having_param])
+            need_filters = current_with_filters < min_with_filters
+            need_having = current_with_having < min_with_having
+
+            selection = _select_next_skeleton(pool, need_filters, need_having)
+            if not selection:
+                debug(f"[qsim_ops.generate_all_intents] EARLY_EXIT ({stratum_name}): skeleton pool exhausted")
+                break
+
+            skeleton, table_set = selection
+
+            if _is_no_variance_skeleton(skeleton) and no_variance_count >= max_no_variance:
+                debug(
+                    f"[qsim_ops.generate_all_intents] SKIPPING ({stratum_name}): no-variance budget exceeded ({no_variance_count}/{max_no_variance})"
+                )
+                continue
+
+            intent = _llm_fill_intent(skeleton, schema, column_roles)
+
+            if not intent:
+                consecutive_failures += 1
+                debug(f"[qsim_ops.generate_all_intents] LLM failed, consecutive_failures={consecutive_failures}")
+                continue
+
+            consecutive_failures = 0
+
+            normalized = _normalize_qsim_intent(intent, schema)
+
+            if num_tables == 3 and len(normalized.tables) < 3:
+                debug(
+                    f"[qsim_ops.generate_all_intents] SKIPPING ({stratum_name}): normalized to {len(normalized.tables)} tables"
+                )
+                continue
+
+            if normalized.intent_id in seen_ids:
+                consecutive_duplicates += 1
+                debug(
+                    f"[qsim_ops.generate_all_intents] DUPLICATE: intent_id={normalized.intent_id}, consecutive_duplicates={consecutive_duplicates}"
+                )
+                continue
+
+            consecutive_duplicates = 0
+
+            if _is_no_variance_skeleton(skeleton):
+                no_variance_count += 1
+
+            table_set_key = "|".join(sorted(table_set))
+            table_set_usage[table_set_key] = table_set_usage.get(table_set_key, 0) + 1
+
+            intents.append(normalized)
+            seen_ids.add(normalized.intent_id)
+            stratum_intents += 1
+            debug(
+                f"[qsim_ops.generate_all_intents] ADDED: intent_id={normalized.intent_id}, tables={table_set}, filters={len(normalized.filters_param)}, having={len(normalized.having_param)}, total={len(intents)}/{num_intents}"
+            )
+
+    final_with_filters = len([i for i in intents if i.filters_param])
+    final_with_having = len([i for i in intents if i.having_param])
+    single_count = len([i for i in intents if len(i.tables) == 1])
+    two_count = len([i for i in intents if len(i.tables) == 2])
+    three_count = len([i for i in intents if len(i.tables) >= 3])
+
+    debug(
+        f"[qsim_ops.generate_all_intents] generated {len(intents)} intents: single={single_count}, two={two_count}, three={three_count}"
+    )
+    debug(
+        f"[qsim_ops.generate_all_intents] coverage: with_filters={final_with_filters}/{min_with_filters}, with_having={final_with_having}/{min_with_having}, three_table={three_count}/{min_three_table}, no_variance={no_variance_count}/{max_no_variance}"
+    )
+    debug(
+        f"[qsim_ops.generate_all_intents] table_set_usage: {
+            dict(sorted(table_set_usage.items(), key=lambda x: x[1], reverse=True)[:10])
+        }"
+    )
+
+    return intents