refactor: split streamlit_app.py 1184→200 lines (Kimi P1.3)

Decompose monolithic streamlit_app.py into focused modules:

- app/i18n.py — I18N dict + t() helper (187 lines)
- app/theme.py — FONT_CSS + inject_chrome + chart palette (343 lines)
- app/samples.py — SAMPLE_QUESTIONS + SOURCE_LINKS (122 lines)
- app/bootstrap.py — bootstrap + make_pipeline (93 lines)
- app/components/output.py — render_output + chart helpers (83 lines)
- app/components/show_working.py — render_show_working (55 lines)
- app/components/schema_explorer.py — render_schema_explorer (42 lines)
- app/components/welcome.py — render_welcome + render_lang_toggle (104 lines)

streamlit_app.py becomes a thin entry-point (main + replay turn), 200 lines.
pyproject.toml: add "app" to ruff src so sibling imports sort first-party.

Zero behavior change verified via local Streamlit + Playwright E2E:
EN 94.0% renders, RU toggle switches to 94,0%, schema explorer label
visible. 357 pytest pass, ruff + mypy strict clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: JuliaEdom

app/bootstrap.py

@@ -0,0 +1,93 @@
+"""Resource bootstrap + pipeline factory for the Streamlit UI."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import chromadb
+import streamlit as st
+
+from nl_sql.agent.graph import PipelineConfig, build_pipeline
+from nl_sql.config import get_settings
+from nl_sql.db.registry import DatabaseRegistry, get_default_registry
+from nl_sql.llm.cache import CachingEmbeddingProvider, CachingLLMProvider
+from nl_sql.llm.providers import build_provider
+from nl_sql.llm.providers.base import EmbeddingProvider, LLMProvider
+from nl_sql.llm.providers.mistral import MistralProvider
+from nl_sql.schema_index.indexer import SchemaIndex
+
+
+@st.cache_resource(show_spinner="Initialising providers + Chroma index…")
+def bootstrap() -> tuple[DatabaseRegistry, SchemaIndex, LLMProvider, LLMProvider]:
+    settings = get_settings()
+    if not settings.mistral_api_key:
+        raise RuntimeError(
+            "MISTRAL_API_KEY is not set in .env — required for codestral + mistral-embed."
+        )
+
+    registry = get_default_registry()
+
+    persist_dir = Path("chroma_data")
+    if not persist_dir.is_dir():
+        raise RuntimeError(
+            f"Chroma persist dir {persist_dir!r} not found. "
+            "Run `uv run python scripts/build_index.py --db all` first."
+        )
+    chroma_client = chromadb.PersistentClient(path=str(persist_dir))
+
+    raw_embedder = MistralProvider(
+        api_key=settings.mistral_api_key,
+        gen_model=settings.mistral_gen_model,
+        embed_model=settings.mistral_embed_model,
+        base_url=settings.mistral_base_url,
+    )
+    embedder: EmbeddingProvider = CachingEmbeddingProvider(
+        raw_embedder,
+        cache_dir=settings.llm_cache_dir,
+        size_limit_gb=settings.llm_cache_size_limit_gb,
+    )
+    schema_index = SchemaIndex(persist_dir=persist_dir, embedder=embedder, client=chroma_client)
+
+    raw_sql = build_provider("mistral", settings=settings)
+    sql_provider: LLMProvider = CachingLLMProvider(
+        raw_sql,
+        cache_dir=settings.llm_cache_dir,
+        size_limit_gb=settings.llm_cache_size_limit_gb,
+    )
+    explain_provider = sql_provider
+
+    return registry, schema_index, sql_provider, explain_provider
+
+
+def make_pipeline(
+    registry: DatabaseRegistry,
+    schema_index: SchemaIndex,
+    sql_provider: LLMProvider,
+    explain_provider: LLMProvider,
+    *,
+    schema_top_k: int,
+    fk_hops: int,
+    table_budget: int,
+    sort_schema_block: bool,
+    extended_sample_size: int,
+    fewshot_top_k: int = 3,
+    cross_db_fewshot: bool = True,
+    verify_retry_on_empty: bool = True,
+) -> Any:
+    config = PipelineConfig(
+        sql_provider=sql_provider,
+        explain_provider=explain_provider,
+        schema_index=schema_index,
+        registry=registry,
+        schema_top_k=schema_top_k,
+        fewshot_top_k=fewshot_top_k,
+        fk_hops=fk_hops,
+        table_budget=table_budget,
+        sort_schema_block=sort_schema_block,
+        primary_sample_size=3,
+        extended_sample_size=extended_sample_size,
+        cross_db_fewshot=cross_db_fewshot,
+        verify_retry_on_empty=verify_retry_on_empty,
+    )
+    return build_pipeline(config)

app/components/__init__.py

@@ -0,0 +1 @@
+"""UI components for the Streamlit assistant."""

app/components/output.py

@@ -0,0 +1,83 @@
+"""Output renderers: scalar, sentence, table, chart + label helpers."""
+
+from __future__ import annotations
+
+import pandas as pd
+import plotly.express as px
+import streamlit as st
+
+from i18n import t
+from nl_sql.render.formats import (
+    BarChart,
+    LineChart,
+    OutputFormat,
+    PieChart,
+    Scalar,
+    ScatterChart,
+    Sentence,
+    Table,
+)
+from nl_sql.render.labels import classify_scalar_label
+from theme import style_fig
+
+
+def scalar_metric_label(column: str) -> str:
+    """Translate a raw SQL column label into a localized business label
+    (audit P2 #5). Engine columns like ``COUNT(DISTINCT s.CDSCode)`` become
+    "Count" / "Количество"; identifier-like columns (``total_revenue``) are
+    kept as-is."""
+    kind = classify_scalar_label(column)
+    if kind == "identifier":
+        return column
+    return t(f"scalar_label_{kind}")
+
+
+def confidence_label(value: float) -> str:
+    if value >= 0.8:
+        return t("conf_high")
+    if value >= 0.5:
+        return t("conf_med")
+    if value > 0.0:
+        return t("conf_low")
+    return t("conf_unknown")
+
+
+def render_chart(
+    spec: BarChart | LineChart | PieChart | ScatterChart,
+    df: pd.DataFrame,
+) -> None:
+    if isinstance(spec, BarChart):
+        fig = px.bar(df, x=spec.x_field, y=spec.y_fields)
+    elif isinstance(spec, LineChart):
+        fig = px.line(df, x=spec.x_field, y=spec.y_fields)
+    elif isinstance(spec, PieChart):
+        y_field = spec.y_fields[0] if spec.y_fields else df.columns[1]
+        fig = px.pie(df, names=spec.x_field, values=y_field)
+    else:
+        y_field = spec.y_fields[0] if spec.y_fields else df.columns[1]
+        fig = px.scatter(df, x=spec.x_field, y=y_field)
+    st.plotly_chart(style_fig(fig), use_container_width=True)
+
+
+def render_output(output: OutputFormat | None, *, caption: str) -> None:
+    if isinstance(output, Scalar):
+        st.metric(scalar_metric_label(output.column), str(output.value))
+    elif isinstance(output, Sentence):
+        st.markdown(
+            f"<div style=\"font-family:'NLEdSerif',Georgia,serif; "
+            f"font-size:1.25rem; line-height:1.45; color:var(--ink); "
+            f'margin:0.4rem 0 0.6rem;">{output.text}</div>',
+            unsafe_allow_html=True,
+        )
+        if output.fields:
+            st.json(output.fields, expanded=False)
+    elif isinstance(output, Table):
+        df = pd.DataFrame(output.rows, columns=output.columns)
+        st.dataframe(df, use_container_width=True, hide_index=True)
+    elif isinstance(output, BarChart | LineChart | PieChart | ScatterChart):
+        df = pd.DataFrame(output.rows, columns=output.columns)
+        render_chart(output, df)
+    elif output is None:
+        st.warning(t("no_output_warning"))
+    if caption:
+        st.caption(caption)

app/components/schema_explorer.py

@@ -0,0 +1,42 @@
+"""Sidebar schema explorer: per-table chunk cards rendered from the index."""
+
+from __future__ import annotations
+
+import streamlit as st
+
+from i18n import t
+
+
+@st.cache_data(show_spinner=False)
+def fetch_schema_chunks(_index_id: int, db_id: str) -> list[tuple[str, str]]:
+    schema_index = st.session_state.get("_schema_index")
+    if schema_index is None:
+        return []
+    records = schema_index.schema_collection.get(
+        where={"db_id": db_id},
+        include=["documents", "metadatas"],
+    )
+    docs = records.get("documents") or []
+    metas = records.get("metadatas") or []
+    pairs: list[tuple[str, str]] = []
+    for doc, meta in zip(docs, metas, strict=False):
+        table_name = str((meta or {}).get("table_name") or "")
+        if table_name:
+            pairs.append((table_name, str(doc)))
+    pairs.sort(key=lambda p: p[0].lower())
+    return pairs
+
+
+def render_schema_explorer(db_id: str) -> None:
+    schema_index = st.session_state.get("_schema_index")
+    if schema_index is None:
+        return
+    chunks = fetch_schema_chunks(id(schema_index), db_id)
+    if not chunks:
+        st.caption(t("schema_explorer_empty"))
+        return
+    with st.expander(t("schema_explorer_collapsed", n=len(chunks)), expanded=False):
+        st.caption(t("schema_explorer_caption"))
+        for table_name, text in chunks:
+            with st.expander(table_name, expanded=False):
+                st.code(text, language="text")

app/components/show_working.py

@@ -0,0 +1,55 @@
+"""Show-working expander: pipeline trace, metadata, shape, rationale."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+import streamlit as st
+
+from components.output import confidence_label
+from i18n import t
+from nl_sql.agent.graph import PipelineRunResult
+
+
+def render_show_working(result: PipelineRunResult) -> None:
+    with st.expander(t("show_working")):
+        trace_rows: list[dict[str, Any]] = []
+        for entry in result.trace:
+            trace_rows.append(
+                {
+                    "node": str(entry.get("node", "?")),
+                    "model": str(entry.get("model", "—")),
+                    "tokens_in": entry.get("input_tokens", "—"),
+                    "tokens_out": entry.get("output_tokens", "—"),
+                    "confidence": entry.get("confidence", "—"),
+                }
+            )
+        if trace_rows:
+            st.markdown(f"**{t('trace_header')}**")
+            st.dataframe(
+                pd.DataFrame(trace_rows),
+                use_container_width=True,
+                hide_index=True,
+            )
+
+        col_a, col_b = st.columns(2)
+        with col_a:
+            st.markdown(f"**{t('meta_header')}**")
+            conf_label = confidence_label(result.confidence)
+            st.markdown(f"- {t('confidence_label')}: **{conf_label}** ({result.confidence:.2f})")
+            st.markdown(f"- {t('repair_attempted')}: {result.repair_attempted}")
+            st.markdown(f"- {t('db_field')}: `{result.db_id}`")
+        with col_b:
+            st.markdown(f"**{t('shape_header')}**")
+            if result.outcome and result.outcome.result:
+                st.markdown(f"- {t('rows_returned')}: {result.outcome.result.row_count}")
+                cols = ", ".join(result.outcome.result.columns) or "—"
+                st.markdown(f"- {t('columns_field')}: {cols}")
+            else:
+                st.markdown(f"- {t('no_rows')}")
+        if result.rationale:
+            st.markdown(f"**{t('rationale_header')}**")
+            st.write(result.rationale)
+        if result.error_kind:
+            st.error(f"{t('error_kind')}: {result.error_kind} — {result.error_message}")

app/components/welcome.py

@@ -0,0 +1,104 @@
+"""Hero block + sample question cards + sidebar language toggle."""
+
+from __future__ import annotations
+
+import streamlit as st
+
+from i18n import t
+from samples import SAMPLE_QUESTIONS
+
+
+def render_lang_toggle() -> None:
+    """Two flat segments: EN / RU. Active one inverts."""
+    lang = st.session_state.get("lang", "en")
+    st.markdown(f"<div class='nl-side-sub'>{t('lang_label')}</div>", unsafe_allow_html=True)
+    cols = st.columns(2)
+    with cols[0]:
+        if st.button(
+            t("lang_en"),
+            key="lang_en_btn",
+            use_container_width=True,
+            type="primary" if lang == "en" else "secondary",
+        ):
+            st.session_state.lang = "en"
+            st.rerun()
+    with cols[1]:
+        if st.button(
+            t("lang_ru"),
+            key="lang_ru_btn",
+            use_container_width=True,
+            type="primary" if lang == "ru" else "secondary",
+        ):
+            st.session_state.lang = "ru"
+            st.rerun()
+
+
+def render_welcome(db_id: str) -> None:
+    st.markdown(
+        "<div class='nl-display'>NL<span class='arrow'>→</span>SQL</div>",
+        unsafe_allow_html=True,
+    )
+    st.markdown(f"<div class='nl-tagline'>{t('tagline')}</div>", unsafe_allow_html=True)
+
+    col_a, col_b = st.columns(2)
+    with col_a:
+        st.markdown(
+            f"""
+            <div class='nl-metric'>
+              <div class='nl-kicker'>{t("metric_kicker")}</div>
+              <div class='nl-metric-row'>
+                <span class='nl-metric-value'>{t("metric_value")}</span>
+                <span class='nl-metric-aside'>{t("metric_percent")}</span>
+              </div>
+              <div class='nl-metric-cap'>{t("metric_caption")}</div>
+            </div>
+            """,
+            unsafe_allow_html=True,
+        )
+    with col_b:
+        st.markdown(
+            f"""
+            <div class='nl-metric'>
+              <div class='nl-kicker'>{t("research_kicker")}</div>
+              <div class='nl-metric-row'>
+                <span class='nl-metric-value'>{t("research_value")}</span>
+              </div>
+              <div class='nl-metric-cap'>{t("research_caption")}</div>
+            </div>
+            """,
+            unsafe_allow_html=True,
+        )
+
+    samples = SAMPLE_QUESTIONS.get(db_id)
+    if not samples:
+        st.markdown(
+            f"<div class='nl-section-label'>{t('ask_intro_label')}</div>",
+            unsafe_allow_html=True,
+        )
+        st.info(t("no_samples"))
+        return
+
+    st.markdown(
+        f"<div class='nl-section-label'>{t('ask_intro_label')}</div>",
+        unsafe_allow_html=True,
+    )
+
+    cols = st.columns(len(samples))
+    diff_map = {
+        "simple": t("diff_simple"),
+        "moderate": t("diff_moderate"),
+        "challenging": t("diff_challenging"),
+    }
+    for col, (difficulty, question) in zip(cols, samples, strict=False):
+        with col:
+            st.markdown(
+                f"<div class='nl-sample-kicker'>{diff_map.get(difficulty, difficulty)}</div>",
+                unsafe_allow_html=True,
+            )
+            if st.button(
+                question,
+                key=f"sample_{db_id}_{hash(question)}",
+                use_container_width=True,
+            ):
+                st.session_state.pending_question = question
+                st.rerun()