aetherdialect 0.1.0__py3-none-any.whl

text2sql/main_execution.py

@@ -0,0 +1,799 @@
+"""Orchestrator for Coverage Simulator, Question Simulator, and Interactive Pipeline execution.
+
+Coordinates the three top-level execution modes: the coverage simulator builds synthetic templates from seed questions via expansion and validation; the question simulator (QSim) generates natural-language questions from schema-profiled intent skeletons; the interactive pipeline answers live user questions with template reuse, SQL generation, and feedback learning.
+
+Also provides artifact path utilities, QSim summary loading, and template list builders.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+from collections import Counter
+from datetime import datetime
+from typing import Any
+
+from platformdirs import user_data_dir
+
+from .config import EngineConfig, PolicyConfig, QSimConfig, SimulatorConfig
+from .contracts_base import (
+    QSimSummary,
+    RejectedTemplateInfo,
+    SchemaGraph,
+    SimulatorSummary,
+    TemplateInfo,
+)
+from .contracts_core import RuntimeIntent
+from .core_utils import ask_user_choice, debug, log, normalize_question
+from .expansion_ops import expand_gold_intents
+from .intent_process import match_template_for_union
+from .pipeline import (
+    check_and_handle_hard_block,
+    check_template_reuse,
+    compute_final_metrics,
+    confirm_intent_with_user,
+    display_final_results,
+    generate_and_validate_sql,
+    generate_join_candidates,
+    handle_direct_sql_reuse,
+    handle_user_feedback,
+    load_pipeline_resources,
+    parse_intent_via_llm,
+    save_result_csv,
+)
+from .qsim_ops import generate_all_intents, generate_all_questions
+from .qsim_sample import instantiate_all
+from .schema import compute_schema_limits, compute_schema_stats
+from .simulator import (
+    get_next_simulator_version,
+    resolve_joins_for_table_set,
+    run_deterministic_simulation,
+    run_gold_intent_generation,
+    save_simulation_failures,
+    save_simulation_report,
+)
+from .templates import save_template_store, templates_to_store
+from .utils import flatten_param_values, intent_key, validate_question
+from .validation_execute import execute_sql, get_spark_sql_for_execution
+
+
+def qsim_run_once(
+    num_intents: int | None = None,
+    num_questions: int | None = None,
+    seed: int | None = None,
+    artifacts_dir: str | None = None,
+    schema: SchemaGraph | None = None,
+) -> QSimSummary:
+    """Generate synthetic natural-language questions and persist them to a timestamped JSON file.
+
+    Runs the full QSim pipeline: intent skeleton generation, instantiation with sampled values, LLM question generation, and artifact persistence.
+
+    Args:
+
+        num_intents: Number of distinct intent types to generate; defaults to ``QSimConfig.INTENT_TYPES``.
+        num_questions: Total number of question variants to produce; defaults to ``QSimConfig.QUESTIONS_COUNT``.
+        seed: Random seed for reproducible generation; defaults to ``QSimConfig.RANDOM_SEED``.
+        artifacts_dir: Directory for output files; when ``None``, files are written to the current working directory.
+        schema: Pre-loaded and profiled ``SchemaGraph``; must not be ``None``.
+
+    Returns:
+
+        ``QSimSummary`` with timestamp, intent count, question count, and seed.
+
+    Raises:
+
+        RuntimeError: If *schema* is ``None`` or no column roles are found on the schema.
+    """
+    if num_intents is None:
+        num_intents = QSimConfig.INTENT_TYPES
+    if num_questions is None:
+        num_questions = QSimConfig.QUESTIONS_COUNT
+    if seed is None:
+        seed = QSimConfig.RANDOM_SEED
+
+    random.seed(seed)
+
+    log(f"Starting question simulation: {num_intents} intent types, {num_questions} questions, seed={seed}")
+
+    if schema is None:
+        raise RuntimeError("Schema must be provided to qsim_run_once")
+
+    has_profiled_columns = any(
+        col.role is not None for table in schema.tables.values() for col in table.columns.values()
+    )
+    if not has_profiled_columns:
+        raise RuntimeError(
+            "Schema profiling failed - no column roles found. Check database connection and column data."
+        )
+
+    total_cols = sum(len(t.columns) for t in schema.tables.values())
+    log(f"  Loaded {len(schema.tables)} tables, {total_cols} columns with metadata")
+
+    column_roles: dict[str, str] = {}
+    for table_name, table_meta in schema.tables.items():
+        for col_name, col_meta in table_meta.columns.items():
+            if col_meta.role:
+                column_roles[f"{table_name}.{col_name}"] = col_meta.role
+
+    timestamp = datetime.now().strftime("%y%m%d%H%M%S")
+
+    log("Generating QSimIntent structures...")
+    intents = generate_all_intents(schema, column_roles, num_intents)
+    log(f"  Generated {len(intents)} QSimIntent structures")
+
+    log("Instantiating QSimIntents with values...")
+    instantiated = instantiate_all(intents, schema, num_questions)
+    log(f"  Created {len(instantiated)} QSimIntent variants with values")
+
+    log("Generating NL questions via LLM...")
+    results = generate_all_questions(instantiated, schema)
+    log(f"  Generated {len(results)} QSimIntents with questions")
+
+    output_results = [intent.to_dict() for intent in results]
+
+    parent_ids = [
+        (intent.intent_id.rsplit("_v", 1)[0] if "_v" in intent.intent_id else intent.intent_id) for intent in results
+    ]
+    intent_counts = Counter(parent_ids)
+    log(f"  Questions per intent type: {dict(intent_counts)}")
+
+    if artifacts_dir:
+        os.makedirs(artifacts_dir, exist_ok=True)
+        qsim_questions_path = os.path.join(artifacts_dir, f"qsim_intents_with_questions_{timestamp}.json")
+        qsim_summary_path = os.path.join(artifacts_dir, "qsim_summary.json")
+    else:
+        qsim_questions_path = f"qsim_intents_with_questions_{timestamp}.json"
+        qsim_summary_path = "qsim_summary.json"
+
+    log(f"Saving QSimIntents with questions to {qsim_questions_path}...")
+    with open(qsim_questions_path, "w", encoding="utf-8") as f:
+        json.dump(output_results, f, indent=2, ensure_ascii=False)
+
+    summary_entry = QSimSummary(
+        timestamp=timestamp,
+        num_intents=len(intents),
+        num_questions=len(output_results),
+        seed=seed,
+    )
+
+    summaries = []
+    if os.path.exists(qsim_summary_path):
+        with open(qsim_summary_path, encoding="utf-8") as f:
+            summaries = json.load(f)
+    summaries.append(summary_entry.to_dict())
+    with open(qsim_summary_path, "w", encoding="utf-8") as f:
+        json.dump(summaries, f, indent=2, ensure_ascii=False)
+
+    log(f"Question simulation complete: {len(output_results)} questions saved")
+    print(f"QSim timestamp: {timestamp}")
+
+    if output_results and EngineConfig.DEBUG:
+        debug("[main_execution.qsim_run_once] samples:")
+        for i, item in enumerate(output_results[:5]):
+            debug(f"[main_execution.qsim_run_once]   {i + 1}. {item.get('question', 'N/A')}")
+
+    return summary_entry
+
+
+def load_generated_questions(path: str | None = None) -> list[dict[str, Any]]:
+    """Load previously generated QSim questions from a JSON file.
+
+    Args:
+
+        path: Path to the JSON file; defaults to ``QSimConfig.QUESTIONS_OUTPUT_PATH``.
+
+    Returns:
+
+        List of QSimIntent dicts as stored in the file.
+    """
+    if path is None:
+        path = QSimConfig.QUESTIONS_OUTPUT_PATH
+
+    with open(path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def get_questions_only(results: list[dict[str, Any]], output_path: str | None = None) -> None:
+    """Print and save a numbered list of NL questions from QSim results.
+
+    Args:
+
+        results: List of QSimIntent dicts, each containing a ``"question"`` key.
+        output_path: File path for the output text file; defaults to ``QSimConfig.QUESTIONS_OUTPUT_PATH`` with ``.json`` replaced by ``.txt``.
+    """
+    questions = [r["question"] for r in results]
+
+    if output_path is None:
+        base = QSimConfig.QUESTIONS_OUTPUT_PATH
+        if base.endswith(".json"):
+            output_path = base[:-5] + ".txt"
+        else:
+            timestamp = datetime.now().strftime("%y%m%d%H%M")
+            output_path = f"qsim_{timestamp}_questions.txt"
+
+    for i, q in enumerate(questions, 1):
+        print(f"{i}. {q}")
+
+    with open(output_path, "w", encoding="utf-8") as f:
+        for i, q in enumerate(questions, 1):
+            f.write(f"{i}. {q}\n")
+
+
+def simulator_run_once(
+    schema: SchemaGraph,
+    dialect: Any,
+    seed_filepath: str,
+    output_dir: str,
+    store: dict[str, Any] | None = None,
+    templates: dict[str, Any] | None = None,
+    interactive_gold: bool = True,
+    seed: int | None = None,
+) -> SimulatorSummary:
+    """Execute the full deterministic coverage simulator pipeline.
+
+    Phases:
+      1. Gold intent generation from seed questions (LLM parse).
+      2. Deterministic multi-depth expansion (no LLM).
+      3. Cross-gold SHA-256 dedup.
+      4. Join resolution at gold level, cached per table-set.
+      5. SQL build + instantiate + validate/execute + LLM question
+         generation with realism gate (1 per intent).
+      6. Template creation + store merge + report.
+
+    Args:
+
+        schema: Pre-loaded SchemaGraph with profiled columns.
+        dialect: SQL dialect object for validation and execution.
+        seed_filepath: Path to the seed questions text file.
+        output_dir: Directory for output artefacts.
+        store: Existing template store dict; may be None.
+        templates: Existing templates dict keyed by id; may be None.
+        interactive_gold: When True, confirm each gold intent.
+        seed: Random seed; defaults to SimulatorConfig.RANDOM_SEED.
+
+    Returns:
+
+        SimulatorSummary with version and success/failure counts.
+    """
+    if seed is None:
+        seed = SimulatorConfig.RANDOM_SEED
+    random.seed(seed)
+
+    os.makedirs(output_dir, exist_ok=True)
+    version = get_next_simulator_version(output_dir)
+    gold_filepath = os.path.join(
+        output_dir,
+        SimulatorConfig.GOLD_OUTPUT_PATTERN.format(version=version),
+    )
+    report_filepath = os.path.join(
+        output_dir,
+        SimulatorConfig.REPORT_PATTERN.format(version=version),
+    )
+    results_csv_filepath = os.path.join(
+        output_dir,
+        SimulatorConfig.RESULTS_CSV_PATTERN.format(version=version),
+    )
+    failures_filepath = os.path.join(
+        output_dir,
+        SimulatorConfig.FAILURES_PATTERN.format(version=version),
+    )
+
+    log(f"Starting simulator version {version}")
+    print(f"Simulator version: {version}")
+
+    schema_stats = compute_schema_stats(schema)
+    limits = compute_schema_limits(schema_stats)
+    log(
+        f"Computed SchemaLimits: max_filters={limits.max_filters}, "
+        f"max_groupby={limits.max_groupby}, "
+        f"max_tables={limits.max_tables}"
+    )
+
+    log("PHASE 1: Gold Intent Generation")
+    gold_intents_raw = run_gold_intent_generation(
+        schema, seed_filepath, gold_filepath,
+        interactive=interactive_gold,
+    )
+    gold_sim_intents = [
+        SimulatorIntent.from_dict(d) if isinstance(d, dict) else d
+        for d in gold_intents_raw
+    ]
+    log(f"Gold intents: {len(gold_sim_intents)}")
+
+    log("PHASE 2: Deterministic Multi-Depth Expansion")
+    synthetic_intents = expand_gold_intents(
+        gold_sim_intents, schema, limits,
+    )
+    log(f"Synthetic intents (deduped): {len(synthetic_intents)}")
+
+    log("PHASE 3: Join Resolution (cached per table-set)")
+    join_cache: dict[frozenset[str], Any] = {}
+    for gold in gold_sim_intents:
+        resolve_joins_for_table_set(
+            gold.tables or [], schema,
+            gold.intent_id or "gold", join_cache,
+        )
+    log(f"Join cache seeded with {len(join_cache)} table-set entries")
+
+    log("PHASE 4: SQL Build + Validate + Execute + Question Generation")
+    next_id = int(store["next_id"]) if store else 1
+    results, new_templates, updated_next_id = run_deterministic_simulation(
+        synthetic_intents, schema, dialect, next_id,
+        join_cache=join_cache,
+        csv_output_path=results_csv_filepath,
+    )
+    log(
+        f"Simulation results: {len(results)}, "
+        f"templates: {len(new_templates)}"
+    )
+
+    save_simulation_report(results, report_filepath)
+    save_simulation_failures(results, failures_filepath)
+
+    if store is not None and templates is not None:
+        for tmpl in new_templates:
+            dedupe_key = (
+                tmpl.intent_key,
+                getattr(
+                    tmpl.intent_signature,
+                    "chosen_join_candidate_id", "",
+                ),
+                tmpl.sql_fp,
+            )
+            found = False
+            for existing in templates.values():
+                k = (
+                    existing.intent_key,
+                    getattr(
+                        existing.intent_signature,
+                        "chosen_join_candidate_id", "",
+                    ),
+                    existing.sql_fp,
+                )
+                if k == dedupe_key:
+                    found = True
+                    for i, q in enumerate(tmpl.value_history.questions):
+                        pv = (
+                            tmpl.value_history.param_values[i]
+                            if i < len(tmpl.value_history.param_values)
+                            else {}
+                        )
+                        nl = (
+                            tmpl.value_history.natural_language[i]
+                            if i < len(tmpl.value_history.natural_language)
+                            else ""
+                        )
+                        existing.value_history.add(pv, q, nl)
+                    break
+            if not found:
+                templates[tmpl.id] = tmpl
+        store["next_id"] = updated_next_id
+        store = templates_to_store(store, templates)
+        save_template_store(store)
+
+    total = len(results)
+    success = sum(1 for r in results if r.success)
+    failed = total - success
+    success_rate = round(success / total, 3) if total > 0 else 0.0
+
+    log(
+        f"SIMULATOR COMPLETE: {len(new_templates)} synthetic templates created"
+    )
+    return SimulatorSummary(
+        version=version,
+        total=total,
+        success=success,
+        failed=failed,
+        success_rate=success_rate,
+    )
+
+
+def interactive_run_once(
+    schema: SchemaGraph | None = None,
+    store: Any | None = None,
+    templates: list | None = None,
+    rejected: list | None = None,
+    schema_terms: Any | None = None,
+    question: str | None = None,
+    engine: Any | None = None,
+) -> dict[str, Any] | None:
+    """Execute a single interactive pipeline iteration.
+
+    Reads a question from stdin (or uses the supplied *question*),
+    validates it, checks for template reuse, parses intent via LLM
+    if needed, generates SQL, executes it, and handles user
+    feedback.
+
+    Args:
+
+        schema: Pre-loaded ``SchemaGraph``; raises when ``None``.
+        store: Template store dict; raises when ``None``.
+        templates: List of accepted ``Template`` objects; raises
+            when ``None``.
+        rejected: List of ``RejectedTemplate`` objects; raises
+            when ``None``.
+        schema_terms: Set of schema term tokens; raises when
+            ``None``.
+        question: When provided the pipeline uses this question
+            instead of reading from stdin.
+        engine: SQLAlchemy engine for query execution; when
+            ``None`` the default engine is used.
+
+    Returns:
+
+        A dict with pipeline results on a full run, or ``None``
+        on early exit.
+    """
+    if question is None:
+        print("Enter question")
+        try:
+            question = input().strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\nUser terminated.")
+            return None
+
+    if not question:
+        print("\nInvalid input.")
+        return None
+    print(f"User input: {question}")
+
+    valid, query_type, corrected = validate_question(question)
+    if not valid:
+        if query_type == "restricted":
+            print("Restricted access, only querying is allowed. Please rephrase.")
+        else:
+            print("Unable to process your question. Please rephrase to a valid question.")
+        return None
+    if corrected != question:
+        debug(f"[main_execution.interactive_run_once] typo_corrected: '{question}' -> '{corrected}'")
+        question = corrected
+
+    q_norm = normalize_question(question)
+    debug(f"[main_execution.interactive_run_once] q_norm: {q_norm}")
+
+    dialect, _, schema, store, templates, rejected, schema_terms = load_pipeline_resources(
+        schema, store, templates, rejected, schema_terms
+    )
+
+    tmpl_match = check_template_reuse(q_norm, templates)
+
+    if tmpl_match.reuse_type == "direct_reuse":
+        log(f"direct SQL reuse via exact question match (trust=2, template='{tmpl_match.best_template.id}')")
+        debug("[main_execution.interactive_run_once] direct_reuse: question_match")
+        handled = handle_direct_sql_reuse(
+            q_norm,
+            tmpl_match.best_template,
+            dialect,
+            store,
+            templates,
+            schema,
+            engine=engine,
+            existing_nl=None,
+        )
+        if handled:
+            return None
+
+    intent = tmpl_match.intent
+    semantic_warnings: list[dict[str, Any]] = []
+
+    if intent is None:
+        parsed = parse_intent_via_llm(q_norm, schema, templates, store)
+        if parsed is None:
+            return None
+        intent, semantic_warnings, _ = parsed
+
+    ikey = intent_key(intent)
+    debug(f"[main_execution.interactive_run_once] intent_key: {ikey[:32]}")
+
+    union_result = match_template_for_union(intent, templates)
+    matched_template = None
+    union_select_cols = None
+    cols_changed = False
+    has_union_match = union_result is not None
+    if union_result is not None:
+        matched_template, union_select_cols, cols_changed = union_result
+
+    if not confirm_intent_with_user(
+        intent, store, semantic_warnings, has_union_match=has_union_match,
+    ):
+        return None
+
+    join_candidates, cmap, cte_join_hints = generate_join_candidates(intent, schema)
+    if join_candidates is None:
+        save_template_store(store)
+        return None
+
+    (
+        hard_block_override,
+        hard_block_rejected_template,
+        matched_rejected_template,
+        proceed,
+    ) = check_and_handle_hard_block(rejected, ikey, intent)
+    if not proceed:
+        save_template_store(store)
+        return None
+
+    sql, ok = generate_and_validate_sql(
+        q_norm,
+        intent,
+        schema,
+        join_candidates,
+        cmap,
+        dialect,
+        store,
+        engine=engine,
+        cte_join_hints=cte_join_hints,
+        matched_template=matched_template,
+        union_select_cols=union_select_cols,
+        cols_changed=cols_changed,
+    )
+    if not ok:
+        return None
+
+    log("executing SQL")
+    spark_sql = get_spark_sql_for_execution(
+        intent.sql_param or "",
+        dict(flatten_param_values(intent)),
+        schema,
+        intent,
+        dialect,
+    )
+    rows = execute_sql(
+        dialect,
+        sql,
+        spark_sql_for_execution=spark_sql if spark_sql else None,
+    )
+
+    conf = compute_final_metrics(sql, intent, schema, templates, join_candidates, store)
+
+    ux_summary = display_final_results(q_norm, intent, sql, rows)
+
+    if conf >= PolicyConfig.FINAL_SQL_AUTO_ACCEPT_THRESHOLD:
+        log(f"[AUTO-ACCEPT] confidence={conf:.3f} >= {PolicyConfig.FINAL_SQL_AUTO_ACCEPT_THRESHOLD}")
+        choice = "y"
+    else:
+        choice = ask_user_choice("\nIs this correct?", ["y", "n"])
+        if choice is None:
+            save_template_store(store)
+            return None
+
+    if choice == "y":
+        save_result_csv(rows, intent, sql)
+
+    handle_user_feedback(
+        choice,
+        intent,
+        sql,
+        schema,
+        store,
+        templates,
+        rejected,
+        q_norm,
+        hard_block_override,
+        hard_block_rejected_template,
+        matched_rejected_template,
+        ux_summary,
+        dialect=dialect,
+    )
+
+
+def _obfuscate_trust_level(trust_level: int) -> str:
+    """Convert an internal trust level integer to a user-facing string.
+
+    Args:
+
+        trust_level: Internal trust level in the range 0–2.
+
+    Returns:
+
+        One of ``"high"``, ``"moderate"``, or ``"low"``.
+    """
+    if trust_level >= 2:
+        return "high"
+    elif trust_level == 1:
+        return "moderate"
+    return "low"
+
+
+def _obfuscate_rejection_category(categories: dict[str, int]) -> str:
+    """Convert a rejection category frequency dict to a user-facing category string.
+
+    Args:
+
+        categories: Dict mapping rejection category names to occurrence counts.
+
+    Returns:
+
+        One of ``"invalid_sql"``, ``"incorrect_results"``, ``"ambiguous_intent"``, or ``"other"``.
+    """
+    if not categories:
+        return "other"
+    max_cat = max(categories.items(), key=lambda x: x[1])[0]
+    if max_cat in ("wrong_tables", "wrong_join"):
+        return "invalid_sql"
+    elif max_cat in (
+        "too_many_rows",
+        "too_few_rows",
+        "wrong_filters_or_values",
+        "wrong_columns_selected",
+    ):
+        return "incorrect_results"
+    elif max_cat == "wrong_intent":
+        return "ambiguous_intent"
+    return "other"
+
+
+def get_templates_list(templates: dict[str, Any]) -> list[TemplateInfo]:
+    """Build a ``TemplateInfo`` list from the templates dictionary.
+
+    Args:
+
+        templates: Dict of accepted ``Template`` objects keyed by template id.
+
+    Returns:
+
+        List of ``TemplateInfo`` instances with obfuscated trust levels.
+    """
+    results = []
+    for t in templates.values():
+        vh = t.value_history
+        example_question = vh.questions[-1] if vh.questions else ""
+        last_natural_language = vh.natural_language[-1] if vh.natural_language else ""
+
+        results.append(
+            TemplateInfo(
+                id=t.id,
+                natural_language=last_natural_language,
+                example_question=example_question,
+                trust_level=_obfuscate_trust_level(t.trust_level),
+                source=t.source,
+            )
+        )
+    return results
+
+
+def get_rejected_templates_list(rejected: dict[str, Any]) -> list[RejectedTemplateInfo]:
+    """Build a ``RejectedTemplateInfo`` list from the rejected templates dictionary.
+
+    Args:
+
+        rejected: Dict of ``RejectedTemplate`` objects keyed by template id.
+
+    Returns:
+
+        List of ``RejectedTemplateInfo`` instances with obfuscated rejection categories.
+    """
+    results = []
+    for rt in rejected.values():
+        vh = rt.value_history
+        example_question = vh.questions[-1] if vh.questions else ""
+        last_natural_language = vh.natural_language[-1] if vh.natural_language else ""
+        rejection_count = len(vh.rejection_categories)
+
+        category_counts: dict[str, int] = {}
+        for cat in vh.rejection_categories:
+            category_counts[cat] = category_counts.get(cat, 0) + 1
+
+        results.append(
+            RejectedTemplateInfo(
+                id=rt.id,
+                natural_language=last_natural_language,
+                example_question=example_question,
+                rejection_category=_obfuscate_rejection_category(category_counts),
+                rejection_count=rejection_count,
+            )
+        )
+    return results
+
+
+def get_simulator_summary_from_dir(artifacts_dir: str, version: int) -> SimulatorSummary:
+    """Build a ``SimulatorSummary`` from a persisted simulation report file.
+
+    Args:
+
+        artifacts_dir: Directory containing ``simulation_report_v{version}.json``.
+        version: Simulator run version number.
+
+    Returns:
+
+        ``SimulatorSummary`` with total, success, failed counts, and success rate.
+
+    Raises:
+
+        FileNotFoundError: If the report file for *version* does not exist.
+    """
+    report_path = os.path.join(artifacts_dir, f"simulation_report_v{version}.json")
+    if not os.path.exists(report_path):
+        raise FileNotFoundError(f"Simulator report v{version} not found")
+
+    with open(report_path, encoding="utf-8") as f:
+        report = json.load(f)
+
+    total = report.get("total", 0)
+    success = report.get("success", 0)
+    failed = report.get("failed", 0)
+    success_rate = round(success / total, 3) if total > 0 else 0.0
+
+    return SimulatorSummary(
+        version=version,
+        total=total,
+        success=success,
+        failed=failed,
+        success_rate=success_rate,
+    )
+
+
+def get_artifacts_dir(
+    engine: str,
+    host: str | None,
+    database: str | None,
+    schema: str | None,
+    catalog: str | None,
+) -> str:
+    """Compute the artifacts directory path inside the platform-specific user data directory.
+
+    Args:
+
+        engine: SQL engine type, either ``"postgresql"`` or ``"databricks"``.
+        host: Database host (PostgreSQL only).
+        database: Database name (PostgreSQL only).
+        schema: Schema name.
+        catalog: Unity Catalog name (Databricks only).
+
+    Returns:
+
+        Absolute path to the artifacts directory (always writable).
+    """
+    if engine == "postgresql":
+        parts = [
+            "artifacts",
+            engine,
+            host or "localhost",
+            database or "db",
+            schema or "public",
+        ]
+    else:
+        parts = ["artifacts", engine, catalog or "catalog", schema or "schema"]
+    safe_parts = [p.replace(".", "_").replace("-", "_").replace(":", "_") for p in parts]
+    folder_name = "_".join(safe_parts)
+    base = user_data_dir(appname="text2sql", appauthor=False)
+    return os.path.join(base, folder_name)
+
+
+def resolve_qsim_path(timestamp_or_result: str | QSimSummary, artifacts_dir: str) -> str:
+    """Resolve the full file path for a QSim output JSON from a timestamp or summary.
+
+    Args:
+
+        timestamp_or_result: Either a timestamp string or a ``QSimSummary`` instance.
+        artifacts_dir: Directory where QSim output files are stored.
+
+    Returns:
+
+        Absolute path to the ``qsim_intents_with_questions_{timestamp}.json`` file.
+    """
+    if isinstance(timestamp_or_result, QSimSummary):
+        timestamp = timestamp_or_result.timestamp
+    else:
+        timestamp = timestamp_or_result
+    return os.path.join(artifacts_dir, f"qsim_intents_with_questions_{timestamp}.json")
+
+
+def get_qsim(artifacts_dir: str) -> list[QSimSummary]:
+    """Load all QSim run summaries from ``qsim_summary.json`` in temporal order.
+
+    Args:
+
+        artifacts_dir: Directory containing the ``qsim_summary.json`` file.
+
+    Returns:
+
+        List of ``QSimSummary`` instances ordered oldest-first, or an empty list if the summary file does not exist.
+    """
+    qsim_summary_path = os.path.join(artifacts_dir, "qsim_summary.json")
+    if not os.path.exists(qsim_summary_path):
+        return []
+    with open(qsim_summary_path, encoding="utf-8") as f:
+        summaries = json.load(f)
+    return [QSimSummary.from_dict(s) for s in summaries]