"""API collector — transform Agent-collected structured data for bitable upsert.

The Agent already has crawl/API tools (web_crawl, web_search, etc.). This
module only handles the "shape" transformation: map arbitrary JSON records
to bitable field IDs via a ``field_mapping`` dict, then return records
ready for the upsert API.

Usage::

    transformed = transform_records(
        records=[{"name": "Alice", "age": 30}],
        field_mapping={"name": "fld_abc", "age": "fld_def"},
    )
    # → [{"fld_abc": "Alice", "fld_def": 30}]
"""

from __future__ import annotations


def transform_records(
    records: list[dict[str, object]],
    field_mapping: dict[str, str],
) -> list[dict[str, object]]:
    """Map source record keys to bitable field IDs via field_mapping.

    Keys not in ``field_mapping`` are dropped. Values are passed through
    as-is (the bitable upsert API handles type coercion).

    Args:
        records: List of source records (arbitrary keys).
        field_mapping: ``{source_key: bitable_field_id}``.

    Returns:
        List of records with bitable field IDs as keys.
    """
    if not records:
        return []
    if not field_mapping:
        return []

    transformed: list[dict[str, object]] = []
    for rec in records:
        out: dict[str, object] = {}
        for src_key, field_id in field_mapping.items():
            if src_key in rec:
                out[field_id] = rec[src_key]
        if out:
            transformed.append(out)
    return transformed