[NOTICKET] Humanize check output: hide UUIDs, add lead-in, list format

Turn the deterministic check reply into something that reads like an answer
instead of a raw catalog dump:

- Hide internal id columns (source_id/table_id/column_id) from rendered output.
- Humanize + localize (EN/ID) headers and the source_type enum
(tabular -> "File tabular"/"Tabular file", schema -> "Database", etc.).
- Add localized lead-in sentences ("Berikut data yang kamu punya:", "Kamu
punya N sumber data terstruktur:", "Berikut isi X:").
- Render the source *listing* as a grouped bullet list (structured vs
documents) rather than a table; the column-level schema drill-down stays a
table since that data is genuinely tabular.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/agents/handlers/check.py

@@ -54,9 +54,40 @@ _DATA_CUES = (
 )
 
 
+# Internal id columns — meaningful to the system (drill-down keys off them via
+# the ToolOutput rows), but noise in a user-facing answer. Hidden from the
+# rendered table; the raw ToolOutput still carries them for _matched_source_ids.
+# `table_count` is kept: always 1 for a tabular file, but the real table count
+# for a database, which is worth showing.
+_HIDDEN_COLUMNS = frozenset({"source_id", "table_id", "column_id"})
+
+# Friendly, localized labels for the catalog column ids the tools emit. Any
+# column not listed falls back to its raw name.
+_HEADER_LABELS = {
+    "English": {
+        "name": "Name", "source_type": "Type", "table_count": "Tables",
+        "table_name": "Table", "table_row_count": "Rows",
+        "column_name": "Column", "data_type": "Data type",
+        "nullable": "Nullable", "pii_flag": "PII",
+    },
+    "Indonesian": {
+        "name": "Nama", "source_type": "Jenis", "table_count": "Jumlah tabel",
+        "table_name": "Tabel", "table_row_count": "Jumlah baris",
+        "column_name": "Kolom", "data_type": "Tipe data",
+        "nullable": "Boleh kosong", "pii_flag": "PII",
+    },
+}
+
+# Friendly values for the raw `source_type` enum ("schema"/"tabular"/"unstructured").
+_SOURCE_TYPE_LABELS = {
+    "English": {"tabular": "Tabular file", "schema": "Database", "unstructured": "Document"},
+    "Indonesian": {"tabular": "File tabular", "schema": "Database", "unstructured": "Dokumen"},
+}
+
+
 # User-facing fixed strings, localized by reply language (detect_reply_language
-# returns "Indonesian"/"English"). Table headers stay as the tool's technical
-# column ids; only the prose the user reads is translated.
+# returns "Indonesian"/"English"). Table headers/values are humanized via the
+# maps above; only the prose the user reads is translated here.
 _STRINGS = {
     "English": {
         "no_match": "Nothing registered yet — I don't see any matching sources.",
@@ -80,6 +111,31 @@ def _s(reply_language: str) -> dict[str, str]:
     return _STRINGS.get(reply_language, _STRINGS["English"])
 
 
+# Natural-language lead-ins so a check reply reads like an answer, not a raw
+# table dump. `{n}` = item count, `{s}` = English plural suffix, `{name}` = source.
+_LEADS = {
+    "English": {
+        "opener": "Here's what you have:",
+        "structured": "You have {n} structured data source{s}:",
+        "documents": "You have {n} document{s}:",
+        "schema": "Here's what's inside {name}:",
+    },
+    "Indonesian": {
+        "opener": "Berikut data yang kamu punya:",
+        "structured": "Kamu punya {n} sumber data terstruktur:",
+        "documents": "Kamu punya {n} dokumen:",
+        "schema": "Berikut isi {name}:",
+    },
+}
+
+
+def _lead(kind: str, reply_language: str, n: int = 0, name: str = "") -> str:
+    """Build a localized lead-in sentence (English pluralizes on {n})."""
+    bundle = _LEADS.get(reply_language, _LEADS["English"])
+    suffix = "s" if (reply_language == "English" and n != 1) else ""
+    return bundle[kind].format(n=n, s=suffix, name=name)
+
+
 def _intent(message: str) -> str:
     """Return 'knowledge', 'data', or 'both' (helicopter view) from keyword cues."""
     lowered = message.lower()
@@ -100,14 +156,67 @@ def render_tool_output(out: ToolOutput, reply_language: str = "English") -> str:
     rows = out.rows or []
     if not rows:
         return ""
-    header = "| " + " | ".join(columns) + " |"
-    separator = "| " + " | ".join("---" for _ in columns) + " |"
+
+    # Drop internal id columns, humanize the rest of the headers, and translate
+    # the source_type enum — the user sees names, not UUIDs and raw enums.
+    keep = [i for i, c in enumerate(columns) if c not in _HIDDEN_COLUMNS] or list(
+        range(len(columns))
+    )
+    labels = _HEADER_LABELS.get(reply_language, _HEADER_LABELS["English"])
+    type_labels = _SOURCE_TYPE_LABELS.get(reply_language, _SOURCE_TYPE_LABELS["English"])
+    type_idx = columns.index("source_type") if "source_type" in columns else -1
+
+    def _cell(i: int, row: list) -> str:
+        if i == type_idx:
+            return type_labels.get(str(row[i]), str(row[i]))
+        return str(row[i])
+
+    header = "| " + " | ".join(labels.get(columns[i], columns[i]) for i in keep) + " |"
+    separator = "| " + " | ".join("---" for _ in keep) + " |"
     body = "\n".join(
-        "| " + " | ".join(str(cell) for cell in row) + " |" for row in rows
+        "| " + " | ".join(_cell(i, row) for i in keep) + " |" for row in rows
     )
     return f"{header}\n{separator}\n{body}"
 
 
+def _render_source_list(out: ToolOutput, reply_language: str) -> str:
+    """Render a check_data/check_knowledge *listing* as a bullet list, not a table.
+
+    One bullet per source: `- name — Type (N tables)`. The type + table-count
+    annotation is only added for structured sources (file vs database); documents
+    are all "unstructured", so the section header already says so — just the name.
+    Returns '' when there are no rows. (The column-level schema drill-down still
+    renders as a table via `render_tool_output` — that data is genuinely tabular.)
+    """
+    if out.kind == "error":
+        return _s(reply_language)["lookup_error"].format(error=out.error)
+    columns = out.columns or []
+    rows = out.rows or []
+    if not rows:
+        return ""
+
+    idx = {c: i for i, c in enumerate(columns)}
+    type_labels = _SOURCE_TYPE_LABELS.get(reply_language, _SOURCE_TYPE_LABELS["English"])
+
+    def _table_word(n: int) -> str:
+        if reply_language == "English":
+            return "table" if n == 1 else "tables"
+        return "tabel"
+
+    items: list[str] = []
+    for row in rows:
+        name = str(row[idx["name"]]) if "name" in idx else ""
+        st = str(row[idx["source_type"]]) if "source_type" in idx else ""
+        annotation = ""
+        if st and st != "unstructured":
+            annotation = type_labels.get(st, st)
+            if "table_count" in idx:
+                tc = row[idx["table_count"]]
+                annotation += f" ({tc} {_table_word(int(tc))})"
+        items.append(f"- {name} — {annotation}" if annotation else f"- {name}")
+    return "\n".join(items)
+
+
 def _matched_source_ids(message: str, inventory: ToolOutput) -> list[str]:
     """All source_ids whose name appears as a whole word in the message.
 
@@ -143,18 +252,19 @@ def _render_helicopter(
     strings = _s(reply_language)
     parts: list[str] = []
 
-    data_table = render_tool_output(data_out, reply_language)
-    if data_table:
-        parts.append(f"**{strings['structured']}**\n{data_table}")
+    data_list = _render_source_list(data_out, reply_language)
+    if data_list:
+        parts.append(f"{strings['structured']}:\n{data_list}")
 
-    knowledge_table = render_tool_output(knowledge_out, reply_language)
-    if knowledge_table:
-        parts.append(f"**{strings['documents']}**\n{knowledge_table}")
+    knowledge_list = _render_source_list(knowledge_out, reply_language)
+    if knowledge_list:
+        parts.append(f"{strings['documents']}:\n{knowledge_list}")
 
     if not parts:
         return strings["none"]
 
-    return "\n\n".join(parts)
+    opener = _lead("opener", reply_language)
+    return opener + "\n\n" + "\n\n".join(parts)
 
 
 async def run_check(
@@ -172,7 +282,10 @@ async def run_check(
 
     if intent == "knowledge":
         out = await invoker.invoke("check_knowledge", {})
-        return render_tool_output(out, reply_language) or _no_match
+        listing = _render_source_list(out, reply_language)
+        if not listing:
+            return _no_match
+        return _lead("documents", reply_language, len(out.rows or [])) + "\n\n" + listing
 
     if intent == "data":
         inventory = await invoker.invoke("check_data", {})
@@ -182,12 +295,20 @@ async def run_check(
         # none, return the source listing.
         source_ids = _matched_source_ids(message, inventory)
         if not source_ids:
-            return render_tool_output(inventory, reply_language) or _no_match
+            listing = _render_source_list(inventory, reply_language)
+            if not listing:
+                return _no_match
+            n = len(inventory.rows or [])
+            return _lead("structured", reply_language, n) + "\n\n" + listing
         schemas = await asyncio.gather(
             *(invoker.invoke("check_data", {"source_id": sid}) for sid in source_ids)
         )
         if len(schemas) == 1:
-            return render_tool_output(schemas[0], reply_language) or _no_match
+            table = render_tool_output(schemas[0], reply_language)
+            if not table:
+                return _no_match
+            name = (schemas[0].meta or {}).get("source_name") or ""
+            return _lead("schema", reply_language, name=name) + "\n\n" + table
         # Multiple named sources → one labelled section per source.
         sections: list[str] = []
         for out in schemas: