"""Read-only end-to-end walkthrough for new Ursa users.

This script is the consumer-side counterpart to the ingestion-flavoured
``mvp_demo_*.py`` examples. It walks the M2 read API:

    query()  -> get()  -> inspect

Run it once you've followed ``docs/source/setup.md`` and your sanity
check (``python -c 'import ursa; print(ursa.load_config())'``) prints
a working ``UrsaConfig``.

Profile: defaults to ``CONSTELLATION_PROFILE=testing`` (the documented
on-ramp). Switch to ``production`` only if the testing bucket is empty
under your install — see the empty-catalog branch below.
"""

from __future__ import annotations

import ursa
from ursa.catalog import Catalog
from ursa.store import get_store

# ENG-1063's first registered recording, used as the empty-catalog
# fallback below. Valid under CONSTELLATION_PROFILE=production.
PINNED_DEMO_RECORDING = "rec_20260325_195950_c924"


def main() -> None:
    cat = Catalog.from_store(get_store("assets_ro"))

    # 1) Discovery: no filters, capped to a handful so we don't dump the
    #    entire catalog. ``limit=`` is a result cap, not a scan cap.
    results = ursa.query(catalog=cat, limit=5)

    if not results:
        print(
            "Catalog empty for current CONSTELLATION_PROFILE. "
            "Try CONSTELLATION_PROFILE=production, or fall back to the "
            "pinned demo recording per docs/source/setup.md troubleshooting:\n"
            f"  ursa.query(catalog=cat, recording_hash={PINNED_DEMO_RECORDING!r})"
        )
        return

    print(f"\nFound {len(results)} recording(s):")
    for qr in results:
        print(f"  {qr.recording_hash}  modalities={sorted(qr.modalities)}  duration={qr.duration}")

    # 2) Pick the first result. QueryResult is a catalog projection of
    #    the recording row plus a narrowed modalities dict.
    first = results[0]
    print(f"\nFirst recording in detail ({first.recording_hash}):")
    print(f"  participant_ids: {first.participant_ids}")
    print(f"  start_time:      {first.start_time}")
    print(f"  metadata:        {first.metadata}")

    # 3) Materialise the bytes. In M2 every modality is raw, so
    #    ``data.modalities[name]`` is a ``RawBytes`` carrier whose
    #    ``.segments`` is a tuple of ``(object_key, bytes)``. Once
    #    Virgo's ingestion node flips a modality to
    #    ``ingestion_status="processed"`` (see ENG-1093), the payload
    #    becomes a ``temporaldata`` subclass with a different accessor
    #    surface — check docs/source/concepts.md#modalityrow for the
    #    lifecycle.
    data = ursa.get(first)
    print(f"\nMaterialised modalities ({list(data.modalities)}):")
    for name, payload in data.modalities.items():
        print(f"  {name}: {len(payload.segments)} segment(s)")


# Things this example does NOT do in M2 — they raise NotImplementedError
# against raw modalities and arrive when Virgo's ingestion node lands:
#   - time_range= / time_filters= temporal slicing  (ENG-1082)
#   - ursa.get(results, concat=True)                (ENG-1093)
#   - reads against ingestion_status="processed"    (ENG-1093)


if __name__ == "__main__":
    main()