@nomadamas/k-skill 0.9.2 → 0.10.0

package/skills/market-event-impact/scripts/event_study.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Deterministic event-window, curve, and threshold calculations."""
+
+from __future__ import annotations
+
+from datetime import date, datetime, time, timedelta, timezone
+from typing import Any, Iterable
+
+from calendars import TIMEZONE_CLOSES, align_date, window_indices, zone_for_date
+
+
+DEFAULT_OFFSETS = (-1, 0, 1, 5)
+
+
+def _change(value: float | None, anchor: float | None, rates: bool, unit: str = "pct") -> float | None:
+    if value is None or anchor is None:
+        return None
+    if rates:
+        scale = 1.0 if unit.casefold() == "bp" else 100.0
+        return round((value - anchor) * scale, 10)
+    if anchor == 0:
+        return None
+    return round((value / anchor - 1.0) * 100.0, 10)
+
+
+def analyze_series(series: dict[str, Any], event_date: str, alignment: str = "next",
+                   offsets: Iterable[int] = DEFAULT_OFFSETS, alignment_date: str | None = None) -> dict[str, Any]:
+    observations = series["observations"]
+    dates = [row["date"] for row in observations]
+    target_date = alignment_date or event_date
+    aligned, anchor_index = align_date(target_date, dates, alignment)
+    result = {
+        "symbol": series["symbol"],
+        "region": series.get("region"),
+        "asset_class": series["asset_class"],
+        "unit": series["unit"],
+        "event_date": event_date,
+        "alignment_anchor_date": target_date,
+        "aligned_event_date": aligned,
+        "alignment": alignment,
+        "alignment_basis": series.get("alignment_basis", "region_calendar_proxy"),
+        "observation_provenance": {
+            "observation_timezone": series.get("observation_timezone"),
+            "observation_time": series.get("observation_time"),
+            "market_timezone": series.get("market_timezone"),
+            "price_type": series.get("price_type"),
+        },
+        "source": series["source"],
+        "latest_observation_date": dates[-1] if dates else None,
+        "window": {},
+        "warnings": [],
+    }
+    if anchor_index is None:
+        result["failure"] = "no_observation_for_alignment"
+        return result
+    positions = window_indices(anchor_index, len(observations), offsets)
+    rates = series["asset_class"].casefold() in {"rates", "policy", "spread", "credit"}
+    base_index = positions.get(-1)
+    base = observations[base_index]["value"] if base_index is not None else None
+    for offset, index in positions.items():
+        key = "d0" if offset == 0 else f"d{offset:+d}"
+        row = observations[index] if index is not None else None
+        result["window"][key] = {
+            "date": row["date"] if row else None,
+            "value": row["value"] if row else None,
+            "change_from_d_minus_1": _change(row["value"] if row else None, base, rates, series["unit"]),
+            "change_unit": "bp" if rates else "pct",
+        }
+        if row is None:
+            warning = f"pending_{key}" if offset > 0 and anchor_index + offset >= len(observations) else f"missing_{key}"
+            result["warnings"].append(warning)
+    if base is None:
+        result["warnings"].append("changes_unavailable_without_d_minus_1")
+    if not series.get("observation_timezone") or not series.get("observation_time"):
+        result["warnings"].append("observation_time_basis_missing")
+    return result
+
+
+def analyze_intraday_reaction(series: dict[str, Any], event: dict[str, Any]) -> dict[str, Any] | None:
+    """Measure source-stamped pre-event, +1h, and first-session end observations."""
+    rows = series.get("intraday_observations") or []
+    if not rows:
+        return None
+    if not event.get("event_time_local") or not event.get("event_timezone"):
+        return {"symbol": series["symbol"], "status": "unavailable", "reason": "exact_event_timestamp_required"}
+    event_day = date.fromisoformat(event["event_date"])
+    event_local_time = time.fromisoformat(event["event_time_local"])
+    event_instant = datetime.combine(
+        event_day, event_local_time, zone_for_date(event["event_timezone"], event_day)
+    ).astimezone(timezone.utc)
+    normalized = []
+    for row in rows:
+        instant = datetime.fromisoformat(str(row["timestamp"]).replace("Z", "+00:00"))
+        normalized.append((instant.astimezone(timezone.utc), instant, float(row["value"])))
+    normalized.sort(key=lambda item: item[0])
+    before = [row for row in normalized if row[0] < event_instant]
+    after = [row for row in normalized if row[0] >= event_instant]
+    one_hour_after = [row for row in normalized if row[0] >= event_instant + timedelta(hours=1)]
+    market_timezone = series.get("market_timezone") or event["event_timezone"]
+    session_end = None
+    close_confirmed = False
+    if after:
+        first_market_date = after[0][1].astimezone(zone_for_date(market_timezone, after[0][1].date())).date()
+        session_rows = [row for row in after if row[1].astimezone(zone_for_date(market_timezone, row[1].date())).date() == first_market_date]
+        if session_rows:
+            session_end = session_rows[-1]
+            close_time = TIMEZONE_CLOSES.get(market_timezone)
+            close_confirmed = bool(close_time and session_end[1].astimezone(zone_for_date(market_timezone, first_market_date)).time().replace(tzinfo=None) == close_time)
+    rates = series["asset_class"].casefold() in {"rates", "policy", "spread", "credit"}
+    unit = series["unit"]
+    anchor = before[-1] if before else None
+
+    def pack(row: tuple[datetime, datetime, float] | None) -> dict[str, Any] | None:
+        if row is None:
+            return None
+        return {
+            "timestamp": row[1].isoformat(),
+            "value": row[2],
+            "change_from_pre_event": _change(row[2], anchor[2] if anchor else None, rates, unit),
+            "change_unit": "bp" if rates else "pct",
+        }
+
+    return {
+        "symbol": series["symbol"],
+        "status": "ok",
+        "pre_event": pack(anchor),
+        "plus_1h": pack(one_hour_after[0] if one_hour_after else None),
+        "session_end": pack(session_end),
+        "session_end_label": "market_close" if close_confirmed else "last_supplied_bar_not_confirmed_close",
+        "warnings": [name for name, missing in (
+            ("intraday_missing_pre_event", anchor is None),
+            ("intraday_missing_plus_1h", not one_hour_after),
+            ("intraday_session_close_unconfirmed", session_end is not None and not close_confirmed),
+        ) if missing],
+        "source": series["source"],
+    }
+
+
+def classify_curve(short_change_bp: float | None, long_change_bp: float | None) -> dict[str, Any]:
+    if short_change_bp is None or long_change_bp is None:
+        return {"classification": None, "spread_change_bp": None}
+    spread = round(long_change_bp - short_change_bp, 10)
+    if short_change_bp > 0 and long_change_bp > 0:
+        direction = "Bear"
+    elif short_change_bp < 0 and long_change_bp < 0:
+        direction = "Bull"
+    else:
+        return {"classification": "Mixed", "spread_change_bp": spread}
+    shape = "Steepening" if spread > 0 else "Flattening" if spread < 0 else "Parallel"
+    return {"classification": f"{direction} {shape}", "spread_change_bp": spread}
+
+
+def threshold_events(series: dict[str, Any], metric: str, direction: str, threshold: float) -> list[dict[str, Any]]:
+    if direction not in {"above", "below"}:
+        raise ValueError("direction must be above or below")
+    rates = metric == "bp_change"
+    if metric not in {"bp_change", "pct_change"}:
+        raise ValueError("metric must be bp_change or pct_change")
+    is_rates = series["asset_class"].casefold() in {"rates", "policy", "spread", "credit"}
+    if rates and not is_rates:
+        raise ValueError("bp_change requires a rates, policy, spread, or credit series")
+    rows = series["observations"]
+    matches = []
+    for previous, current in zip(rows, rows[1:]):
+        value = _change(current["value"], previous["value"], rates, series["unit"])
+        if value is None:
+            continue
+        matched = value >= threshold if direction == "above" else value <= threshold
+        if matched:
+            matches.append({"date": current["date"], "metric": metric, "value": value, "threshold": threshold})
+    return matches

package/skills/market-event-impact/scripts/market_data.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""Strict JSON/CSV market-series loader with source metadata."""
+
+from __future__ import annotations
+
+import csv
+import json
+import math
+import re
+from datetime import date, datetime, time, timezone
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+from calendars import valid_timezone, zone_for_date
+
+
+class SeriesError(ValueError):
+    pass
+
+
+def _finite(value: Any) -> float:
+    if isinstance(value, bool):
+        raise SeriesError(f"not a number: {value!r}")
+    try:
+        number = float(value)
+    except (TypeError, ValueError) as exc:
+        raise SeriesError(f"not a number: {value!r}") from exc
+    if not math.isfinite(number):
+        raise SeriesError(f"not finite: {value!r}")
+    return number
+
+
+def _normalize_series(item: dict[str, Any]) -> dict[str, Any]:
+    symbol = str(item.get("symbol") or "").strip()
+    if not symbol:
+        raise SeriesError("series symbol is required")
+    region = str(item.get("region") or "").strip().upper() or None
+    if region is not None and not re.fullmatch(r"[A-Z]{2,6}", region):
+        raise SeriesError(f"{symbol}: region must be a 2-6 letter market code")
+    asset_class = str(item.get("asset_class") or "").strip().casefold()
+    if asset_class not in {"rates", "policy", "spread", "credit", "fx", "equity", "commodity", "volatility", "price"}:
+        raise SeriesError(f"{symbol}: unsupported asset_class {asset_class!r}")
+    unit = str(item.get("unit") or "").strip()
+    if not unit:
+        raise SeriesError(f"{symbol}: unit is required")
+    unit = unit.casefold()
+    if asset_class in {"rates", "policy", "spread", "credit"} and unit not in {"pct", "bp"}:
+        raise SeriesError(f"{symbol}: rates, policy, spread, and credit unit must be pct or bp")
+    source = item.get("source") if isinstance(item.get("source"), dict) else {}
+    if not str(source.get("name") or "").strip() or not str(source.get("url") or "").strip():
+        raise SeriesError(f"{symbol}: source.name and source.url are required")
+    parsed_url = urlparse(str(source["url"]))
+    if parsed_url.scheme not in {"http", "https"} or not parsed_url.netloc:
+        raise SeriesError(f"{symbol}: source.url must be an http(s) URL")
+    observations = item.get("observations")
+    if not isinstance(observations, list) or not observations:
+        raise SeriesError(f"{symbol}: observations must be a non-empty array")
+    seen: set[str] = set()
+    clean = []
+    for row in observations:
+        if not isinstance(row, dict) or "date" not in row or "value" not in row:
+            raise SeriesError(f"{symbol}: each observation needs date and value")
+        try:
+            observed = date.fromisoformat(str(row["date"])).isoformat()
+        except ValueError as exc:
+            raise SeriesError(f"{symbol}: invalid ISO date {row['date']!r}") from exc
+        if observed in seen:
+            raise SeriesError(f"{symbol}: duplicate date {observed}")
+        seen.add(observed)
+        clean.append({"date": observed, "value": _finite(row["value"])})
+    clean.sort(key=lambda row: row["date"])
+    observation_timezone = str(item.get("observation_timezone") or "").strip() or None
+    observation_time = str(item.get("observation_time") or "").strip() or None
+    market_timezone = str(item.get("market_timezone") or "").strip() or None
+    if bool(observation_timezone) != bool(observation_time):
+        raise SeriesError(f"{symbol}: observation_timezone and observation_time must be provided together")
+    for field, timezone_name in (("observation_timezone", observation_timezone), ("market_timezone", market_timezone)):
+        if timezone_name and not valid_timezone(timezone_name, date.fromisoformat(clean[0]["date"])):
+            raise SeriesError(f"{symbol}: {field} must be a valid IANA timezone")
+    if observation_time:
+        try:
+            parsed_observation_time = time.fromisoformat(observation_time)
+            if parsed_observation_time.tzinfo is not None:
+                raise ValueError
+            observation_time = parsed_observation_time.isoformat(timespec="minutes" if parsed_observation_time.second == 0 else "seconds")
+        except ValueError as exc:
+            raise SeriesError(f"{symbol}: observation_time must be local HH:MM[:SS] without an offset") from exc
+    price_type = str(item.get("price_type") or "").strip() or None
+    if price_type and len(price_type) > 64:
+        raise SeriesError(f"{symbol}: price_type must be 64 characters or fewer")
+    raw_intraday = item.get("intraday_observations") or []
+    if not isinstance(raw_intraday, list):
+        raise SeriesError(f"{symbol}: intraday_observations must be an array")
+    intraday = []
+    intraday_seen: set[str] = set()
+    for index, row in enumerate(raw_intraday):
+        if not isinstance(row, dict) or "timestamp" not in row or "value" not in row:
+            raise SeriesError(f"{symbol}: intraday_observations[{index}] needs timestamp and value")
+        try:
+            timestamp = datetime.fromisoformat(str(row["timestamp"]).replace("Z", "+00:00"))
+        except ValueError as exc:
+            raise SeriesError(f"{symbol}: invalid intraday timestamp {row.get('timestamp')!r}") from exc
+        if timestamp.tzinfo is None:
+            raise SeriesError(f"{symbol}: intraday timestamps must include a timezone offset")
+        utc_key = timestamp.astimezone(timezone.utc).isoformat()
+        if utc_key in intraday_seen:
+            raise SeriesError(f"{symbol}: duplicate intraday timestamp {timestamp.isoformat()}")
+        intraday_seen.add(utc_key)
+        intraday.append({"timestamp": timestamp.isoformat(), "value": _finite(row["value"]), "_utc": utc_key})
+    intraday.sort(key=lambda row: row["_utc"])
+    for row in intraday:
+        row.pop("_utc")
+    roles = item.get("roles") or []
+    if not isinstance(roles, list) or not all(isinstance(role, str) and role.strip() for role in roles):
+        raise SeriesError(f"{symbol}: roles must be non-empty strings")
+    priority = item.get("selection_priority", 0)
+    if isinstance(priority, bool) or not isinstance(priority, int) or not -100 <= priority <= 100:
+        raise SeriesError(f"{symbol}: selection_priority must be an integer from -100 to 100")
+    return {
+        "symbol": symbol,
+        "region": region,
+        "asset_class": asset_class,
+        "unit": unit,
+        "source": {"name": str(source.get("name")).strip(), "url": str(source.get("url")).strip()},
+        "observation_timezone": observation_timezone,
+        "observation_time": observation_time,
+        "market_timezone": market_timezone,
+        "price_type": price_type,
+        "intraday_observations": intraday,
+        "roles": list(dict.fromkeys(role.strip().casefold() for role in roles)),
+        "selection_priority": priority,
+        "observations": clean,
+    }
+
+
+def _unique_symbols(items: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    if not items:
+        raise SeriesError("series input must contain at least one series")
+    symbols = [item["symbol"].casefold() for item in items]
+    duplicates = sorted({symbol for symbol in symbols if symbols.count(symbol) > 1})
+    if duplicates:
+        raise SeriesError(f"duplicate symbols: {', '.join(duplicates)}")
+    return items
+
+
+def load_series(path_text: str) -> list[dict[str, Any]]:
+    path = Path(path_text).expanduser()
+    if not path.is_file():
+        raise SeriesError(f"series file not found: {path}")
+    if path.suffix.casefold() == ".json":
+        payload = json.loads(path.read_text(encoding="utf-8-sig"))
+        items = payload.get("series") if isinstance(payload, dict) else payload
+        if not isinstance(items, list):
+            raise SeriesError("JSON must be an array or contain a series array")
+        return _unique_symbols([_normalize_series(item) for item in items])
+    if path.suffix.casefold() == ".csv":
+        groups: dict[str, dict[str, Any]] = {}
+        with path.open(encoding="utf-8-sig", newline="") as handle:
+            for row in csv.DictReader(handle):
+                symbol = (row.get("symbol") or "").strip()
+                item = groups.setdefault(symbol, {
+                    "symbol": symbol,
+                    "region": row.get("region") or None,
+                    "asset_class": row.get("asset_class") or "price",
+                    "unit": row.get("unit") or "index",
+                    "source": {"name": row.get("source_name"), "url": row.get("source_url")},
+                    "observation_timezone": row.get("observation_timezone") or None,
+                    "observation_time": row.get("observation_time") or None,
+                    "market_timezone": row.get("market_timezone") or None,
+                    "price_type": row.get("price_type") or None,
+                    "observations": [],
+                })
+                item["observations"].append({"date": row.get("date"), "value": row.get("value")})
+        return _unique_symbols([_normalize_series(item) for item in groups.values()])
+    raise SeriesError("series input must be .json or .csv")
+
+
+def series_as_of(item: dict[str, Any], observed_at: str) -> dict[str, Any]:
+    """Exclude observations that were not yet observable at the analysis cutoff."""
+    cutoff = datetime.fromisoformat(observed_at.replace("Z", "+00:00")).astimezone(timezone.utc)
+    zone_name = item.get("observation_timezone") or item.get("market_timezone")
+    zone = zone_for_date(zone_name, cutoff.date()) if zone_name else timezone.utc
+    local_cutoff_date = cutoff.astimezone(zone).date()
+    observation_time = item.get("observation_time")
+    retained = []
+    for row in item["observations"]:
+        row_date = date.fromisoformat(row["date"])
+        if observation_time and item.get("observation_timezone"):
+            observed = datetime.combine(
+                row_date, time.fromisoformat(observation_time),
+                zone_for_date(item["observation_timezone"], row_date),
+            ).astimezone(timezone.utc)
+            available = observed <= cutoff
+        else:
+            # A daily date without a verified clock cannot establish same-day availability.
+            available = row_date < local_cutoff_date
+        if available:
+            retained.append(row)
+    intraday = [row for row in item.get("intraday_observations", [])
+                if datetime.fromisoformat(row["timestamp"].replace("Z", "+00:00")).astimezone(timezone.utc) <= cutoff]
+    return {**item, "observations": retained, "intraday_observations": intraday,
+            "asof_excluded_observations": len(item["observations"]) - len(retained),
+            "original_first_observation_date": item["observations"][0]["date"]}