"""FinData OS access from Python through the compiled client (`raid._core`). The API key is read by the C++ client
from FINDATA_API_KEY or FINDATA_API_KEY_FILE — never passed through Python, never logged, never cached in files.

    from raid.findata import bars, export, catalog, sessions
    b = bars("AAPL", "1m", "2024-11-25", "2024-11-29")          # dict of NumPy arrays + provenance (dataset version, request ids)
    e = export(["AAPL", "MSFT"], "2024-01-01", "2024-12-31")       # async Parquet export → cached file + sha256
"""
from __future__ import annotations
from typing import Any, Sequence


def _core():
    from . import _core as c
    if c is None:
        raise ImportError("raid._core is not built")
    return c


def bars(symbol: str, interval: str = "1m", start: str = "", end: str = "", adjustment: str = "raw", cache_dir: str = "", offline: bool = False) -> dict[str, Any]:
    """1m/5m/1d bars via Arrow pages (≤ 31/186/3650 days per call, chunked and paginated), cached per dataset version."""
    return _core().findata_bars(symbol, interval, start, end, adjustment, cache_dir, offline)


def export(symbols: Sequence[str], start: str, end: str, dataset_id: str = "market_bars.stock.1m.raw", adjustment: str = "raw", out_path: str = "", cache_dir: str = "") -> dict[str, Any]:
    """Asynchronous Parquet export (≤ 12 years per request) with polling, download, SHA-256 and dataset version."""
    return _core().findata_export(list(symbols), dataset_id, start, end, adjustment, out_path, cache_dir)


def health() -> dict: return _core().findata_json("health")
def catalog() -> dict: return _core().findata_json("catalog")
def dataset(dataset_id: str) -> dict: return _core().findata_json("dataset", dataset_id)
def sessions(symbol: str, start: str, end: str, interval: str = "1m") -> dict: return _core().findata_json("sessions", symbol, interval, f"{start} {end}")
def coverage(dataset_id: str = "market_bars.stock.1m.raw", min_sessions: int = 250) -> list: return _core().findata_json("coverage", dataset_id, "", "", min_sessions)
def fundamentals(entity: str, as_of: str, metrics: Sequence[str] = ()) -> dict: return _core().findata_json("fundamentals", entity, as_of, ",".join(metrics))
def query(sql: str, max_rows: int = 1000) -> dict: return _core().findata_json("query", sql, "", "", max_rows)


def read_parquet(path: str, symbols: Sequence[str] = ()) -> dict[str, Any]:
    """Read a FinData bars Parquet file (schema v1) into per-symbol NumPy dicts (requires the Arrow build)."""
    return _core().read_bars_parquet(path, list(symbols))