[KM-630] Data-Access Tools: coerce DB Decimal to float

DB NUMERIC columns arrive as decimal.Decimal (asyncpg). This broke
analyze_contribution with a `float + Decimal` TypeError, and the same
Decimal would also break JSON serialization (SSE / analysis_record) of
query_structured output.

- query_structured: _json_safe coerces Decimal -> float when building
ToolOutput.rows, so the output is JSON-safe at the source.
- _materialize: _coerce_decimals normalizes Decimal object-columns to
float64 so the whole analyze_* family receives consistent float input.

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

src/tools/data_access.py

@@ -25,6 +25,7 @@ Frozen guarantee (§8.4): **never throws.** Any failure returns
 from __future__ import annotations
 
 from collections.abc import Callable
+from decimal import Decimal
 from typing import Any, Protocol
 
 from pydantic import ValidationError
@@ -216,8 +217,13 @@ class DataAccessToolInvoker:
             )
 
         # QueryResult.rows is list[dict]; ToolOutput.rows is list[list] ordered
-        # by `columns` so downstream materialization is positional.
-        rows = [[row.get(c) for c in result.columns] for row in result.rows]
+        # by `columns` so downstream materialization is positional. DB NUMERIC
+        # columns arrive as `Decimal` (asyncpg) — coerce to float here so the
+        # output is JSON-serializable (SSE / analysis_record persistence) and
+        # plays nicely with the float math in the analyze_* tools.
+        rows = [
+            [_json_safe(row.get(c)) for c in result.columns] for row in result.rows
+        ]
         return ToolOutput(
             tool="query_structured",
             kind="table",
@@ -296,6 +302,18 @@ class DataAccessToolInvoker:
         )
 
 
+def _json_safe(value: Any) -> Any:
+    """Coerce DB scalar types that JSON can't represent into plain Python.
+
+    DB drivers return NUMERIC/DECIMAL as `decimal.Decimal`, which is neither
+    JSON-serializable nor mixable with `float` math. Convert those to `float`;
+    everything else passes through unchanged.
+    """
+    if isinstance(value, Decimal):
+        return float(value)
+    return value
+
+
 def _result_source_id(result: RetrievalResult) -> str | None:
     """Best-effort extraction of a source_id from a retrieval result's metadata.
 

src/tools/invoker.py

@@ -20,6 +20,7 @@ keeps working.
 
 from __future__ import annotations
 
+import decimal
 from collections.abc import Callable
 from typing import Any
 
@@ -126,21 +127,43 @@ def _materialize(data: Any) -> tuple[pd.DataFrame, None] | tuple[None, str]:
     Accepts the upstream `ToolOutput` (kind="table"), a raw DataFrame, or a
     {"columns", "rows"} dict (a serialized table). Returns (df, None) on success
     or (None, error_message) on failure — the caller wraps the message.
+
+    Numeric columns are coerced to float (see `_coerce_decimals`): DB NUMERIC
+    columns arrive as Python `Decimal`, which mixes badly with the float math in
+    the `analyze_*` compute functions (e.g. `float + Decimal` -> TypeError).
+    Normalizing here fixes the whole tool family in one place.
     """
     if data is None:
         return None, "missing 'data' argument (no upstream table to analyze)"
 
     if isinstance(data, pd.DataFrame):
-        return data, None
+        return _coerce_decimals(data), None
 
     if isinstance(data, ToolOutput):
         if data.kind == "error":
             return None, f"upstream data unavailable: {data.error}"
         if data.kind != "table" or data.columns is None:
             return None, f"cannot materialize 'data' of kind {data.kind!r}"
-        return pd.DataFrame(data.rows or [], columns=data.columns), None
+        return _coerce_decimals(pd.DataFrame(data.rows or [], columns=data.columns)), None
 
     if isinstance(data, dict) and "columns" in data:
-        return pd.DataFrame(data.get("rows") or [], columns=data["columns"]), None
+        df = pd.DataFrame(data.get("rows") or [], columns=data["columns"])
+        return _coerce_decimals(df), None
 
     return None, f"unsupported 'data' type: {type(data).__name__}"
+
+
+def _coerce_decimals(df: pd.DataFrame) -> pd.DataFrame:
+    """Convert `decimal.Decimal` object-columns to float64 in place.
+
+    DB drivers (asyncpg) return NUMERIC/DECIMAL values as Python `Decimal`, which
+    land in object-dtype columns. The `analyze_*` compute functions do float math
+    on these (share-of-total, cumulative sums), and `float + Decimal` raises
+    TypeError. We only touch columns that actually contain a `Decimal`, so real
+    string/categorical columns are left untouched. `None`/missing values become
+    NaN, which the compute functions already handle.
+    """
+    for col in df.columns:
+        if df[col].dtype == object and df[col].map(lambda v: isinstance(v, decimal.Decimal)).any():
+            df[col] = df[col].astype(float)
+    return df